@abot-ai/runtime 1.9.0 → 2.0.0

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

@@ -0,0 +1,105 @@
+import { resolveMemoryRecallSteeringVersion } from "../../long-term-memory/recall-binding.js";
+import { buildSupervisorMemoryRecallContinuationParts } from "./memory-recall-continuation.js";
+import { buildSparkConversationInstructions } from "../../context/spark-conversation-policy.js";
+import { projectLatestSettledConversationTurn, projectRequestContext } from "../../context/request-context.js";
+import { buildRequestTemporalContextMessage } from "../../context/request-temporal-context.js";
+import { projectScheduledExecutionContext } from "../../context/scheduled-execution-context.js";
+import { resolveModelContextBudget } from "../../model/model-context-budget.js";
+import { traceDebug } from "../../observability/debug-logger.js";
+import { SUPERVISOR_DECISION_MODEL_STEP, SUPERVISOR_DELEGATE_ROLE_IDS } from "./contracts.js";
+import { createSupervisorDelegationFormat } from "./delegation-contract.js";
+import { buildSupervisorDelegationInstructions } from "./delegation-prompt.js";
+import { projectSupervisorArtifactPaths } from "./artifact-paths.js";
+/**
+ * Initial delegation uses one exact settled conversation turn, not the full routing
+ * history or captured Skill bodies. Those remain available to their execution
+ * owners. This projection is phase-local and never changes session checkpoints.
+ */
+export function buildSupervisorDelegationInput(request, options) {
+    const allowedRoleIds = [...new Set(options.allowedRoleIds ?? SUPERVISOR_DELEGATE_ROLE_IDS)]
+        .filter((role) => role === "worker" || role === "planner");
+    const allowMemoryRecall = options.allowMemoryRecall === true && options.memoryRecallMessage === undefined;
+    const continuationParts = [];
+    if (options.memoryRecallMessage) {
+        const diagnostic = options.diagnostic;
+        if (!diagnostic?.callId || !diagnostic.invocationAttempt)
+            throw new Error("supervisor_recall_call_identity_required");
+        resolveMemoryRecallSteeringVersion(options.memoryRecallMessage, request.requestId, diagnostic.callId);
+        continuationParts.push(...buildSupervisorMemoryRecallContinuationParts({
+            memoryRecallMessage: options.memoryRecallMessage,
+            currentCallId: diagnostic.callId,
+            currentInvocationAttempt: diagnostic.invocationAttempt,
+        }));
+    }
+    const format = createSupervisorDelegationFormat({ allowedRoleIds, allowMemoryRecall });
+    const budget = resolveModelContextBudget({
+        runnerConfig: request.runnerConfig,
+        agentMode: request.agentMode,
+        modelStep: SUPERVISOR_DECISION_MODEL_STEP,
+        modelPreference: request.modelPreference,
+        modelPolicy: request.modelPolicy,
+    });
+    const instructions = [
+        buildSupervisorDelegationInstructions({
+            allowedRoleIds, allowMemoryRecall, hasMemoryRecallContext: options.memoryRecallMessage !== undefined,
+        }),
+        ...buildSparkConversationInstructions(request.sessionKind),
+    ].join("\n");
+    const scheduledExecution = projectScheduledExecutionContext(request, instructions, "decision");
+    const referenceMessages = [
+        ...scheduledExecution.referenceMessages,
+        ...(!options.memoryRecallMessage && options.initialMemoryMessage ? [options.initialMemoryMessage] : []),
+        ...(request.temporalContext ? [buildRequestTemporalContextMessage(request.temporalContext)] : []),
+    ];
+    const historyMessages = projectLatestSettledConversationTurn(request.historyMessages) ?? [];
+    const contextInput = {
+        instructions: scheduledExecution.instructions,
+        format,
+        prompt: request.prompt,
+        historyMessages,
+        // Keep this single source turn whole. The exact model-step admission still
+        // accounts for it and rejects oversize input before any child is dispatched.
+        historyRetention: "compaction_managed",
+        referenceMessages,
+        continuationParts,
+        ...(request.attachments ? { attachments: request.attachments } : {}),
+        budget,
+        diagnostic: options.diagnostic,
+        onEvent: request.onEvent,
+        deferCompactionFailure: true,
+    };
+    const artifactPathsProjection = projectSupervisorArtifactPaths({
+        targets: request.sessionArtifactPaths,
+        context: contextInput,
+        additionalBudgetMessages: options.capabilityBriefBudgetMessages,
+    });
+    if (artifactPathsProjection)
+        referenceMessages.push(artifactPathsProjection.message);
+    const projected = projectRequestContext({
+        ...contextInput,
+        instructions: artifactPathsProjection?.instructions ?? contextInput.instructions,
+    });
+    const selectedIds = new Set(projected.selectedHistoryMessageIds);
+    const context = {
+        ...projected,
+        omittedHistoryMessageIds: request.historyMessages
+            .filter((message) => !selectedIds.has(message.id)).map((message) => message.id),
+    };
+    traceDebug("runtime.supervisor", "delegation.context.projected", {
+        ...options.diagnostic,
+        messageCount: context.messages.length,
+        messageCharacterCount: context.messages.reduce((sum, message) => sum + message.content.length, 0),
+        selectedHistoryMessageCount: context.selectedHistoryMessageIds.length,
+        omittedHistoryMessageCount: context.omittedHistoryMessageIds.length,
+        referenceMessageCount: referenceMessages.length,
+        allowedRoleIds,
+    });
+    return {
+        context, format, modelStep: SUPERVISOR_DECISION_MODEL_STEP,
+        delegationOnly: true,
+        includeAcknowledgement: false, includeTitle: false, includeResponseRecommendation: false,
+        allowMemoryRecall, allowSkillAuthoring: false, allowedRoleIds,
+        workerCapabilityAffordances: [], availableWorkerCapabilityCatalog: [],
+        ...(artifactPathsProjection ? { artifactPathsProjection } : {}),
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { SupervisorDelegateRoleId } from "./contracts.js";
+/** A procedure was accepted; this phase chooses root recall or a bounded child assignment. */
+export declare function buildSupervisorDelegationInstructions(options: Readonly<{
+    allowedRoleIds: readonly SupervisorDelegateRoleId[];
+    allowMemoryRecall?: boolean;
+    hasMemoryRecallContext?: boolean;
+}>): string;

package/dist/src/runtime/steps/supervisor-decision/delegation-prompt.js

@@ -0,0 +1,13 @@
+import { buildMemoryRecallDecisionInstructions } from "../memory-recall-prompt.js";
+import { buildSupervisorRoleGuidance, buildSupervisorDelegationGuidance } from "./role-guidance.js";
+/** A procedure was accepted; this phase chooses root recall or a bounded child assignment. */
+export function buildSupervisorDelegationInstructions(options) {
+    return [
+        options.allowMemoryRecall
+            ? "A procedure is required. Choose your own memory lookup or Worker/Planner with a bounded task using only the supplied JSON schema. Do not reconsider a direct reply here. Tool availability and tool selection belong to the execution role, not this decision."
+            : "A procedure is required. Choose Worker or Planner and its bounded task using only the supplied JSON schema. Do not reconsider a direct reply. Tool availability and tool selection belong to the execution role, not this decision.",
+        ...buildMemoryRecallDecisionInstructions(options.allowMemoryRecall === true, options.hasMemoryRecallContext),
+        ...buildSupervisorRoleGuidance(options.allowedRoleIds),
+        ...buildSupervisorDelegationGuidance(),
+    ].join("\n");
+}

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

@@ -31,6 +31,7 @@ export declare function buildSupervisorDecisionInput(request: SupervisorDecision
     includeAcknowledgement: boolean;
     includeTitle: boolean;
     includeResponseRecommendation: boolean;
+    delegationOnly?: boolean;
     allowMemoryRecall: boolean;
     allowSkillAuthoring: boolean;
     allowedRoleIds: readonly SupervisorDelegateRoleId[];

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

@@ -1,18 +1,16 @@
-import type { ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
+import type { ChatMessage, ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
 import type { RequestExecutionScope } from "../../request/execution-scope.js";
-import type { KnowledgeSkillMetadata } from "../../knowledge-skills/store.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;
-    availableSkills?: readonly KnowledgeSkillMetadata[];
-    expandedCatalog?: boolean;
+    referenceMessages?: readonly ChatMessage[];
 }): {
     format: ModelGatewayJsonSchemaFormat;
     context: Readonly<{
-        messages: import("../../../model-gateway/types.js").ChatMessage[];
+        messages: ChatMessage[];
         selectedHistoryMessageIds: string[];
         omittedHistoryMessageIds: string[];
         budget: import("../../context/request-context-contracts.js").RequestContextBudgetEstimate & {

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

@@ -1,9 +1,5 @@
 import { projectRequestContext } from "../../context/request-context.js";
-import { resolveModelContextAdmission, resolveModelContextBudget } from "../../model/model-context-budget.js";
-import { estimateMessagesTokens } from "../../context/token-estimator.js";
-import { appendRequestSteeringContext } from "../../request/request-steering-context.js";
-import { resolveRequestSteeringInbox } from "../../request/request-steering.js";
-import { buildAvailableSkillsText, AVAILABLE_SKILLS_MAX_TOKENS } from "../../knowledge-skills/available-skills-projection.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) {
@@ -14,26 +10,14 @@ export function buildSupervisorPreparationInput(request, options) {
         ...(request.modelPolicy ? { modelPolicy: request.modelPolicy } : {}),
     };
     const budget = resolveModelContextBudget(admissionOptions);
-    const calibration = resolveModelContextAdmission(admissionOptions).invocation.instructions ?? [];
-    const additionalMessages = appendRequestSteeringContext(calibration.length ? [{ role: "system", content: calibration.join("\n") }] : [], resolveRequestSteeringInbox(request.requestSteering).snapshot());
-    const additionalTokens = estimateMessagesTokens(additionalMessages, budget.tokenEstimation);
     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,
     };
-    const baseContext = projectRequestContext(base);
-    const catalog = options.availableSkills === undefined ? undefined : buildAvailableSkillsText({
-        skills: options.availableSkills,
-        budgetTokens: options.expandedCatalog
-            ? Math.max(0, baseContext.budget.availableInputTokens - baseContext.budget.estimatedInputTokens - additionalTokens)
-            : AVAILABLE_SKILLS_MAX_TOKENS,
-        tokenEstimation: budget.tokenEstimation,
-        includeListHint: false,
-    });
-    const instructions = options.availableSkills === undefined ? options.instructions : [
-        catalog ?? "Available Skills: no remaining candidate metadata is available.", options.instructions,
-    ].join("\n");
-    return { format: options.format, context: projectRequestContext({ ...base, instructions }) };
+    // 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

@@ -1,6 +1,7 @@
 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 } from "./contracts.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: {
@@ -9,6 +10,8 @@ export declare function prepareSupervisorDecision(request: RequestExecutionScope
     includeTitle: boolean;
     allowSkillReads: boolean;
     skillReadHead?: RoleCallLedgerHead;
+    resume?: SupervisorResumeContext;
+    skillSelectionWindow: SupervisorSkillSelectionWindow;
     boundSteeringVersion?: number;
 }): Promise<{
     presentation: SupervisorPresentation;

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

@@ -1,14 +1,16 @@
-import { invokeStructuredModelStep } from "../../model/invoke-structured-step.js";
+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 { parseSupervisorSkillSelectionOutput } from "./skill-selection.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)) {
@@ -27,11 +29,44 @@ export async function prepareSupervisorDecision(request, options) {
     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 });
-    const accepted = await invokePreparationPhase(request, {
-        input, diagnostic, boundSteeringVersion: steeringVersion,
-        parse: parseSupervisorSkillSelectionOutput,
+    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) {
@@ -40,8 +75,25 @@ function needsSupervisorPresentation(options) {
 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();

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 {};

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

@@ -0,0 +1,146 @@
+import { projectRequestContext } from "../../context/request-context.js";
+import { invokeStructuredModelStep } from "../../model/invoke-structured-step.js";
+import { resolveModelContextBudget } from "../../model/model-context-budget.js";
+import { assertBoundModelStepSteeringCurrent } from "../../model/model-step-steering.js";
+import { createStructuredDecisionEnvelopeSchema, readStructuredDecisionEnvelope, structuredDecisionVariantSchemaPath } from "../../model/structured-decision-envelope.js";
+import { traceDebug } from "../../observability/debug-logger.js";
+import { resolveRequestSteeringInbox } from "../../request/request-steering.js";
+import { SUPERVISOR_DECISION_MODEL_STEP } from "./contracts.js";
+import { projectSupervisorResponseRecommendation, SUPERVISOR_RESPONSE_RECOMMENDATION_MAX_LENGTH } from "./response-recommendation.js";
+import { projectSupervisorProcedureRecall } from "./procedure-recall.js";
+import { projectSupervisorProcedureMemory } from "./procedure-memory.js";
+const PROCEDURE_GATE_INSTRUCTIONS = [
+    "Decide only whether fulfilling the current user request requires a procedure before answering.",
+    "requiresProcedure=true: work must be carried out, observed or changed before a grounded final reply can fulfill the request.",
+    "requiresProcedure=false: the requested outcome is a direct conversational answer, explanation, or necessary clarification.",
+    "Judge what the request requires, regardless of which tools exist. Tool availability and role/tool selection belong to later stages.",
+    "Do not execute work, plan it, or claim completion. Return only the supplied JSON. If false, include a short response recommendation, not the final answer.",
+].join("\n");
+export function createSupervisorProcedureGateFormat() {
+    return {
+        type: "json_schema", name: "supervisor_procedure_gate", strict: true,
+        schema: createStructuredDecisionEnvelopeSchema([
+            {
+                type: "object", properties: { requiresProcedure: { type: "boolean", const: true } },
+                required: ["requiresProcedure"], additionalProperties: false,
+            },
+            {
+                type: "object",
+                properties: {
+                    requiresProcedure: { type: "boolean", const: false },
+                    responseRecommendation: { type: "string", minLength: 1, maxLength: SUPERVISOR_RESPONSE_RECOMMENDATION_MAX_LENGTH },
+                },
+                required: ["requiresProcedure", "responseRecommendation"], additionalProperties: false,
+            },
+        ]),
+        postValidatedSchemaConstraints: [{
+                keyword: "maxLength",
+                path: `${structuredDecisionVariantSchemaPath(1, 2)}/properties/responseRecommendation/maxLength`,
+            }],
+    };
+}
+export function parseSupervisorProcedureGateOutput(text) {
+    let record;
+    try {
+        record = readStructuredDecisionEnvelope(JSON.parse(text));
+    }
+    catch { /* Rejected below. */ }
+    if (isProcedureRequiredDecision(record)) {
+        return { ok: true, decision: Object.freeze({ requiresProcedure: true }) };
+    }
+    if (isDirectResponseDecision(record)) {
+        return { ok: true, decision: Object.freeze({
+                requiresProcedure: false, ...projectSupervisorResponseRecommendation(record.responseRecommendation),
+            }) };
+    }
+    return {
+        ok: false, stage: "domain_parser", issues: [{
+                code: "supervisor_procedure_gate_invalid", path: "decision",
+                message: "Return requiresProcedure as a boolean. Only false may include responseRecommendation; supply a non-empty recommendation of at most 300 characters. Include no other fields.",
+            }],
+    };
+}
+function isProcedureRequiredDecision(record) {
+    if (!record)
+        return false;
+    if (record.requiresProcedure !== true)
+        return false;
+    return Object.keys(record).length === 1;
+}
+function isDirectResponseDecision(record) {
+    if (!record)
+        return false;
+    if (record.requiresProcedure !== false)
+        return false;
+    return Object.keys(record).every((key) => key === "requiresProcedure" || key === "responseRecommendation");
+}
+function projectProcedureMemoryContext(request, options) {
+    if (!request.longTermMemory?.enabled)
+        return undefined;
+    if (!options.memoryRecallMessage)
+        return projectSupervisorProcedureMemory(options.initialMemoryMessage);
+    return projectSupervisorProcedureRecall(options.memoryRecallMessage, {
+        requestId: request.requestId,
+        callId: options.diagnostic.callId ?? "",
+        steeringVersion: options.boundSteeringVersion ?? 0,
+    });
+}
+export function buildSupervisorProcedureGateInput(request, options) {
+    const format = createSupervisorProcedureGateFormat();
+    const memory = projectProcedureMemoryContext(request, options);
+    const budget = resolveModelContextBudget({
+        runnerConfig: request.runnerConfig, agentMode: request.agentMode,
+        modelStep: SUPERVISOR_DECISION_MODEL_STEP,
+        configuredInstructionPolicy: "omit",
+        ...(request.modelPreference ? { modelPreference: request.modelPreference } : {}),
+        ...(request.reasoningPreference ? { reasoningPreference: request.reasoningPreference } : {}),
+        ...(request.modelPolicy ? { modelPolicy: request.modelPolicy } : {}),
+    });
+    const context = projectRequestContext({
+        instructions: [PROCEDURE_GATE_INSTRUCTIONS, ...(memory ? [memory.instructions] : [])].join("\n"), format,
+        prompt: request.prompt, historyMessages: [], budget,
+        ...(memory ? { referenceMessages: [memory.message] } : {}),
+        diagnostic: options.diagnostic, onEvent: request.onEvent,
+        deferCompactionFailure: true,
+    });
+    return { modelStep: SUPERVISOR_DECISION_MODEL_STEP, format, context };
+}
+export async function runSupervisorProcedureGate(request, options) {
+    const diagnostic = { ...options.diagnostic, decisionPhase: "procedure_gate" };
+    const steering = resolveRequestSteeringInbox(request.requestSteering);
+    const startedAt = Date.now();
+    try {
+        assertBoundModelStepSteeringCurrent(steering, options.boundSteeringVersion);
+        const input = buildSupervisorProcedureGateInput(request, { ...options, diagnostic });
+        traceDebug("runtime.supervisor", "model.started", {
+            ...diagnostic, outputContract: input.format.name, messageCount: input.context.messages.length,
+        });
+        const accepted = await invokeStructuredModelStep({
+            request, modelStep: SUPERVISOR_DECISION_MODEL_STEP,
+            messages: input.context.messages, format: input.format,
+            boundSteeringVersion: options.boundSteeringVersion, contextRetention: "exact",
+            configuredInstructionPolicy: "omit",
+            timeoutReason: "supervisor_decision_timeout", invalidOutputReason: "invalid_supervisor_decision",
+            parse(text) {
+                const parsed = parseSupervisorProcedureGateOutput(text);
+                if (!parsed.ok)
+                    return parsed;
+                return { ok: true, decision: { decision: parsed.decision, steeringVersion: steering.snapshot().version } };
+            },
+        });
+        request.abortSignal.throwIfAborted();
+        assertBoundModelStepSteeringCurrent(steering, accepted.steeringVersion);
+        traceDebug("runtime.supervisor", "model.completed", {
+            ...diagnostic, outputContract: input.format.name, durationMs: Date.now() - startedAt,
+            requiresProcedure: accepted.decision.requiresProcedure,
+        });
+        return accepted;
+    }
+    catch (error) {
+        traceDebug("runtime.supervisor", "model.failed", {
+            ...diagnostic, durationMs: Date.now() - startedAt,
+            errorType: error instanceof Error ? error.name : typeof error,
+        });
+        throw error;
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { ChatMessage } from "../../../model-gateway/types.js";
+export declare const MAX_MEMORY_CHARACTERS = 1000;
+export declare const MEMORY_INSTRUCTIONS: string;
+/** Read-only view of the existing request snapshot; never changes stored memory. */
+export declare function projectSupervisorProcedureMemory(message: ChatMessage | undefined): Readonly<{
+    message: ChatMessage;
+    instructions: string;
+}> | undefined;
+export declare function renderCompleteMemory(value: unknown): string | undefined;