@abot-ai/runtime 1.3.1 → 1.4.0

package/dist/src/runtime/projects/service.js

@@ -0,0 +1,34 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { copySessionProject } from "../../sessions/project-binding.js";
+import { FileProjectRepository } from "./repository.js";
+import { browseProjectFolders, projectDisplayName, resolveProjectDirectory, } from "./folders.js";
+import { ProjectOperationError, } from "./contracts.js";
+export function createRuntimeProjectService(config, sessions) {
+    const repository = new FileProjectRepository(join(config.paths.runtimeDir, "projects", "registry.json"));
+    const get = async (id) => (await repository.list()).find((project) => project.id === id) ?? null;
+    return Object.freeze({
+        list: () => repository.list(),
+        get,
+        async create(input) {
+            const directory = await resolveProjectDirectory(input.directory);
+            return repository.create({
+                id: randomUUID(),
+                name: projectDisplayName(input.name, directory),
+                directory,
+                createdAt: new Date().toISOString(),
+            });
+        },
+        browseFolders: (input) => browseProjectFolders(config.paths.agentWorkDir, input),
+        async createSession(projectId) {
+            const record = await get(projectId);
+            if (!record)
+                throw new ProjectOperationError("project_not_found", "This project no longer exists.", 404);
+            await resolveProjectDirectory(record.directory);
+            const project = copySessionProject(record);
+            const sessionId = randomUUID();
+            await sessions.getOrCreateSession(sessionId, { project });
+            return { sessionId, project };
+        },
+    });
+}

package/dist/src/runtime/projects/session-paths.d.ts

@@ -0,0 +1,5 @@
+import type { SessionRecord } from "../../sessions/types.js";
+import type { RuntimePaths } from "../ports.js";
+/** Derive only the request-local work root; all configured namespaces stay distinct. */
+export declare function resolveSessionWorkingDirectory(session: SessionRecord): string | undefined;
+export declare function projectSessionRuntimePaths(paths: RuntimePaths, session: SessionRecord): RuntimePaths;

package/dist/src/runtime/projects/session-paths.js

@@ -0,0 +1,13 @@
+import { copySessionProject } from "../../sessions/project-binding.js";
+/** Derive only the request-local work root; all configured namespaces stay distinct. */
+export function resolveSessionWorkingDirectory(session) {
+    if (!session.project)
+        return undefined;
+    return copySessionProject(session.project).directory;
+}
+export function projectSessionRuntimePaths(paths, session) {
+    const agentWorkDir = resolveSessionWorkingDirectory(session);
+    if (!agentWorkDir)
+        return paths;
+    return Object.freeze({ ...paths, agentWorkDir });
+}

package/dist/src/runtime/request/execution-agent-plan-update.d.ts

@@ -0,0 +1,4 @@
+import type { RoleCallFrame, RoleCallLedgerHead } from "../orchestration/role-calls/index.js";
+import type { ModelWorkPlanUpdate } from "../orchestration/role-calls/work-plan-contracts.js";
+import { type ExecutionWorkPlanReport } from "../steps/execution-agent/work-plan-contract.js";
+export declare function bindExecutionAgentPlanUpdate(head: RoleCallLedgerHead, call: RoleCallFrame, report: ExecutionWorkPlanReport): ModelWorkPlanUpdate;

package/dist/src/runtime/request/execution-agent-plan-update.js

@@ -0,0 +1,13 @@
+import { parseExecutionWorkPlanReport, } from "../steps/execution-agent/work-plan-contract.js";
+import { projectExecutionWorkPlanOptions, resolveExecutionWorkPlanDefinition, } from "../steps/execution-agent/work-plan-sources.js";
+export function bindExecutionAgentPlanUpdate(head, call, report) {
+    const validated = parseExecutionWorkPlanReport(report, projectExecutionWorkPlanOptions(head, call));
+    if (!validated)
+        throw new Error("execution_agent_work_plan_report_invalid");
+    if (validated.mode === "progress")
+        return { ...validated, mode: "progress" };
+    const definition = resolveExecutionWorkPlanDefinition(head, call, validated.sourceResultRef);
+    if (!definition)
+        throw new Error("execution_agent_work_plan_source_invalid");
+    return { ...validated, mode: "adopt", definition };
+}

package/dist/src/runtime/request/execution-agent-root-execution.js

@@ -1,6 +1,7 @@
 import { projectSupervisorCallIdentity, projectSupervisorResumeContext, } from "../steps/supervisor-decision/index.js";
 import { EXECUTION_AGENT_DECISION_MODEL_STEP, EXECUTION_AGENT_RESPONSE_MODEL_STEP, runExecutionAgentDecision, runExecutionAgentAuthoredResponse, } from "../steps/execution-agent/index.js";
 import { encodeExecutionAgentAuditObjective } from "../steps/auditor-decision/index.js";
+import { bindExecutionAgentPlanUpdate } from "./execution-agent-plan-update.js";
 import { projectRequestSteeringSnapshot, resolveRequestSteeringInbox, } from "./request-steering.js";
 export const EXECUTION_AGENT_ROOT_CONTRACT = Object.freeze({
     contractId: "execution_agent",
@@ -24,7 +25,14 @@ export const EXECUTION_AGENT_ROOT_CONTRACT = Object.freeze({
                 : {}),
         });
         return Object.freeze({
-            decision: projectKernelDecision(outcome.decision, outcome.steeringVersion),
+            decision: {
+                ...projectKernelDecision(outcome.decision, outcome.steeringVersion),
+                ...("workPlan" in outcome.decision && outcome.decision.workPlan
+                    ? {
+                        workPlan: bindExecutionAgentPlanUpdate(options.head, options.callFrame, outcome.decision.workPlan),
+                    }
+                    : {}),
+            },
             steeringVersion: outcome.steeringVersion,
         });
     },

package/dist/src/runtime/request/handler.js

@@ -1,3 +1,4 @@
+import { resolveSessionWorkingDirectory } from "../projects/session-paths.js";
 import { traceDebug } from "../observability/debug-logger.js";
 import { RequestLifecycle } from "../orchestration/lifecycle/request-lifecycle.js";
 import { createRequestContextCompactionStore } from "../context/semantic-compaction/index.js";
@@ -80,6 +81,7 @@ class RequestHandlingSession {
             sessionStore,
             attachmentStore,
         });
+        const requestWorkingDirectory = resolveSessionWorkingDirectory(openedSession.session);
         const historyMessages = snapshotRequestHistory(openedSession.session);
         const sessionMemory = createRequestSessionMemory({
             sessionId,
@@ -157,18 +159,23 @@ class RequestHandlingSession {
             onEvent: (name, extra) => this.events.event(name, extra),
             ...(sessionArtifactPaths.length > 0 ? { sessionArtifactPaths } : {}),
         };
+        const toolRegistry = this.options.toolRegistry?.prepareRequest
+            ? await this.options.toolRegistry.prepareRequest()
+            : this.options.toolRegistry;
+        this.lifecycle.signal.throwIfAborted();
         const runnerRequest = createRequestExecutionScope({
             seed: runnerRequestSeed,
             executionPolicy,
             createWorkerCapabilities: (request) => createRequestWorkerCapabilityProvider({
                 request,
+                requestWorkingDirectory,
                 executionPolicyAuthority: executionPolicy.authority,
                 requestAttachments: initializedRequest.toolAttachments,
                 ...(this.options.runtimeConfig
                     ? { runtimeConfig: this.options.runtimeConfig }
                     : {}),
-                ...(this.options.toolRegistry
-                    ? { toolRegistryOverride: this.options.toolRegistry }
+                ...(toolRegistry
+                    ? { toolRegistryOverride: toolRegistry }
                     : {}),
             }),
         });

package/dist/src/runtime/request/input.d.ts

@@ -1,3 +1,4 @@
+import { type ToolPermissionMode } from "../../capabilities/tool-permission-mode.js";
 import type { RunRequestMessage } from "./contracts.js";
 export declare function parseRequestInput(msg: RunRequestMessage): {
     requestId: string;
@@ -6,5 +7,5 @@ export declare function parseRequestInput(msg: RunRequestMessage): {
     rawAttachments: unknown;
     rawAgentMode: unknown;
     rawModelPreference: unknown;
-    toolPermissionMode: "full_access" | "ask";
+    toolPermissionMode: ToolPermissionMode;
 };

package/dist/src/runtime/request/input.js

@@ -1,3 +1,4 @@
+import { resolveToolPermissionMode, } from "../../capabilities/tool-permission-mode.js";
 export function parseRequestInput(msg) {
     return {
         requestId: msg.requestId,
@@ -13,9 +14,3 @@ export function parseRequestInput(msg) {
         toolPermissionMode: resolveToolPermissionMode(msg.toolPermissionMode),
     };
 }
-function resolveToolPermissionMode(value) {
-    const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
-    return normalized === "full_access" || normalized === "full"
-        ? "full_access"
-        : "ask";
-}

package/dist/src/runtime/request/role-call-planner-events.js

@@ -1,6 +1,7 @@
 import { projectRequestPlanCommit, } from "./plan-event-projection.js";
 import { consumeUnexpectedThenable } from "../orchestration/synchronous-boundary.js";
 import { createRequestPlanEventPresentation } from "./planner-plan-events.js";
+import { projectRootWorkPlanCommit } from "./root-plan-event-projection.js";
 import { traceRequestPlannerEventsEmitted, traceRequestPlannerEventsFailed, traceRequestPlannerEventsProjected, } from "./role-call-planner-event-diagnostics.js";
 const REQUEST_PLANNER_EVENT_EMISSION_FAILURE_MESSAGE = "One or more canonical Planner plan events could not be emitted.";
 const ROLE_CALL_PLAN_EVENT_PRESENTATION = createRequestPlanEventPresentation({
@@ -11,6 +12,9 @@ const ROLE_CALL_PLAN_EVENT_PRESENTATION = createRequestPlanEventPresentation({
  * canonical plan. It never proposes work or changes role-call state.
  */
 export function projectRequestPlannerRoleCallCommit(commit) {
+    if (commit.effect.type === "model_work_plan_updated") {
+        return projectRootWorkPlanCommit(commit, ROLE_CALL_PLAN_EVENT_PRESENTATION);
+    }
     if (commit.effect.type !== "child_opened" &&
         commit.effect.type !== "child_returned") {
         return Object.freeze([]);

package/dist/src/runtime/request/role-executor-composition.js

@@ -49,11 +49,12 @@ const SUPERVISOR_WORKER_V1_POLICY_DEFINITION = Object.freeze({
 });
 const EXECUTION_AGENT_V1_POLICY_DEFINITION = Object.freeze({
     id: "execution-agent-v1",
-    version: 1,
+    version: 2,
     rootContract: EXECUTION_AGENT_ROOT_CONTRACT,
     roleExecutors: EXECUTION_AGENT_ROLE_EXECUTORS,
     capabilityAuthorities: Object.freeze(["root"]),
     terminalTextMode: "exact",
+    modelWorkPlanAuthority: "root",
 });
 export const SUPERVISOR_WORKER_V1_EXECUTION_POLICY = compileSupervisorWorkerV1Policy();
 export const EXECUTION_AGENT_V1_EXECUTION_POLICY = compileExecutionPolicy(EXECUTION_AGENT_V1_POLICY_DEFINITION);
@@ -83,6 +84,9 @@ function compileExecutionPolicy(definition) {
         rootContractId: definition.rootContract.contractId,
         availableSubordinateContractIds: definition.roleExecutors.roleIds,
         capabilityAuthorities: definition.capabilityAuthorities,
+        ...(definition.modelWorkPlanAuthority
+            ? { modelWorkPlanAuthority: definition.modelWorkPlanAuthority }
+            : {}),
         ...(definition.terminalTextMode !== undefined
             ? { terminalTextMode: definition.terminalTextMode }
             : {}),
@@ -99,6 +103,9 @@ function compileExecutionPolicy(definition) {
             ...definition.roleExecutors.roleIds,
         ]),
         capabilityAuthorities: Object.freeze([...definition.capabilityAuthorities]),
+        ...(definition.modelWorkPlanAuthority
+            ? { modelWorkPlanAuthority: definition.modelWorkPlanAuthority }
+            : {}),
         ...(definition.terminalTextMode !== undefined
             ? { terminalTextMode: definition.terminalTextMode }
             : {}),
@@ -114,6 +121,7 @@ function sameAuthority(left, right) {
         left.version === right.version &&
         left.definitionHash === right.definitionHash &&
         left.rootContractId === right.rootContractId &&
+        left.modelWorkPlanAuthority === right.modelWorkPlanAuthority &&
         sameOrderedValues(left.availableSubordinateContractIds, right.availableSubordinateContractIds) &&
         sameOrderedValues(left.capabilityAuthorities, right.capabilityAuthorities) &&
         (left.terminalTextMode ?? "normalized") ===

package/dist/src/runtime/request/root-contract.d.ts

@@ -1,4 +1,5 @@
 import type { ModelStep } from "../../shared/model-steps.js";
+import type { ModelWorkPlanUpdate } from "../orchestration/role-calls/work-plan-contracts.js";
 import type { ChatMessage } from "../../model-gateway/types.js";
 import type { MemoryRecallDecision } from "../steps/memory-recall-decision.js";
 import type { RequestToolResultsView } from "../context/request-tool-results.js";
@@ -15,7 +16,7 @@ export type RootContractCallIdentity = Readonly<{
     depth: number;
     invocationAttempt: number;
 }>;
-export type RootContractDecision = MemoryRecallDecision | Readonly<{
+type RootContractAction = MemoryRecallDecision | Readonly<{
     action: "respond";
     responseRecommendation?: string;
     acknowledgement?: string;
@@ -64,6 +65,9 @@ export type RootContractDecision = MemoryRecallDecision | Readonly<{
     acknowledgement?: undefined;
     title?: undefined;
 }>;
+export type RootContractDecision = RootContractAction & Readonly<{
+    workPlan?: ModelWorkPlanUpdate;
+}>;
 export type RootContractDecisionOutcome = Readonly<{
     decision: RootContractDecision;
     steeringVersion: number;
@@ -104,3 +108,4 @@ export type CompiledExecutionPolicy<TRequest> = Readonly<{
     rootContract: RootContractAdapter<TRequest>;
     roleExecutors: RoleExecutorRegistry<TRequest, RequestRoleExecutionHandoff>;
 }>;
+export {};

package/dist/src/runtime/request/root-execution-kernel.js

@@ -9,6 +9,7 @@ import { projectRequestSteeringSnapshot, resolveRequestSteeringInbox, } from "./
 import { traceSupervisorRootAcknowledgementPublished, traceSupervisorRootActivationFailed, traceSupervisorRootActivationStarted, traceSupervisorRootInvocationSuperseded, traceSupervisorRootResponseSuperseded, } from "./supervisor-root-execution-diagnostics.js";
 import { bindSupervisorObservationHandoff, projectSupervisorFinalObservation, } from "./root-observation-handoff.js";
 import { performRootMemoryRecall } from "./root-memory-recall.js";
+import { applyRootModelWorkPlan } from "./root-plan-update.js";
 import { projectRootMemoryRecallMessage } from "../long-term-memory/recall-context.js";
 import { createPlainRootAuthoredResponse } from "../orchestration/final-response/authoring-contract.js";
 const CONTINUE_ROOT_EXECUTION = Object.freeze({
@@ -176,6 +177,22 @@ class RootExecutionSession {
     }
     async executeDecision(activation, attempt) {
         const { decision } = activation;
+        if (decision.workPlan) {
+            attempt.failureStage = "apply_root_transition";
+            const updated = await applyRootModelWorkPlan({
+                request: this.request,
+                ledger: this.ledger,
+                head: activation.head,
+                call: activation.call,
+                steeringVersion: activation.decisionSteeringVersion,
+                update: decision.workPlan,
+            });
+            if (!updated)
+                return CONTINUE_ROOT_EXECUTION;
+            activation = { ...activation, ...updated };
+            attempt.head = updated.head;
+            attempt.call = updated.call;
+        }
         if (decision.action === "recall_memory") {
             attempt.failureStage = "recall_memory";
             await performRootMemoryRecall({

package/dist/src/runtime/request/root-plan-event-projection.d.ts

@@ -0,0 +1,3 @@
+import type { RoleCallLedgerCommit } from "../orchestration/role-calls/index.js";
+import { type RequestPlanClientEvent, type RequestPlanEventPresentation } from "./plan-event-projection.js";
+export declare function projectRootWorkPlanCommit(commit: RoleCallLedgerCommit, presentation: RequestPlanEventPresentation<RequestPlanClientEvent>): readonly RequestPlanClientEvent[];

package/dist/src/runtime/request/root-plan-event-projection.js

@@ -0,0 +1,32 @@
+import { projectRequestPlanCommit, } from "./plan-event-projection.js";
+export function projectRootWorkPlanCommit(commit, presentation) {
+    if (commit.effect.type !== "model_work_plan_updated")
+        return [];
+    return projectRequestPlanCommit({
+        previousState: projectRootPlanState(commit.previousHead.state),
+        state: projectRootPlanState(commit.head.state),
+        presentation,
+    });
+}
+function projectRootPlanState(state) {
+    const plan = state.calls.find((call) => call.callId === state.rootCallId)?.adoptedWorkPlan;
+    if (!plan)
+        return {};
+    // Namespace only presentation IDs; canonical graph node identifiers retain their exact bounds.
+    const itemId = (localId) => `${plan.sourceResultRef}:${localId}`;
+    return {
+        plan: {
+            definition: {
+                summary: plan.definition.summary,
+                items: plan.definition.items.map((item) => ({
+                    itemId: itemId(item.itemId),
+                    title: item.title,
+                })),
+            },
+            itemStates: plan.itemStates.map((item) => ({
+                itemId: itemId(item.itemId),
+                status: item.status,
+            })),
+        },
+    };
+}

package/dist/src/runtime/request/root-plan-update.d.ts

@@ -0,0 +1,15 @@
+import { type RoleCallFrame, type RoleCallLedger, type RoleCallLedgerHead } from "../orchestration/role-calls/index.js";
+import type { ModelWorkPlanUpdate } from "../orchestration/role-calls/work-plan-contracts.js";
+import type { RequestExecutionScope } from "./execution-scope.js";
+/** Commit the model's declaration, not the eventual outcome of its paired action. */
+export declare function applyRootModelWorkPlan(params: {
+    request: RequestExecutionScope;
+    ledger: RoleCallLedger;
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+    steeringVersion: number;
+    update: ModelWorkPlanUpdate;
+}): Promise<Readonly<{
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+}> | undefined>;

package/dist/src/runtime/request/root-plan-update.js

@@ -0,0 +1,20 @@
+import { resolveRoleCallTransactions, } from "../orchestration/role-calls/index.js";
+import { resolveRequestSteeringInbox } from "./request-steering.js";
+/** Commit the model's declaration, not the eventual outcome of its paired action. */
+export async function applyRootModelWorkPlan(params) {
+    params.request.abortSignal.throwIfAborted();
+    const steering = resolveRequestSteeringInbox(params.request.requestSteering);
+    if (!steering.isCurrent(params.steeringVersion))
+        return undefined;
+    const result = await resolveRoleCallTransactions(params.ledger).updateModelWorkPlan({
+        expectedHead: params.head,
+        callId: params.call.callId,
+        invocationAttempt: params.call.activationCount,
+        update: params.update,
+    });
+    if (!result.ok)
+        throw new Error(`role_call_ledger_rejected:${result.issueCode}`);
+    const head = result.commit.head;
+    const call = head.state.calls.find((candidate) => candidate.callId === params.call.callId);
+    return { head, call };
+}

package/dist/src/runtime/request/worker-capability-composition.d.ts

@@ -6,6 +6,7 @@ import type { ExecutionPolicyAuthoritySnapshot } from "../orchestration/role-cal
 import type { RequestCapabilityCompositionView, RequestCapabilityExecutionView } from "./execution-scope.js";
 type RequestWorkerCapabilityProviderParams<TRequest> = Readonly<{
     request: TRequest;
+    requestWorkingDirectory?: string;
     executionPolicyAuthority?: ExecutionPolicyAuthoritySnapshot;
     requestAttachments?: readonly ToolRequestAttachment[];
     runtimeConfig?: RuntimeConfig;

package/dist/src/runtime/request/worker-capability-composition.js

@@ -14,6 +14,8 @@ export function createRequestWorkerCapabilityProvider(params) {
     function getRequestToolRegistry() {
         requestToolRegistry ??= createRequestRuntimeToolRegistry({
             request: params.request,
+            requestWorkingDirectory: params.requestWorkingDirectory,
+            toolPermissionMode: params.request.toolPermissionMode,
             ...(params.requestAttachments
                 ? { requestAttachments: params.requestAttachments }
                 : {}),

package/dist/src/runtime/runtime-environment.d.ts

@@ -5,6 +5,7 @@ export declare function createRuntimeEnvironment(config: RuntimeConfig, override
     services: Readonly<{
         config: RuntimeConfig;
         sessions: import("./ports.js").SessionStore;
+        projects?: import("./projects/contracts.js").RuntimeProjectService;
         attachments: import("./index.js").RuntimeAttachmentStore;
         tools: import("./ports.js").ToolRegistry;
         models: import("./ports.js").ModelGatewayClient;

package/dist/src/runtime/runtime-environment.js

@@ -1,3 +1,4 @@
+import { createRuntimeProjectService } from "./projects/service.js";
 import { createDefaultAttachmentStore, createDefaultEventSinkFactory, createDefaultModelGatewayClient, createDefaultLongTermMemoryService, createDefaultSessionStore, createDefaultToolRegistry, } from "./default-environment-adapters.js";
 import { createBoundRuntimeRequestHandler } from "./request/bound-runtime-handler.js";
 import { createModelSessionMemoryCompactor } from "./context/session-memory/index.js";
@@ -35,6 +36,7 @@ export function createRuntimeEnvironment(config, overrides = {}) {
     const services = Object.freeze({
         config,
         sessions: sessionLifecycle.store,
+        projects: createRuntimeProjectService(config, sessionLifecycle.store),
         attachments,
         tools,
         models,

package/dist/src/runtime/steps/auditor-decision/advisory-receipt.d.ts

@@ -0,0 +1,32 @@
+import type { AuditorAssignment, AuditorDecision } from "./contracts.js";
+export declare const AUDITOR_ADVISORY_KIND = "runtime_execution_agent_auditor_advisory_v1";
+declare const EVIDENCE_BINDING_KIND = "runtime_auditor_evidence_binding_v1";
+export type AuditorAdvisoryReceipt = Readonly<{
+    auditId: string;
+    verdict: "pass" | "gaps" | "needs_evidence" | "failed";
+    requestedEvidenceIds: readonly string[];
+    evidenceBinding: Readonly<{
+        kind: typeof EVIDENCE_BINDING_KIND;
+        workFingerprint: string;
+        selectedEvidenceIds: readonly string[];
+        bundleFingerprint: string | null;
+    }>;
+}>;
+export declare function settleAuditorAdvisory(assignment: AuditorAssignment, decision: AuditorDecision): Readonly<{
+    kind: "terminal";
+    outcome: "failed";
+    summary: string;
+}> | Readonly<{
+    kind: "terminal";
+    outcome: "completed";
+    summary: string;
+}>;
+export declare function serializeAuditorAdvisory(assignment: AuditorAssignment, decision: AuditorDecision): string;
+export declare function isAuditorAdvisorySummaryAdmissible(summary: string): boolean;
+export declare function failedAuditorAdvisory(assignment: AuditorAssignment, reason: string): Readonly<{
+    kind: "terminal";
+    outcome: "failed";
+    summary: string;
+}>;
+export declare function readAuditorAdvisoryReceipt(summary: string): AuditorAdvisoryReceipt | undefined;
+export {};

package/dist/src/runtime/steps/auditor-decision/advisory-receipt.js

@@ -0,0 +1,106 @@
+import { ROLE_CALL_RESULT_MAX_LENGTH } from "../../orchestration/role-calls/index.js";
+import { fingerprintAuditorBundle } from "./evidence-inventory.js";
+export const AUDITOR_ADVISORY_KIND = "runtime_execution_agent_auditor_advisory_v1";
+const EVIDENCE_BINDING_KIND = "runtime_auditor_evidence_binding_v1";
+export function settleAuditorAdvisory(assignment, decision) {
+    const summary = serializeAuditorAdvisory(assignment, decision);
+    if (!isAuditorAdvisorySummaryAdmissible(summary)) {
+        return failedAuditorAdvisory(assignment, "auditor_result_not_admissible");
+    }
+    return Object.freeze({
+        kind: "terminal",
+        outcome: "completed",
+        summary,
+    });
+}
+export function serializeAuditorAdvisory(assignment, decision) {
+    return JSON.stringify({
+        kind: AUDITOR_ADVISORY_KIND,
+        authority: "model_advisory",
+        presenceEffect: "passive_result_not_execution_or_completion",
+        ...decision,
+        evidenceBinding: binding(assignment),
+    });
+}
+export function isAuditorAdvisorySummaryAdmissible(summary) {
+    return summary.length <= ROLE_CALL_RESULT_MAX_LENGTH;
+}
+export function failedAuditorAdvisory(assignment, reason) {
+    return Object.freeze({
+        kind: "terminal",
+        outcome: "failed",
+        summary: JSON.stringify({
+            kind: AUDITOR_ADVISORY_KIND,
+            authority: "runtime_validation",
+            presenceEffect: "passive_result_not_execution_or_completion",
+            auditId: assignment.auditId,
+            verdict: "failed",
+            requestedEvidenceIds: [],
+            reason,
+            evidenceBinding: binding(assignment),
+        }),
+    });
+}
+export function readAuditorAdvisoryReceipt(summary) {
+    let value;
+    try {
+        value = JSON.parse(summary);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value) || value.kind !== AUDITOR_ADVISORY_KIND)
+        return undefined;
+    if (typeof value.auditId !== "string")
+        return undefined;
+    if (!isAuditorVerdict(value.verdict))
+        return undefined;
+    if (!hasAdvisoryAuthority(value.authority, value.verdict))
+        return undefined;
+    if (!isStringArray(value.requestedEvidenceIds))
+        return undefined;
+    const source = value.evidenceBinding;
+    if (!isRecord(source) || source.kind !== EVIDENCE_BINDING_KIND)
+        return undefined;
+    if (typeof source.workFingerprint !== "string")
+        return undefined;
+    if (!isStringArray(source.selectedEvidenceIds))
+        return undefined;
+    const expectedBundle = source.selectedEvidenceIds.length > 0
+        ? fingerprintAuditorBundle(source.workFingerprint, source.selectedEvidenceIds)
+        : null;
+    if (source.bundleFingerprint !== expectedBundle)
+        return undefined;
+    return value;
+}
+function binding(assignment) {
+    return Object.freeze({
+        kind: EVIDENCE_BINDING_KIND,
+        workFingerprint: assignment.workFingerprint,
+        selectedEvidenceIds: assignment.selectedEvidenceIds,
+        bundleFingerprint: assignment.selectedEvidenceIds.length > 0
+            ? fingerprintAuditorBundle(assignment.workFingerprint, assignment.selectedEvidenceIds)
+            : null,
+    });
+}
+function isAuditorVerdict(value) {
+    return (value === "pass" ||
+        value === "gaps" ||
+        value === "needs_evidence" ||
+        value === "failed");
+}
+function hasAdvisoryAuthority(authority, verdict) {
+    if (verdict === "failed")
+        return authority === "runtime_validation";
+    return authority === "model_advisory";
+}
+function isStringArray(value) {
+    if (!Array.isArray(value))
+        return false;
+    if (!value.every((item) => typeof item === "string"))
+        return false;
+    return new Set(value).size === value.length;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/src/runtime/steps/auditor-decision/advisory-result-budget.d.ts

@@ -0,0 +1,5 @@
+import { type AuditorAssignment } from "./contracts.js";
+export declare class AuditorAdvisoryCapacityError extends Error {
+    constructor();
+}
+export declare function getAuditorAdvisoryDescriptionMaxLength(assignment: AuditorAssignment): number;

package/dist/src/runtime/steps/auditor-decision/advisory-result-budget.js

@@ -0,0 +1,40 @@
+import { ROLE_CALL_RESULT_MAX_LENGTH } from "../../orchestration/role-calls/index.js";
+import { serializeAuditorAdvisory } from "./advisory-receipt.js";
+import { AUDITOR_DECISION_TEXT_MAX_LENGTH, } from "./contracts.js";
+// JSON uses at most six UTF-16 units per Unicode code point, including escapes.
+const JSON_STRING_MAX_ESCAPE_CHARS_PER_CODE_POINT = 6;
+export class AuditorAdvisoryCapacityError extends Error {
+    constructor() {
+        super("auditor_result_metadata_exceeds_budget");
+        this.name = "AuditorAdvisoryCapacityError";
+    }
+}
+export function getAuditorAdvisoryDescriptionMaxLength(assignment) {
+    const ids = assignment.inventory.map(({ executionId }) => executionId);
+    // All IDs in one partition is at least as large as any valid split. Reserving
+    // every ID in the requested bundle preserves every offered evidence choice.
+    const reservedEnvelope = serializeAuditorAdvisory(assignment, {
+        auditId: assignment.auditId,
+        verdict: "needs_evidence",
+        criterionIds: assignment.criterionIds,
+        gaps: assignment.criterionIds.map((criterionId) => ({
+            criterionId,
+            description: "",
+        })),
+        neededEvidenceIds: ids,
+        notNeededEvidenceIds: [],
+        requestedEvidenceIds: ids,
+    });
+    const remainingChars = ROLE_CALL_RESULT_MAX_LENGTH - reservedEnvelope.length;
+    const escapedCharsPerDescriptionUnit = JSON_STRING_MAX_ESCAPE_CHARS_PER_CODE_POINT *
+        assignment.criterionIds.length;
+    const maxLength = Math.min(AUDITOR_DECISION_TEXT_MAX_LENGTH, Math.floor(remainingChars / escapedCharsPerDescriptionUnit));
+    if (!hasAuditorDescriptionCapacity(maxLength))
+        throw new AuditorAdvisoryCapacityError();
+    return maxLength;
+}
+function hasAuditorDescriptionCapacity(maxLength) {
+    if (!Number.isSafeInteger(maxLength))
+        return false;
+    return maxLength >= 1;
+}

package/dist/src/runtime/steps/auditor-decision/audit-input-state.d.ts

@@ -0,0 +1,12 @@
+import type { RoleCallLedgerHead } from "../../orchestration/role-calls/index.js";
+import { type AuditorCapabilityEvidence } from "./contracts.js";
+export type AuditorInputState = Readonly<{
+    available: boolean;
+    reason: string;
+    workFingerprint: string;
+    pendingEvidenceIds: readonly string[] | null;
+    reviewedBundleFingerprints: readonly string[];
+    reviewedEvidenceBundles: readonly (readonly string[])[];
+    reviewedBundleCount: number;
+}>;
+export declare function projectAuditorInputState(head: RoleCallLedgerHead, callerCallId: string, steeringVersion: number, criterionIds?: readonly string[], suppliedEvidence?: readonly AuditorCapabilityEvidence[]): AuditorInputState;