@abot-ai/runtime 1.3.1 → 1.4.0

package/dist/src/runtime/context/capability-brief-readmission.d.ts

@@ -0,0 +1,21 @@
+import type { ToolAvailabilityEntry } from "../../capabilities/tool-types.js";
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { ToolAvailabilityOverviewGroup } from "../../plugin-sdk/tool-availability-overview.js";
+import type { ModelStepContextCompactionController } from "../model/model-step-port.js";
+import { type CapabilityBriefProjection } from "./capability-brief.js";
+import type { RequestContextBudget } from "./request-context-contracts.js";
+export type CapabilityBriefReadmissionOptions = Readonly<{
+    entries?: readonly ToolAvailabilityEntry[];
+    groups: readonly ToolAvailabilityOverviewGroup[];
+    budget: RequestContextBudget;
+    format?: Readonly<{
+        schema: unknown;
+    }>;
+    additionalBudgetMessages?: readonly ChatMessage[];
+}>;
+/** Re-admits an existing optional brief against the current attempt's context. */
+export declare function createCapabilityBriefReadmissionController(params: Readonly<{
+    controller: ModelStepContextCompactionController;
+    resolveOptions(): CapabilityBriefReadmissionOptions;
+    onReadmitted?(projection: CapabilityBriefProjection): void;
+}>): ModelStepContextCompactionController;

package/dist/src/runtime/context/capability-brief-readmission.js

@@ -0,0 +1,47 @@
+import { isCapabilityBriefMessage, projectCapabilityBriefAtHeadroom, } from "./capability-brief.js";
+import { resolveCapabilityBriefMessageHeadroom } from "./capability-brief-budget.js";
+/** Re-admits an existing optional brief against the current attempt's context. */
+export function createCapabilityBriefReadmissionController(params) {
+    const { controller } = params;
+    return Object.freeze({
+        get compactionScope() {
+            return controller.compactionScope;
+        },
+        project(messages) {
+            const projected = controller.project(messages);
+            const briefIndex = projected.findIndex(isCapabilityBriefMessage);
+            if (briefIndex < 0)
+                return projected;
+            const withoutBrief = projected.filter((_, index) => index !== briefIndex);
+            const options = params.resolveOptions();
+            const headroom = resolveCapabilityBriefMessageHeadroom({
+                messages: [
+                    ...withoutBrief,
+                    ...(options.additionalBudgetMessages ?? []),
+                ],
+                budget: options.budget,
+                format: options.format,
+            });
+            const replacement = projectCapabilityBriefAtHeadroom({
+                entries: options.entries,
+                groups: options.groups,
+                headroom,
+                tokenEstimation: options.budget.tokenEstimation,
+            });
+            if (replacement.message?.content === projected[briefIndex].content) {
+                return projected;
+            }
+            params.onReadmitted?.(replacement);
+            if (!replacement.message)
+                return withoutBrief;
+            return [
+                ...projected.slice(0, briefIndex),
+                replacement.message,
+                ...projected.slice(briefIndex + 1),
+            ];
+        },
+        prepare(messages) {
+            return controller.prepare(messages);
+        },
+    });
+}

package/dist/src/runtime/context/capability-brief.d.ts

@@ -1,10 +1,10 @@
-import type { ChatMessage } from "../../model-gateway/types.js";
+import type { ChatMessage, ModelTokenEstimationConfig } from "../../model-gateway/types.js";
 import type { ToolAvailabilityEntry } from "../../capabilities/tool-types.js";
 import { type ToolAvailabilityOverviewGroup, type ToolAvailabilityOverviewLevel } from "../../plugin-sdk/tool-availability-overview.js";
 import type { projectRequestContext } from "./request-context.js";
 export declare const CAPABILITY_BRIEF_KIND = "runtime_capability_brief_v1";
 export declare const CAPABILITY_BRIEF_MAX_TOKENS = 512;
-export type CapabilityBriefLevel = ToolAvailabilityOverviewLevel | "none";
+export type CapabilityBriefLevel = ToolAvailabilityOverviewLevel | "descriptions" | "none";
 export type CapabilityBriefProjection = Readonly<{
     level: CapabilityBriefLevel;
     message?: ChatMessage;
@@ -20,6 +20,13 @@ export declare function projectCapabilityBrief(params: Readonly<{
     context: ContextInput;
     additionalBudgetMessages?: readonly ChatMessage[];
 }>): CapabilityBriefProjection;
+/** Selects complete availability within the current invocation's input budget. */
+export declare function projectCapabilityBriefAtHeadroom(params: Readonly<{
+    entries?: readonly ToolAvailabilityEntry[];
+    groups: readonly ToolAvailabilityOverviewGroup[];
+    headroom: number;
+    tokenEstimation?: ModelTokenEstimationConfig;
+}>): CapabilityBriefProjection;
 /** Consumers explicitly remove this optional reference at narrower phases. */
 export declare function isCapabilityBriefMessage(message: ChatMessage): boolean;
 export {};

package/dist/src/runtime/context/capability-brief.js

@@ -1,20 +1,34 @@
 import { buildToolAvailabilityOverview, } from "../../plugin-sdk/tool-availability-overview.js";
-import { assessRequestMessagesBudget } from "./request-context-budget.js";
+import { resolveCapabilityBriefHeadroom } from "./capability-brief-budget.js";
+import { buildCapabilityDescriptions } from "./capability-descriptions.js";
 import { estimateMessageTokens } from "./token-estimator.js";
 export const CAPABILITY_BRIEF_KIND = "runtime_capability_brief_v1";
 export const CAPABILITY_BRIEF_MAX_TOKENS = 512;
 const CAPABILITY_BRIEF_PREFIX = `${CAPABILITY_BRIEF_KIND}\n`;
 /** Optional availability metadata admitted against the full context estimate. */
 export function projectCapabilityBrief(params) {
-    const budgetTokens = resolveCapabilityBriefBudget(params);
+    return projectCapabilityBriefAtHeadroom({
+        entries: params.entries,
+        groups: params.groups,
+        headroom: resolveCapabilityBriefHeadroom(params),
+        tokenEstimation: params.context.budget.tokenEstimation,
+    });
+}
+/** Selects complete availability within the current invocation's input budget. */
+export function projectCapabilityBriefAtHeadroom(params) {
+    const headroom = Math.max(0, params.headroom);
+    const compactBudgetTokens = Math.min(CAPABILITY_BRIEF_MAX_TOKENS, headroom);
     if (params.groups.length === 0) {
-        return omittedBrief(budgetTokens, "empty_catalog");
+        return omittedBrief(compactBudgetTokens, "empty_catalog");
     }
     const levels = hasCompleteCapabilityBriefEntries(params.entries, params.groups)
-        ? ["detailed", "titles", "groups"]
+        ? ["descriptions", "detailed", "titles", "groups"]
         : ["groups"];
     for (const level of levels) {
-        const body = buildToolAvailabilityOverview(params.entries ?? [], params.groups, level);
+        const budgetTokens = level === "descriptions" ? headroom : compactBudgetTokens;
+        const body = level === "descriptions"
+            ? buildCapabilityDescriptions(params.entries ?? [])
+            : buildToolAvailabilityOverview(params.entries ?? [], params.groups, level);
         const message = Object.freeze({
             role: "system",
             content: [
@@ -24,7 +38,7 @@ export function projectCapabilityBrief(params) {
                 body,
             ].join("\n"),
         });
-        const estimatedTokens = estimateMessageTokens(message, params.context.budget.tokenEstimation);
+        const estimatedTokens = estimateMessageTokens(message, params.tokenEstimation);
         if (!fitsCapabilityBriefBudget(estimatedTokens, budgetTokens))
             continue;
         return Object.freeze({
@@ -35,7 +49,7 @@ export function projectCapabilityBrief(params) {
             reason: "complete_catalog",
         });
     }
-    return omittedBrief(budgetTokens, "insufficient_budget");
+    return omittedBrief(compactBudgetTokens, "insufficient_budget");
 }
 /** Consumers explicitly remove this optional reference at narrower phases. */
 export function isCapabilityBriefMessage(message) {
@@ -43,38 +57,6 @@ export function isCapabilityBriefMessage(message) {
         return false;
     return message.content.startsWith(CAPABILITY_BRIEF_PREFIX);
 }
-function resolveCapabilityBriefBudget(params) {
-    const { context } = params;
-    const messages = [
-        { role: "system", content: context.instructions },
-        ...(context.priorConversationMessages ?? []),
-        ...context.historyMessages,
-        ...(context.referenceMessages ?? []),
-        ...(context.referenceParts?.flatMap((part) => part.messages) ?? []),
-        ...(context.continuationMessages ?? []),
-        ...(context.continuationParts?.flatMap((part) => part.messages) ?? []),
-        {
-            role: "user",
-            content: context.prompt,
-            ...(context.attachments ? { attachments: context.attachments } : {}),
-        },
-        ...(params.additionalBudgetMessages ?? []),
-    ];
-    const { budget } = assessRequestMessagesBudget({
-        messages,
-        budget: context.budget,
-        ...(context.format ? { format: context.format } : {}),
-    });
-    // Configured methodology is added later; reserve it for the 70% threshold
-    // as well as the input ceiling. Strictly below: admission triggers on >=.
-    const instructionReserve = context.budget.configuredInstructionReserveTokens ?? 0;
-    const compactionHeadroom = budget.compactionTriggerInputTokens -
-        1 -
-        budget.estimatedInputTokens -
-        instructionReserve;
-    const admissionHeadroom = budget.availableInputTokens - budget.estimatedInputTokens;
-    return Math.max(0, Math.min(CAPABILITY_BRIEF_MAX_TOKENS, compactionHeadroom, admissionHeadroom));
-}
 function hasCompleteCapabilityBriefEntries(entries, groups) {
     if (entries === undefined)
         return false;

package/dist/src/runtime/context/capability-descriptions.d.ts

@@ -0,0 +1,3 @@
+import type { ToolAvailabilityEntry } from "../../capabilities/tool-types.js";
+/** Complete request-registry facts; neither a selected subset nor tool schemas. */
+export declare function buildCapabilityDescriptions(entries: readonly ToolAvailabilityEntry[]): string;

package/dist/src/runtime/context/capability-descriptions.js

@@ -0,0 +1,23 @@
+/** Complete request-registry facts; neither a selected subset nor tool schemas. */
+export function buildCapabilityDescriptions(entries) {
+    const ordered = [...entries].sort(compareCapabilityDescriptions);
+    return JSON.stringify(ordered.map(({ toolName, operationId, summary, catalogGroups }) => ({
+        toolName,
+        operationId,
+        summary,
+        catalogGroups: [...new Set(catalogGroups)].sort(compareAscii),
+    })));
+}
+function compareCapabilityDescriptions(left, right) {
+    const byOperation = compareAscii(left.operationId, right.operationId);
+    if (byOperation !== 0)
+        return byOperation;
+    return compareAscii(left.toolName, right.toolName);
+}
+function compareAscii(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}

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

@@ -1,3 +1,4 @@
+import { loadRuntimeCapabilityPlugins } from "./plugins/runtime-capability-plugins.js";
 import { join } from "node:path";
 import { buildContextBuckets, buildContextWindow } from "../sessions/index.js";
 import { createModelGatewayClient, embedModelGateway, invokeModelGateway, invokeRawModelGateway, } from "../model-gateway/client.js";
@@ -9,7 +10,7 @@ import { createSourceWorkspaceProvider } from "./adapters/source-workspace-provi
 import { createRuntimeEventBus } from "./events/runtime-emitter.js";
 import { configureDebugLogger } from "./observability/debug-logger.js";
 import { createConfiguredToolRegistry } from "./capabilities/configured-tool-registry.js";
-import { loadBundledRuntimePlugins, loadConfiguredRuntimePlugins, runtimePluginsToToolModules, } from "./plugins/loader.js";
+import { runtimePluginsToToolModules } from "./plugins/loader.js";
 import { createSchedulingToolModule } from "./capabilities/scheduling/tool-module.js";
 import { createFileLongTermMemoryRepository } from "./adapters/long-term-memory/file-repository.js";
 import { createInMemoryLongTermMemoryRepository } from "./adapters/long-term-memory/in-memory-repository.js";
@@ -29,9 +30,7 @@ export function createDefaultConversationContextProvider() {
     };
 }
 export function createDefaultToolRegistry(config, scheduling) {
-    const plugins = config
-        ? loadConfiguredRuntimePlugins(config)
-        : loadBundledRuntimePlugins();
+    const plugins = loadRuntimeCapabilityPlugins(config);
     return createConfiguredToolRegistry(config, [
         ...runtimePluginsToToolModules(plugins),
         ...(config && scheduling

package/dist/src/runtime/local-application.d.ts

@@ -11,12 +11,30 @@ export declare function createLocalRuntimeApplication(config?: RuntimeConfig, op
         sessions: import("./ports.js").SessionStore;
         attachments: import("./index.js").RuntimeAttachmentStore;
         scheduler: Omit<import("./scheduler/contracts.js").SchedulerService, "stop" | "start">;
+        projects: Readonly<{
+            list: () => Promise<readonly import("./projects/contracts.js").RuntimeProject[]>;
+            get: (id: string) => Promise<import("./projects/contracts.js").RuntimeProject | null>;
+            create: (input: {
+                name?: string;
+                directory: string;
+            }) => Promise<import("./projects/contracts.js").RuntimeProject>;
+            browseFolders: (input?: {
+                path?: string;
+                cursor?: string;
+            }) => Promise<import("./projects/contracts.js").ProjectFolderPage>;
+            createSession: (projectId: string) => Promise<{
+                sessionId: string;
+                project: import("../sessions/project-binding.js").SessionProject;
+            }>;
+        }>;
         config: RuntimeConfig;
     }>;
     requests: RuntimeRequestHandler;
     start: () => Promise<void>;
     stop(): Promise<void>;
     getOwnership: () => "owner" | "client" | undefined;
+    isOwnerIdle: () => boolean;
+    stopIfIdle(): Promise<boolean>;
     subscribeScheduledEvents: (listener: (event: Record<string, unknown>) => void) => () => void;
 }>;
 export type LocalRuntimeApplication = ReturnType<typeof createLocalRuntimeApplication>;

package/dist/src/runtime/local-application.js

@@ -76,6 +76,18 @@ export function createLocalRuntimeApplication(config = loadRuntimeConfig(), opti
             }
         },
         getOwnership: () => connection?.ownership,
+        isOwnerIdle: () => !stopped && connection?.isOwnerIdle() === true,
+        stopIfIdle() {
+            if (stopped)
+                return Promise.resolve(false);
+            if (!connection?.isOwnerIdle())
+                return Promise.resolve(false);
+            // Do not await startup between checking admission and closing intake.
+            const closing = connection.closeIfIdle();
+            stopped = true;
+            client.close();
+            return closing;
+        },
         subscribeScheduledEvents: client.subscribe.bind(client),
     });
 }

package/dist/src/runtime/local-host/app-service-dispatch.d.ts

@@ -1,5 +1,6 @@
 import type { RuntimeEnvironmentServices } from "../composition.js";
 export declare const LOCAL_SESSION_METHODS: readonly ["getOrCreateSession", "getAllSessions", "listSessions", "getSessionById", "getSessionSnapshot", "getRequestReplayById", "updateSessionTitle", "updateSessionRuntimeMode", "appendMessage", "appendContextEntry", "upsertArtifactPaths", "startRequestStream", "appendRequestEvent", "deleteSession", "deleteSessionWithStats", "resetSession", "clearSessionMessages", "deleteMessage", "deleteMessageWithStats", "compareAndSwapSessionMemoryCheckpoint"];
+export declare const LOCAL_PROJECT_METHODS: readonly ["list", "get", "create", "browseFolders", "createSession"];
 export declare const LOCAL_ATTACHMENT_METHODS: readonly ["saveAttachment", "validateAttachmentReferences", "resolveAttachment", "deleteAttachment", "deleteSessionAttachments"];
 export declare const LOCAL_SCHEDULER_METHODS: readonly ["tick", "create", "list", "get", "update", "pause", "resume", "cancel", "runNow", "deleteSession", "listRuns"];
 export declare function dispatchLocalServiceCall(services: RuntimeEnvironmentServices, method: string, args: readonly unknown[]): Promise<unknown>;

package/dist/src/runtime/local-host/app-service-dispatch.js

@@ -20,6 +20,13 @@ export const LOCAL_SESSION_METHODS = [
     "deleteMessageWithStats",
     "compareAndSwapSessionMemoryCheckpoint",
 ];
+export const LOCAL_PROJECT_METHODS = [
+    "list",
+    "get",
+    "create",
+    "browseFolders",
+    "createSession",
+];
 export const LOCAL_ATTACHMENT_METHODS = [
     "saveAttachment",
     "validateAttachmentReferences",
@@ -56,6 +63,8 @@ export async function dispatchLocalServiceCall(services, method, args) {
         throw new Error("local_runtime_method_unknown");
     if (service === "sessions")
         return selectServiceMethod(services.sessions, operation, LOCAL_SESSION_METHODS)(...args);
+    if (service === "projects")
+        return selectServiceMethod(services.projects, operation, LOCAL_PROJECT_METHODS)(...args);
     if (service === "attachments")
         return selectServiceMethod(services.attachments, operation, LOCAL_ATTACHMENT_METHODS)(...args);
     if (service === "scheduler")

package/dist/src/runtime/local-host/client-services.d.ts

@@ -7,4 +7,20 @@ export declare function createLocalServiceClients(call: LocalRuntimeCallHandler)
     sessions: SessionStore;
     attachments: RuntimeAttachmentStore;
     scheduler: Omit<SchedulerService, "stop" | "start">;
+    projects: Readonly<{
+        list: () => Promise<readonly import("../projects/contracts.js").RuntimeProject[]>;
+        get: (id: string) => Promise<import("../projects/contracts.js").RuntimeProject | null>;
+        create: (input: {
+            name?: string;
+            directory: string;
+        }) => Promise<import("../projects/contracts.js").RuntimeProject>;
+        browseFolders: (input?: {
+            path?: string;
+            cursor?: string;
+        }) => Promise<import("../projects/contracts.js").ProjectFolderPage>;
+        createSession: (projectId: string) => Promise<{
+            sessionId: string;
+            project: import("../../sessions/project-binding.js").SessionProject;
+        }>;
+    }>;
 };

package/dist/src/runtime/local-host/client-services.js

@@ -1,5 +1,5 @@
 import { bindManagedSessionAttachmentDeletion } from "../session/session-attachment-deletion.js";
-import { LOCAL_SESSION_METHODS, LOCAL_ATTACHMENT_METHODS, LOCAL_SCHEDULER_METHODS, } from "./app-service-dispatch.js";
+import { LOCAL_SESSION_METHODS, LOCAL_PROJECT_METHODS, LOCAL_ATTACHMENT_METHODS, LOCAL_SCHEDULER_METHODS, } from "./app-service-dispatch.js";
 /** Projections of owner APIs; lifecycle remains with the managed application. */
 export function createLocalServiceClients(call) {
     const service = (prefix, methods) => Object.fromEntries(methods.map((method) => [
@@ -10,5 +10,6 @@ export function createLocalServiceClients(call) {
     const attachments = service("attachments", LOCAL_ATTACHMENT_METHODS);
     const scheduler = service("scheduler", LOCAL_SCHEDULER_METHODS);
     bindManagedSessionAttachmentDeletion(sessions, attachments);
-    return { sessions, attachments, scheduler };
+    const projects = service("projects", LOCAL_PROJECT_METHODS);
+    return { sessions, attachments, scheduler, projects };
 }

package/dist/src/runtime/local-host/contracts.d.ts

@@ -20,6 +20,10 @@ export type LocalRuntimeConnection = Readonly<{
     setClientHandler: (handler: LocalRuntimeCallHandler) => void;
     onClose: (listener: () => void) => () => void;
     close: () => Promise<void>;
+    /** Only the owning connection can synchronously observe its idle fence. */
+    isOwnerIdle: () => boolean;
+    /** Closes intake in the same turn as the idle check; clients never close owners. */
+    closeIfIdle: () => Promise<boolean>;
 }>;
 export type LocalRuntimeConnectionOptions = Readonly<{
     directory: string;

package/dist/src/runtime/local-host/startup-connection.js

@@ -31,20 +31,32 @@ export async function connectToRuntimeOwner(endpoint, deadline) {
                 authorization: `Bearer ${endpoint.token}`,
                 "x-abot-runtime-identity": localRuntimeIdentityHeader(endpoint.identity),
             },
-            handshakeTimeout: Math.max(1, deadline - Date.now()),
             maxPayload: 64 * 1024 * 1024,
             perMessageDeflate: false,
         });
         const peer = new LocalRuntimeRpcPeer(socket);
+        const cleanupHandshake = () => {
+            clearTimeout(startupTimer);
+            socket.removeListener("error", failed);
+            socket.removeListener("open", opened);
+        };
         const failed = (error) => {
-            peer.close();
+            cleanupHandshake();
             reject(error);
+            peer.close();
         };
-        socket.once("error", failed);
-        socket.once("open", () => {
-            socket.removeListener("error", failed);
+        const timedOut = () => failed(new Error("local_runtime_owner_start_timeout"));
+        const opened = () => {
+            if (hasRuntimeOwnerStartupDeadlineExpired(deadline)) {
+                timedOut();
+                return;
+            }
+            cleanupHandshake();
             resolve(peer);
-        });
+        };
+        const startupTimer = setTimeout(timedOut, Math.max(1, deadline - Date.now()));
+        socket.once("error", failed);
+        socket.once("open", opened);
     });
 }
 function assertRuntimeOwnerIdentity(endpoint, identity) {
@@ -52,9 +64,12 @@ function assertRuntimeOwnerIdentity(endpoint, identity) {
         throw new Error("local_runtime_identity_mismatch");
 }
 function assertRuntimeOwnerStartupTimeRemaining(deadline) {
-    if (Date.now() >= deadline)
+    if (hasRuntimeOwnerStartupDeadlineExpired(deadline))
         throw new Error("local_runtime_owner_start_timeout");
 }
+function hasRuntimeOwnerStartupDeadlineExpired(deadline) {
+    return Date.now() >= deadline;
+}
 function isTransientRuntimeOwnerHandshakeFailure(error) {
     if (!(error instanceof Error))
         return false;

package/dist/src/runtime/local-host/transport.js

@@ -41,7 +41,7 @@ async function establishRuntimeOwner(options, release) {
                     await releaseRuntimeOwnerWhenIdle(owner, release);
                 }
             }
-        });
+        }, () => owner?.isIdle?.() === true);
     }
     catch (error) {
         try {
@@ -58,10 +58,22 @@ async function establishRuntimeOwner(options, release) {
         throw error;
     }
 }
-function createConnection(peer, ownership, close) {
+function createConnection(peer, ownership, close, isOwnerIdle = () => false) {
     let shutdown;
     return Object.freeze({
         ownership,
+        isOwnerIdle: () => !shutdown && isOwnerIdle(),
+        closeIfIdle: () => {
+            if (ownership !== "owner")
+                return Promise.resolve(false);
+            if (shutdown)
+                return shutdown.then(() => true);
+            if (!isOwnerIdle())
+                return Promise.resolve(false);
+            // close() synchronously closes host intake before its first await.
+            shutdown = close();
+            return shutdown.then(() => true);
+        },
         call: (method, args) => peer.call(method, args),
         subscribe: (listener) => peer.subscribe(listener),
         setClientHandler: (handler) => peer.setHandler(handler),

package/dist/src/runtime/orchestration/role-calls/candidate-validation.js

@@ -3,6 +3,7 @@ import { createRoleCapabilitySelectionFingerprint, normalizeRoleCapabilitySelect
 import { isRoleCapabilitySelectionSupervisionState, } from "./capability-selection-supervision.js";
 import { isValidRoleCapabilitySelectionSupervision } from "./capability-selection-supervision-validation.js";
 import { validateRoleMemoryRecalls } from "./memory-recall-state-validation.js";
+import { isValidAdoptedModelWorkPlan } from "./work-plan-validation.js";
 import { isRoleOperationFingerprint, isRoleOperationOutcomeFingerprintForOutcome, isSameRoleOperationIdentity, replayRoleOperationSupervisionEvidence, } from "./operation-supervision.js";
 import { isIssuedRoleOperationSupervisionInterventionForRequest } from "./operation-supervision-issuance.js";
 import { isRoleOperationSupervisionSettlementHistoryValid, isRoleOperationSupervisionState, } from "./operation-supervision-state-validation.js";
@@ -134,7 +135,8 @@ export function validateRoleCallState(state, policy) {
             (call.parentCallId === null
                 ? call.objective !== null || call.dependencyResultRefs.length !== 0
                 : !isBoundedText(call.objective, policy.limits.maxObjectiveChars)) ||
-            !isValidCapabilitySelectionReconsideration(call, policy, state)) {
+            !isValidCapabilitySelectionReconsideration(call, policy, state) ||
+            !isValidAdoptedModelWorkPlan(state, call, policy)) {
             issues.push(issue("invalid_role_call_frame", `state.calls.${call.callId}`));
             continue;
         }
@@ -408,7 +410,7 @@ function isExecutionPolicyAuthoritySnapshot(value) {
             "rootContractId",
             "availableSubordinateContractIds",
             "capabilityAuthorities",
-        ], ["terminalTextMode"]) ||
+        ], ["terminalTextMode", "modelWorkPlanAuthority"]) ||
         typeof value.id !== "string" ||
         !/^[a-z][a-z0-9-]*$/.test(value.id) ||
         !Number.isInteger(value.version) ||
@@ -418,6 +420,7 @@ function isExecutionPolicyAuthoritySnapshot(value) {
         !isExecutionContractId(value.rootContractId) ||
         !Array.isArray(value.availableSubordinateContractIds) ||
         !Array.isArray(value.capabilityAuthorities) ||
+        (value.modelWorkPlanAuthority !== undefined && value.modelWorkPlanAuthority !== "root") ||
         (value.terminalTextMode !== undefined &&
             value.terminalTextMode !== "normalized" &&
             value.terminalTextMode !== "exact")) {

package/dist/src/runtime/orchestration/role-calls/command-decoder.js

@@ -6,6 +6,7 @@ import { isRoleCapabilityId, } from "./contracts.js";
 import { parseRoleCallPlanBinding } from "./plan.js";
 import { normalizeRoleCallResultReceipt } from "./result-receipt.js";
 import { decodeMemoryRecallCommand } from "./memory-recall-decoder.js";
+import { decodeModelWorkPlanCommand } from "./work-plan-validation.js";
 import { parseRoleCallWorkerCapabilityScope } from "./worker-capability-scope.js";
 import { isRoleCallWorkingDirectoryRoleId, normalizeEstablishedRoleCallWorkingDirectory, normalizeRoleCallWorkingDirectory, } from "./working-directory.js";
 import { exactKeys, isRecord, isRoleCapabilityDeclaredEffect, isRoleCapabilityObservedEffect, isUniqueStringArray, parseCapabilityResultReferences, parseOptionalCapabilityAdapterResult, } from "./reducer-primitives.js";
@@ -14,6 +15,8 @@ export function decodeRoleCallCommand(input) {
         return { ok: false, code: "invalid_command" };
     }
     switch (input.type) {
+        case "update_model_work_plan":
+            return decodeModelWorkPlanCommand(input);
         case "begin_memory_recall":
         case "settle_memory_recall":
             return decodeMemoryRecallCommand(input);

package/dist/src/runtime/orchestration/role-calls/command-dispatch/work-plan-transition.d.ts

@@ -0,0 +1,3 @@
+import type { RoleCallPolicy, RoleCallState, RoleCallTransitionResult } from "../contracts.js";
+import type { UpdateModelWorkPlanCommand } from "../work-plan-contracts.js";
+export declare function updateModelWorkPlan(state: RoleCallState, command: UpdateModelWorkPlanCommand, policy: RoleCallPolicy): RoleCallTransitionResult;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/work-plan-transition.js

@@ -0,0 +1,46 @@
+import { updatesNameKnownItems } from "../work-plan-validation.js";
+import { areModelWorkPlanDefinitionsEqual, resolveModelWorkPlanSourceDefinition, } from "../work-plan-source.js";
+import { commit, reject } from "../reducer-primitives.js";
+import { replaceCall } from "./call-frame-state.js";
+export function updateModelWorkPlan(state, command, policy) {
+    if (policy.authority.modelWorkPlanAuthority !== "root")
+        return reject(state, "model_work_plan_update_invalid");
+    const call = state.calls.find((candidate) => candidate.callId === command.callId);
+    if (!call || call.callId !== state.rootCallId || call.parentCallId !== null)
+        return reject(state, "model_work_plan_update_invalid");
+    if (state.activeCallId !== call.callId || call.status !== "active")
+        return reject(state, "caller_not_active");
+    if (call.activationCount !== command.invocationAttempt)
+        return reject(state, "capability_invocation_mismatch");
+    const update = command.update;
+    const definition = resolveModelWorkPlanSourceDefinition(state, call, update.sourceResultRef, policy);
+    if (!definition)
+        return reject(state, "model_work_plan_update_invalid");
+    const previous = call.adoptedWorkPlan;
+    const isCurrentSource = previous?.sourceResultRef === update.sourceResultRef;
+    if (update.mode === "progress" && !isCurrentSource)
+        return reject(state, "model_work_plan_update_invalid");
+    if (update.mode === "adopt" &&
+        !areModelWorkPlanDefinitionsEqual(update.definition, definition))
+        return reject(state, "model_work_plan_update_invalid");
+    if (!updatesNameKnownItems(definition, update.itemUpdates))
+        return reject(state, "model_work_plan_update_invalid");
+    const statusById = new Map(isCurrentSource
+        ? previous.itemStates.map((item) => [item.itemId, item.status])
+        : []);
+    for (const item of update.itemUpdates)
+        statusById.set(item.itemId, item.status);
+    const adoptedWorkPlan = {
+        sourceResultRef: update.sourceResultRef,
+        definition,
+        itemStates: definition.items.map((item) => ({
+            itemId: item.itemId,
+            status: statusById.get(item.itemId) ?? "pending",
+        })),
+    };
+    // A declaration consumes no extra activation and neither settles work nor resets supervision.
+    return commit({ ...state, calls: replaceCall(state.calls, { ...call, adoptedWorkPlan }) }, {
+        type: "model_work_plan_updated",
+        callId: call.callId,
+    });
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch.js

@@ -1,12 +1,15 @@
 import { beginCapabilityBatch, settleCapabilityBatch, } from "./command-dispatch/capability-batch-transitions.js";
 import { beginCapabilityExecution, settleCapabilityExecution, } from "./command-dispatch/capability-execution-transitions.js";
 import { reconsiderCapabilitySelection } from "./command-dispatch/capability-selection-transition.js";
+import { updateModelWorkPlan } from "./command-dispatch/work-plan-transition.js";
 import { beginMemoryRecall, settleMemoryRecall } from "./command-dispatch/memory-recall-transitions.js";
 import { establishWorkingDirectory, updateCapabilityScope, } from "./command-dispatch/call-scope-transitions.js";
 import { openChild, returnChild, } from "./command-dispatch/child-transitions.js";
 import { completeRootResponse, createRoot, } from "./command-dispatch/root-transitions.js";
 export function dispatchRoleCallCommand(state, command, policy, admittedHeadRevision) {
     switch (command.type) {
+        case "update_model_work_plan":
+            return updateModelWorkPlan(state, command, policy);
         case "begin_memory_recall":
             return beginMemoryRecall(state, command);
         case "settle_memory_recall":