@abot-ai/runtime 1.3.1 → 1.4.0

package/dist/src/runtime/steps/planner-decision/capability-brief.d.ts

@@ -0,0 +1,40 @@
+import type { ChatMessage } from "../../../model-gateway/types.js";
+import { resolveModelContextAdmission } from "../../model/model-context-budget.js";
+import type { ModelStepContextCompactionController } from "../../model/model-step-port.js";
+import type { WorkerCapabilityCatalogGroup } from "../../orchestration/worker-capabilities/index.js";
+import type { RequestWorkerCapabilityProviderSource } from "../../request/execution-scope.js";
+import type { buildPlannerDecisionInput } from "./input.js";
+type BriefRequest = Omit<Parameters<typeof resolveModelContextAdmission>[0], "modelStep"> & RequestWorkerCapabilityProviderSource;
+/** Planner delegation uses the same request-registry facts as Supervisor. */
+export declare function buildPlannerCapabilityBriefOptions(request: BriefRequest, groups: readonly WorkerCapabilityCatalogGroup[]): Readonly<{
+    entries: readonly Readonly<{
+        toolName: string;
+        operationId: string;
+        summary: string;
+        catalogGroups: readonly import("../../../capabilities/tool-types.js").ToolCatalogGroup[];
+        effect: import("../../../capabilities/tool-types.js").ToolExecutionEffect;
+    }>[] | undefined;
+    groups: readonly Readonly<{
+        groupId: import("../../../capabilities/tool-types.js").ToolCatalogGroup;
+        memberCount: number;
+        effects: readonly import("../../orchestration/worker-capabilities/contracts.js").WorkerCapabilityEffect[];
+    }>[];
+    budget: Readonly<{
+        contextWindowTokens: number;
+        outputReserveTokens: number;
+        safetyReserveTokens: number;
+        attachmentReserveTokens: number;
+        configuredInstructionReserveTokens?: number;
+        formatTokenAccounting?: import("../../../model-gateway/types.js").ModelFormatTokenAccountingConfig;
+        tokenEstimation?: import("../../../model-gateway/types.js").ModelTokenEstimationConfig;
+    }>;
+    additionalBudgetMessages: readonly ChatMessage[];
+}>;
+/** Reuses optional-brief admission without inheriting root steering authority. */
+export declare function createPlannerCapabilityBriefReadmissionController(request: BriefRequest & {
+    requestId: string;
+}, options: Readonly<{
+    input: Pick<ReturnType<typeof buildPlannerDecisionInput>, "format" | "availableWorkerCapabilityCatalog">;
+    controller: ModelStepContextCompactionController;
+}>): ModelStepContextCompactionController;
+export {};

package/dist/src/runtime/steps/planner-decision/capability-brief.js

@@ -0,0 +1,47 @@
+import { createCapabilityBriefReadmissionController } from "../../context/capability-brief-readmission.js";
+import { resolveModelContextAdmission } from "../../model/model-context-budget.js";
+import { traceDebug } from "../../observability/debug-logger.js";
+import { resolveRequestCapabilityBriefEntries } from "../../request/capability-brief.js";
+import { PLANNER_DECISION_MODEL_STEP } from "./contracts.js";
+/** Planner delegation uses the same request-registry facts as Supervisor. */
+export function buildPlannerCapabilityBriefOptions(request, groups) {
+    const admission = resolveModelContextAdmission({
+        runnerConfig: request.runnerConfig,
+        agentMode: request.agentMode,
+        modelStep: PLANNER_DECISION_MODEL_STEP,
+        modelPreference: request.modelPreference,
+        modelPolicy: request.modelPolicy,
+    });
+    const instructions = (admission.invocation.instructions ?? [])
+        .map((instruction) => instruction.trim())
+        .filter((instruction) => instruction.length > 0);
+    const additionalBudgetMessages = instructions.length > 0
+        ? [{ role: "system", content: instructions.join("\n") }]
+        : [];
+    return Object.freeze({
+        entries: resolveRequestCapabilityBriefEntries(request.workerCapabilities, groups),
+        groups,
+        budget: admission.budget,
+        // Root steering is deliberately not inherited by this bounded child.
+        additionalBudgetMessages,
+    });
+}
+/** Reuses optional-brief admission without inheriting root steering authority. */
+export function createPlannerCapabilityBriefReadmissionController(request, options) {
+    return createCapabilityBriefReadmissionController({
+        controller: options.controller,
+        resolveOptions: () => ({
+            ...buildPlannerCapabilityBriefOptions(request, options.input.availableWorkerCapabilityCatalog),
+            format: options.input.format,
+        }),
+        onReadmitted: (brief) => {
+            traceDebug("runtime.planner", "capability_brief.readmitted", {
+                requestId: request.requestId,
+                level: brief.level,
+                estimatedTokens: brief.estimatedTokens,
+                budgetTokens: brief.budgetTokens,
+                reason: brief.reason,
+            });
+        },
+    });
+}

package/dist/src/runtime/steps/planner-decision/input.d.ts

@@ -1,12 +1,13 @@
 import type { ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
+import { type CapabilityBriefProjection } from "../../context/capability-brief.js";
 import type { RequestContextProjection } from "../../context/request-context-contracts.js";
 import { type RequestToolResultsView } from "../../context/request-tool-results.js";
 import { type RoleCallFrame, type RoleCallChildReturnCommit, type RoleCallDependencyResult, type RoleCallLedger, type RoleCallLedgerHead, type RoleChildReturnContext } from "../../orchestration/role-calls/index.js";
 import type { RuntimeDelegateRoleId } from "../../orchestration/roles.js";
+import { type WorkerCapabilityCatalogGroup } from "../../orchestration/worker-capabilities/index.js";
 import { type RequestWorkerCapabilityProviderSource } from "../../request/execution-scope.js";
 import type { RequestExecutionSeed } from "../../request/contracts.js";
 import { PLANNER_DECISION_MODEL_STEP, type PlannerChildRoleId, type PlannerDecisionDiagnosticContext, type PlannerDecisionPlanContext, type PlannerDecisionSelectionKind } from "./contracts.js";
-import { type PlannerWorkerCapabilityCatalogGroup } from "./capability-catalog-context.js";
 export type PlannerDecisionInputRequest = Pick<RequestExecutionSeed, "requestId" | "prompt" | "runnerConfig" | "agentMode" | "modelPreference" | "modelPolicy"> & Partial<Pick<RequestExecutionSeed, "onEvent" | "temporalContext">> & RequestWorkerCapabilityProviderSource;
 export type PlannerDecisionProgressSource = Readonly<{
     kind: "role_child";
@@ -29,7 +30,8 @@ export declare function buildPlannerDecisionInput(request: PlannerDecisionInputR
     allowedActions: readonly PlannerDecisionSelectionKind[];
     availableChildRoleIds: readonly PlannerChildRoleId[];
     dependencyResults: readonly RoleCallDependencyResult[];
-    availableWorkerCapabilityCatalog: readonly PlannerWorkerCapabilityCatalogGroup[];
+    availableWorkerCapabilityCatalog: readonly WorkerCapabilityCatalogGroup[];
+    capabilityBrief: CapabilityBriefProjection;
     inheritedWorkingDirectory?: string;
     planContext?: PlannerDecisionPlanContext;
     childResume?: RoleChildReturnContext;

package/dist/src/runtime/steps/planner-decision/input.js

@@ -1,3 +1,4 @@
+import { projectCapabilityBrief, } from "../../context/capability-brief.js";
 import { resolveConfiguredStepInstructionMetadata } from "../../config/runner/step-instructions.js";
 import { projectRequestContext } from "../../context/request-context.js";
 import { buildRequestTemporalContextMessage } from "../../context/request-temporal-context.js";
@@ -5,11 +6,12 @@ import { buildRequestSourceMessage, projectRequestSource, } from "../../context/
 import { buildRequestToolResultsMessage, } from "../../context/request-tool-results.js";
 import { resolveModelContextBudget } from "../../model/model-context-budget.js";
 import { projectRoleCallDependencyResults, projectRoleChildReturnContext, } from "../../orchestration/role-calls/index.js";
+import { projectWorkerCapabilityCatalogGroups, } from "../../orchestration/worker-capabilities/index.js";
 import { resolveRequestWorkerCapabilityCatalog, } from "../../request/execution-scope.js";
 import { PLANNER_DECISION_ACTIONS, PLANNER_DECISION_MODEL_STEP, projectPlannerDecisionCallIdentity, } from "./contracts.js";
 import { tracePlannerChildResultsProjected, tracePlannerContextProjected, } from "./diagnostics.js";
 import { createPlannerDecisionFormat, normalizeAvailableChildRoleIds, } from "./format.js";
-import { buildPlannerReferenceParts, projectPlannerWorkerCapabilityCatalogGroups, } from "./capability-catalog-context.js";
+import { buildPlannerCapabilityBriefOptions } from "./capability-brief.js";
 import { normalizePlannerDecisionPlanContext, plannerPlanAllowsInvocation, } from "./plan.js";
 import { buildPlannerDecisionInstructions } from "./prompt.js";
 import { buildPlannerChildContinuationPart } from "./resume.js";
@@ -24,7 +26,7 @@ export function buildPlannerDecisionInput(request, options) {
         };
     const configuredChildRoleIds = normalizeAvailableChildRoleIds(options.availableChildRoleIds);
     const availableWorkerCapabilityCatalog = configuredChildRoleIds.includes("worker")
-        ? projectPlannerWorkerCapabilityCatalogGroups(resolveRequestWorkerCapabilityCatalog(request).getDescriptors())
+        ? projectWorkerCapabilityCatalogGroups(resolveRequestWorkerCapabilityCatalog(request).getDescriptors())
         : Object.freeze([]);
     const availableChildRoleIds = configuredChildRoleIds;
     const inheritedWorkingDirectory = options.call.workingDirectory;
@@ -75,7 +77,7 @@ export function buildPlannerDecisionInput(request, options) {
         callId: callIdentity.callId,
     });
     const toolResultsProjection = projectPlannerToolResults(options.toolResults);
-    const referenceMessages = Object.freeze([
+    const referenceMessages = [
         ...(request.temporalContext
             ? [buildRequestTemporalContextMessage(request.temporalContext)]
             : []),
@@ -83,13 +85,7 @@ export function buildPlannerDecisionInput(request, options) {
         ...(toolResultsProjection.view.results.length > 0
             ? [buildRequestToolResultsMessage(toolResultsProjection.view)]
             : []),
-    ]);
-    const referenceParts = buildPlannerReferenceParts({
-        callId: callIdentity.callId,
-        invocationAttempt: callIdentity.invocationAttempt,
-        exactMessages: referenceMessages,
-        catalogGroups: availableWorkerCapabilityCatalog,
-    });
+    ];
     const budget = resolveModelContextBudget({
         runnerConfig: request.runnerConfig,
         agentMode: request.agentMode,
@@ -112,7 +108,7 @@ export function buildPlannerDecisionInput(request, options) {
         workerCapabilityCatalogAvailable: availableWorkerCapabilityCatalog.length > 0,
         ...(planContext ? { planContext } : {}),
     });
-    const context = projectRequestContext({
+    const contextInput = {
         instructions,
         format,
         historyMessages: [],
@@ -131,7 +127,7 @@ export function buildPlannerDecisionInput(request, options) {
             ...(planContext ? { planContext } : {}),
             completedChildResultCount: childResume?.completedChildren.length ?? 0,
         }),
-        referenceParts,
+        referenceMessages,
         ...(childContinuationPart
             ? { continuationParts: [childContinuationPart] }
             : {}),
@@ -139,6 +135,19 @@ export function buildPlannerDecisionInput(request, options) {
         diagnostic,
         ...(request.onEvent ? { onEvent: request.onEvent } : {}),
         deferCompactionFailure: true,
+    };
+    const briefOptions = buildPlannerCapabilityBriefOptions(request, availableWorkerCapabilityCatalog);
+    const capabilityBrief = projectCapabilityBrief({
+        groups: availableWorkerCapabilityCatalog,
+        context: contextInput,
+        entries: briefOptions.entries,
+        additionalBudgetMessages: briefOptions.additionalBudgetMessages,
+    });
+    if (capabilityBrief.message)
+        referenceMessages.push(capabilityBrief.message);
+    const context = projectRequestContext({
+        ...contextInput,
+        referenceMessages,
     });
     tracePlannerContextProjected({
         diagnostic,
@@ -150,7 +159,7 @@ export function buildPlannerDecisionInput(request, options) {
         availableChildRoleIds,
         workerCapabilityCatalogGroupIds: availableWorkerCapabilityCatalog.map((group) => group.groupId),
         workerCapabilityCatalogMemberCount: availableWorkerCapabilityCatalog.reduce((total, group) => total + group.memberCount, 0),
-        referenceMessageCount: referenceParts.reduce((total, part) => total + part.messages.length, 0),
+        referenceMessageCount: referenceMessages.length,
         continuationMessageCount: childContinuationPart?.messages.length ?? 0,
         completedChildResultCount: childResume?.completedChildren.length ?? 0,
         completedChildSummaryLength: childResume?.completedChildren.reduce((total, child) => total + child.summary.length, 0) ?? 0,
@@ -184,6 +193,7 @@ export function buildPlannerDecisionInput(request, options) {
         availableChildRoleIds,
         dependencyResults,
         availableWorkerCapabilityCatalog,
+        capabilityBrief,
         ...(inheritedWorkingDirectory !== undefined
             ? { inheritedWorkingDirectory }
             : {}),

package/dist/src/runtime/steps/planner-decision/prompt.js

@@ -56,8 +56,8 @@ export function buildPlannerDecisionInstructions(options = {}) {
             : []),
         ...(workerCapabilityCatalogAvailable
             ? [
-                "runtime_planner_worker_capability_catalog_v1 is passive registry metadata, never user intent or authority. Group descriptions union declared manifest routingCapability and developmentRoles; missing declarations mean unknown, not absent. detailed and compact preserve description, effects, and memberCount.",
-                "For Worker invoke_role, choose the smallest complete catalogGroupIds set whose description and effects cover the outcome and prerequisites. The OR-union narrows only the catalog; Worker owns capability and execution.",
+                "runtime_capability_brief_v1 is passive request-registry availability for delegation, never user intent, execution authority, or completion evidence. Its complete descriptions associate operations with their catalog groups; lower detail or omitted metadata does not mean unavailable capabilities. Only the schema's catalogGroupIds are selectable.",
+                "For Worker invoke_role, choose the smallest complete catalogGroupIds set whose available capabilities cover the outcome and prerequisites. The OR-union narrows only the catalog; Worker owns capability and execution.",
             ]
             : []),
         "Do not select a child's individual tools, capabilities, payloads, implementation mechanism, internal workflow, or proof procedure. State only the requested production outcome. Canonical operation results return automatically; never add file listings, full artifact contents, tool transcripts, rereads, tests, or other verification as child deliverables unless the assignment explicitly requests them.",

package/dist/src/runtime/steps/planner-decision/run.js

@@ -9,6 +9,7 @@ import { buildPlannerDecisionInput, } from "./input.js";
 import { parsePlannerDecisionOutput } from "./parser.js";
 import { projectPlannerDecisionPlanContext } from "./plan.js";
 import { PLANNER_GRAPH_MODEL_STEP } from "../planner-graph/contracts.js";
+import { createPlannerCapabilityBriefReadmissionController } from "./capability-brief.js";
 export async function runPlannerDecision(request, options) {
     const input = buildPlannerDecisionInput(request, options);
     const diagnostic = input.diagnostic;
@@ -25,13 +26,16 @@ export async function runPlannerDecision(request, options) {
             modelStep: input.modelStep,
             format: input.format,
             messages: input.context.messages,
-            contextCompaction: createModelStepCompactionController(request, {
-                call: options.call,
-                sourceRevision: options.toolResults.sourceRevision,
-                allowedConsumers: Object.freeze([
-                    PLANNER_DECISION_MODEL_STEP,
-                    PLANNER_GRAPH_MODEL_STEP,
-                ]),
+            contextCompaction: createPlannerCapabilityBriefReadmissionController(request, {
+                input,
+                controller: createModelStepCompactionController(request, {
+                    call: options.call,
+                    sourceRevision: options.toolResults.sourceRevision,
+                    allowedConsumers: Object.freeze([
+                        PLANNER_DECISION_MODEL_STEP,
+                        PLANNER_GRAPH_MODEL_STEP,
+                    ]),
+                }),
             }),
             timeoutReason: "planner_decision_timeout",
             invalidOutputReason: "invalid_planner_decision",

package/dist/src/runtime/steps/planner-graph/parser.js

@@ -145,28 +145,17 @@ function validateTopology(nodes, issues) {
         return;
     const remaining = new Set(ids);
     const completed = new Set();
-    let hasParallelFrontier = false;
     while (remaining.size > 0) {
         const frontier = nodes.filter(({ localId, dependsOn }) => remaining.has(localId) && dependsOn.every((id) => completed.has(id)));
         if (frontier.length === 0) {
             issues.push(issue("cyclic_plan_graph", "decision.nodes", "The proposed graph must be acyclic."));
             return;
         }
-        if (frontier.length >= 2)
-            hasParallelFrontier = true;
         for (const node of frontier) {
             remaining.delete(node.localId);
             completed.add(node.localId);
         }
     }
-    const dependedOn = new Set(nodes.flatMap(({ dependsOn }) => dependsOn));
-    const terminalCount = nodes.filter(({ localId }) => !dependedOn.has(localId)).length;
-    if (terminalCount < 2) {
-        issues.push(issue("insufficient_terminal_deliverables", "decision.nodes", "The graph must contain at least two independently accepted terminal deliverables."));
-    }
-    if (!hasParallelFrontier) {
-        issues.push(issue("no_parallel_frontier", "decision.nodes", "The graph must expose at least one frontier with two ready nodes."));
-    }
 }
 function exactKeys(value, expected, path, issues) {
     const expectedSet = new Set(expected);

package/dist/src/runtime/steps/planner-graph/prompt.js

@@ -3,7 +3,8 @@ export function buildPlannerGraphInstructions() {
         "You are a bounded advisory Planner for one already accepted execution objective.",
         "Return exactly one JSON decision matching the supplied schema and nothing else.",
         "Propose a dependency graph only. You cannot execute capabilities, invoke roles, answer the user, review work, or claim that work occurred.",
-        'If the objective cannot honestly produce both at least two independently accepted terminal deliverables and a real parallel frontier, return the strict {"action":"decline","reason":"..."} variant. Decline is an advisory outcome, not an error.',
+        "Propose a plan when the accepted objective benefits from multiple substantial implementation or verification steps, dependency ordering, or integration. A single integrated deliverable and sequential work are valid; do not invent parallelism or extra terminal deliverables.",
+        'For a direct question or simple isolated change that needs no meaningful decomposition, return the strict {"action":"decline","reason":"..."} variant. Decline is an advisory outcome, not an error.',
         "Use dependsOn only for actual data, ordering, or integration dependencies.",
         "Every node must describe an outcome the Execution Agent can establish and contain explicit acceptance criteria. Mark a criterion mechanical only when runtime evidence can decide it; otherwise mark it semantic.",
         "The proposal is passive advice. The Execution Agent decides what to do next, and no work is complete merely because a graph was proposed.",

package/dist/src/runtime/steps/supervisor-decision/capability-brief-readmission.d.ts

@@ -0,0 +1,10 @@
+import type { ModelStepContextCompactionController } from "../../model/model-step-port.js";
+import type { RequestExecutionScope } from "../../request/execution-scope.js";
+import type { buildSupervisorDecisionInput } from "./input.js";
+type BriefRoutingInput = Pick<ReturnType<typeof buildSupervisorDecisionInput>, "format" | "allowedRoleIds" | "availableWorkerCapabilityCatalog">;
+/** Optional routing metadata yields capacity to actual repair and steering. */
+export declare function createSupervisorCapabilityBriefReadmissionController(request: RequestExecutionScope, options: Readonly<{
+    input: BriefRoutingInput;
+    controller: ModelStepContextCompactionController;
+}>): ModelStepContextCompactionController;
+export {};

package/dist/src/runtime/steps/supervisor-decision/capability-brief-readmission.js

@@ -0,0 +1,39 @@
+import { createCapabilityBriefReadmissionController } from "../../context/capability-brief-readmission.js";
+import { resolveModelContextAdmission } from "../../model/model-context-budget.js";
+import { traceDebug } from "../../observability/debug-logger.js";
+import { buildSupervisorCapabilityBriefOptions } from "./capability-brief.js";
+import { SUPERVISOR_DECISION_MODEL_STEP } from "./contracts.js";
+/** Optional routing metadata yields capacity to actual repair and steering. */
+export function createSupervisorCapabilityBriefReadmissionController(request, options) {
+    const { input, controller } = options;
+    return createCapabilityBriefReadmissionController({
+        controller,
+        resolveOptions() {
+            const admission = resolveModelContextAdmission({
+                runnerConfig: request.runnerConfig,
+                agentMode: request.agentMode,
+                modelStep: SUPERVISOR_DECISION_MODEL_STEP,
+                modelPreference: request.modelPreference,
+                modelPolicy: request.modelPolicy,
+                requestFormat: input.format,
+            });
+            const briefOptions = buildSupervisorCapabilityBriefOptions(request, input);
+            return {
+                entries: briefOptions.capabilityBriefEntries,
+                groups: input.availableWorkerCapabilityCatalog,
+                budget: admission.budget,
+                format: input.format,
+                additionalBudgetMessages: briefOptions.capabilityBriefBudgetMessages,
+            };
+        },
+        onReadmitted(replacement) {
+            traceDebug("runtime.supervisor", "capability_brief.readmitted", {
+                requestId: request.requestId,
+                level: replacement.level,
+                estimatedTokens: replacement.estimatedTokens,
+                budgetTokens: replacement.budgetTokens,
+                reason: replacement.reason,
+            });
+        },
+    });
+}

package/dist/src/runtime/steps/supervisor-decision/run.js

@@ -8,6 +8,7 @@ import { SUPERVISOR_DECISION_MODEL_STEP, } from "./contracts.js";
 import { traceSupervisorDecisionPhaseSuperseded, traceSupervisorModelCompleted, traceSupervisorModelFailed, traceSupervisorModelStarted, traceSupervisorWorkingDirectoryModelStarted, } from "./diagnostics.js";
 import { buildSupervisorDecisionInput } from "./input.js";
 import { buildSupervisorCapabilityBriefOptions } from "./capability-brief.js";
+import { createSupervisorCapabilityBriefReadmissionController } from "./capability-brief-readmission.js";
 import { parseSupervisorDecisionOutput } from "./parser.js";
 import { buildSupervisorWorkingDirectoryInput, mergeSupervisorWorkingDirectory, parseSupervisorWorkingDirectoryOutput, } from "./working-directory.js";
 import { SUPERVISOR_RESPONSE_MODEL_STEP } from "../supervisor-response/contracts.js";
@@ -81,7 +82,7 @@ export async function runSupervisorDecision(request, options) {
             boundSteeringVersion,
             input,
             diagnostic: routingDiagnostic,
-            contextCompaction,
+            contextCompaction: createSupervisorCapabilityBriefReadmissionController(request, { input, controller: contextCompaction }),
         });
         if (routing.decision.action === "invoke_role" &&
             routing.decision.roleId === "reviewer") {

package/dist/src/runtime/steps/worker-decision/parser/accepted-decision.d.ts

@@ -1,3 +1,5 @@
-import type { WorkerControlDecision } from "../contracts.js";
+import { type WorkerControlDecision } from "../contracts.js";
 import type { ActionValidation, DecisionValidationContext, WorkerDecisionAction } from "./validation-contract.js";
+/** Bounds generated client-facing text without changing execution inputs. */
+export declare function normalizeWorkerCapabilityIntent(value: unknown): string | undefined;
 export declare function buildAcceptedWorkerDecision(action: WorkerDecisionAction, record: Record<string, unknown>, context: DecisionValidationContext, validation: ActionValidation): WorkerControlDecision;

package/dist/src/runtime/steps/worker-decision/parser/accepted-decision.js

@@ -1,3 +1,22 @@
+import { WORKER_CAPABILITY_INTENT_MAX_LENGTH, } from "../contracts.js";
+/** Bounds generated client-facing text without changing execution inputs. */
+export function normalizeWorkerCapabilityIntent(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    const bounded = trimmed.slice(0, WORKER_CAPABILITY_INTENT_MAX_LENGTH);
+    if (hasSplitIntentSurrogatePair(trimmed, bounded.length)) {
+        return bounded.slice(0, -1).trimEnd();
+    }
+    return bounded.trimEnd();
+}
+function hasSplitIntentSurrogatePair(value, boundary) {
+    const before = value.charCodeAt(boundary - 1);
+    if (before < 0xd800 || before > 0xdbff)
+        return false;
+    const after = value.charCodeAt(boundary);
+    return after >= 0xdc00 && after <= 0xdfff;
+}
 export function buildAcceptedWorkerDecision(action, record, context, validation) {
     switch (action) {
         case "return_result":
@@ -17,7 +36,7 @@ function buildAcceptedSingleCapabilityDecision(record, context, validation) {
     const capabilityId = context.pendingCapabilitySelection?.capabilityId ??
         record.capabilityId;
     const intent = context.pendingCapabilitySelection?.intent ??
-        record.intent.trim();
+        normalizeWorkerCapabilityIntent(record.intent);
     const authoringObjective = context.pendingCapabilitySelection?.authoringObjective ??
         validation.acceptedAuthoringObjective;
     const acceptedInvocation = {

package/dist/src/runtime/steps/worker-decision/parser/capability-batch-validation.d.ts

@@ -1,3 +1,3 @@
-import { type WorkerDecisionValidationIssue } from "../contracts.js";
+import type { WorkerDecisionValidationIssue } from "../contracts.js";
 import type { ActionValidation, DecisionValidationContext } from "./validation-contract.js";
 export declare function validateCapabilityBatchDecision(record: Record<string, unknown>, context: DecisionValidationContext, issues: WorkerDecisionValidationIssue[]): ActionValidation;

package/dist/src/runtime/steps/worker-decision/parser/capability-batch-validation.js

@@ -1,5 +1,5 @@
-import { WORKER_CAPABILITY_INTENT_MAX_LENGTH, } from "../contracts.js";
 import { workerCapabilityBatchExecutionSlotId } from "../format.js";
+import { normalizeWorkerCapabilityIntent } from "./accepted-decision.js";
 import { parseCapabilityInvocation } from "./capability-invocation-validation.js";
 import { readWorkerDecisionRecord, validateExactWorkerDecisionKeys, } from "./decision-shape-validation.js";
 import { createWorkerDecisionIssue } from "./validation-contract.js";
@@ -89,16 +89,16 @@ function canAcceptObservationBatchInvocation(context, invocationRecord, invocati
 function hasValidGeneratedCapabilityIdentity(invocation) {
     if (typeof invocation.capabilityId !== "string")
         return false;
-    if (typeof invocation.intent !== "string")
+    const intent = normalizeWorkerCapabilityIntent(invocation.intent);
+    if (intent === undefined)
         return false;
-    if (invocation.intent.trim().length === 0)
-        return false;
-    return invocation.intent.length <= WORKER_CAPABILITY_INTENT_MAX_LENGTH;
+    return intent.length > 0;
 }
 function projectAcceptedCapabilityInvocation(context, invocationRecord, invocation, pendingInvocation) {
     const capabilityId = pendingInvocation?.capabilityId ??
         invocationRecord.capabilityId;
-    const intent = pendingInvocation?.intent ?? invocationRecord.intent.trim();
+    const intent = pendingInvocation?.intent ??
+        normalizeWorkerCapabilityIntent(invocationRecord.intent);
     const authoringObjective = pendingInvocation?.authoringObjective ?? invocation.authoringObjective;
     if (context.decisionPhase === "capability_execution") {
         return Object.freeze({

package/dist/src/runtime/steps/worker-decision/parser/capability-invocation-validation.js

@@ -1,4 +1,5 @@
 import { WORKER_CAPABILITY_AUTHORING_OBJECTIVE_MAX_LENGTH, WORKER_CAPABILITY_INTENT_MAX_LENGTH, } from "../contracts.js";
+import { normalizeWorkerCapabilityIntent } from "./accepted-decision.js";
 import { partitionSelectedCapabilityControls, validateCapabilityExecutionControls, validateCapabilitySelectionControls, } from "./capability-controls-validation.js";
 import { validateBoundedWorkerDecisionText, validateExactWorkerDecisionKeys, } from "./decision-shape-validation.js";
 import { createWorkerDecisionIssue, hasObservationOnlyCapabilityMismatch, } from "./validation-contract.js";
@@ -31,7 +32,7 @@ function hasMissingPendingCapabilityRefinement(context) {
 export function parseCapabilityInvocation(params, issues) {
     const selectedCapability = resolveCapabilityInvocationDescriptor(params, issues);
     if (params.decisionPhase === "capability_selection") {
-        validateBoundedWorkerDecisionText(params.record.intent, WORKER_CAPABILITY_INTENT_MAX_LENGTH, "worker_capability_intent_invalid", `${params.path}.intent`, issues);
+        validateBoundedWorkerDecisionText(normalizeWorkerCapabilityIntent(params.record.intent), WORKER_CAPABILITY_INTENT_MAX_LENGTH, "worker_capability_intent_invalid", `${params.path}.intent`, issues);
     }
     const controlsPartition = partitionSelectedCapabilityControls(selectedCapability, `${params.path}.capabilityId`, issues);
     validateExactWorkerDecisionKeys(params.record, expectedCapabilityInvocationKeys(params, controlsPartition?.selectionControlIds.length ?? 0, selectedCapability), issues, params.path);

package/dist/src/sessions/project-binding.d.ts

@@ -0,0 +1,12 @@
+import type { SessionRecord } from "./types.js";
+/** Immutable workspace identity captured when a project conversation is created. */
+export type SessionProject = Readonly<{
+    id: string;
+    name: string;
+    directory: string;
+}>;
+export type SessionCreationOptions = Readonly<{
+    project?: SessionProject;
+}>;
+export declare function copySessionProject(project: SessionProject): SessionProject;
+export declare function assertSessionProjectUnchanged(session: SessionRecord, requested?: SessionProject): void;

package/dist/src/sessions/project-binding.js

@@ -0,0 +1,49 @@
+import { isAbsolute } from "node:path";
+function isSessionProjectRecord(value) {
+    if (!value)
+        return false;
+    if (Array.isArray(value))
+        return false;
+    return typeof value === "object";
+}
+function hasProjectIdentityText(value) {
+    if (typeof value !== "string")
+        return false;
+    return value.trim().length > 0;
+}
+function hasAbsoluteProjectDirectory(value) {
+    if (typeof value !== "string")
+        return false;
+    return isAbsolute(value);
+}
+export function copySessionProject(project) {
+    if (!isSessionProjectRecord(project))
+        throw new TypeError("session_project_invalid");
+    if (!hasProjectIdentityText(project.id))
+        throw new TypeError("session_project_id_required");
+    if (!hasProjectIdentityText(project.name))
+        throw new TypeError("session_project_name_required");
+    if (!hasAbsoluteProjectDirectory(project.directory))
+        throw new TypeError("session_project_directory_absolute_required");
+    if (project.directory.includes("\0"))
+        throw new TypeError("session_project_directory_invalid");
+    return Object.freeze({
+        id: project.id,
+        name: project.name,
+        directory: project.directory,
+    });
+}
+function matchesSavedProjectBinding(saved, requested) {
+    if (!saved)
+        return false;
+    if (saved.id !== requested.id)
+        return false;
+    return saved.directory === requested.directory;
+}
+export function assertSessionProjectUnchanged(session, requested) {
+    if (!requested)
+        return;
+    const project = copySessionProject(requested);
+    if (!matchesSavedProjectBinding(session.project, project))
+        throw new Error("session_project_binding_immutable");
+}

package/dist/src/sessions/record/projection.d.ts

@@ -14,7 +14,6 @@ export declare function toSnapshotMessage(sessionId: string, message: SessionRec
 export declare function toSnapshotRequest(request: SessionRequestRecord): SessionSnapshotRequest;
 export declare function normalizeSessionTitle(title: string): string;
 export declare function toSessionListItem(session: SessionRecord): {
-    id: string;
     title: string;
     createdAt: number;
     updatedAt: number;
@@ -22,4 +21,10 @@ export declare function toSessionListItem(session: SessionRecord): {
     lastMessageAt: number | null;
     latestMessageId: string | number | null;
     latestAssistantMessageId: string | number | null;
+    project?: Readonly<{
+        id: string;
+        name: string;
+        directory: string;
+    }> | undefined;
+    id: string;
 };

package/dist/src/sessions/record/projection.js

@@ -200,6 +200,7 @@ export function toSessionListItem(session) {
         .find((message) => message.role === "assistant");
     return {
         id: session.id,
+        ...(session.project ? { project: session.project } : {}),
         title: session.title,
         createdAt: toEpochMs(session.createdAt),
         updatedAt: toEpochMs(session.updatedAt),

package/dist/src/sessions/session-service.d.ts

@@ -1,3 +1,4 @@
+import { type SessionCreationOptions } from "./project-binding.js";
 import type { SessionContextEntryKind, SessionArtifactPathInput, SessionMessageGrounding, SessionMessage, SessionMessageDeleteResult, SessionMessageObservationMeta, SessionMessageRole, SessionMessageSource, SessionMessageTaskType, SessionMessagesClearResult, SessionDeleteResult, SessionListResult, SessionRequestReplay, SessionRecord, SessionSnapshot, SessionThinkingTraceEntry } from "./types.js";
 import type { SessionMemoryCheckpointCommit, SessionMemoryCheckpointCommitResult } from "./memory/contracts.js";
 import type { AgentMode } from "../shared/types.js";
@@ -12,7 +13,7 @@ export declare class SessionService {
     private readonly createMessageId;
     private readonly sessionMutationQueues;
     constructor(options?: SessionServiceOptions);
-    getOrCreateSession(sessionId: string): Promise<SessionRecord>;
+    getOrCreateSession(sessionId: string, options?: SessionCreationOptions): Promise<SessionRecord>;
     getAllSessions(): Promise<SessionRecord[]>;
     listSessions(params?: {
         limit?: number;

package/dist/src/sessions/session-service.js

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+import { assertSessionProjectUnchanged, copySessionProject, } from "./project-binding.js";
 import { getDefaultSessionsDir } from "../runtime/config/layout.js";
 import { assertValidSessionArtifactPathInputs, upsertSessionArtifactPaths, } from "./artifact-paths.js";
 import { clientVisibleMessages, compactRequestEvents, filterMessagesAfter, getRequestFinalState, getSessionRequest, isSameMessageId, normalizeAfterSeq, normalizeCursor, normalizeLimit, normalizeSessionTitle, toClientReplayEvent, toEpochMs, toSessionListItem, toSnapshotMessage, toSnapshotRequest, } from "./record/projection.js";
@@ -18,16 +20,20 @@ export class SessionService {
         this.now = options.now || (() => new Date());
         this.createMessageId = options.createMessageId || defaultCreateMessageId;
     }
-    async getOrCreateSession(sessionId) {
+    async getOrCreateSession(sessionId, options = {}) {
         assertValidSessionId(sessionId);
         await ensureSessionsDir(this.sessionsDir);
         const existing = await loadSessionFile(this.sessionsDir, sessionId);
         if (existing) {
+            assertSessionProjectUnchanged(existing, options.project);
             return existing;
         }
         const timestamp = toIso(this.now);
         const session = {
             id: sessionId,
+            ...(options.project
+                ? { project: copySessionProject(options.project) }
+                : {}),
             title: sessionId,
             createdAt: timestamp,
             updatedAt: timestamp,
@@ -65,6 +71,7 @@ export class SessionService {
         }
         return {
             sessionId,
+            ...(session.project ? { project: session.project } : {}),
             title: session.title,
             messages: filterMessagesAfter(clientVisibleMessages(session.messages), options.afterMessageId).map((message) => toSnapshotMessage(sessionId, message, session.requests ?? [])),
             requests: options.includeRequests === false
@@ -85,6 +92,7 @@ export class SessionService {
             return {
                 requestId,
                 sessionId: request.sessionId,
+                ...(request.generation ? { generation: request.generation } : {}),
                 events: request.events
                     .filter((event) => event.seqNo > normalizedAfterSeq)
                     .map(toClientReplayEvent),
@@ -287,6 +295,8 @@ export class SessionService {
             const request = {
                 requestId,
                 sessionId,
+                // Only an explicit new stream establishes a request lifetime.
+                generation: randomUUID(),
                 status: "streaming",
                 createdAt: timestamp,
                 updatedAt: timestamp,