@abot-ai/runtime 1.8.1 → 2.0.0

package/dist/src/runtime/steps/supervisor-decision/diagnostics.d.ts

@@ -16,6 +16,8 @@ export declare function traceSupervisorContextProjected(params: {
     completedChildSummaryLength: number;
     allowedRoleIds: readonly SupervisorDelegateRoleId[];
     allowMemoryRecall: boolean;
+    allowSkillAuthoring?: boolean;
+    allowSkillReads?: boolean;
     workerCapabilityAffordances: readonly SupervisorWorkerCapabilityAffordance[];
     availableWorkerCapabilityCatalog: readonly WorkerCapabilityCatalogGroup[];
     capabilityBrief: CapabilityBriefProjection;
@@ -52,7 +54,7 @@ export declare function traceSupervisorAcknowledgementNormalized(params: {
 export declare function traceSupervisorDecisionRejected(params: {
     diagnostic: SupervisorDecisionDiagnosticContext;
     issues: readonly SupervisorDecisionValidationIssue[];
-    selectedAction?: SupervisorDecision["action"];
+    selectedAction?: SupervisorDecision["action"] | SupervisorRoutingDecision["action"];
 }): void;
 export declare function traceSupervisorModelStarted(params: {
     diagnostic: SupervisorDecisionDiagnosticContext;
@@ -62,6 +64,8 @@ export declare function traceSupervisorModelStarted(params: {
     includeTitle: boolean;
     allowedRoleIds: readonly SupervisorDelegateRoleId[];
     allowMemoryRecall: boolean;
+    allowSkillAuthoring?: boolean;
+    allowSkillReads?: boolean;
     availableWorkerCapabilityCatalog: readonly WorkerCapabilityCatalogGroup[];
 }): void;
 export declare function traceSupervisorModelCompleted(params: {

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

@@ -286,5 +286,9 @@ function projectSupervisorAllowedActions(params) {
         : ["respond"];
     if (params.allowMemoryRecall)
         actions.push("recall_memory");
+    if (params.allowSkillReads)
+        actions.push("list_skills", "read_skills");
+    if (params.allowSkillAuthoring)
+        actions.push("author_skill");
     return actions;
 }

package/dist/src/runtime/steps/supervisor-decision/format.d.ts

@@ -6,6 +6,7 @@ export declare function createSupervisorDecisionFormat(params?: Readonly<{
     includeTitle?: boolean;
     includeResponseRecommendation?: boolean;
     allowMemoryRecall?: boolean;
+    allowSkillAuthoring?: boolean;
     allowedRoleIds?: readonly SupervisorDelegateRoleId[];
     availableWorkerCapabilityCatalog?: readonly WorkerCapabilityCatalogGroup[];
 }>): ModelGatewayJsonSchemaFormat;

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

@@ -1,4 +1,5 @@
 import { createMemoryRecallDecisionSchema } from "../memory-recall-decision.js";
+import { SUPERVISOR_SKILL_AUTHORING_ROUTE_SCHEMA } from "../supervisor-skill-authoring/contract.js";
 import { createStructuredDecisionEnvelopeSchema, structuredDecisionVariantSchemaPath, } from "../../model/structured-decision-envelope.js";
 import { SUPERVISOR_RESPONSE_RECOMMENDATION_MAX_LENGTH } from "./response-recommendation.js";
 import { createWorkerCapabilityScopeDecisionContract } from "../worker-capability-scope-decision.js";
@@ -38,6 +39,7 @@ export function createSupervisorDecisionFormat(params = {}) {
     const variants = [
         respondSchema(includeAcknowledgement, includeTitle, includeResponseRecommendation),
         ...invokeVariants,
+        ...(params.allowSkillAuthoring ? [SUPERVISOR_SKILL_AUTHORING_ROUTE_SCHEMA] : []),
         ...(params.allowMemoryRecall
             ? [
                 createMemoryRecallDecisionSchema({

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

@@ -1,3 +1,4 @@
+import type { RoleCallLedgerHead } from "../../orchestration/role-calls/index.js";
 import type { ChatMessage, ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
 import type { ToolAvailabilityEntry } from "../../../capabilities/tool-types.js";
 import type { RequestContextProjection } from "../../context/request-context-contracts.js";
@@ -5,12 +6,15 @@ import { type RequestToolResultsView } from "../../context/request-tool-results.
 import { type WorkerCapabilityCatalogGroup } from "../../orchestration/worker-capabilities/index.js";
 import type { RequestExecutionSeed } from "../../request/contracts.js";
 import { SUPERVISOR_DECISION_MODEL_STEP, type SupervisorDecisionDiagnosticContext, type SupervisorDelegateRoleId, type SupervisorResumeContext, type SupervisorWorkerCapabilityAffordance } from "./contracts.js";
-export type SupervisorDecisionInputRequest = Pick<RequestExecutionSeed, "requestId" | "prompt" | "historyMessages" | "sessionKind" | "runnerConfig" | "attachments" | "agentMode" | "modelPreference" | "modelPolicy"> & Partial<Pick<RequestExecutionSeed, "shouldGenerateSessionTitle" | "onEvent" | "temporalContext" | "scheduledExecution" | "sessionMemory" | "longTermMemory">>;
+import { type SupervisorArtifactPathsProjection } from "./artifact-paths.js";
+export type SupervisorDecisionInputRequest = Pick<RequestExecutionSeed, "requestId" | "prompt" | "historyMessages" | "sessionKind" | "runnerConfig" | "attachments" | "agentMode" | "modelPreference" | "modelPolicy"> & Partial<Pick<RequestExecutionSeed, "shouldGenerateSessionTitle" | "onEvent" | "temporalContext" | "scheduledExecution" | "sessionMemory" | "sessionArtifactPaths" | "longTermMemory">>;
 export declare function buildSupervisorDecisionInput(request: SupervisorDecisionInputRequest, options: Readonly<{
     toolResults: RequestToolResultsView;
+    skillReadHead?: RoleCallLedgerHead;
     includeAcknowledgement?: boolean;
     includeTitle?: boolean;
     allowMemoryRecall?: boolean;
+    allowSkillAuthoring?: boolean;
     memoryRecallMessage?: ChatMessage;
     initialMemoryMessage?: ChatMessage;
     allowedRoleIds?: readonly SupervisorDelegateRoleId[];
@@ -27,8 +31,11 @@ export declare function buildSupervisorDecisionInput(request: SupervisorDecision
     includeAcknowledgement: boolean;
     includeTitle: boolean;
     includeResponseRecommendation: boolean;
+    delegationOnly?: boolean;
     allowMemoryRecall: boolean;
+    allowSkillAuthoring: boolean;
     allowedRoleIds: readonly SupervisorDelegateRoleId[];
     workerCapabilityAffordances: readonly SupervisorWorkerCapabilityAffordance[];
     availableWorkerCapabilityCatalog: readonly WorkerCapabilityCatalogGroup[];
+    artifactPathsProjection?: SupervisorArtifactPathsProjection;
 };

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

@@ -1,9 +1,9 @@
+import { projectSupervisorSkillReadContext } from "../../context/core-skill-read-context.js";
 import { buildSparkConversationInstructions } from "../../context/spark-conversation-policy.js";
 import { projectCapabilityBrief } from "../../context/capability-brief.js";
 import { resolveConfiguredStepInstructionMetadata } from "../../config/runner/step-instructions.js";
 import { projectRequestContext } from "../../context/request-context.js";
 import { projectRootSessionMemory } from "../../context/session-memory/root-projection.js";
-import { buildConversationMemoryAvailabilityInstructions } from "../../long-term-memory/conversation-authoring/prompt.js";
 import { buildRequestTemporalContextMessage } from "../../context/request-temporal-context.js";
 import { projectScheduledExecutionContext } from "../../context/scheduled-execution-context.js";
 import { buildRequestToolResultsMessage, } from "../../context/request-tool-results.js";
@@ -12,7 +12,8 @@ import { WORKER_CAPABILITY_COUNT_MAX, WORKER_CAPABILITY_SUMMARY_MAX_LENGTH, } fr
 import { SUPERVISOR_DECISION_MODEL_STEP, SUPERVISOR_DELEGATE_ROLE_IDS, } from "./contracts.js";
 import { traceSupervisorChildResultProjected, traceSupervisorContextProjected, } from "./diagnostics.js";
 import { createSupervisorDecisionFormat } from "./format.js";
-import { buildSupervisorDecisionInstructions } from "./prompt.js";
+import { projectSupervisorArtifactPaths, } from "./artifact-paths.js";
+import { buildSupervisorDecisionInstructions, buildSupervisorMemoryAvailabilityInstructions, } from "./prompt.js";
 import { buildSupervisorContinuationPart } from "./resume.js";
 import { buildSupervisorMemoryRecallContinuationParts } from "./memory-recall-continuation.js";
 import { canRecommendDirectSupervisorResponse } from "./response-recommendation.js";
@@ -43,6 +44,7 @@ export function buildSupervisorDecisionInput(request, options) {
         : EMPTY_WORKER_CAPABILITY_AFFORDANCES;
     const format = createSupervisorDecisionFormat({
         allowMemoryRecall: options.allowMemoryRecall === true,
+        allowSkillAuthoring: options.allowSkillAuthoring === true,
         includeAcknowledgement,
         includeTitle,
         includeResponseRecommendation,
@@ -65,7 +67,9 @@ export function buildSupervisorDecisionInput(request, options) {
     const initialMemoryMessage = options.memoryRecallMessage
         ? undefined
         : options.initialMemoryMessage;
+    const skillReadContext = projectSupervisorSkillReadContext(options.skillReadHead);
     const referenceMessages = [
+        ...skillReadContext.referenceMessages,
         ...(initialMemoryMessage ? [initialMemoryMessage] : []),
         ...(request.temporalContext
             ? [buildRequestTemporalContextMessage(request.temporalContext)]
@@ -90,6 +94,7 @@ export function buildSupervisorDecisionInput(request, options) {
     const instructions = [
         buildSupervisorDecisionInstructions({
             allowMemoryRecall: options.allowMemoryRecall === true,
+            allowSkillAuthoring: options.allowSkillAuthoring === true,
             hasMemoryRecallContext: options.memoryRecallMessage !== undefined,
             hasInitialMemoryContext: initialMemoryMessage !== undefined,
             includeAcknowledgement,
@@ -101,7 +106,7 @@ export function buildSupervisorDecisionInput(request, options) {
             workerCapabilityAffordances,
             availableWorkerCapabilityCatalog,
         }),
-        ...buildConversationMemoryAvailabilityInstructions(request.longTermMemory?.enabled === true),
+        ...buildSupervisorMemoryAvailabilityInstructions(request.longTermMemory?.enabled === true),
         ...buildSparkConversationInstructions(request.sessionKind),
     ].join("\n");
     const scheduledExecution = projectScheduledExecutionContext(request, instructions, "decision");
@@ -114,14 +119,17 @@ export function buildSupervisorDecisionInput(request, options) {
         prompt: request.prompt,
         ...(request.attachments ? { attachments: request.attachments } : {}),
         ...(referenceMessages.length > 0 ? { referenceMessages } : {}),
-        continuationParts: options.memoryRecallMessage
-            ? buildSupervisorMemoryRecallContinuationParts({
-                memoryRecallMessage: options.memoryRecallMessage,
-                ...(options.resume ? { resume: options.resume } : {}),
-                currentCallId: requireSupervisorCallId(diagnostic),
-                currentInvocationAttempt: requireSupervisorInvocationAttempt(diagnostic),
-            })
-            : roleContinuationParts,
+        continuationParts: [
+            ...(options.memoryRecallMessage
+                ? buildSupervisorMemoryRecallContinuationParts({
+                    memoryRecallMessage: options.memoryRecallMessage,
+                    ...(options.resume ? { resume: options.resume } : {}),
+                    currentCallId: requireSupervisorCallId(diagnostic),
+                    currentInvocationAttempt: requireSupervisorInvocationAttempt(diagnostic),
+                })
+                : roleContinuationParts),
+            ...skillReadContext.continuationParts,
+        ],
         budget,
         diagnostic,
         ...(request.onEvent ? { onEvent: request.onEvent } : {}),
@@ -139,13 +147,22 @@ export function buildSupervisorDecisionInput(request, options) {
     });
     if (capabilityBrief.message)
         referenceMessages.push(capabilityBrief.message);
+    const artifactPaths = projectSupervisorArtifactPaths({
+        targets: request.sessionArtifactPaths,
+        context: { ...contextInput, referenceMessages },
+        additionalBudgetMessages: options.capabilityBriefBudgetMessages,
+    });
+    if (artifactPaths)
+        referenceMessages.push(artifactPaths.message);
     const context = projectRequestContext({
         ...contextInput,
+        instructions: artifactPaths?.instructions ?? contextInput.instructions,
         ...(referenceMessages.length > 0 ? { referenceMessages } : {}),
     });
     traceSupervisorContextProjected({
         diagnostic,
         allowMemoryRecall: options.allowMemoryRecall === true,
+        allowSkillAuthoring: options.allowSkillAuthoring === true,
         context,
         format,
         historyMessageCount: sessionMemory.historyMessages.length,
@@ -178,9 +195,11 @@ export function buildSupervisorDecisionInput(request, options) {
         includeTitle,
         includeResponseRecommendation,
         allowMemoryRecall: options.allowMemoryRecall === true,
+        allowSkillAuthoring: options.allowSkillAuthoring === true,
         allowedRoleIds,
         workerCapabilityAffordances,
         availableWorkerCapabilityCatalog,
+        ...(artifactPaths ? { artifactPathsProjection: artifactPaths } : {}),
     };
 }
 const EMPTY_WORKER_CAPABILITY_AFFORDANCES = Object.freeze([]);

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

@@ -5,6 +5,7 @@ export declare function parseSupervisorDecisionOutput(text: string, options?: Re
     includeTitle?: boolean;
     includeResponseRecommendation?: boolean;
     allowMemoryRecall?: boolean;
+    allowSkillAuthoring?: boolean;
     allowedRoleIds?: readonly SupervisorDelegateRoleId[];
     availableWorkerCapabilityCatalog?: readonly WorkerCapabilityCatalogGroup[];
     diagnostic?: SupervisorDecisionDiagnosticContext;

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

@@ -1,4 +1,5 @@
 import { isSupervisorDelegateRoleId, SUPERVISOR_ACKNOWLEDGEMENT_MAX_LENGTH, SUPERVISOR_DECISION_ACTIONS, SUPERVISOR_DELEGATE_ROLE_IDS, SUPERVISOR_OBJECTIVE_MAX_LENGTH, SUPERVISOR_TITLE_MAX_LENGTH, } from "./contracts.js";
+import { parseSupervisorSkillAuthoringRoute } from "../supervisor-skill-authoring/contract.js";
 import { createWorkerCapabilityScopeDecisionContract, parseWorkerCapabilityScopeDecision, } from "../worker-capability-scope-decision.js";
 import { traceSupervisorAcknowledgementNormalized, traceSupervisorDecisionAccepted, traceSupervisorDecisionRejected, traceSupervisorEnvelopeAccepted, traceSupervisorEnvelopeRejected, } from "./diagnostics.js";
 import { readStructuredDecisionEnvelope } from "../../model/structured-decision-envelope.js";
@@ -41,6 +42,16 @@ export function parseSupervisorDecisionOutput(text, options = {}) {
         });
     }
     const issues = [];
+    if (record.action === "author_skill") {
+        const parsed = parseSupervisorSkillAuthoringRoute(record, options.allowSkillAuthoring === true);
+        if (diagnostic) {
+            if (parsed.ok)
+                traceSupervisorDecisionAccepted({ diagnostic, decision: parsed.decision });
+            else
+                traceSupervisorDecisionRejected({ diagnostic, selectedAction: "author_skill", issues: parsed.issues });
+        }
+        return parsed.ok ? parsed : { ...parsed, stage: "domain_parser" };
+    }
     if (isMemoryRecallDecisionRecord(record)) {
         const recalled = parseMemoryRecallDecision(record, {
             allowMemoryRecall: options.allowMemoryRecall,

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

@@ -0,0 +1,24 @@
+import type { ChatMessage, ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
+import type { RequestExecutionScope } from "../../request/execution-scope.js";
+import { type SupervisorDecisionDiagnosticContext } from "./contracts.js";
+/** Preparation sees the current request, not routing state or prior tool/document bodies. */
+export declare function buildSupervisorPreparationInput(request: RequestExecutionScope, options: {
+    instructions: string;
+    format: ModelGatewayJsonSchemaFormat;
+    diagnostic: SupervisorDecisionDiagnosticContext;
+    referenceMessages?: readonly ChatMessage[];
+}): {
+    format: ModelGatewayJsonSchemaFormat;
+    context: Readonly<{
+        messages: ChatMessage[];
+        selectedHistoryMessageIds: string[];
+        omittedHistoryMessageIds: string[];
+        budget: import("../../context/request-context-contracts.js").RequestContextBudgetEstimate & {
+            parts: import("../../context/request-context-contracts.js").RequestContextBudgetParts;
+        };
+        compaction: Readonly<{
+            applied: boolean;
+            compactedSourceRefs: readonly string[];
+        }>;
+    }>;
+};

package/dist/src/runtime/steps/supervisor-decision/preparation-input.js

@@ -0,0 +1,23 @@
+import { projectRequestContext } from "../../context/request-context.js";
+import { resolveModelContextBudget } from "../../model/model-context-budget.js";
+import { SUPERVISOR_DECISION_MODEL_STEP } from "./contracts.js";
+/** Preparation sees the current request, not routing state or prior tool/document bodies. */
+export function buildSupervisorPreparationInput(request, options) {
+    const admissionOptions = {
+        runnerConfig: request.runnerConfig, agentMode: request.agentMode,
+        modelStep: SUPERVISOR_DECISION_MODEL_STEP,
+        ...(request.modelPreference ? { modelPreference: request.modelPreference } : {}),
+        ...(request.modelPolicy ? { modelPolicy: request.modelPolicy } : {}),
+    };
+    const budget = resolveModelContextBudget(admissionOptions);
+    const base = {
+        instructions: options.instructions, format: options.format,
+        prompt: request.prompt, historyMessages: [], budget,
+        referenceMessages: options.referenceMessages,
+        ...(request.attachments ? { attachments: request.attachments } : {}),
+        diagnostic: options.diagnostic, onEvent: request.onEvent, deferCompactionFailure: true,
+    };
+    // The exact model-step admission measures the complete envelope, including late
+    // calibration and steering. Keep metadata whole even when this estimate exceeds it.
+    return { format: options.format, context: projectRequestContext(base) };
+}

package/dist/src/runtime/steps/supervisor-decision/preparation.d.ts

@@ -0,0 +1,20 @@
+import type { RequestExecutionScope } from "../../request/execution-scope.js";
+import type { SupervisorSkillSelectionWindow } from "../../request/supervisor-skill-selection-window.js";
+import type { RoleCallLedgerHead } from "../../orchestration/role-calls/index.js";
+import { type SupervisorDecisionDiagnosticContext, type SupervisorResumeContext } from "./contracts.js";
+import { type SupervisorPresentation } from "./presentation.js";
+import { type SupervisorSkillSelection } from "./skill-selection.js";
+export declare function prepareSupervisorDecision(request: RequestExecutionScope, options: {
+    diagnostic: SupervisorDecisionDiagnosticContext;
+    includeAcknowledgement: boolean;
+    includeTitle: boolean;
+    allowSkillReads: boolean;
+    skillReadHead?: RoleCallLedgerHead;
+    resume?: SupervisorResumeContext;
+    skillSelectionWindow: SupervisorSkillSelectionWindow;
+    boundSteeringVersion?: number;
+}): Promise<{
+    presentation: SupervisorPresentation;
+    selection: SupervisorSkillSelection;
+    steeringVersion: number;
+}>;

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

@@ -0,0 +1,117 @@
+import { invokeStructuredModelStep, StructuredModelInvalidOutputError } from "../../model/invoke-structured-step.js";
+import { assertBoundModelStepSteeringCurrent } from "../../model/model-step-steering.js";
+import { STRUCTURED_MODEL_MAX_REPAIR_ATTEMPTS } from "../../model/repair-prompts.js";
+import { traceDebug } from "../../observability/debug-logger.js";
+import { resolveRequestSteeringInbox } from "../../request/request-steering.js";
+import { SUPERVISOR_DECISION_MODEL_STEP } from "./contracts.js";
+import { buildSupervisorPreparationInput } from "./preparation-input.js";
+import { buildSupervisorSkillSelectionInput } from "./skill-selection-input.js";
+import { buildSupervisorPresentationInstructions, createSupervisorPresentationFormat, parseSupervisorPresentationOutput } from "./presentation.js";
+import { hasEligibleSkillCandidates, parseSupervisorSkillSelectionOutput } from "./skill-selection.js";
+export async function prepareSupervisorDecision(request, options) {
+    const steering = resolveRequestSteeringInbox(request.requestSteering);
+    const { skillSelectionWindow } = options;
+    let steeringVersion = options.boundSteeringVersion;
+    let presentation = {};
+    if (needsSupervisorPresentation(options)) {
+        const diagnostic = { ...options.diagnostic, decisionPhase: "presentation" };
+        const input = buildSupervisorPreparationInput(request, {
+            instructions: buildSupervisorPresentationInstructions(options),
+            format: createSupervisorPresentationFormat(options), diagnostic,
+        });
+        const accepted = await invokePreparationPhase(request, {
+            input, diagnostic, boundSteeringVersion: steeringVersion,
+            parse: (text) => parseSupervisorPresentationOutput(text, options),
+        });
+        presentation = accepted.decision;
+        steeringVersion = accepted.steeringVersion;
+    }
+    if (!canSelectSupervisorSkills(options))
+        return { presentation, selection: { action: "continue" }, steeringVersion: steeringVersion ?? steering.snapshot().version };
+    const diagnostic = { ...options.diagnostic, decisionPhase: "skill_selection" };
+    const input = buildSupervisorSkillSelectionInput(request, {
+        skillReadHead: options.skillReadHead, diagnostic, ...(options.resume ? { resume: options.resume } : {}),
+    });
+    if (!hasEligibleSkillCandidates(input.eligibleSkillIds)) {
+        skillSelectionWindow.complete();
+        return { presentation, selection: { action: "continue" }, steeringVersion: steeringVersion ?? steering.snapshot().version };
+    }
+    let accepted;
+    let rejectedSteeringVersion;
+    try {
+        accepted = await invokePreparationPhase(request, {
+            input, diagnostic, boundSteeringVersion: steeringVersion,
+            parse(text) {
+                const parsed = parseSupervisorSkillSelectionOutput(text, input.eligibleSkillIds);
+                if (!parsed.ok)
+                    rejectedSteeringVersion = steering.snapshot().version;
+                return parsed;
+            },
+        });
+    }
+    catch (error) {
+        request.abortSignal.throwIfAborted();
+        if (!isExhaustedDuplicateSkillSelection(error))
+            throw error;
+        if (rejectedSteeringVersion === undefined)
+            throw error;
+        assertBoundModelStepSteeringCurrent(steering, steeringVersion);
+        assertBoundModelStepSteeringCurrent(steering, rejectedSteeringVersion);
+        skillSelectionWindow.complete();
+        traceDebug("runtime.supervisor", "skill_selection.rejected", {
+            ...diagnostic, steeringVersion: rejectedSteeringVersion,
+            issues: error.issues.map(({ code, path }) => ({ code, path })),
+            repairAttempts: error.repairAttempts, disposition: "continue_routing",
+        });
+        return { presentation, selection: { action: "continue" }, steeringVersion: rejectedSteeringVersion };
+    }
+    assertBoundModelStepSteeringCurrent(steering, accepted.steeringVersion);
+    skillSelectionWindow.complete();
+    return { presentation, selection: accepted.decision, steeringVersion: accepted.steeringVersion };
+}
+function needsSupervisorPresentation(options) {
+    return options.includeAcknowledgement || options.includeTitle;
+}
+function canSelectSupervisorSkills(options) {
+    if (!options.allowSkillReads)
+        return false;
+    if (!options.skillSelectionWindow.isOpen())
+        return false;
+    return !options.skillReadHead?.state.skillReads?.some((read) => read.result.outcome === "failed");
+}
+function isExhaustedDuplicateSkillSelection(error) {
+    if (!(error instanceof StructuredModelInvalidOutputError))
+        return false;
+    if (error.modelStep !== SUPERVISOR_DECISION_MODEL_STEP)
+        return false;
+    if (error.message !== "invalid_supervisor_decision")
+        return false;
+    if (error.validationStage !== "domain_parser")
+        return false;
+    if (error.repairAttempts !== STRUCTURED_MODEL_MAX_REPAIR_ATTEMPTS)
+        return false;
+    if (error.issues.length !== 1)
+        return false;
+    return error.issues[0]?.code === "skill_selection_ids_duplicate";
+}
+async function invokePreparationPhase(request, options) {
+    const steering = resolveRequestSteeringInbox(request.requestSteering);
+    const startedAt = Date.now();
+    assertBoundModelStepSteeringCurrent(steering, options.boundSteeringVersion);
+    traceDebug("runtime.supervisor", "model.started", { ...options.diagnostic, outputContract: options.input.format.name, messageCount: options.input.context.messages.length });
+    const accepted = await invokeStructuredModelStep({
+        request, modelStep: SUPERVISOR_DECISION_MODEL_STEP,
+        format: options.input.format, messages: options.input.context.messages,
+        boundSteeringVersion: options.boundSteeringVersion,
+        contextRetention: "exact",
+        timeoutReason: "supervisor_decision_timeout", invalidOutputReason: "invalid_supervisor_decision",
+        parse(text) {
+            const parsed = options.parse(text);
+            if (!parsed.ok)
+                return parsed;
+            return { ok: true, decision: { decision: parsed.decision, steeringVersion: steering.snapshot().version } };
+        },
+    });
+    traceDebug("runtime.supervisor", "model.completed", { ...options.diagnostic, outputContract: options.input.format.name, durationMs: Date.now() - startedAt });
+    return accepted;
+}

package/dist/src/runtime/steps/supervisor-decision/presentation.d.ts

@@ -0,0 +1,13 @@
+import type { ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
+import type { StructuredModelParseResult } from "../../model/invoke-structured-step.js";
+export type SupervisorPresentation = Readonly<{
+    acknowledgement?: string;
+    title?: string;
+}>;
+export type SupervisorPresentationOptions = Readonly<{
+    includeAcknowledgement: boolean;
+    includeTitle: boolean;
+}>;
+export declare function createSupervisorPresentationFormat(options: SupervisorPresentationOptions): ModelGatewayJsonSchemaFormat;
+export declare function buildSupervisorPresentationInstructions(options: SupervisorPresentationOptions): string;
+export declare function parseSupervisorPresentationOutput(text: string, options: SupervisorPresentationOptions): StructuredModelParseResult<SupervisorPresentation>;

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

@@ -0,0 +1,47 @@
+import { createStructuredDecisionEnvelopeSchema, readStructuredDecisionEnvelope } from "../../model/structured-decision-envelope.js";
+import { SUPERVISOR_ACKNOWLEDGEMENT_MAX_LENGTH, SUPERVISOR_TITLE_MAX_LENGTH } from "./contracts.js";
+export function createSupervisorPresentationFormat(options) {
+    const fields = presentationFields(options);
+    return {
+        type: "json_schema", name: "supervisor_presentation", strict: true,
+        schema: createStructuredDecisionEnvelopeSchema([{
+                type: "object",
+                properties: Object.fromEntries(fields.map(([name, maxLength]) => [name, { type: "string", minLength: 2, maxLength }])),
+                required: fields.map(([name]) => name), additionalProperties: false,
+            }]),
+        postValidatedSchemaConstraints: fields.map(([name]) => ({
+            keyword: "maxLength", path: `/properties/decision/properties/${name}/maxLength`,
+        })),
+    };
+}
+export function buildSupervisorPresentationInstructions(options) {
+    return [
+        "Write only the requested opening acknowledgement and conversation title, in the user's language. Return exactly the supplied JSON shape.",
+        "Do not plan, choose actions, answer the request, or claim completed work.",
+        ...(options.includeAcknowledgement ? [`acknowledgement: at most ${SUPERVISOR_ACKNOWLEDGEMENT_MAX_LENGTH} characters; one short sentence acknowledging the requested outcome. No implementation details or promises about a particular method.`] : []),
+        ...(options.includeTitle ? [`title: at most ${SUPERVISOR_TITLE_MAX_LENGTH} characters; a short description of the user's request.`] : []),
+    ].join("\n");
+}
+export function parseSupervisorPresentationOutput(text, options) {
+    let record;
+    try {
+        record = readStructuredDecisionEnvelope(JSON.parse(text));
+    }
+    catch { /* Rejected below. */ }
+    const fields = presentationFields(options);
+    if (!record || Object.keys(record).length !== fields.length || fields.some(([name, max]) => !isBoundedPresentation(record[name], max))) {
+        return { ok: false, stage: "domain_parser", issues: [{ code: "supervisor_presentation_invalid", path: "decision", message: "Return only the requested bounded acknowledgement/title fields." }] };
+    }
+    return { ok: true, decision: Object.freeze(Object.fromEntries(fields.map(([name]) => [name, record[name].trim()]))) };
+}
+function presentationFields(options) {
+    return [
+        ...(options.includeAcknowledgement ? [["acknowledgement", SUPERVISOR_ACKNOWLEDGEMENT_MAX_LENGTH]] : []),
+        ...(options.includeTitle ? [["title", SUPERVISOR_TITLE_MAX_LENGTH]] : []),
+    ];
+}
+function isBoundedPresentation(value, maximum) {
+    if (typeof value !== "string")
+        return false;
+    return value.trim().length >= 2 && value.length <= maximum;
+}

package/dist/src/runtime/steps/supervisor-decision/procedure-entry.d.ts

@@ -0,0 +1,22 @@
+import { type SupervisorDecisionCallIdentity, type SupervisorDelegateRoleId, type SupervisorResumeContext } from "./contracts.js";
+import type { RequestToolResultsView } from "../../context/request-tool-results.js";
+import type { ChatMessage } from "../../../model-gateway/types.js";
+import type { RoleCallLedgerHead } from "../../orchestration/role-calls/index.js";
+import { canOfferMemoryRecall } from "../../long-term-memory/recall-policy.js";
+type ProcedureEntryOptions = Readonly<{
+    resume?: SupervisorResumeContext;
+    call: SupervisorDecisionCallIdentity;
+    skillReadHead?: RoleCallLedgerHead;
+    memoryRecallMessage?: ChatMessage;
+    toolResults: RequestToolResultsView;
+    allowedRoleIds?: readonly SupervisorDelegateRoleId[];
+}>;
+type ProcedureEntry = Readonly<{
+    classifyProcedure: boolean;
+    allowInitialMemoryRecall: boolean;
+    memoryRecallMessage: ChatMessage | undefined;
+}>;
+/** One canonical projection owns initial entry, recall eligibility and its receipt. */
+export declare function projectSupervisorProcedureEntry(options: ProcedureEntryOptions, steeringVersion: number): ProcedureEntry;
+export declare function canRecallSupervisorMemory(entry: ProcedureEntry, policy: Parameters<typeof canOfferMemoryRecall>[0]): boolean;
+export {};

package/dist/src/runtime/steps/supervisor-decision/procedure-entry.js

@@ -0,0 +1,61 @@
+import { SUPERVISOR_DELEGATE_ROLE_IDS, } from "./contracts.js";
+import { projectRootMemoryRecallMessage } from "../../long-term-memory/recall-context.js";
+import { canOfferMemoryRecall } from "../../long-term-memory/recall-policy.js";
+/** One canonical projection owns initial entry, recall eligibility and its receipt. */
+export function projectSupervisorProcedureEntry(options, steeringVersion) {
+    const continuation = Object.freeze({
+        classifyProcedure: false, allowInitialMemoryRecall: false,
+        memoryRecallMessage: options.memoryRecallMessage,
+    });
+    if (options.resume !== undefined)
+        return continuation;
+    if (options.toolResults.results.length > 0)
+        return continuation;
+    if (!hasProcedureDelegate(options))
+        return continuation;
+    const head = options.skillReadHead;
+    // Isolated callers retain fresh classification, but cannot open a recall
+    // without canonical state proving that its initial allowance is unused.
+    if (!head)
+        return Object.freeze({
+            ...continuation, classifyProcedure: options.memoryRecallMessage === undefined,
+        });
+    const root = head.state.calls.find(call => call.callId === head.state.rootCallId);
+    if (!root)
+        return continuation;
+    if (root.callId !== options.call.callId)
+        return continuation;
+    if (root.status !== "active")
+        return continuation;
+    if (root.activationCount !== options.call.invocationAttempt)
+        return continuation;
+    if (root.childCallIds.length > 0)
+        return continuation;
+    return Object.freeze({
+        classifyProcedure: true,
+        allowInitialMemoryRecall: !hasInitialRecallForCurrentIntent(head, steeringVersion),
+        memoryRecallMessage: projectRootMemoryRecallMessage({
+            head, callId: root.callId, steeringVersion,
+        }),
+    });
+}
+function hasProcedureDelegate(options) {
+    const roles = options.allowedRoleIds ?? SUPERVISOR_DELEGATE_ROLE_IDS;
+    return roles.some((role) => role === "worker" || role === "planner");
+}
+export function canRecallSupervisorMemory(entry, policy) {
+    if (!policy.enabled)
+        return false;
+    if (entry.classifyProcedure && !entry.allowInitialMemoryRecall)
+        return false;
+    return canOfferMemoryRecall(policy);
+}
+function hasInitialRecallForCurrentIntent(head, steeringVersion) {
+    return head.state.memoryRecalls.some(recall => {
+        if (recall.callId !== head.state.rootCallId)
+            return false;
+        if (recall.steeringVersion !== steeringVersion)
+            return false;
+        return recall.completedChildCount === 0;
+    });
+}

package/dist/src/runtime/steps/supervisor-decision/procedure-gate.d.ts

@@ -0,0 +1,39 @@
+import type { ChatMessage, ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
+import { type StructuredModelParseResult } from "../../model/invoke-structured-step.js";
+import type { RequestExecutionScope } from "../../request/execution-scope.js";
+import { type SupervisorDecisionDiagnosticContext } from "./contracts.js";
+export type SupervisorProcedureGateDecision = Readonly<{
+    requiresProcedure: true;
+} | {
+    requiresProcedure: false;
+    responseRecommendation?: string;
+}>;
+export declare function createSupervisorProcedureGateFormat(): ModelGatewayJsonSchemaFormat;
+export declare function parseSupervisorProcedureGateOutput(text: string): StructuredModelParseResult<SupervisorProcedureGateDecision>;
+type ProcedureGateContextOptions = Readonly<{
+    diagnostic: SupervisorDecisionDiagnosticContext;
+    initialMemoryMessage?: ChatMessage;
+    memoryRecallMessage?: ChatMessage;
+    boundSteeringVersion?: number;
+}>;
+export declare function buildSupervisorProcedureGateInput(request: RequestExecutionScope, options: ProcedureGateContextOptions): {
+    modelStep: "supervisor.decision";
+    format: ModelGatewayJsonSchemaFormat;
+    context: Readonly<{
+        messages: ChatMessage[];
+        selectedHistoryMessageIds: string[];
+        omittedHistoryMessageIds: string[];
+        budget: import("../../context/request-context-contracts.js").RequestContextBudgetEstimate & {
+            parts: import("../../context/request-context-contracts.js").RequestContextBudgetParts;
+        };
+        compaction: Readonly<{
+            applied: boolean;
+            compactedSourceRefs: readonly string[];
+        }>;
+    }>;
+};
+export declare function runSupervisorProcedureGate(request: RequestExecutionScope, options: ProcedureGateContextOptions): Promise<{
+    decision: SupervisorProcedureGateDecision;
+    steeringVersion: number;
+}>;
+export {};