@sema-agent/client-core 0.109.0 → 0.111.0

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -5,16 +5,16 @@ import { ccToolDenialKindForToolEnd, gateOutcomeOf, toolInputRewriteOf } from '.
 import { projectToolRoster, projectToolRosterDelta } from '../../toolRoster.js';
 import { projectHandsSection } from '../../handsSeam.js';
 import { readMcpAuthorization, readMcpLiveness } from '../../mcpLiveness.js';
-import { contextUsageReadingOf, humanInputAttachmentsOf, humanInputAuthorKeys, guardedRead, markMcpSectionDroppedNamedRows, ownSnapshotTyped, promptManifestIdentityOfFrame, promptManifestSectionViewOf, readFrameStringKey, readFrameTrueMark, readOwnDataFiniteNumber, readOwnDataNonEmptyString, workflowCompletionExtrasOf } from '../../ownKey.js';
+import { contextUsageReadingOf, humanInputAttachmentsOf, guardedRead, markMcpSectionDroppedNamedRows, ownSnapshotTyped, promptManifestIdentityOfFrame, promptManifestSectionViewOf, readFrameStringKey, readFrameTrueMark, readOwnDataFiniteNumber, readOwnDataNonEmptyString, resupplyTruncatedOf, workflowCompletionExtrasOf } from '../../ownKey.js';
+import { humanInputAuthorKeys, runOriginKeys } from '../../inputAuthor.js';
 import { SEGMENT_END_IDENTITY_KEYS, eventSeq, stripToolUseSideChannels } from '../types.js';
+import { promptSuggestionBatchOf } from '../../promptSuggestionBatch.js';
 import { frozenSet } from '../../frozenSet.js';
 import { isCoreWorkflowRunTerminal } from '../../terminalStatuses.js';
 import { envelopeUuidOf, mintEngineRowRef, readBoundRun, wireEventIdOf } from '../../engineRowRef.js';
 function armBody(body) {
     return body;
 }
-const SUGGESTION_BATCH_CAP = 8;
-const SUGGESTION_CHARS_CAP = 200;
 export const INTERNAL_SDK_ARM_TYPES = frozenSet([
     'tool_disclosure',
     'tool_progress',
@@ -72,9 +72,6 @@ function streamEventArm(ctx, event) {
 const projected = (message) => ({ kind: 'message', message });
 const nothing = (why) => ({ kind: 'none', why });
 const dropped = (why, type) => ({ kind: 'dropped', why, type });
-function isCompactionStartedFrame(ev) {
-    return ev.type === 'compaction_started';
-}
 const BEYOND_FLOOR_ARMS = Object.freeze(['cross_boundary_taint', 'approval_complete', 'session_titled']);
 function isBeyondFloorArm(ev) {
     const word = ev.type;
@@ -111,8 +108,6 @@ function withEngineIdentity(p, ev, ctx, identityFrame = ev) {
     return projected(Object.assign({}, env, { uuid: envelopeUuidOf(eventId, env.type), _sema_engine_ref: ref }));
 }
 function projectEvent(ev, ctx) {
-    if (isCompactionStartedFrame(ev))
-        return compactionStartedProjection(ev, ctx);
     if (isBeyondFloorArm(ev)) {
         const word = ev.type;
         if (word === 'cross_boundary_taint')
@@ -127,6 +122,8 @@ function projectEvent(ev, ctx) {
     switch (ev.type) {
         case 'task_started':
             return taskStartedProjection(ev, ctx);
+        case 'compaction_started':
+            return compactionStartedProjection(ev, ctx);
         case 'text_end':
             return textEndProjection(ev, ctx);
         case 'reasoning_end':
@@ -176,6 +173,10 @@ function projectEvent(ev, ctx) {
                 status: wf.status,
                 summary: typeof wf.summary === 'string' ? wf.summary : '',
                 ...workflowCompletionExtrasOf(wf),
+                ...(() => {
+                    const t = resupplyTruncatedOf(wf);
+                    return t === undefined ? {} : { payloadTruncated: { bytes: t.bytes, droppedKeys: [...t.droppedKeys] } };
+                })(),
             })));
         }
         case 'text':
@@ -405,16 +406,13 @@ function projectEvent(ev, ctx) {
             })));
         }
         case 'suggestions': {
-            const filtered = (Array.isArray(ev.suggestions) ? ev.suggestions : []).filter((s) => typeof s === 'string' && s.trim().length > 0);
-            const list = filtered
-                .slice(0, SUGGESTION_BATCH_CAP)
-                .map((s) => (s.length > SUGGESTION_CHARS_CAP ? `${s.slice(0, SUGGESTION_CHARS_CAP)}…` : s));
-            if (list.length === 0)
+            const batch = promptSuggestionBatchOf(ev.suggestions);
+            if (batch === undefined)
                 return nothing('empty_payload');
             return projected(stamp(ctx, armBody({
                 type: 'prompt_suggestions',
-                suggestions: list,
-                ...(filtered.length > list.length ? { truncatedCount: filtered.length - list.length } : {}),
+                suggestions: [...batch.list],
+                ...(batch.truncatedCount !== undefined ? { truncatedCount: batch.truncatedCount } : {}),
             })));
         }
         case 'turn_end':
@@ -955,6 +953,7 @@ function humanInputProjection(ev, ctx) {
         ...(str(ev.parentToolCallId) !== undefined ? { parentToolCallId: str(ev.parentToolCallId) } : {}),
         ...attachmentsKey(humanInputAttachmentsOf(ev)),
         ...humanInputAuthorKeys(ev),
+        ...runOriginKeys(ev),
     })));
 }
 function attachmentsKey(rows) {
@@ -974,3 +973,9 @@ export function turnEndUsage(ev) {
 export function gateKind(gate) {
     return gate?.kind ?? 'human';
 }
+const _pinCompaction = [true, true, true, true, true, true, true, true, true, true, true];
+void _pinCompaction;
+const _pinMods = [true, true, true, true, true, true, true, true, true, true, true, true, true, true, true];
+void _pinMods;
+const _pinPrompt = [true, true, true, true, true, true, true, true, true, true];
+void _pinPrompt;

package/dist/adapter/downstream/terminalToSdkResult.d.ts

@@ -5,6 +5,7 @@ import type { SDKPermissionDenial, SDKResultError, SDKResultSuccess, TerminalRea
 import { type RunTerminalCodedDetail, type RunTerminalRead } from '../../runTerminal.js';
 import { type SemaModelUsage } from './turnUsageToModelUsage.js';
 import { type ResultLimitWord } from '../../engineErrorCodes.js';
+import type { RunCostSettlement } from '../../sessionCostReading.js';
 import { type ResultWayOutFacts } from '../../providerRejection.js';
 export interface SemaFlatUsage {
     readonly inputTokens: number;
@@ -89,6 +90,7 @@ export interface RunCostFacts {
 export declare function readRunCostFacts(stats: TaskStats | undefined, observed?: {
     readonly usageMissingObserved?: boolean;
 }): RunCostFacts | undefined;
+export declare function runCostSettlementOf(stats: TaskStats | undefined): Exclude<RunCostSettlement, 'awaiting'>;
 export interface ObservedTerminalParts extends PermissionDenialParts {
     readonly _sema_usage_lower_bound?: true;
 }

package/dist/adapter/downstream/terminalToSdkResult.js

@@ -261,6 +261,17 @@ export function readRunCostFacts(stats, observed) {
         reconcile,
     };
 }
+export function runCostSettlementOf(stats) {
+    try {
+        const facts = readRunCostFacts(stats);
+        if (facts === undefined)
+            return 'lost';
+        return facts.reconcile.ownMicroUsd !== undefined ? 'priced' : 'unpriced';
+    }
+    catch {
+        return 'lost';
+    }
+}
 function structuredOutputParts(r) {
     const so = r.structuredOutput;
     return so !== undefined ? { structured_output: so } : {};

package/dist/adapter/runStream.d.ts

@@ -5,6 +5,7 @@ import type { ObservedTerminalParts } from './downstream/terminalToSdkResult.js'
 import { type ToolHistoryErrorCarrier } from '../toolHistoryMismatch.js';
 import { MODEL_OUTPUT_ERROR_PREFIX, OUTCOME_UNKNOWN_ROW_PREFIX, RUN_BLOCKED_MESSAGE_PREFIX, RUN_STOPPED_MESSAGE_PREFIX } from '../rowKind.js';
 export { MODEL_OUTPUT_ERROR_PREFIX, OUTCOME_UNKNOWN_ROW_PREFIX, RUN_BLOCKED_MESSAGE_PREFIX, RUN_STOPPED_MESSAGE_PREFIX };
+import { type PlanReviewCardFacts } from '../planReviewCardFacts.js';
 export interface ActiveRunPendingGate {
     readonly kind: string | null;
     readonly decidePath: string | null;
@@ -37,5 +38,9 @@ export interface RunStreamHandle {
     latestUsageMissing?: true;
     observedTerminalParts?: () => ObservedTerminalParts;
 }
+export interface PlanReviewFrameClaim {
+    feed(frame: {} | null | undefined): PlanReviewCardFacts | undefined;
+}
+export declare function openPlanReviewFrameClaim(): PlanReviewFrameClaim;
 export declare function isRunStreamActive(): boolean;
 export declare function runStream(events: AsyncIterable<AgentEvent>, ctx: EmitContext, handle?: RunStreamHandle): AsyncGenerator<SDKMessage>;

package/dist/adapter/runStream.js

@@ -20,7 +20,7 @@ import { MODEL_OUTPUT_ERROR_PREFIX, OUTCOME_UNKNOWN_ROW_PREFIX, RUN_BLOCKED_MESS
 export { MODEL_OUTPUT_ERROR_PREFIX, OUTCOME_UNKNOWN_ROW_PREFIX, RUN_BLOCKED_MESSAGE_PREFIX, RUN_STOPPED_MESSAGE_PREFIX };
 import { ccToolDenialKindForToolEnd, gateDeniedBy, gateOutcomeOf } from '../gateOutcome.js';
 import { resumeReopenContent, resumeReopenFromError, suspendedReopenOf } from '../hitl/suspendedReopen.js';
-import { openPlanBodyClaimLeg, planReviewParkFacts, stepPlanBodyClaim } from '../planReviewCardFacts.js';
+import { openPlanBodyClaimLeg, planReviewClaimStep } from '../planReviewCardFacts.js';
 import { isCcToolDenialKind, isCcToolDenialKindADenial, isGateDeniedByWord } from '../gateVocabulary.js';
 const ENGINE_TURN_USAGE_KEYS = Object.freeze(['inputTokens', 'totalInputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'costMicroUsd']);
 const _engineTurnUsageKeysPin = true;
@@ -454,6 +454,18 @@ function wireFrameIsSubFlow(ev) {
     });
     return snap === undefined || snapshotIsSubFlow(snap);
 }
+export function openPlanReviewFrameClaim() {
+    const leg = openPlanBodyClaimLeg();
+    return Object.freeze({
+        feed(frame) {
+            if (typeof frame !== 'object' || frame === null)
+                return undefined;
+            const subFlow = wireFrameIsSubFlow(frame);
+            const seq = guardedRead(() => eventSeq(frame));
+            return planReviewClaimStep(leg, frame, subFlow, seq);
+        },
+    });
+}
 function withStringFailureFields(ev) {
     if (ev.type !== 'failed')
         return ev;
@@ -592,7 +604,7 @@ async function* runStreamInner(events, ctx, handle = {}) {
             }
             seen.add(seq);
         }
-        stepPlanBodyClaim(planLeg, ev, wireSubFlow);
+        const planReviewAtTerminal = planReviewClaimStep(planLeg, ev, wireSubFlow, seq);
         if (ev.type === 'tool_start') {
             const callId = ev.toolCallId;
             if (typeof callId === 'string' && callId.length > 0 && !toolInputAmbiguous.has(callId)) {
@@ -855,7 +867,7 @@ async function* runStreamInner(events, ctx, handle = {}) {
                     accepted: ev.type === 'done' && (doneTerminal?.kind === 'completed' || doneTerminal?.kind === 'paused'),
                 }).acceptedSinceMismatch;
             }
-            const planReview = ev.type === 'done' ? planReviewParkFacts(planLeg, engineResultOf(ev.result)) : undefined;
+            const planReview = planReviewAtTerminal;
             if (ev.type === 'done' && isReviewPark(doneTerminal) && ctx.emitChrome) {
                 try {
                     await ctx.emitChrome({ kind: 'plan_review_park', laneProof: mainLane(), result: ev.result, ...(planReview !== undefined ? { planReview } : {}) });

package/dist/attachmentRoute.d.ts

@@ -0,0 +1,20 @@
+import type { UiLanguage } from './env/uiLanguage.js';
+export declare const TOOLS_LOCATIONS: readonly ["this-machine", "elsewhere", "unconfirmed"];
+export type ToolsLocation = (typeof TOOLS_LOCATIONS)[number];
+export declare const ATTACHMENT_ROUTE_LEGS: readonly ["at_mention", "edited_file", "paste", "ide_selection"];
+export type AttachmentRouteLeg = (typeof ATTACHMENT_ROUTE_LEGS)[number];
+export interface AttachmentRouteFacts {
+    readonly leg: AttachmentRouteLeg;
+    readonly toolsLocation: ToolsLocation;
+}
+export type AttachmentWithheldReason = 'tools-elsewhere' | 'tools-location-unconfirmed';
+export type AttachmentRoute = {
+    readonly route: 'attach_content';
+    readonly localCopy: boolean;
+} | {
+    readonly route: 'withhold';
+    readonly reason: AttachmentWithheldReason;
+};
+export declare function attachmentRouteOf(facts: AttachmentRouteFacts): AttachmentRoute;
+export declare function attachmentWithheldReasonText(reason: AttachmentWithheldReason, lang?: UiLanguage): string;
+export declare function attachmentLocalCopyNote(): string;

package/dist/attachmentRoute.js

@@ -0,0 +1,39 @@
+import { msg, renderMessage } from './i18n/translate.js';
+import { readOwnDataNonEmptyString } from './ownKey.js';
+export const TOOLS_LOCATIONS = Object.freeze(['this-machine', 'elsewhere', 'unconfirmed']);
+export const ATTACHMENT_ROUTE_LEGS = Object.freeze(['at_mention', 'edited_file', 'paste', 'ide_selection']);
+const _withheldReasonsPinned = true;
+void _withheldReasonsPinned;
+const ATTACH = Object.freeze({ route: 'attach_content', localCopy: false });
+const ATTACH_LOCAL_COPY = Object.freeze({ route: 'attach_content', localCopy: true });
+const WITHHOLD_ELSEWHERE = Object.freeze({ route: 'withhold', reason: 'tools-elsewhere' });
+const WITHHOLD_UNCONFIRMED = Object.freeze({ route: 'withhold', reason: 'tools-location-unconfirmed' });
+const SNAPSHOT_LEGS = new Set(['paste', 'ide_selection']);
+function closedWord(facts, key, words) {
+    try {
+        if (typeof facts !== 'object' || facts === null)
+            return undefined;
+        const raw = readOwnDataNonEmptyString(facts, key);
+        return raw !== undefined && words.includes(raw) ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function attachmentRouteOf(facts) {
+    const where = closedWord(facts, 'toolsLocation', TOOLS_LOCATIONS);
+    if (where === 'this-machine')
+        return ATTACH;
+    const leg = closedWord(facts, 'leg', ATTACHMENT_ROUTE_LEGS);
+    if (leg !== undefined && SNAPSHOT_LEGS.has(leg))
+        return ATTACH_LOCAL_COPY;
+    return where === 'elsewhere' ? WITHHOLD_ELSEWHERE : WITHHOLD_UNCONFIRMED;
+}
+export function attachmentWithheldReasonText(reason, lang) {
+    return reason === 'tools-elsewhere'
+        ? renderMessage(msg('attachments.withheld.toolsElsewhere.row'), lang)
+        : renderMessage(msg('attachments.withheld.toolsLocationUnconfirmed.row'), lang);
+}
+export function attachmentLocalCopyNote() {
+    return renderMessage(msg('attachments.localCopy.model'));
+}

package/dist/attachmentsWireCaps.js

@@ -25,7 +25,7 @@ const OPT_IN_KEYS = [
     'mcpInstructions',
 ];
 const DEFAULT_ON_ONLY_KEYS = ['agentListing', 'skillsListing'];
-const PRODUCT_DEFAULT_KEYS = ['backgroundTasks', 'toolsDelta', 'todoReminder'];
+const PRODUCT_DEFAULT_KEYS = ['backgroundTasks', 'toolsDelta', 'todoReminder', 'mcpInstructions'];
 function productDefaultAttachments() {
     const out = {};
     for (const k of PRODUCT_DEFAULT_KEYS)

package/dist/builtinOutputStyles.d.ts

@@ -0,0 +1,12 @@
+export type BuiltinOutputStyleName = 'default' | 'Proactive' | 'Concise' | 'Explanatory' | 'Learning';
+export interface BuiltinOutputStyle {
+    readonly name: string;
+    readonly source: 'built-in';
+    readonly description: string;
+    readonly keepCodingInstructions: true;
+    readonly prompt: string;
+    readonly turnReminder?: string;
+    readonly waitingTurnReminder?: string;
+}
+export declare const BUILTIN_OUTPUT_STYLES: Readonly<Record<BuiltinOutputStyleName, BuiltinOutputStyle | null>>;
+export declare function builtinOutputStyleOf(name: string): BuiltinOutputStyle | null | undefined;

package/dist/builtinOutputStyles.js

@@ -0,0 +1,147 @@
+const INSIGHTS_SECTION = `
+## Insights
+In order to encourage learning, before and after writing code, always provide brief educational explanations about implementation choices using (with backticks):
+"\`★ Insight ─────────────────────────────────────\`
+[2-3 key educational points]
+\`─────────────────────────────────────────────────\`"
+
+These insights should be included in the conversation, not in the codebase. You should generally focus on interesting insights that are specific to the codebase or the code you just wrote, rather than general programming concepts.`;
+const PROACTIVE_SECTION = `The user chose continuous, autonomous execution. You should:
+
+1. **Execute immediately** — Start implementing right away. Make reasonable assumptions and proceed on low-risk work.
+2. **Minimize interruptions** — Prefer making reasonable assumptions over asking questions for routine decisions.
+3. **Prefer action over planning** — Do not enter plan mode unless the user explicitly asks. When in doubt, start coding.
+4. **Expect course corrections** — The user may provide suggestions or course corrections at any point; treat those as normal input.
+5. **Do not take overly destructive actions** — This is not a license to destroy. Anything that deletes data or modifies shared or production systems still needs explicit user confirmation. If you reach such a decision point, ask and wait, or course correct to a safer method instead.
+6. **Avoid data exfiltration** — Post even routine messages to chat platforms or work tickets only if the user has directed you to. You must not share secrets (e.g. credentials, internal documentation) unless the user has explicitly authorized both that specific secret and its destination.`;
+const CONCISE_SECTION = `The user chose brevity over narration. You should:
+
+1. **Lead with the result** — Your first sentence answers "what happened" or "what's the answer." No preamble ("Let me...", "Now I'll...") and no closing recap of what you already said.
+2. **Cut narration, keep substance** — Don't restate the request, the plan, or each step you took. Report outcomes, decisions, and anything the user must act on.
+3. **Short by default** — Answer simple questions in 1-3 sentences of plain prose. Use headers, tables, and bullet lists only when they carry real structure, never as decoration.
+4. **State things plainly** — Skip hedging boilerplate. Mention a caveat only when it changes what the user should do next.
+5. **Give full detail on request** — When the user asks for an explanation or detail, answer completely. Conciseness never means withholding requested information.
+6. **Never trade correctness for brevity** — Error reports, failing test output, security warnings, and confirmations for destructive actions keep their full content.
+
+Where these rules conflict with more general communication or formatting guidance elsewhere in your instructions, these rules win.`;
+export const BUILTIN_OUTPUT_STYLES = Object.freeze({
+    default: null,
+    Proactive: Object.freeze({
+        name: 'Proactive',
+        source: 'built-in',
+        description: "Sema executes immediately, minimizes interruptions, and prefers action over planning",
+        keepCodingInstructions: true,
+        prompt: `You are an interactive CLI tool that helps users with software engineering tasks. You should work proactively and autonomously, executing immediately and minimizing interruptions.
+
+# Proactive Style Active
+${PROACTIVE_SECTION}`,
+        turnReminder: "Execute autonomously, minimize interruptions, prefer action over planning.",
+        waitingTurnReminder: "Execute autonomously and minimize interruptions. If the only work left is waiting for a background task or monitor you started, end your turn now: you will be notified when it finishes or fires. Do not poll, sleep, or re-read its output while you wait.",
+    }),
+    Concise: Object.freeze({
+        name: 'Concise',
+        source: 'built-in',
+        description: "Sema responds tersely, leading with results and skipping preamble and narration",
+        keepCodingInstructions: true,
+        prompt: `You are an interactive CLI tool that helps users with software engineering tasks. Keep your responses short and direct while doing the work just as thoroughly.
+
+# Concise Style Active
+${CONCISE_SECTION}`,
+        turnReminder: "Be concise: lead with the result, skip preamble and narration, keep only what the user needs.",
+    }),
+    Explanatory: Object.freeze({
+        name: 'Explanatory',
+        source: 'built-in',
+        description: "Sema explains its implementation choices and codebase patterns",
+        keepCodingInstructions: true,
+        prompt: `You are an interactive CLI tool that helps users with software engineering tasks. In addition to software engineering tasks, you should provide educational insights about the codebase along the way.
+
+You should be clear and educational, providing helpful explanations while remaining focused on the task. Balance educational content with task completion. When providing insights, you may exceed typical length constraints, but remain focused and relevant.
+
+# Explanatory Style Active
+${INSIGHTS_SECTION}`,
+    }),
+    Learning: Object.freeze({
+        name: 'Learning',
+        source: 'built-in',
+        description: "Sema pauses and asks you to write small pieces of code for hands-on practice",
+        keepCodingInstructions: true,
+        prompt: `You are an interactive CLI tool that helps users with software engineering tasks. In addition to software engineering tasks, you should help users learn more about the codebase through hands-on practice and educational insights.
+
+You should be collaborative and encouraging. Balance task completion with learning by requesting user input for meaningful design decisions while handling routine implementation yourself.   
+
+# Learning Style Active
+## Requesting Human Contributions
+In order to encourage learning, ask the human to contribute 2-10 line code pieces when generating 20+ lines involving:
+- Design decisions (error handling, data structures)
+- Business logic with multiple valid approaches  
+- Key algorithms or interface definitions
+
+**TodoList Integration**: If using a TodoList for the overall task, include a specific todo item like "Request human input on [specific decision]" when planning to request human input. This ensures proper task tracking. Note: TodoList is not required for all tasks.
+
+Example TodoList flow:
+   ✓ "Set up component structure with placeholder for logic"
+   ✓ "Request human collaboration on decision logic implementation"
+   ✓ "Integrate contribution and complete feature"
+
+### Request Format
+\`\`\`
+● **Learn by Doing**
+**Context:** [what's built and why this decision matters]
+**Your Task:** [specific function/section in file, mention file and TODO(human) but do not include line numbers]
+**Guidance:** [trade-offs and constraints to consider]
+\`\`\`
+
+### Key Guidelines
+- Frame contributions as valuable design decisions, not busy work
+- You must first add a TODO(human) section into the codebase with your editing tools before making the Learn by Doing request      
+- Make sure there is one and only one TODO(human) section in the code
+- Don't take any action or output anything after the Learn by Doing request. Wait for human implementation before proceeding.
+
+### Example Requests
+
+**Whole Function Example:**
+\`\`\`
+● **Learn by Doing**
+
+**Context:** I've set up the hint feature UI with a button that triggers the hint system. The infrastructure is ready: when clicked, it calls selectHintCell() to determine which cell to hint, then highlights that cell with a yellow background and shows possible values. The hint system needs to decide which empty cell would be most helpful to reveal to the user.
+
+**Your Task:** In sudoku.js, implement the selectHintCell(board) function. Look for TODO(human). This function should analyze the board and return {row, col} for the best cell to hint, or null if the puzzle is complete.
+
+**Guidance:** Consider multiple strategies: prioritize cells with only one possible value (naked singles), or cells that appear in rows/columns/boxes with many filled cells. You could also consider a balanced approach that helps without making it too easy. The board parameter is a 9x9 array where 0 represents empty cells.
+\`\`\`
+
+**Partial Function Example:**
+\`\`\`
+● **Learn by Doing**
+
+**Context:** I've built a file upload component that validates files before accepting them. The main validation logic is complete, but it needs specific handling for different file type categories in the switch statement.
+
+**Your Task:** In upload.js, inside the validateFile() function's switch statement, implement the 'case "document":' branch. Look for TODO(human). This should validate document files (pdf, doc, docx).
+
+**Guidance:** Consider checking file size limits (maybe 10MB for documents?), validating the file extension matches the MIME type, and returning {valid: boolean, error?: string}. The file object has properties: name, size, type.
+\`\`\`
+
+**Debugging Example:**
+\`\`\`
+● **Learn by Doing**
+
+**Context:** The user reported that number inputs aren't working correctly in the calculator. I've identified the handleInput() function as the likely source, but need to understand what values are being processed.
+
+**Your Task:** In calculator.js, inside the handleInput() function, add 2-3 console.log statements after the TODO(human) comment to help debug why number inputs fail.
+
+**Guidance:** Consider logging: the raw input value, the parsed result, and any validation state. This will help us understand where the conversion breaks.
+\`\`\`
+
+### After Contributions
+Share one insight connecting their code to broader patterns or system effects. Avoid praise or repetition.
+
+## Insights
+${INSIGHTS_SECTION}`,
+    }),
+});
+export function builtinOutputStyleOf(name) {
+    if (typeof name !== 'string' || !Object.hasOwn(BUILTIN_OUTPUT_STYLES, name))
+        return undefined;
+    return BUILTIN_OUTPUT_STYLES[name];
+}

package/dist/compactionStatus.d.ts

@@ -1,6 +1,8 @@
+import type { UiLanguage } from './env/uiLanguage.js';
 export interface CompactionStatusReading {
     readonly compacting: boolean;
     readonly since?: number;
+    readonly openTriggers?: readonly string[];
 }
 export type CompactionStatusChange = {
     readonly kind: 'opened';
@@ -32,3 +34,10 @@ export interface PrintCompactionStatusCtx {
 }
 export declare function createCompactionStatusTracker(): CompactionStatusTracker;
 export declare function compactionStatusFrameOf(change: CompactionStatusChange | null | undefined, ctx: PrintCompactionStatusCtx): PrintCompactionStatusFrame | null;
+export type CompactionStopVerdict = {
+    readonly kind: 'compaction_canceled';
+} | {
+    readonly kind: 'interrupted';
+};
+export declare function compactionStopVerdict(reading: CompactionStatusReading | null | undefined): CompactionStopVerdict;
+export declare function compactionCanceledSentence(lang?: UiLanguage): string;

package/dist/compactionStatus.js

@@ -1,4 +1,5 @@
-import { readOwnDataValue } from './ownKey.js';
+import { msg, renderMessage } from './i18n/translate.js';
+import { appendOwnElement, readOwnDataValue } from './ownKey.js';
 import { snapshotIsSubFlow, snapshotSegmentIdentity } from './adapter/types.js';
 const _printStatusFramePins = [true, true];
 void _printStatusFramePins;
@@ -20,9 +21,10 @@ function armLane(m) {
 function openOf(pass, lane, startedAt, trigger) {
     if (lane === 'unreadable')
         return null;
-    if (nonEmpty(trigger) === undefined)
+    const t = nonEmpty(trigger);
+    if (t === undefined)
         return null;
-    return { kind: 'open', pass, main: lane === 'main', ...(typeof startedAt === 'number' && Number.isFinite(startedAt) ? { startedAt } : {}) };
+    return { kind: 'open', pass, main: lane === 'main', trigger: t, ...(typeof startedAt === 'number' && Number.isFinite(startedAt) ? { startedAt } : {}) };
 }
 function parse(input) {
     const plane = own(input, 'plane');
@@ -101,7 +103,11 @@ export function createCompactionStatusTracker() {
         if (mainOpen() === 0)
             return { compacting: false };
         const s = since();
-        return { compacting: true, ...(s !== undefined ? { since: s } : {}) };
+        const triggers = [];
+        for (const e of open.values())
+            if (e.main)
+                appendOwnElement(triggers, e.trigger);
+        return { compacting: true, ...(s !== undefined ? { since: s } : {}), openTriggers: Object.freeze(triggers) };
     };
     return {
         take(input) {
@@ -115,7 +121,7 @@ export function createCompactionStatusTracker() {
                     if (open.has(p.pass) || closed.has(p.pass))
                         return null;
                     const before = mainOpen();
-                    open.set(p.pass, { main: p.main === true, ...(p.startedAt !== undefined ? { startedAt: p.startedAt } : {}) });
+                    open.set(p.pass, { main: p.main === true, trigger: p.trigger ?? '', ...(p.startedAt !== undefined ? { startedAt: p.startedAt } : {}) });
                     if (before === 0 && p.main === true) {
                         const s = since();
                         return { kind: 'opened', pass: p.pass, ...(s !== undefined ? { since: s } : {}) };
@@ -194,3 +200,21 @@ export function compactionStatusFrameOf(change, ctx) {
         return null;
     }
 }
+const STOP_CANCELED = Object.freeze({ kind: 'compaction_canceled' });
+const STOP_INTERRUPTED = Object.freeze({ kind: 'interrupted' });
+export function compactionStopVerdict(reading) {
+    try {
+        if (own(reading, 'compacting') !== true)
+            return STOP_INTERRUPTED;
+        const triggers = own(reading, 'openTriggers');
+        if (!Array.isArray(triggers) || own(triggers, 'length') !== 1)
+            return STOP_INTERRUPTED;
+        return own(triggers, '0') === 'manual' ? STOP_CANCELED : STOP_INTERRUPTED;
+    }
+    catch {
+        return STOP_INTERRUPTED;
+    }
+}
+export function compactionCanceledSentence(lang) {
+    return renderMessage(msg('session.compaction.canceled'), lang);
+}

package/dist/controlRouter.js

@@ -1,4 +1,5 @@
 import { cancelConflictContent, cancelConflictFromError } from './wireRefusalCopy.js';
+import { STEERING_NOT_RUNNING } from './engineErrorCodes.js';
 import { PROTOCOL_ERROR_NAME, THROWN_SLOT_UNREADABLE, protocolErrorNameOf, readThrownSlot, readThrownStatusSlot } from './wireFailureShape.js';
 import { steerPriorityMode } from './steerPriorityCapability.js';
 import { preemptReadingOfAck, preemptReadingOfError } from './preemptWire.js';
@@ -166,7 +167,7 @@ export function errCodes(e) {
     return { code, name, status };
 }
 const STEERING_CODE_TO_SAFETY = new Map([
-    ['steering.not_running', 'not_running'],
+    [STEERING_NOT_RUNNING, 'not_running'],
     ['steering.invalid_content', 'invalid_content'],
     ['steering.queue_full', 'queue_full'],
     ['steering.duplicate_input_id', 'duplicate_input_id'],

package/dist/coreValuePorts.d.ts

@@ -154,6 +154,40 @@ export interface CoreValuePorts {
     runParkedOf(run: WorkflowRunParkedInputView): boolean;
     parkedAgentsOf(agents: ReadonlyArray<WorkflowAgentStatusView>): WorkflowAgentStatusView[];
     modelFaceResolvable(face: object, options?: ModelFaceOptionsView): ModelFaceVerdictView;
+    accountRowOfResult(result: {
+        readonly stats: AccountRowStatsView;
+    }): AccountRowView;
+    foldAccount(rows: Iterable<AccountRowView>): SessionAccountView;
+}
+export interface AccountRowView {
+    origin: 'run' | 'side_query';
+    tokens: number;
+    costMicroUsd?: number;
+    usageMissing?: true;
+}
+export interface AccountTotalView {
+    rows: number;
+    tokens: number;
+    costMicroUsd?: number;
+    usageMissing?: true;
+}
+export interface SessionAccountView extends AccountTotalView {
+    byOrigin: {
+        readonly run: AccountTotalView;
+        readonly side_query: AccountTotalView;
+    };
+}
+export interface AccountRowStatsView {
+    readonly tokens: number;
+    readonly costMicroUsd?: number;
+    readonly usageMissing?: true;
+    readonly nested?: AccountRowNestedStatsView;
+}
+export interface AccountRowNestedStatsView {
+    readonly tokens: number;
+    readonly turns: number;
+    readonly tasks: number;
+    readonly costMicroUsd?: number;
 }
 export interface WorkflowAgentStatusView {
     readonly status: string;
@@ -176,7 +210,7 @@ export type ModelFaceVerdictView = {
     readonly role: string;
     readonly code: string;
 };
-export declare const CORE_VALUE_PORT_NAMES: readonly ["resolveAutonomousLoopPrompt", "loosenReasons", "combinePolicies", "createAllowDenyPolicy", "MCP_NAMESPACE", "protocolOf", "ruleToolGrammarOf", "validatePermissionRules", "mintNamespacePrefix", "compileAllowList", "routeKeyOf", "joinRequestUrl", "resolveRouteCredential", "adjudicateModelRoute", "routePairingStatus", "judgeRuleToolName", "readRuleEntry", "readMcpToolAxes", "ANTHROPIC_DEFAULT_BASE_URL", "readToolFaces", "ruleNameCovers", "IMPORTED_SETTINGS_LAYERS", "runParkedOf", "parkedAgentsOf", "modelFaceResolvable"];
+export declare const CORE_VALUE_PORT_NAMES: readonly ["resolveAutonomousLoopPrompt", "loosenReasons", "combinePolicies", "createAllowDenyPolicy", "MCP_NAMESPACE", "protocolOf", "ruleToolGrammarOf", "validatePermissionRules", "mintNamespacePrefix", "compileAllowList", "routeKeyOf", "joinRequestUrl", "resolveRouteCredential", "adjudicateModelRoute", "routePairingStatus", "judgeRuleToolName", "readRuleEntry", "readMcpToolAxes", "ANTHROPIC_DEFAULT_BASE_URL", "readToolFaces", "ruleNameCovers", "IMPORTED_SETTINGS_LAYERS", "runParkedOf", "parkedAgentsOf", "modelFaceResolvable", "accountRowOfResult", "foldAccount"];
 export type CoreValuePortName = (typeof CORE_VALUE_PORT_NAMES)[number];
 export declare function installCoreValuePorts(ports: Partial<CoreValuePorts> | null): () => void;
 export declare function hasCoreValuePorts(): boolean;
@@ -211,3 +245,7 @@ export declare function importedSettingsLayers(): CoreValuePorts['IMPORTED_SETTI
 export declare function runParkedOf(run: WorkflowRunParkedInputView): boolean | undefined;
 export declare function parkedAgentsOf(agents: ReadonlyArray<WorkflowAgentStatusView>): WorkflowAgentStatusView[] | undefined;
 export declare function modelFaceResolvable(face: object, options?: ModelFaceOptionsView): ModelFaceVerdictView | undefined;
+export declare function accountRowOfResult(result: {
+    readonly stats: AccountRowStatsView;
+}): AccountRowView | undefined;
+export declare function foldAccount(rows: Iterable<AccountRowView>): SessionAccountView | undefined;

package/dist/coreValuePorts.js

@@ -24,6 +24,8 @@ export const CORE_VALUE_PORT_NAMES = Object.freeze([
     'runParkedOf',
     'parkedAgentsOf',
     'modelFaceResolvable',
+    'accountRowOfResult',
+    'foldAccount',
 ]);
 let installed = null;
 export function installCoreValuePorts(ports) {
@@ -142,3 +144,11 @@ export function modelFaceResolvable(face, options) {
     const fn = port('modelFaceResolvable');
     return fn === undefined ? undefined : fn(face, options);
 }
+export function accountRowOfResult(result) {
+    const fn = port('accountRowOfResult');
+    return fn === undefined ? undefined : fn(result);
+}
+export function foldAccount(rows) {
+    const fn = port('foldAccount');
+    return fn === undefined ? undefined : fn(rows);
+}

package/dist/declared/supportFloorDeclared.js

@@ -1,5 +1,5 @@
 export const DECLARED_SUPPORT_FLOOR = Object.freeze({
     server: "7.139.0",
     core: "7.60.0",
-    sdk: "23.1.0",
+    sdk: "25.0.0",
 });

package/dist/displayUntrusted.d.ts

@@ -51,6 +51,7 @@ export declare function capDisplay(text: string, max: number | undefined, mark:
 export declare function paintAndCap(text: string, face: DisplayFace, max?: number): string;
 export declare function credentialWashPasses(text: string, opts?: DisplayUntrustedOptions | null): Readonly<WashStats>;
 export declare function displayUntrusted(text: string, opts?: DisplayUntrustedOptions): string;
+export declare function displayUntrustedCapped(text: string, max: number, opts?: DisplayUntrustedOptions): string;
 export declare function cleanUntrustedScalar(v: string | number | bigint | boolean | null | undefined): string;
 export declare function queryCarriesCredential(query: string): boolean;
 export declare function displayConfiguredUrl(url: string, opts?: DisplayUntrustedOptions): string;