@sema-agent/core 7.18.0 → 7.19.0

package/dist/core/runner/prepare-task.js

@@ -574,7 +574,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
             }
         }
-        const projectContext = await prepareProjectContext({ deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, roster, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume });
+        const projectContext = await prepareProjectContext({ deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, roster, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume, skillListingBudget: doors.skillListingBudget });
         const { memoryBlock: memoryBlockWithProject, instructionSources, projectInstructionContent, hasSkillManifest, skillsListing, sharedMemoryPairMounted, memoryEnginePairMounted } = projectContext;
         const { provider, featureFlags, userSystemPrompt, userAppendSystemPrompt, mcpInstructionsBlock, envFacts, tzValid, userTz, gitStatusRef } = await preparePromptInputs({ spec, deps, failClosedReason: selfOrchestrationFailClosedReason(spec, deps), lockedPreflight, selfOrchestrationActive, executionEnv, reminderMark, resolvedReadFace, resolvedWriteFace, toolFaceSnapshot, promptProfile, fableMitigations, internals, thinking, ownedEnv, delegation, resolvedRole, mcp, model, externalContentTargetActive, resume, handsEnabled, taskRootFinal, additionalRootsCanonical, additionalReadRootsCanonical, sessionId, ...(advertisedWritableDirs !== undefined ? { advertisedWritableDirs } : {}) });
         const { deferred, memoryBlock, toolSearch: toolSearchPolicy } = prepareDeferClassify({ spec, deps, roster, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryBlock: memoryBlockWithProject, memoryRecallSegment, onceLedger, sessionId });

package/dist/core/runner/resume-apply.js

@@ -2,6 +2,7 @@ import { snapshotActorAssertion } from "../../internal/llm.js";
 import { isAskOrigin } from "../ask-origin.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
 import { CheckpointError, remainingBudgetMicroUsd } from "../checkpoint-store.js";
+import { settledByPerson } from "../gate-outcome.js";
 import { cloneObserverInput, mintHookInvocationIdentity, resolveHookTimeoutMs, runHookSeat } from "../hooks.js";
 import { checkToolPolicyProjection, refuseOutOfContractDecision } from "../tool-policy.js";
 import { callFaceSeat, parkedCallFaceOf } from "../tool-roster.js";
@@ -170,10 +171,9 @@ export async function resumeApply(input) {
             throw new CheckpointError("checkpoint.unsupported_version", "this checkpoint's pending approval carries no origin word (a row minted before the ask's origin was persisted on the park) — its settlement cannot be recorded; the checkpoint stays pending", { reason: "origin_missing" });
         }
         const facts = plainPolicyOutcome.hostDecision;
-        const approverCell = facts.approver !== undefined ? { approver: facts.approver } : {};
         const settlement = facts.decidedBy === "sla_timeout"
-            ? { kind: "park_sla_expired", who: { party: "host", ...approverCell }, when: Date.now() }
-            : { kind: plainPolicyOutcome.decision === "allow" ? "human_allowed" : "human_refused", who: { party: "person", ...approverCell }, when: Date.now(), ...(plainPolicyOutcome.decision === "deny" && plainPolicyOutcome.reason !== undefined ? { note: plainPolicyOutcome.reason } : {}) };
+            ? { kind: "park_sla_expired", who: { party: "host", ...(facts.approver !== undefined ? { approver: facts.approver } : {}) }, when: Date.now() }
+            : settledByPerson(plainPolicyOutcome.decision === "allow" ? "human_allowed" : "human_refused", facts.approver, plainPolicyOutcome.decision === "deny" ? plainPolicyOutcome.reason : undefined);
         plainPolicyOutcome = { ...plainPolicyOutcome, gateOutcome: mintGateOutcome({ ...(plainPolicyOutcome.decision === "deny" ? { deniedBy: "ask_resolution" } : {}), settled: { settlement, origin: parkedOrigin } }) };
     }
     const outcomeForStore = plainPolicyOutcome ?? plainReviewOutcome ?? plainParkOutcome;

package/dist/core/runner/run-leg.js

@@ -26,7 +26,8 @@ import { maybeHumanRejectionHalt } from "./prepare-gate-stations.js";
 import { nextHumanInputSeq } from "./steer-admission.js";
 import { settleTeardownLeg } from "./teardown-bounded.js";
 import { toolEndBodyFrom, toolResultMsg } from "./tool-end-body.js";
-import { attachmentEnvelopeTags, commitAgentListing, commitSkillsListing, reduceToolEnd, renderAgentListingDelta, renderOrphanedBackgroundTasks, renderSkillsListingDelta, stampWriteAnchor } from "./turn-attachments.js";
+import { announceSkillListingTruncation } from "../skill-listing-budget.js";
+import { attachmentEnvelopeTags, commitAgentListing, commitSkillsListing, reduceToolEnd, renderAgentListingDelta, renderOrphanedBackgroundTasks, renderSkillsListingFrame, stampWriteAnchor } from "./turn-attachments.js";
 export async function runLeg(input) {
     const { spec, queue, prepared, resume, rs, isDelegatedChild, entryActor, effectiveTimeoutMs, timeout, pushContent, ident, emitCommitted, writeFamilyOf, startedToolCallIds, announceWorkspaceMove, withBrainSinks, flushGitMirror, loopLatch, notificationLane, unsubscribeTaskNotifications, unsubGitRetry, unsubBoundary, unsub, runner, next } = input;
     let final;
@@ -331,6 +332,7 @@ export async function runLeg(input) {
                 }
             }
             const firstFrames = [];
+            let skillsListingCost;
             if (rs.attach.attachState !== undefined) {
                 const attach = rs.attach.attachState;
                 if (rs.attach.agentListingOn && prepared.agentListing !== undefined) {
@@ -351,14 +353,15 @@ export async function runLeg(input) {
                 }
                 if (rs.attach.skillsListingOn && prepared.skillsListing !== undefined) {
                     const listing = prepared.skillsListing;
-                    const body = renderSkillsListingDelta(attach, listing.entries);
-                    if (body !== undefined) {
+                    const frame = renderSkillsListingFrame(attach, listing.entries, listing.budget);
+                    if (frame !== undefined) {
                         firstFrames.push({
                             source: "skills_listing",
-                            body,
+                            body: frame.text,
                             commit: () => {
                                 commitSkillsListing(attach, listing.entries);
                                 prepared.announcedListingsRef.skills = listing.entries.map((e) => e.name);
+                                skillsListingCost = { total: frame.listed, nameOnly: frame.nameOnly, dropped: frame.dropped, budget: listing.budget };
                             },
                         });
                     }
@@ -432,6 +435,9 @@ export async function runLeg(input) {
                 rs.attach.attachmentsInjected += firstFrames.length;
                 if (firstFrames.length > 0 && prepared.announcedSnapshotRecovered)
                     await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+                if (skillsListingCost !== undefined) {
+                    announceSkillListingTruncation(runner.deps.onNotice, { ...skillsListingCost, sessionId: prepared.sessionId });
+                }
                 const enginePrefixChars = effectiveObjective.length - projectedObjective.length;
                 queue.push({
                     ...buildHumanInputEvent({

package/dist/core/runner/run-turn-boundary.js

@@ -4,7 +4,8 @@ import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
 import { DEFAULT_COMPACTION_INSTRUCTIONS, isCompactionManualCancel, maybeCompact, nextTrimForceBackoff, recordCompactionAndCheckRapidRefill } from "../auto-compaction.js";
 import { emitTrace } from "../trace.js";
 import { redactThenCut } from "../../agents/subagent-steps.js";
-import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, TOTAL_TOKENS_REMINDER_DEFAULT_MODE, attachmentEnvelopeTags, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, rebaseCadenceWindows, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta } from "./turn-attachments.js";
+import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, TOTAL_TOKENS_REMINDER_DEFAULT_MODE, attachmentEnvelopeTags, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, rebaseCadenceWindows, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, selectMcpDroppedBatch, renderSkillsListingFrame, renderToolsDelta } from "./turn-attachments.js";
+import { announceSkillListingTruncation } from "../skill-listing-budget.js";
 import { buildWorkingFileAttachments, centerAdoptionOption, contextInstructionFilesOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
 import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
 import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
@@ -202,6 +203,7 @@ export function createTurnBoundary(input) {
         }
         let boundaryAttachmentBytes = 0;
         let attachmentsPayload;
+        let skillsListingCost;
         if ((rs.attach.dateState !== undefined ||
             rs.attach.instrState !== undefined ||
             rs.attach.sizeGuidelineState !== undefined ||
@@ -313,7 +315,9 @@ export function createTurnBoundary(input) {
                             ...(prepared.agentListing.models !== undefined ? { agentModels: prepared.agentListing.models } : {}),
                         }
                         : {}),
-                    ...(rs.attach.skillsListingOn && prepared.skillsListing !== undefined ? { skillsListing: prepared.skillsListing.entries } : {}),
+                    ...(rs.attach.skillsListingOn && prepared.skillsListing !== undefined
+                        ? { skillsListing: prepared.skillsListing.entries, skillsListingBudget: prepared.skillsListing.budget }
+                        : {}),
                     ...(mcpAdds !== undefined || mcpRemovals !== undefined
                         ? { mcpInstructions: { added: mcpAdds ?? [], removed: mcpRemovals ?? [] } }
                         : {}),
@@ -377,9 +381,10 @@ export function createTurnBoundary(input) {
                 }
                 if (rs.attach.skillsListingOn && prepared.skillsListing !== undefined && due.some((a) => a.source === "skills_listing")) {
                     const listing = prepared.skillsListing;
-                    const intactBody = renderSkillsListingDelta(rs.attach.attachState, listing.entries);
-                    if (intactBody !== undefined && due.some((a) => a.source === "skills_listing" && a.body === intactBody)) {
+                    const intact = renderSkillsListingFrame(rs.attach.attachState, listing.entries, listing.budget);
+                    if (intact !== undefined && due.some((a) => a.source === "skills_listing" && a.body === intact.text)) {
                         commitSkillsListing(rs.attach.attachState, listing.entries);
+                        skillsListingCost = { total: intact.listed, nameOnly: intact.nameOnly, dropped: intact.dropped, budget: listing.budget };
                         prepared.announcedListingsRef.skills = listing.entries.map((e) => e.name);
                         if (prepared.announcedSnapshotRecovered)
                             await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
@@ -474,6 +479,9 @@ export function createTurnBoundary(input) {
         if ((attachmentsPayload !== undefined || batchContextBlock !== undefined) && prepared.batchHaltRef.current === undefined) {
             const payload = attachmentsPayload !== undefined && batchContextBlock !== undefined ? `${attachmentsPayload}\n${batchContextBlock}` : (attachmentsPayload ?? batchContextBlock);
             void prepared.harness.steer(payload, { engineMinted: true }).catch(() => { });
+            if (skillsListingCost !== undefined) {
+                announceSkillListingTruncation(deps.runner.deps.onNotice, { ...skillsListingCost, sessionId: prepared.sessionId });
+            }
         }
         const forceManual = manualCompactRef.requested;
         if ((!withinTaskCompaction && !forceManual) ||

package/dist/core/runner/synthetic-tools.d.ts

@@ -1,6 +1,7 @@
 import { type TSchema } from "typebox";
 import type { AgentTool } from "../../internal/harness-types.js";
 import type { SkillManifest } from "../types.js";
+import { type ResolvedSkillListingBudget } from "../skill-listing-budget.js";
 import type { ActiveSkillScope } from "./active-skill-scope.js";
 /** Reserved name of the injected structured-output tool (CC 2.1.187 `StructuredOutput`; batch-A rename — old
  *  "submit_output" is canonicalized for pre-rename durable state). */
@@ -57,15 +58,11 @@ export declare const SKILL_TOOL_NAME = "Skill";
  *  an oversized skill is excluded from the disclosure block and the tool, with an operator-visible config error. The compaction-time retention caps are a
  *  different door, deliberately. */
 export declare const SKILL_CONTENT_MAX_CHARS: number;
-/** Total listing-block cap in UTF-8 BYTES — [c209-C] R2 C4①: the old 8000-CHAR cap measured a
- *  different coordinate than the bundle's `ATTACHMENT_BYTE_CAP` (8192 UTF-8 bytes) and counted only
- *  the description lines (fence framing + name-only tail rode free), so a near-cap frame could
- *  exceed the bundle cap, get clip-mangled every boundary, never pass the intact-survival commit
- *  predicate, and REPLAY FOREVER. The cap is now enforced byte-exact over the WHOLE rendered block
- *  (fences, headers, markers, joiners included), so `buildSkillsBlock` output always fits the
- *  bundle cap solo and an intact commit is always reachable. MUST stay ≤ ATTACHMENT_BYTE_CAP
- *  (turn-attachments.ts; not imported here — that module imports this one — pinned by test instead). */
-export declare const SKILLS_BLOCK_MAX_BYTES = 8000;
+/** The listing's budget vocabulary lives in `core/skill-listing-budget.ts` (the seat reader that lowers
+ *  the two `TaskSpec` knobs to these numbers); re-exported here because this module is where every
+ *  existing consumer of the cap imports it from, and the ceiling's structural reason is a property of
+ *  the delivery lane rather than of the renderer. */
+export { SKILLS_BLOCK_MAX_BYTES } from "../skill-listing-budget.js";
 /** Total per-invoke cap for a skill's inlined attachments (`SkillSpec.files`) — an ATTACHMENT-face budget, distinct from the (gone) body truncation door:
  *  the body is delivered untruncated at invoke time (CC parity), while attachments ride along bounded and truncation-disclosed. */
 export declare const SKILL_ATTACHMENTS_MAX_CHARS = 50000;
@@ -123,31 +120,73 @@ export declare const SKILLS_LISTING_PROBE_HEADER = "The following skills are ava
 /** [c209-C] One skill's disclosure line — `- name: description[(files 尾缀)]` with the per-skill
  *  description cap. Single-sourced so the skills_listing DELTA frame (turn-attachments) renders adds
  *  with byte-identical line shape to the initial `<skills>` block. */
-export declare function skillListingLine(s: SkillListingEntry): string;
+export declare function skillListingLine(s: SkillListingEntry, descMaxChars?: number): string;
+/** What one {@link renderSkillsBlock} call produced: the block, and which skills the budget degraded. */
+export interface SkillsBlockRender {
+    /** The rendered block — what {@link buildSkillsBlock} returns. */
+    text: string;
+    /** Skills listed WITHOUT their description (tier B's unspent candidates, or every listed name under
+     *  tier C), in display order. Raw names: this is host-facing structured data, not prompt text. */
+    nameOnly: readonly string[];
+    /** Skills the block could not list at all (tier C's overflow tail). The `Skill` tool still serves them. */
+    dropped: readonly string[];
+}
+/** The text-only face of {@link renderSkillsBlock} — the `<skills>` BLOCK's face, not the listing
+ *  family's: the drift frame renders its own arms through the shared tier engine
+ *  ({@link renderSkillLinesWithin}), which is where "one ruler for every frame" lives. */
+export declare function buildSkillsBlock(skills: ReadonlyArray<SkillListingEntry>, budget?: ResolvedSkillListingBudget): string | undefined;
 /** Render the `<skills>` disclosure block (metadata only — bodies stay behind the tool).
  *  [c209-C] REVERSAL: no longer composed into the stable system prompt — this is now the RENDERER for
  *  the `skills_listing` initial frame (first-user-turn reminder / boundary re-announce), so the
  *  cached prefix carries zero skill bytes (design/C §2.3; CC 209 classic ships the same listing as a
  *  first-turn reminder; Q6: 8KB cap ≈ CC's observed 5.9KB listing).
  *
- *  [c209-C] R2 C4① — the cap is BYTE-EXACT over the whole rendered block (see
- *  {@link SKILLS_BLOCK_MAX_BYTES}): three honesty tiers, each chosen with the LATER tiers' fixed
- *  overhead (cap marker / name-only tail / overflow count line) already reserved so the final
- *  render can never blow the budget it was sized against —
- *    A. everything fits → every skill gets its full `- name: description` line (byte-identical to
- *       the pre-C4 render for every block that was legal under the old cap);
- *    B. (CC 220 `sbs` @317547-317586) — reserve the cap marker + EVERY skill's name-only line
- *       first, then spend the remaining slack on descriptions in PRIORITY order
- *       ({@link SkillListingEntry.declaredRank}), admitting each description whose incremental cost
- *       still fits and skipping (not stopping at) the ones that do not. Every skill stays listed;
- *       the ones that lose their description are the low-priority ones, not the alphabetically late
- *       ones. This replaces the prior "longest full-line PREFIX" cut, which had two defects the
- *       anchor does not: the surviving set was decided by name sort order (a skill named `zip-deploy`
- *       lost its description to `aardvark-lint` for no reason connected to either skill), and one
- *       oversized description truncated the block at itself instead of being skipped over;
- *    C. even all-name-only overflows (pathological name census) → list what fits and close with an
- *       honest `(… +N more skills …)` count line — the tool still serves all of them. */
-export declare function buildSkillsBlock(skills: ReadonlyArray<SkillListingEntry>): string | undefined;
+ *  The fence and its four header lines are this lane's frame; the budget arithmetic and the three
+ *  degradation tiers belong to {@link renderSkillLinesWithin}, which the drift frame renders through
+ *  as well. {@link buildSkillsBlock} is the text-only face; this one additionally reports what the
+ *  budget cost, for the disclosure lane. */
+export declare function renderSkillsBlock(skills: ReadonlyArray<SkillListingEntry>, budget?: ResolvedSkillListingBudget): SkillsBlockRender | undefined;
+/**
+ * The three honesty tiers over ONE set of skills, measured byte-exact inside a caller-supplied FRAME —
+ * the engine both {@link renderSkillsBlock} and the drift frame's ADD arm render through, so the
+ * initial `<skills>` block and a later "new skills are now available" announcement degrade by the same
+ * rules against the same number. A lane that folded by its own rules (or by none) renders a body the
+ * bundle cap CLIPS, and a clipped body can never equal the intact-survival re-render, so the
+ * announcement replays at every boundary for the life of the task — the failure
+ * `@contract skills.listing_budget_ceiling` names, on whichever lane skipped the measurement.
+ *
+ * `frame` renders the body lines into the shape its lane carries; its fixed cost is priced once, by
+ * rendering it empty, so the tiers below decide against the bytes that actually ship.
+ *
+ * [c209-C] R2 C4① — the cap is BYTE-EXACT over the whole rendered frame (see
+ * {@link SKILLS_BLOCK_MAX_BYTES}): three honesty tiers, each chosen with the LATER tiers' fixed
+ * overhead (cap marker / name-only tail / overflow count line) already reserved so the final
+ * render can never blow the budget it was sized against —
+ *   A. everything fits → every skill gets its full `- name: description` line (byte-identical to
+ *      the pre-C4 render for every block that was legal under the old cap);
+ *   B. (CC 220 `sbs` @317547-317586) — reserve the cap marker + EVERY skill's name-only line
+ *      first, then spend the remaining slack on descriptions in PRIORITY order
+ *      ({@link SkillListingEntry.declaredRank}), admitting each description whose incremental cost
+ *      still fits and skipping (not stopping at) the ones that do not. Every skill stays listed;
+ *      the ones that lose their description are the low-priority ones, not the alphabetically late
+ *      ones. This replaces the prior "longest full-line PREFIX" cut, which had two defects the
+ *      anchor does not: the surviving set was decided by name sort order (a skill named `zip-deploy`
+ *      lost its description to `aardvark-lint` for no reason connected to either skill), and one
+ *      oversized description truncated the block at itself instead of being skipped over;
+ *   C. even all-name-only overflows (pathological name census) → list what fits and close with an
+ *      honest `(… +N more skills …)` count line — the tool still serves all of them.
+ *
+ * Pure: the same entries, budget and frame always render the same bytes, which is what the
+ * prompt-prefix stability contract requires of the listing frames.
+ */
+export declare function renderSkillLinesWithin(skills: ReadonlyArray<SkillListingEntry>, opts: {
+    /** The whole frame's byte budget. Re-clamped to {@link SKILLS_BLOCK_MAX_BYTES} here, not only in
+     *  the seat reader: this renderer is reachable from every listing lane, and the ceiling invariant
+     *  has to hold for a caller that computed its own number. */
+    blockMaxBytes: number;
+    descMaxChars: number;
+    frame: (lines: readonly string[]) => string;
+}): SkillsBlockRender | undefined;
 /**
  * The injected `skill` tool: returns a skill's full body as a tool result.
  *
@@ -164,4 +203,3 @@ export declare function buildSkillsBlock(skills: ReadonlyArray<SkillListingEntry
  * widening, so it stays safe-by-construction.
  */
 export declare function createSkillTool(skills: SkillLike[], scope?: ActiveSkillScope): AgentTool;
-export {};

package/dist/core/runner/synthetic-tools.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { defineTool } from "../tools.js";
 import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
+import { SKILLS_BLOCK_MAX_BYTES as SKILL_LISTING_CEILING_BYTES, SKILL_LISTING_DESC_MAX_CHARS_DEFAULT, } from "../skill-listing-budget.js";
 import { toolFace } from "../tool-catalog-entries.js";
 import { substituteSkillRoot, substituteSkillRootBounded } from "./skill-base-dir.js";
 export const OUTPUT_TOOL_NAME = "StructuredOutput";
@@ -85,8 +86,7 @@ export function createReportFindingsTool() {
 }
 export const SKILL_TOOL_NAME = "Skill";
 export const SKILL_CONTENT_MAX_CHARS = 1024 * 1024;
-const SKILL_DESC_MAX_CHARS = 1_536;
-export const SKILLS_BLOCK_MAX_BYTES = 8_000;
+export { SKILLS_BLOCK_MAX_BYTES } from "../skill-listing-budget.js";
 export const SKILL_ATTACHMENTS_MAX_CHARS = 50_000;
 export const SKILL_ATTACHMENT_PATH_MAX_CHARS = 512;
 const SKILL_FILES_LIST_MAX_CHARS = 200;
@@ -121,18 +121,18 @@ export function normalizeSkills(skills) {
     return out.toSorted((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 export const SKILLS_LISTING_PROBE_HEADER = "The following skills are available for this task.";
-export function skillListingLine(s) {
-    const desc = s.description.length > SKILL_DESC_MAX_CHARS
-        ? `${s.description.slice(0, SKILL_DESC_MAX_CHARS - 1)}…`
-        : s.description;
+export function skillListingLine(s, descMaxChars = SKILL_LISTING_DESC_MAX_CHARS_DEFAULT) {
+    const desc = s.description.length > descMaxChars ? `${s.description.slice(0, descMaxChars - 1)}…` : s.description;
     const safe = (t) => sanitizeUntrustedText(t, SHELLED_BODY_ENVELOPE_TAGS);
     return `- ${safe(s.name)}: ${safe(desc)}${safe(skillFilesSuffix(s.files))}`;
 }
 const SKILLS_BLOCK_CAP_MARKER = "(block size cap reached — lower-priority skills are listed name-only; descriptions via the tool)";
-export function buildSkillsBlock(skills) {
+export function buildSkillsBlock(skills, budget) {
+    return renderSkillsBlock(skills, budget)?.text;
+}
+export function renderSkillsBlock(skills, budget) {
     if (skills.length === 0)
         return undefined;
-    const bytes = (s) => Buffer.byteLength(s, "utf8");
     const headerLines = [
         "<skills>",
         `${SKILLS_LISTING_PROBE_HEADER} A skill is a named package of instructions;`,
@@ -140,18 +140,34 @@ export function buildSkillsBlock(skills) {
         `instructions by calling the \`${SKILL_TOOL_NAME}\` tool with \`skill: "<name>"\` (plus optional \`args\`).`,
         "",
     ];
-    const render = (lines) => [...headerLines, ...lines, "</skills>"].join("\n");
+    return renderSkillLinesWithin(skills, {
+        blockMaxBytes: budget?.blockMaxBytes ?? SKILL_LISTING_CEILING_BYTES,
+        descMaxChars: budget?.descMaxChars ?? SKILL_LISTING_DESC_MAX_CHARS_DEFAULT,
+        frame: (lines) => [...headerLines, ...lines, "</skills>"].join("\n"),
+    });
+}
+export function renderSkillLinesWithin(skills, opts) {
+    if (skills.length === 0)
+        return undefined;
+    const blockMaxBytes = Math.min(opts.blockMaxBytes, SKILL_LISTING_CEILING_BYTES);
+    const descMaxChars = opts.descMaxChars;
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const render = opts.frame;
     const lineCost = (l) => bytes(l) + 1;
-    const budget = SKILLS_BLOCK_MAX_BYTES - bytes(render([]));
-    const fullLines = skills.map((s) => skillListingLine(s));
-    const nameLines = skills.map((s) => `- ${sanitizeUntrustedText(s.name, SHELLED_BODY_ENVELOPE_TAGS)}`);
+    const bodyBudget = blockMaxBytes - bytes(render([]));
+    const fullLines = skills.map((s) => skillListingLine(s, descMaxChars));
     const fullTotal = fullLines.reduce((acc, l) => acc + lineCost(l), 0);
-    if (fullTotal <= budget)
-        return render(fullLines);
+    if (fullTotal <= bodyBudget)
+        return { text: render(fullLines), nameOnly: [], dropped: [] };
+    const nameLines = skills.map((s) => `- ${sanitizeUntrustedText(s.name, SHELLED_BODY_ENVELOPE_TAGS)}`);
+    const namePrefix = new Array(nameLines.length + 1);
+    namePrefix[0] = 0;
+    for (let i = 0; i < nameLines.length; i++)
+        namePrefix[i + 1] = namePrefix[i] + lineCost(nameLines[i]);
     const markerCost = lineCost(SKILLS_BLOCK_CAP_MARKER);
-    const floorCost = markerCost + nameLines.reduce((acc, l) => acc + lineCost(l), 0);
-    if (floorCost <= budget) {
-        let slack = budget - floorCost;
+    const floorCost = markerCost + namePrefix[nameLines.length];
+    if (floorCost <= bodyBudget) {
+        let slack = bodyBudget - floorCost;
         const byPriority = skills
             .map((s, i) => ({ i, rank: s.declaredRank ?? i }))
             .toSorted((a, b) => a.rank - b.rank || a.i - b.i);
@@ -163,15 +179,28 @@ export function buildSkillsBlock(skills) {
                 slack -= delta;
             }
         }
-        return render([SKILLS_BLOCK_CAP_MARKER, ...skills.map((_s, i) => (withDescription.has(i) ? fullLines[i] : nameLines[i]))]);
+        return {
+            text: render([SKILLS_BLOCK_CAP_MARKER, ...skills.map((_s, i) => (withDescription.has(i) ? fullLines[i] : nameLines[i]))]),
+            nameOnly: skills.filter((_s, i) => !withDescription.has(i)).map((s) => s.name),
+            dropped: [],
+        };
     }
     for (let m = skills.length - 1; m >= 0; m--) {
         const overflowLine = `(… +${skills.length - m} more skills not listed — the ${SKILL_TOOL_NAME} tool serves them all)`;
-        const cost = markerCost + nameLines.slice(0, m).reduce((acc, l) => acc + lineCost(l), 0) + lineCost(overflowLine);
-        if (cost <= budget)
-            return render([SKILLS_BLOCK_CAP_MARKER, ...nameLines.slice(0, m), overflowLine]);
+        const cost = markerCost + namePrefix[m] + lineCost(overflowLine);
+        if (cost <= bodyBudget) {
+            return {
+                text: render([SKILLS_BLOCK_CAP_MARKER, ...nameLines.slice(0, m), overflowLine]),
+                nameOnly: skills.slice(0, m).map((s) => s.name),
+                dropped: skills.slice(m).map((s) => s.name),
+            };
+        }
     }
-    return render([SKILLS_BLOCK_CAP_MARKER, `(… +${skills.length} more skills not listed — the ${SKILL_TOOL_NAME} tool serves them all)`]);
+    return {
+        text: render([SKILLS_BLOCK_CAP_MARKER, `(… +${skills.length} more skills not listed — the ${SKILL_TOOL_NAME} tool serves them all)`]),
+        nameOnly: [],
+        dropped: skills.map((s) => s.name),
+    };
 }
 export function createSkillTool(skills, scope) {
     const byName = new Map(skills.map((s) => [s.name, s]));

package/dist/core/runner/turn-attachments.d.ts

@@ -1,6 +1,7 @@
 import type { McpDroppedTool } from "../mcp.js";
 import type { TaskSpec } from "../types.js";
-import { type SkillListingEntry } from "./synthetic-tools.js";
+import { type SkillListingEntry, type SkillsBlockRender } from "./synthetic-tools.js";
+import { type ResolvedSkillListingBudget } from "../skill-listing-budget.js";
 /**
  * Turn-boundary attachment seam: the PURE producer layer (CC `getContextAttachments`
  * parity). This module is the single home of the CC-parity cadence judgment + reminder copy (提示词主权批:
@@ -545,6 +546,9 @@ export interface AttachmentInputs {
      *  the delta path serves dynamic-installation deployments and tests, same posture as
      *  `agentListing`). Only passed when `config.skillsListing` is on. */
     skillsListing?: ReadonlyArray<SkillListingEntry>;
+    /** The lowered skills-listing budget seats, resolved once at the config door. Absent ⇒ the module
+     *  defaults, i.e. byte-identical to the pre-seat render. */
+    skillsListingBudget?: ResolvedSkillListingBudget;
     /** G1 续批 mcp_instructions: pending deltas snapshotted from `MaterializedMcp.instructionsDelta`.
      *  CALLER-owned consumption on intact cap survival (same `newTools` discipline). */
     mcpInstructions?: {
@@ -849,21 +853,48 @@ export declare function commitAgentListing(state: AttachmentState, entries: Read
 export declare const SKILLS_LISTING_DELTA_HEADER = "New skills are now available:";
 /** [c209-C] skills removal-arm header — mirrors the agent-listing removal arm's phrasing. */
 export declare const SKILLS_LISTING_REMOVED_HEADER = "The following skills are no longer available:";
+/** What one {@link renderSkillsListingFrame} call produced: the render's own report, plus the
+ *  denominator it is against. */
+export interface SkillsListingFrameRender extends SkillsBlockRender {
+    /** How many skills this frame set out to list — the whole roster on an initial frame, the ADDED set
+     *  on a drift frame. The disclosure's denominator, read off the frame that was actually delivered
+     *  rather than re-derived from the roster. */
+    readonly listed: number;
+}
 /**
- * [c209-C] skills_listing producer — the skills counterpart of {@link renderAgentListingDelta}.
- * First call (no announced map) = the full `<skills>` disclosure block VERBATIM (buildSkillsBlock —
- * the exact bytes that used to sit in the stable system prompt now ride the reminder lane; CC 209
- * classic ships its skills listing the same way, as a first-user-turn reminder ~5.9KB, report §5.1).
- * Later calls announce only drift, name-keyed like the agent arm: adds under
- * {@link SKILLS_LISTING_DELTA_HEADER} with the SAME `- name: description` line shape the block uses,
- * removals under {@link SKILLS_LISTING_REMOVED_HEADER} + `- <name>` lines, followed by the
- * CC-verbatim {@link AMBIENT_CONTEXT_NOTE} (agent-removal-arm parity). A description change on an
- * existing name is not re-announced (name-keyed, agent-arm parity).
+ * [c209-C] skills_listing producer — the skills counterpart of {@link renderAgentListingDelta}, with
+ * the degradation report the disclosure lane announces. First call (no announced map) = the full
+ * `<skills>` disclosure block VERBATIM (the exact bytes that used to sit in the stable system prompt
+ * now ride the reminder lane; CC 209 classic ships its skills listing the same way, as a
+ * first-user-turn reminder ~5.9KB, report §5.1). Later calls announce only drift, name-keyed like the
+ * agent arm: adds under {@link SKILLS_LISTING_DELTA_HEADER} with the SAME `- name: description` line
+ * shape the block uses, removals under {@link SKILLS_LISTING_REMOVED_HEADER} + `- <name>` lines,
+ * followed by the CC-verbatim {@link AMBIENT_CONTEXT_NOTE} (agent-removal-arm parity). A description
+ * change on an existing name is not re-announced (name-keyed, agent-arm parity).
+ *
+ * ONE RULER FOR EVERY FRAME: the drift frame is measured against the SAME resolved budget as the
+ * initial block, arms and joiners included, and its ADD arm degrades through the same three tiers
+ * ({@link renderSkillLinesWithin}). An unmeasured drift frame is the block's own failure mode one lane
+ * over: a roster's worth of new skills renders past `ATTACHMENT_BYTE_CAP`, `capAttachments` clips the
+ * body, a clipped body never equals the intact-survival re-render, and the frame is re-rendered and
+ * re-clipped at every boundary for the life of the task. The split: the ambient tail and the removal
+ * arm's one-line floor are reserved first (both constants), the ADD arm degrades into what is left,
+ * and the removal arm spends whatever the add arm did not — so the frame's size is the resolved budget
+ * or, when even the two floors do not fit it, a small constant, never a function of the roster.
+ *
+ * The report covers the ADD arm only: `nameOnly` / `dropped` name skills this frame listed without a
+ * description or could not list at all. A departed name that did not fit is not a listed skill.
  *
  * MED-3① discipline: PURE — the announced-set advance is CALLER-owned via {@link commitSkillsListing},
- * committed only on first-frame delivery or intact cap survival at a boundary.
+ * committed only on first-frame delivery or intact cap survival at a boundary. The commit records
+ * EVERY entry, including one this frame dropped: the alternative is a frame re-rendering the same
+ * un-listable tail at every boundary, which is the replay this budget exists to end. The `Skill` tool
+ * serves a dropped skill, and `skills.listing_truncated` tells the deployment it happened.
  */
-export declare function renderSkillsListingDelta(state: AttachmentState, entries: ReadonlyArray<SkillListingEntry>): string | undefined;
+export declare function renderSkillsListingFrame(state: AttachmentState, entries: ReadonlyArray<SkillListingEntry>, budget?: ResolvedSkillListingBudget): SkillsListingFrameRender | undefined;
+/** The text-only face of {@link renderSkillsListingFrame} — what the delivery lanes render, and what
+ *  the intact-survival predicate re-renders to compare. */
+export declare function renderSkillsListingDelta(state: AttachmentState, entries: ReadonlyArray<SkillListingEntry>, budget?: ResolvedSkillListingBudget): string | undefined;
 /** [c209-C] commit half of {@link renderSkillsListingDelta} — same MED-3① contract as
  *  {@link commitAgentListing}: called by the run loop only on first-frame delivery or when the
  *  `skills_listing` block survived the capped bundle INTACT; a clipped/dropped block leaves the

package/dist/core/runner/turn-attachments.js

@@ -1,7 +1,8 @@
 import { PRESENT_PLAN_TOOL_NAME } from "../present-plan-tool.js";
 import { delimitUntrustedWithClip, sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
 import { protocolOf } from "../protocol-table.js";
-import { buildSkillsBlock, skillListingLine } from "./synthetic-tools.js";
+import { renderSkillLinesWithin, renderSkillsBlock } from "./synthetic-tools.js";
+import { SKILL_LISTING_DESC_MAX_CHARS_DEFAULT, SKILLS_BLOCK_MAX_BYTES } from "../skill-listing-budget.js";
 import { TOOL_SEARCH_NAME as TOOL_SEARCH_TOOL_NAME } from "./tool-disclosure.js";
 export const TODO_REMINDER_CONFIG = {
     TURNS_SINCE_WRITE: 10,
@@ -209,7 +210,9 @@ export function collectDueAttachments(state, inp) {
     const agentListingBody = inp.config.agentListing && inp.agentListing !== undefined
         ? renderAgentListingDelta(state, inp.agentListing, inp.agentToolName ?? "Agent", inp.agentModels)
         : undefined;
-    const skillsListingBody = inp.config.skillsListing && inp.skillsListing !== undefined ? renderSkillsListingDelta(state, inp.skillsListing) : undefined;
+    const skillsListingBody = inp.config.skillsListing && inp.skillsListing !== undefined
+        ? renderSkillsListingDelta(state, inp.skillsListing, inp.skillsListingBudget)
+        : undefined;
     const listingPair = [];
     if (agentListingBody !== undefined)
         listingPair.push({ source: "agent_listing", body: agentListingBody });
@@ -545,10 +548,9 @@ export function renderAgentListingDelta(state, entries, toolName, models) {
         return blocks.join("\n\n");
     }
     const announcedIds = new Set([...announced.keys()].map(listingIdentity));
+    const entryIds = new Set(entries.map((e) => listingIdentity(e.name)));
     const added = entries.filter((e) => !announcedIds.has(listingIdentity(e.name))).toSorted((a, b) => a.name.localeCompare(b.name));
-    const removed = [...announced.keys()]
-        .filter((n) => !entries.some((e) => listingIdentity(e.name) === listingIdentity(n)))
-        .sort();
+    const removed = [...announced.keys()].filter((n) => !entryIds.has(listingIdentity(n))).sort();
     const modelsDrifted = state.announcedModels !== undefined &&
         models !== undefined &&
         (state.announcedModels.length !== models.length ||
@@ -594,26 +596,68 @@ export function commitAgentListing(state, entries, models) {
 }
 export const SKILLS_LISTING_DELTA_HEADER = "New skills are now available:";
 export const SKILLS_LISTING_REMOVED_HEADER = "The following skills are no longer available:";
-export function renderSkillsListingDelta(state, entries) {
+const SKILLS_DELTA_BLOCK_JOINER = "\n\n";
+function skillsRemovalArmFloor(count) {
+    return [SKILLS_LISTING_REMOVED_HEADER, `(… +${count} more are no longer available)`].join("\n");
+}
+function renderSkillsRemovalArm(removed, maxBytes) {
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const lines = removed.map((n) => `- ${sanitizeUntrustedText(n, SHELLED_BODY_ENVELOPE_TAGS)}`);
+    const head = bytes(SKILLS_LISTING_REMOVED_HEADER);
+    const lineCost = (l) => bytes(l) + 1;
+    const prefix = new Array(lines.length + 1);
+    prefix[0] = 0;
+    for (let i = 0; i < lines.length; i++)
+        prefix[i + 1] = prefix[i] + lineCost(lines[i]);
+    if (head + prefix[lines.length] <= maxBytes)
+        return [SKILLS_LISTING_REMOVED_HEADER, ...lines].join("\n");
+    for (let m = lines.length - 1; m >= 0; m--) {
+        const tail = `(… +${lines.length - m} more are no longer available)`;
+        if (head + prefix[m] + lineCost(tail) <= maxBytes)
+            return [SKILLS_LISTING_REMOVED_HEADER, ...lines.slice(0, m), tail].join("\n");
+    }
+    return skillsRemovalArmFloor(lines.length);
+}
+export function renderSkillsListingFrame(state, entries, budget) {
     const announced = state.announcedSkills;
     if (announced === undefined) {
         if (entries.length === 0)
             return undefined;
-        return buildSkillsBlock(entries);
+        const block = renderSkillsBlock(entries, budget);
+        return block === undefined ? undefined : { ...block, listed: entries.length };
     }
     const announcedIds = new Set([...announced.keys()].map(listingIdentity));
+    const entryIds = new Set(entries.map((e) => listingIdentity(e.name)));
     const added = entries.filter((e) => !announcedIds.has(listingIdentity(e.name)));
-    const removed = [...announced.keys()].filter((n) => !entries.some((e) => listingIdentity(e.name) === listingIdentity(n)));
+    const removed = [...announced.keys()].filter((n) => !entryIds.has(listingIdentity(n)));
     if (added.length === 0 && removed.length === 0)
         return undefined;
-    const blocks = [];
-    if (added.length > 0)
-        blocks.push(`${SKILLS_LISTING_DELTA_HEADER}\n${added.map((e) => skillListingLine(e)).join("\n")}`);
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const joiner = bytes(SKILLS_DELTA_BLOCK_JOINER);
+    const frameMaxBytes = Math.min(budget?.blockMaxBytes ?? SKILLS_BLOCK_MAX_BYTES, SKILLS_BLOCK_MAX_BYTES);
+    const ambientCost = removed.length > 0 ? joiner + bytes(AMBIENT_CONTEXT_NOTE) : 0;
+    const removalReserve = removed.length > 0 ? joiner + bytes(skillsRemovalArmFloor(removed.length)) : 0;
+    const addArm = added.length > 0
+        ? renderSkillLinesWithin(added, {
+            blockMaxBytes: frameMaxBytes - ambientCost - removalReserve,
+            descMaxChars: budget?.descMaxChars ?? SKILL_LISTING_DESC_MAX_CHARS_DEFAULT,
+            frame: (lines) => [SKILLS_LISTING_DELTA_HEADER, ...lines].join("\n"),
+        })
+        : undefined;
+    const addCost = addArm === undefined ? 0 : bytes(addArm.text) + (removed.length > 0 ? joiner : 0);
+    const blocks = addArm === undefined ? [] : [addArm.text];
     if (removed.length > 0) {
-        blocks.push(`${SKILLS_LISTING_REMOVED_HEADER}\n${removed.map((n) => `- ${sanitizeUntrustedText(n, SHELLED_BODY_ENVELOPE_TAGS)}`).join("\n")}`);
-        blocks.push(AMBIENT_CONTEXT_NOTE);
+        blocks.push(renderSkillsRemovalArm(removed, frameMaxBytes - ambientCost - addCost), AMBIENT_CONTEXT_NOTE);
     }
-    return blocks.join("\n\n");
+    return {
+        text: blocks.join(SKILLS_DELTA_BLOCK_JOINER),
+        nameOnly: addArm?.nameOnly ?? [],
+        dropped: addArm?.dropped ?? [],
+        listed: added.length,
+    };
+}
+export function renderSkillsListingDelta(state, entries, budget) {
+    return renderSkillsListingFrame(state, entries, budget)?.text;
 }
 export function commitSkillsListing(state, entries) {
     state.announcedSkills = new Map(entries.map((e) => [e.name, e.description]));