feat(schema,rpc-output-budget): per-step outputLimit knobs (maxBytes, maxAssistantFinals)

[ShinonKagura]

Third of three focused PRs splitting out the usable parts of #2 against current main, as requested in your review. This is the only feature of the three (not a fix) — you mentioned "output-limit knobs as a separate small feature" in #2 as a candidate.

What

Adds optional per-step outputLimit: { maxBytes?, maxAssistantFinals? } field on graph steps. Both fields clamp the existing package-level caps (MAX_STEP_OUTPUT_BYTES = 4 MiB, MAX_ASSISTANT_FINAL_MESSAGES_PER_STEP = 64) downward only.

Out-of-range and non-integer values are rejected by schema validation; an additional runtime clamp in AssistantOutputBudget serves as defense-in-depth for any caller that bypasses schema validation.

Example

{
  "id": "tight",
  "agent": { "ref": "package:scout" },
  "task": "Return the top 5 most relevant files as a numbered list. No prose preamble.",
  "outputLimit": {
    "maxBytes": 4096,
    "maxAssistantFinals": 1
  }
}

This step can produce at most 4 KiB of assistant output across at most 1 final message, instead of the 4 MiB / 64 defaults. Useful when you want a hard structural guarantee that a step's output stays inside a known small budget (chat-fit summaries, one-line decisions, bounded JSON returns).

Plumbing chain (verified end-to-end)

GraphStepInput.outputLimit (types.ts)
→ resolveStep (planning.ts)
→ TeamStepSpec.outputLimit
→ new RpcChildController({outputLimit}) (detached-run.ts)
→ new AssistantOutputBudget({maxBytes, maxAssistantFinals}) (rpc-child-controller.ts)

Backwards-compatibility

constructor(limits: AssistantOutputBudgetLimits = {}) — omitting outputLimit (or the entire field) yields exactly the package caps. new AssistantOutputBudget() without args still works for existing callers and tests.

Tests (+9 new)

• tests/rpc-output-budget.test.ts (NEW, 7 tests): default fallback, downward honor for both knobs, upward clamp protection for both knobs, byte-limit path in canAcceptAssistantFinal, invalid-input fallback (0, -1, 1.5, NaN, Infinity) for both knobs
• tests/schemas.test.ts (+1 test, 11 assertions): valid downward, out-of-range rejection, non-integer rejection (multipleOf:1 guard), unknown-field rejection (additionalProperties:false)
• tests/planning.test.ts (+1 test, 2 assertions): resolveStep propagation with + without outputLimit

Total: 244 baseline tests → 253 with this PR.

Discipline

• Single focused commit (feat(schema,rpc-output-budget): ...)
• No version bump
• Changelog entry under ## Unreleased only
• SKILL.md pseudo-schema updated (step { ..., outputLimit? }) with explanation paragraph
• README.md Limits table extended with Per-step outputLimit override row
• skills/pi-multiagent/references/graph-cookbook.md has a copyable "Per-step output limit override" snippet
• Internal getEffectiveLimits() marked @internal JSDoc

Required checks against this branch

Check	Result
npx tsc --noEmit	✅ exit 0
node --test tests/*.test.ts	✅ 253/253 pass, 0 fail
node tests/check-source-size.ts	✅ PASS
node tests/check-public-docs.ts	✅ PASS
git diff --check HEAD~1..HEAD	✅ clean

Related

Closes the smallest feature carved out of #2. Companion PRs:

• fix(rpc-child-controller): unref detached children so parent Pi can exit (FIX-6) #3 — child unref fix
• (preceding) — preflight GRAPH_BODY_FIELDS trim

Three proposal-issues for the larger features (scheduling, persistent state + reattach, worktree isolation) will be opened separately so we can agree on shape before code, as you requested.