@abot-ai/runtime 1.7.0 → 1.8.1

package/dist/src/runtime/plugins/manifest-platform-compatibility.js

@@ -0,0 +1,39 @@
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION, ABOT_PLUGIN_COMPATIBILITY_VERSION, PLUGIN_RUNTIME_PLATFORMS, } from "../../plugin-contract/platform-compatibility.js";
+import { isRecord } from "../config/utils.js";
+function hasUnknownCompatibilityField(value) {
+    return Object.keys(value).some((key) => key !== "version" && key !== "runtimePlatforms");
+}
+function isRuntimePlatformList(value) {
+    if (!Array.isArray(value))
+        return false;
+    if (value.length === 0)
+        return false;
+    return value.length <= PLUGIN_RUNTIME_PLATFORMS.length;
+}
+function isPluginRuntimePlatform(value) {
+    return PLUGIN_RUNTIME_PLATFORMS.some((platform) => platform === value);
+}
+function hasRepeatedRuntimePlatform(platforms) {
+    return new Set(platforms).size !== platforms.length;
+}
+export function parsePluginPlatformDeclaration(value) {
+    if (value === undefined)
+        return undefined;
+    const path = `extensions.${ABOT_PLUGIN_COMPATIBILITY_EXTENSION}`;
+    if (!isRecord(value))
+        throw new Error(`${path} must be an object`);
+    if (hasUnknownCompatibilityField(value))
+        throw new Error(`${path} contains an unknown field`);
+    if (value.version !== ABOT_PLUGIN_COMPATIBILITY_VERSION)
+        throw new Error(`${path}.version must be ${ABOT_PLUGIN_COMPATIBILITY_VERSION}`);
+    if (!isRuntimePlatformList(value.runtimePlatforms))
+        throw new Error(`${path}.runtimePlatforms must contain one to three platforms`);
+    if (!value.runtimePlatforms.every(isPluginRuntimePlatform))
+        throw new Error(`${path}.runtimePlatforms must use linux, darwin, or win32`);
+    if (hasRepeatedRuntimePlatform(value.runtimePlatforms))
+        throw new Error(`${path}.runtimePlatforms must not contain duplicates`);
+    return Object.freeze({
+        version: ABOT_PLUGIN_COMPATIBILITY_VERSION,
+        runtimePlatforms: Object.freeze([...value.runtimePlatforms]),
+    });
+}

package/dist/src/runtime/plugins/manifest-projection.js

@@ -41,6 +41,9 @@ export function projectManifestRuntimeContract(discovered, selectedCapabilityIds
             definition: {
                 name: capabilityId,
                 pluginName: manifest.name,
+                ...(manifest.description !== undefined
+                    ? { pluginDescription: manifest.description }
+                    : {}),
                 ...(capability.requiredPermissionMode
                     ? { requiredPermissionMode: capability.requiredPermissionMode }
                     : {}),

package/dist/src/runtime/plugins/manifest-validator.js

@@ -1,5 +1,7 @@
 import { parseOptionalToolOutputChannels } from "../../capabilities/normal-invocation/output-channels.js";
 import { parseRequiredToolPermissionMode } from "../../capabilities/tool-permission-mode.js";
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION } from "../../plugin-contract/platform-compatibility.js";
+import { parsePluginPlatformDeclaration } from "./manifest-platform-compatibility.js";
 import { isToolCatalogGroupId } from "../../capabilities/tool-types.js";
 import { parseEventResultMetadata } from "../../capabilities/tool-definition-validator/event-result-metadata.js";
 import { parseEventInputTextOptions } from "../../capabilities/tool-definition-validator/event-input-text-options.js";
@@ -321,7 +323,9 @@ function parseOperation(value, path) {
                 ? { payload: payload }
                 : {}),
             ...(attachmentInput
-                ? { attachmentInput: attachmentInput }
+                ? {
+                    attachmentInput: attachmentInput,
+                }
                 : {}),
         },
         ...(legacySkills ? { legacySkills } : {}),
@@ -481,6 +485,7 @@ export function parseAgentPluginManifest(raw, folderName) {
     }
     const extensions = expectRecord(manifest.extensions, "plugin.json.extensions");
     const runtimeExtension = parseRuntimeExtension(extensions[ABOT_RUNTIME_EXTENSION]);
+    const compatibility = parsePluginPlatformDeclaration(extensions[ABOT_PLUGIN_COMPATIBILITY_EXTENSION]);
     return {
         $schema: AGENT_PLUGIN_MANIFEST_SCHEMA,
         name: manifest.name,
@@ -493,6 +498,9 @@ export function parseAgentPluginManifest(raw, folderName) {
         extensions: {
             ...extensions,
             [ABOT_RUNTIME_EXTENSION]: runtimeExtension,
+            ...(compatibility
+                ? { [ABOT_PLUGIN_COMPATIBILITY_EXTENSION]: compatibility }
+                : {}),
         },
     };
 }

package/dist/src/runtime/plugins/platform-compatibility.d.ts

@@ -0,0 +1,4 @@
+import type { AgentPluginManifest } from "../../plugin-contract/manifest.js";
+import { type PluginPlatformCompatibility } from "../../plugin-contract/platform-compatibility.js";
+/** Compatibility affects loading, never the user's saved plugin selection. */
+export declare function resolvePluginPlatformCompatibility(manifest: AgentPluginManifest, runtimePlatform?: NodeJS.Platform): PluginPlatformCompatibility;

package/dist/src/runtime/plugins/platform-compatibility.js

@@ -0,0 +1,44 @@
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION, } from "../../plugin-contract/platform-compatibility.js";
+function runtimePlatformName(platform) {
+    if (platform === "win32")
+        return "Windows";
+    if (platform === "darwin")
+        return "macOS";
+    if (platform === "linux")
+        return "Linux";
+    return platform;
+}
+function supportsDeclaredRuntimePlatform(declaration, runtimePlatform) {
+    return declaration.runtimePlatforms.some((platform) => platform === runtimePlatform);
+}
+function undeclaredPlatformCompatibility(runtimePlatform) {
+    if (runtimePlatform === "win32")
+        return {
+            supported: false,
+            status: "undeclared",
+            runtimePlatform,
+            reason: "This plugin does not declare support for Windows Runtime.",
+        };
+    return { supported: true, status: "legacy", runtimePlatform };
+}
+/** Compatibility affects loading, never the user's saved plugin selection. */
+export function resolvePluginPlatformCompatibility(manifest, runtimePlatform = process.platform) {
+    const declaration = manifest.extensions[ABOT_PLUGIN_COMPATIBILITY_EXTENSION];
+    if (!declaration)
+        return undeclaredPlatformCompatibility(runtimePlatform);
+    const runtimePlatforms = declaration.runtimePlatforms;
+    if (supportsDeclaredRuntimePlatform(declaration, runtimePlatform))
+        return {
+            supported: true,
+            status: "declared",
+            runtimePlatform,
+            runtimePlatforms,
+        };
+    return {
+        supported: false,
+        status: "unsupported",
+        runtimePlatform,
+        runtimePlatforms,
+        reason: `This plugin supports Runtime on ${runtimePlatforms.map(runtimePlatformName).join(", ")}; this Runtime is running on ${runtimePlatformName(runtimePlatform)}.`,
+    };
+}

package/dist/src/runtime/request/approval-wait/activation-events.js

@@ -45,13 +45,22 @@ export class RequestActivationEvents {
     }
     async commit(operation) {
         await this.events.drain();
-        const result = await operation(this.expectation());
-        if (!result.accepted)
-            throw new Error(`request_lifecycle_rejected:${result.reason}`);
-        this.current = result.current;
-        this.sealed = result.current.status !== "streaming";
-        this.publishCommitted(result.events);
-        return result;
+        // Draining is an observation, not a queue reservation: steering can emit
+        // another event before this continuation runs. Claim this same queue before
+        // reading the revision so no event can race the lifecycle commit.
+        const committed = this.tail.then(async () => {
+            if (this.persistenceError)
+                throw this.persistenceError;
+            const result = await operation(this.expectation());
+            if (!result.accepted)
+                throw new Error(`request_lifecycle_rejected:${result.reason}`);
+            this.current = result.current;
+            this.sealed = result.current.status !== "streaming";
+            this.publishCommitted(result.events);
+            return result;
+        });
+        this.tail = committed.then(() => undefined, () => undefined);
+        return committed;
     }
     /** A failed event write cannot turn a committed wait into an execution failure. */
     async finalizeFailure(input) {
@@ -115,6 +124,9 @@ export class RequestActivationEvents {
             return;
         this.tail = this.tail
             .then(async () => {
+            const hasStreamingActivation = this.current.status === "streaming";
+            if (!hasStreamingActivation)
+                return;
             if (this.persistenceError)
                 return;
             const result = await this.store.appendActivationEvent(this.current.sessionId, {

package/dist/src/runtime/request/approval-wait/execution-compaction-restore.d.ts

@@ -0,0 +1,20 @@
+import type { RequestContextCompactionSnapshot } from "../../context/semantic-compaction/snapshot.js";
+import type { SemanticCompactionSource } from "../../context/semantic-compaction/contracts.js";
+import type { RoleCallLedgerCheckpoint } from "../../orchestration/role-calls/checkpoint.js";
+import type { CompiledRequestExecutionPolicy } from "../execution-scope.js";
+/** Invalidate only proven legacy EA projections; the ledger retains the original evidence. */
+export declare function restoreExecutionApprovalCompaction(params: {
+    snapshot: RequestContextCompactionSnapshot;
+    ledgerCheckpoint: RoleCallLedgerCheckpoint;
+    requestId: string;
+    executionPolicy: CompiledRequestExecutionPolicy;
+}): Readonly<{
+    snapshot?(): RequestContextCompactionSnapshot;
+    get(scopeId: string): import("../../context/semantic-compaction/contracts.js").SemanticCompactionCheckpoint | undefined;
+    findByCallIds(callIds: readonly string[]): readonly import("../../context/semantic-compaction/contracts.js").SemanticCompactionCheckpoint[];
+    registerSources(sources: readonly SemanticCompactionSource[]): void;
+    registerSourcesAtomically?(sources: readonly SemanticCompactionSource[]): void;
+    quarantineScope?(record: import("../../context/semantic-compaction/scope-quarantine.js").InvalidatedCompactionScope): void;
+    materializeSource(sourceRef: string, sourceFingerprint: string): SemanticCompactionSource | undefined;
+    commit(checkpoint: import("../../context/semantic-compaction/contracts.js").SemanticCompactionCheckpoint): void;
+}>;

package/dist/src/runtime/request/approval-wait/execution-compaction-restore.js

@@ -0,0 +1,118 @@
+import { restoreRequestContextCompaction } from "../../context/semantic-compaction/snapshot.js";
+import { createRoleCallLedger, } from "../../orchestration/role-calls/index.js";
+import { traceDebug } from "../../observability/debug-logger.js";
+import { createRequestRoleCallPolicy } from "../role-call-policy.js";
+import { buildExecutionCapabilityResultMessage, EXECUTION_CAPABILITY_RESULT_MESSAGE_KIND, EXECUTION_CAPABILITY_TOOL_NAME, } from "../../steps/execution-agent/capability-result-context.js";
+/** Invalidate only proven legacy EA projections; the ledger retains the original evidence. */
+export function restoreExecutionApprovalCompaction(params) {
+    // Validate original hashes and complete checkpoint coverage before filtering anything.
+    const restored = restoreRequestContextCompaction(params.snapshot);
+    if (!usesExecutionAgentNativeResults(params.executionPolicy))
+        return restored;
+    if (!params.snapshot.sources.some(isNativeResultCompatibilityCandidate))
+        return restored;
+    const ledger = createRoleCallLedger({
+        requestId: params.requestId,
+        policy: createRequestRoleCallPolicy(params.executionPolicy),
+        checkpoint: params.ledgerCheckpoint,
+    });
+    const head = ledger.current();
+    const executions = new Map(head.state.capabilityExecutions
+        .filter((execution) => execution.callId === head.state.rootCallId)
+        .map((execution) => [`tool-result:${execution.executionId}`, execution]));
+    const legacySourceRefs = new Set();
+    for (const source of params.snapshot.sources) {
+        const execution = executions.get(source.sourceRef);
+        if (!isExecutionResultSource(source, execution))
+            continue;
+        if (!isSettledRootExecution(execution, head.state.rootCallId))
+            throw new Error("context_compaction_snapshot_source_incompatible");
+        const current = buildExecutionCapabilityResultMessage(head, execution);
+        const matchesCurrentProjection = source.content === JSON.stringify(current);
+        if (matchesCurrentProjection)
+            continue;
+        const matchesLegacyProjection = source.content === serializeLegacyExecutionResult(execution);
+        if (!matchesLegacyProjection)
+            throw new Error("context_compaction_snapshot_source_incompatible");
+        legacySourceRefs.add(source.sourceRef);
+    }
+    if (legacySourceRefs.size === 0)
+        return restored;
+    const invalidatedCheckpoints = params.snapshot.checkpoints.filter((checkpoint) => checkpoint.sourceDigests.some((source) => legacySourceRefs.has(source.sourceRef)));
+    const ownsInvalidatedCheckpoints = invalidatedCheckpoints.every((checkpoint) => checkpoint.requestId === params.requestId);
+    if (!ownsInvalidatedCheckpoints)
+        throw new Error("context_compaction_snapshot_source_incompatible");
+    const compatible = {
+        ...params.snapshot,
+        sources: params.snapshot.sources.filter((source) => !legacySourceRefs.has(source.sourceRef)),
+        checkpoints: params.snapshot.checkpoints.filter((checkpoint) => !invalidatedCheckpoints.includes(checkpoint)),
+    };
+    const store = restoreRequestContextCompaction(compatible);
+    traceDebug("runtime.approvals", "compaction.legacy_execution_sources_invalidated", {
+        requestId: params.requestId,
+        sourceCount: legacySourceRefs.size,
+        checkpointCount: invalidatedCheckpoints.length,
+        scopeIds: invalidatedCheckpoints
+            .slice(0, 8)
+            .map(({ scopeId }) => scopeId),
+        omittedScopeCount: Math.max(0, invalidatedCheckpoints.length - 8),
+    });
+    return store;
+}
+function usesExecutionAgentNativeResults(policy) {
+    if (policy.authority.id !== "execution-agent-v1")
+        return false;
+    return policy.authority.rootContractId === "execution_agent";
+}
+function isSettledRootExecution(execution, rootCallId) {
+    if (!execution)
+        return false;
+    if (execution.callId !== rootCallId)
+        return false;
+    return execution.status === "settled";
+}
+function isNativeResultCompatibilityCandidate(source) {
+    if (source.sourceRef.startsWith("tool-result:"))
+        return true;
+    return hasExecutionResultEnvelope(source);
+}
+function isExecutionResultSource(source, execution) {
+    if (execution)
+        return true;
+    return hasExecutionResultEnvelope(source);
+}
+function hasExecutionResultEnvelope(source) {
+    try {
+        const message = JSON.parse(source.content);
+        if (message?.role !== "tool")
+            return false;
+        if (message.toolName !== EXECUTION_CAPABILITY_TOOL_NAME)
+            return false;
+        if (typeof message.content !== "string")
+            return false;
+        const envelope = JSON.parse(message.content);
+        return envelope?.kind === EXECUTION_CAPABILITY_RESULT_MESSAGE_KIND;
+    }
+    catch {
+        return false;
+    }
+}
+/** Exact pre-canonical-outcome wire bytes, recognized only against the same ledger execution. */
+function serializeLegacyExecutionResult(execution) {
+    return JSON.stringify({
+        role: "tool",
+        content: JSON.stringify({
+            kind: EXECUTION_CAPABILITY_RESULT_MESSAGE_KIND,
+            authority: "capability_adapter_result",
+            presenceEffect: "runtime_result_only_not_user_intent",
+            invocationAttempt: execution.invocationAttempt,
+            result: {
+                executionId: execution.executionId,
+                capabilityId: execution.capabilityId,
+                adapterResult: execution.exactResult,
+            },
+        }),
+        toolCallId: execution.executionId,
+        toolName: EXECUTION_CAPABILITY_TOOL_NAME,
+    });
+}

package/dist/src/runtime/request/approval-wait/super-compaction-restore.js

@@ -1,3 +1,4 @@
+import { restoreExecutionApprovalCompaction } from "./execution-compaction-restore.js";
 import { createRoleCallLedger } from "../../orchestration/role-calls/index.js";
 import { hasSuperContextContract } from "../../context/super-context-policy.js";
 import { createOwnedSuperContextFailure } from "../../context/super-context-failure.js";
@@ -8,7 +9,7 @@ import { createRequestRoleCallPolicy } from "../role-call-policy.js";
 export function restoreApprovalCompaction(params) {
     const { snapshot, executionPolicy } = params;
     if (!hasSuperContextContract(executionPolicy.authority, "supervisor"))
-        return restoreRequestContextCompaction(snapshot);
+        return restoreExecutionApprovalCompaction(params);
     const ledger = createRoleCallLedger({
         requestId: params.requestId,
         policy: createRequestRoleCallPolicy(executionPolicy),

package/dist/src/runtime/request/capability-execution-freshness.js

@@ -22,7 +22,12 @@ export function restoreApprovalExecutionFreshness(token, requestSteering) {
     });
     if (!isDeepStrictEqual(current.token, token))
         throw new Error("request_approval_steering_mismatch");
-    if (!current.isCurrent())
+    // A newer accepted prefix invalidates execution, not the saved approval.
+    // A closed inbox has no current version and must remain terminal.
+    if (!hasLiveSteeringInbox(inbox))
         throw new Error("request_approval_steering_superseded");
     return Object.freeze({ token, isCurrent: current.isCurrent });
 }
+function hasLiveSteeringInbox(inbox) {
+    return inbox.isCurrent(inbox.snapshot().version);
+}

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

@@ -37,6 +37,8 @@ export const EXECUTION_AGENT_ROOT_CONTRACT = Object.freeze({
         });
     },
     async authorResponse(request, options) {
+        if (options.directResponse !== undefined)
+            return options.directResponse;
         const requestSteering = resolveRequestSteeringInbox(request.requestSteering);
         return runExecutionAgentAuthoredResponse(request, {
             head: options.head,
@@ -115,7 +117,15 @@ function projectKernelDecision(decision, steeringVersion) {
                 ...presentation,
             });
         case "respond":
-            return Object.freeze({ action: "respond", ...presentation });
+            return Object.freeze({
+                action: "respond", ...presentation,
+                ...(decision.response !== undefined ? {
+                    directResponse: Object.freeze({
+                        finalResponse: decision.response,
+                        memoryCandidates: decision.memoryCandidates ?? Object.freeze([]),
+                    }),
+                } : {}),
+            });
         case "blocked":
             return Object.freeze({
                 action: "blocked",

package/dist/src/runtime/request/prepared-execution.js

@@ -1,3 +1,5 @@
+import { bindRequestWorkingDirectory } from "../capabilities/request-working-directory.js";
+import { createRuntimeToolPathResolver } from "../capabilities/runtime-target-path.js";
 import { isSparkSession } from "../../sessions/spark-session.js";
 import { createSuperFailureFinalization, } from "./super-failure-explanation.js";
 import { resolveSessionWorkingDirectory } from "../projects/session-paths.js";
@@ -200,6 +202,7 @@ export async function prepareRequestExecution(params) {
         : preparedSeed;
     const toolRegistry = options.toolRegistry?.prepareRequest
         ? await options.toolRegistry.prepareRequest({
+            runtimePathResolver: createRuntimeToolPathResolver(bindRequestWorkingDirectory(options.toolRegistry.prepareSharedState?.() ?? {}, requestWorkingDirectory).runtimePaths),
             requestState: resources.state,
             onRequestDispose: resources.onRequestDispose,
         })

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

@@ -19,6 +19,7 @@ export type RootContractCallIdentity = Readonly<{
 type RootContractAction = MemoryRecallDecision | Readonly<{
     action: "respond";
     responseRecommendation?: string;
+    directResponse?: RootAuthoredResponse;
     acknowledgement?: string;
     title?: string;
 }> | Readonly<{
@@ -99,6 +100,7 @@ export type RootContractAdapter<TRequest> = Readonly<{
         callFrame: RoleCallFrame;
         steeringVersion: number;
         responseRecommendation?: string;
+        directResponse?: RootAuthoredResponse;
         call: RootContractCallIdentity;
         toolResults: RequestToolResultsView;
         resume?: RoleChildReturnContext;

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

@@ -492,6 +492,7 @@ class RootExecutionSession {
             ? createPlainRootAuthoredResponse(decision.response)
             : await this.policy.rootContract.authorResponse(this.request, {
                 responseRecommendation: decision.responseRecommendation,
+                directResponse: decision.directResponse,
                 memoryRecallMessage: projectRootMemoryRecallMessage({
                     head: activation.head,
                     callId: activation.call.callId,

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

@@ -1,8 +1,9 @@
+import { prepareInitialMemory } from "../long-term-memory/initial-context.js";
 import { createRequestRoleCallPolicy } from "./role-call-policy.js";
 import { restoreApprovalExecutionFreshness } from "./capability-execution-freshness.js";
 import { captureRoleCallLedgerCheckpoint } from "../orchestration/role-calls/checkpoint.js";
 import { isRoleApprovalWait } from "../orchestration/role-executors/approval-continuation.js";
-import { resumeCapabilityApprovalGroup } from "../orchestration/worker-capabilities/execution/approval-group.js";
+import { restoreCapabilityApprovalGroup } from "../orchestration/worker-capabilities/execution/approval-group.js";
 import { createRoleApprovalContinuation, validateRequestApprovalContinuation, } from "./approval-continuation.js";
 import { createRoleCallLedger, resolveRoleCallTransactions, } from "../orchestration/role-calls/index.js";
 import { traceDebug } from "../observability/debug-logger.js";
@@ -26,8 +27,10 @@ export async function runRequestRunner(request, options = {}) {
             }
             : {}),
     });
+    const initialMemory = await prepareInitialMemory(request, options.continuation?.ledger.state.initialMemory);
     const ledger = createRoleCallLedger({
         requestId: request.requestId,
+        ...(initialMemory !== undefined ? { initialMemory } : {}),
         ...(options.continuation
             ? { checkpoint: options.continuation.ledger }
             : {}),
@@ -42,15 +45,18 @@ export async function runRequestRunner(request, options = {}) {
         let continuation;
         if (options.continuation) {
             validateRequestApprovalContinuation(options.continuation, ledger, request.workerCapabilities.provider.getDescriptors());
+            request.abortSignal.throwIfAborted();
             const executionFreshness = restoreApprovalExecutionFreshness(options.continuation.preparedGroup.executionFreshnessToken, request.requestSteering);
-            const settled = await resumeCapabilityApprovalGroup({
+            const prepared = await restoreCapabilityApprovalGroup({
                 ...(executionFreshness ? { executionFreshness } : {}),
                 ledger,
                 context: request.workerCapabilities.executionContext,
                 adapters: request.workerCapabilities.provider.getAdapters(),
                 group: options.continuation.preparedGroup,
-                decisions: options.decisions ?? [],
             });
+            request.abortSignal.throwIfAborted();
+            restoreApprovalExecutionFreshness(options.continuation.preparedGroup.executionFreshnessToken, request.requestSteering);
+            const settled = await prepared.execute(options.decisions ?? []);
             continuation = createRoleApprovalContinuation(options.continuation, settled.executionIds);
         }
         else {

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

@@ -17,6 +17,9 @@ export const SUPERVISOR_ROOT_CONTRACT = Object.freeze({
             includeTitle: options.includeTitle,
             allowedRoleIds: options.allowedRoleIds,
             availableWorkerCapabilityCatalog: options.availableWorkerCapabilityCatalog,
+            ...(options.head.state.initialMemory?.message
+                ? { initialMemoryMessage: options.head.state.initialMemory.message }
+                : {}),
             ...(options.memoryRecallMessage
                 ? { memoryRecallMessage: options.memoryRecallMessage }
                 : {}),
@@ -28,6 +31,9 @@ export const SUPERVISOR_ROOT_CONTRACT = Object.freeze({
             responseRecommendation: options.responseRecommendation,
             call: options.call,
             toolResults: options.toolResults,
+            ...(options.head.state.initialMemory?.message
+                ? { initialMemoryMessage: options.head.state.initialMemory.message }
+                : {}),
             ...(options.memoryRecallMessage
                 ? { memoryRecallMessage: options.memoryRecallMessage }
                 : {}),

package/dist/src/runtime/steps/execution-agent/capability-result-context.d.ts

@@ -0,0 +1,6 @@
+import type { ChatMessage } from "../../../model-gateway/types.js";
+import type { RoleCallLedgerHead, RoleCapabilityExecution } from "../../orchestration/role-calls/index.js";
+export declare const EXECUTION_CAPABILITY_RESULT_MESSAGE_KIND: "runtime_execution_capability_result_v1";
+export declare const EXECUTION_CAPABILITY_TOOL_NAME: "runtime_capability";
+/** One exact native result representation for active input and saved-source compatibility. */
+export declare function buildExecutionCapabilityResultMessage(head: RoleCallLedgerHead, execution: RoleCapabilityExecution): ChatMessage;

package/dist/src/runtime/steps/execution-agent/capability-result-context.js

@@ -0,0 +1,29 @@
+import { projectCanonicalRequestToolResult } from "../../context/canonical-capability-result.js";
+export const EXECUTION_CAPABILITY_RESULT_MESSAGE_KIND = "runtime_execution_capability_result_v1";
+export const EXECUTION_CAPABILITY_TOOL_NAME = "runtime_capability";
+/** One exact native result representation for active input and saved-source compatibility. */
+export function buildExecutionCapabilityResultMessage(head, execution) {
+    if (execution.status !== "settled" || execution.exactResult === undefined) {
+        throw new Error("execution_agent_continuation_result_invalid");
+    }
+    const canonical = projectCanonicalRequestToolResult(head, execution);
+    return Object.freeze({
+        role: "tool",
+        content: JSON.stringify({
+            kind: EXECUTION_CAPABILITY_RESULT_MESSAGE_KIND,
+            authority: "canonical_role_call_ledger",
+            presenceEffect: "runtime_result_only_not_user_intent",
+            invocationAttempt: execution.invocationAttempt,
+            result: {
+                executionId: execution.executionId,
+                capabilityId: execution.capabilityId,
+                outcome: canonical.outcome,
+                observedEffect: canonical.observedEffect,
+                summary: canonical.summary,
+                adapterResult: execution.exactResult,
+            },
+        }),
+        toolCallId: execution.executionId,
+        toolName: EXECUTION_CAPABILITY_TOOL_NAME,
+    });
+}

package/dist/src/runtime/steps/execution-agent/contracts.d.ts

@@ -1,4 +1,6 @@
 import type { MemoryRecallDecision } from "../memory-recall-decision.js";
+import type { MemoryCandidate } from "../../long-term-memory/contracts.js";
+import type { ConversationMemoryAuthoringContext } from "../../long-term-memory/conversation-authoring/context.js";
 import type { ExecutionWorkPlanOptions, ExecutionWorkPlanReport } from "./work-plan-contract.js";
 import type { RoleCapabilitySelectionProjection, RoleCapabilitySelectionReconsiderationCause } from "../../orchestration/role-calls/index.js";
 import { type CapabilityControls, type CapabilityDescriptor } from "../../orchestration/capability-adapters/index.js";
@@ -21,6 +23,10 @@ export type ExecutionAgentDecisionPresentation = Readonly<{
 }>;
 export type ExecutionAgentRespondDecision = Readonly<ExecutionAgentDecisionPresentation & {
     action: "respond";
+    /** Exact prevalidated short answer; absent keeps separate presentation. */
+    response?: string;
+    /** Assessed proposals bound to the same accepted direct response. */
+    memoryCandidates?: readonly MemoryCandidate[];
 }>;
 export type ExecutionAgentOpenCapabilityScopeDecision = Readonly<ExecutionAgentDecisionPresentation & {
     action: "open_capability_scope";
@@ -113,6 +119,10 @@ export type ExecutionAgentDecisionContractOptions = Readonly<{
     includeAcknowledgement?: boolean;
     includeTitle?: boolean;
     allowRespond?: boolean;
+    directResponseMaxLength?: number;
+    directResponseMemoryAuthoring?: Readonly<{
+        context?: ConversationMemoryAuthoringContext;
+    }>;
     allowMemoryRecall?: boolean;
     allowPlanner?: boolean;
     allowAuditor?: boolean;

package/dist/src/runtime/steps/execution-agent/decision-parsing.js

@@ -1,3 +1,4 @@
+import { parseDirectResponse, parseDirectResponseMemoryCandidates, } from "./direct-response-contract.js";
 import { readStructuredDecisionEnvelope } from "../../model/structured-decision-envelope.js";
 import { parseDecisionWithWorkPlan } from "./work-plan-decision-parsing.js";
 import { isMemoryRecallDecisionRecord, parseMemoryRecallDecision, } from "../memory-recall-decision.js";
@@ -62,12 +63,23 @@ function parseExecutionAgentActionOutput(text, options) {
         }
     }
     else if (selectedAction === "respond") {
-        exactKeys(record, ["action", ...presentationKeys(contract)], issues, "decision");
+        const response = parseDirectResponse(record, options.directResponseMaxLength, issues);
+        const memoryCandidates = response !== undefined
+            ? parseDirectResponseMemoryCandidates(record, options.directResponseMemoryAuthoring)
+            : undefined;
+        exactKeys(record, [
+            "action",
+            ...(response !== undefined ? ["response"] : []),
+            ...(memoryCandidates !== undefined ? ["memoryCandidates"] : []),
+            ...presentationKeys(contract),
+        ], issues, "decision");
         if (!contract.allowRespond) {
             issues.push(issue("execution_agent_response_not_allowed", "decision.action", "respond is not available until the canonical completion gate is open."));
         }
         decision = {
             action: "respond",
+            ...(response !== undefined ? { response } : {}),
+            ...(memoryCandidates !== undefined ? { memoryCandidates } : {}),
             ...presentation,
         };
     }

package/dist/src/runtime/steps/execution-agent/direct-response-configuration.d.ts

@@ -0,0 +1,3 @@
+import type { RequestExecutionScope } from "../../request/execution-scope.js";
+/** Preserve a separately configured response model/calibration instead of silently bypassing it. */
+export declare function hasCompatibleDirectResponseConfiguration(request: RequestExecutionScope): boolean;

package/dist/src/runtime/steps/execution-agent/direct-response-configuration.js

@@ -0,0 +1,64 @@
+import { isDeepStrictEqual } from "node:util";
+import { resolveModelInvocation } from "../../../model-gateway/invocation-policy.js";
+import { resolveModelStepTimeout } from "../../model/model-step-timeout-policy.js";
+import { EXECUTION_AGENT_DECISION_MODEL_STEP, EXECUTION_AGENT_RESPONSE_MODEL_STEP, } from "./contracts.js";
+/** Preserve a separately configured response model/calibration instead of silently bypassing it. */
+export function hasCompatibleDirectResponseConfiguration(request) {
+    try {
+        const decision = effectiveConfiguration(request, EXECUTION_AGENT_DECISION_MODEL_STEP);
+        const response = effectiveConfiguration(request, EXECUTION_AGENT_RESPONSE_MODEL_STEP);
+        if (!decision || !response)
+            return false;
+        return isDeepStrictEqual(decision, response);
+    }
+    catch {
+        // Resolution failures keep the existing deferred path and its diagnostics.
+        return false;
+    }
+}
+function effectiveConfiguration(request, modelStep) {
+    const step = request.runnerConfig.steps[modelStep];
+    if (!step)
+        return undefined;
+    const invocation = resolveModelInvocation({
+        modelStep,
+        agentMode: request.agentMode,
+        ...(request.modelPreference
+            ? { modelPreference: request.modelPreference }
+            : {}),
+        ...(request.modelPolicy ? { modelPolicy: request.modelPolicy } : {}),
+    });
+    if (hasSpecialResponseFormat(modelStep, invocation.format))
+        return undefined;
+    const { profile } = invocation;
+    return {
+        profileId: profile.id,
+        providerId: profile.providerId,
+        provider: profile.provider,
+        model: profile.model,
+        contextWindowTokens: profile.contextWindowTokens,
+        capabilities: profile.capabilities,
+        options: profile.options,
+        generation: profile.generation,
+        context: profile.context,
+        think: invocation.think,
+        instructions: invocation.instructions ?? [],
+        timeoutMs: resolveModelStepTimeout({
+            modelStep,
+            fallbackTimeoutMs: step.timeoutMs,
+            ...(request.modelPreference
+                ? { modelPreference: request.modelPreference }
+                : {}),
+            ...(request.modelPolicy ? { modelPolicy: request.modelPolicy } : {}),
+        }).timeoutMs,
+    };
+}
+function hasSpecialResponseFormat(modelStep, format) {
+    if (modelStep !== EXECUTION_AGENT_RESPONSE_MODEL_STEP)
+        return false;
+    if (format === undefined)
+        return false;
+    if (format && typeof format === "object" && "type" in format)
+        return format.type !== "text";
+    return true;
+}