@abot-ai/runtime 1.4.0 → 1.6.0

package/dist/src/runtime/capabilities/request-tool-resources.js

@@ -0,0 +1,92 @@
+import { RequestToolMediaStore } from "../attachments/request-tool-media.js";
+import { RequestToolState } from "./request-tool-state.js";
+/** Owns temporary tool resources and tracks effects beyond a tool's return. */
+export class RequestToolResources {
+    media = new RequestToolMediaStore();
+    stateOwner = new RequestToolState();
+    state = this.stateOwner.port;
+    activeWork = new Set();
+    workListeners = new Set();
+    callbacks = new Set();
+    disposal;
+    work = Object.freeze({
+        trackUntil: (settled) => {
+            if (this.disposal)
+                throw new Error("tool_request_resources_closed");
+            const observed = settled.then(() => undefined, () => undefined);
+            this.activeWork.add(observed);
+            void observed.then(() => {
+                this.activeWork.delete(observed);
+                if (!this.activeWork.size)
+                    for (const notify of this.workListeners)
+                        notify();
+            });
+        },
+    });
+    hasActiveWork() {
+        return this.activeWork.size > 0;
+    }
+    waitForQuiescence(signal) {
+        signal?.throwIfAborted();
+        if (!this.hasActiveWork())
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const clear = () => {
+                this.workListeners.delete(ready);
+                signal?.removeEventListener("abort", aborted);
+            };
+            const ready = () => {
+                if (!this.hasActiveWork()) {
+                    clear();
+                    resolve();
+                }
+            };
+            const aborted = () => {
+                clear();
+                reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+            };
+            this.workListeners.add(ready);
+            signal?.addEventListener("abort", aborted, { once: true });
+            ready();
+        });
+    }
+    assertRestoredStateClaimed() {
+        this.stateOwner.assertRestoredStateClaimed();
+    }
+    snapshot() {
+        if (this.disposal || this.hasActiveWork())
+            throw new Error("tool_request_resources_not_quiescent");
+        return Object.freeze({
+            kind: "request_tool_resources_v1",
+            media: this.media.snapshot(),
+            capsules: this.stateOwner.snapshot(),
+        });
+    }
+    restore(snapshot) {
+        if (this.disposal || snapshot?.kind !== "request_tool_resources_v1")
+            throw new Error("tool_request_resources_invalid");
+        this.media.restore(snapshot.media);
+        this.stateOwner.restore(snapshot.capsules);
+    }
+    onRequestDispose = (callback) => {
+        if (this.disposal) {
+            void Promise.resolve()
+                .then(callback)
+                .catch(() => { });
+            return;
+        }
+        this.callbacks.add(callback);
+    };
+    dispose() {
+        if (this.disposal)
+            return this.disposal;
+        this.media.dispose();
+        const callbacks = [...this.callbacks];
+        this.callbacks.clear();
+        this.disposal = Promise.allSettled([
+            this.stateOwner.dispose(),
+            ...callbacks.map((callback) => Promise.resolve().then(callback)),
+        ]).then(() => undefined);
+        return this.disposal;
+    }
+}

package/dist/src/runtime/capabilities/request-tool-state.d.ts

@@ -0,0 +1,13 @@
+import type { ToolRequestState } from "../../capabilities/tool-request-resources.js";
+/** Pending capsules remain data-only until an owning plugin registers its codec. */
+export declare class RequestToolState {
+    private readonly pending;
+    private readonly owners;
+    private closed;
+    readonly port: ToolRequestState;
+    snapshot(): Readonly<Record<string, unknown>>;
+    restore(value: unknown): void;
+    assertRestoredStateClaimed(): void;
+    dispose(): Promise<void>;
+    private assertOpen;
+}

package/dist/src/runtime/capabilities/request-tool-state.js

@@ -0,0 +1,75 @@
+/** Pending capsules remain data-only until an owning plugin registers its codec. */
+export class RequestToolState {
+    pending = new Map();
+    owners = new Map();
+    closed = false;
+    port = Object.freeze({
+        read: (key) => {
+            this.assertOpen();
+            return structuredClone(this.pending.get(key));
+        },
+        register: (key, codec) => {
+            this.assertOpen();
+            if (!key || this.owners.has(key))
+                throw new Error("tool_request_state_owner_conflict");
+            this.owners.set(key, codec);
+            this.pending.delete(key);
+        },
+    });
+    snapshot() {
+        this.assertOpen();
+        return Object.fromEntries([
+            ...this.pending,
+            ...[...this.owners].map(([key, codec]) => [key, captureJson(codec.snapshot())]),
+        ]);
+    }
+    restore(value) {
+        this.assertOpen();
+        if (!value ||
+            typeof value !== "object" ||
+            Array.isArray(value) ||
+            this.pending.size ||
+            this.owners.size)
+            throw new Error("tool_request_state_invalid");
+        for (const [key, entry] of Object.entries(value))
+            this.pending.set(key, captureJson(entry));
+    }
+    assertRestoredStateClaimed() {
+        if (this.pending.size)
+            throw new Error("tool_request_state_owner_unavailable");
+    }
+    async dispose() {
+        this.closed = true;
+        const owners = [...this.owners.values()];
+        this.pending.clear();
+        this.owners.clear();
+        await Promise.allSettled(owners.map((owner) => Promise.resolve().then(() => owner.dispose?.())));
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new Error("tool_request_state_closed");
+    }
+}
+function captureJson(value) {
+    const visit = (input, seen) => {
+        if (input === null ||
+            typeof input === "string" ||
+            typeof input === "boolean")
+            return;
+        if (typeof input === "number" && Number.isFinite(input))
+            return;
+        if (typeof input !== "object" || seen.has(input))
+            throw new Error("tool_request_state_not_serializable");
+        const prototype = Object.getPrototypeOf(input);
+        if (!Array.isArray(input) &&
+            prototype !== Object.prototype &&
+            prototype !== null)
+            throw new Error("tool_request_state_not_serializable");
+        seen.add(input);
+        for (const child of Object.values(input))
+            visit(child, seen);
+        seen.delete(input);
+    };
+    visit(value, new Set());
+    return structuredClone(value);
+}

package/dist/src/runtime/capabilities/runtime-path-namespace.d.ts

@@ -0,0 +1,6 @@
+/** A relative component cannot normalize into a foreign drive namespace. */
+export declare function isRuntimePathNamespaceCompatible(value: string, platform?: NodeJS.Platform): boolean;
+/** Preserve a native Windows UNC root while normalizing scoped tool paths. */
+export declare function normalizeRuntimePathForScope(value: string, platform?: NodeJS.Platform): string;
+/** A different Windows drive or share produces an absolute relative result. */
+export declare function isRuntimePathWithinRoot(target: string, root: string, platform?: NodeJS.Platform): boolean;

package/dist/src/runtime/capabilities/runtime-path-namespace.js

@@ -0,0 +1,48 @@
+import { posix, win32 } from "node:path";
+function logicalSeparators(value) {
+    return value.replaceAll("\\", "/");
+}
+function hasDrivePrefix(value) {
+    return /^[A-Za-z]:/u.test(value);
+}
+function hasQualifiedDrive(value) {
+    return /^[A-Za-z]:\//u.test(value);
+}
+function hasQualifiedNetworkRoot(value) {
+    if (value.startsWith("//?/") || value.startsWith("//./"))
+        return false;
+    return /^\/\/[^/]+\/[^/]+(?:\/|$)/u.test(value);
+}
+function hasBackslashNetworkOrDeviceRoot(value) {
+    const prefix = value.slice(0, 2);
+    const networkRoot = /^[\\/]{2}$/u.test(prefix) && prefix.includes("\\");
+    return networkRoot || value.startsWith("\\??\\");
+}
+/** A relative component cannot normalize into a foreign drive namespace. */
+export function isRuntimePathNamespaceCompatible(value, platform = process.platform) {
+    const logical = logicalSeparators(value);
+    if (platform !== "win32" && hasBackslashNetworkOrDeviceRoot(value))
+        return false;
+    if (hasDrivePrefix(logical))
+        return platform === "win32" && hasQualifiedDrive(logical);
+    if (platform === "win32" && logical.startsWith("/"))
+        return hasQualifiedNetworkRoot(logical);
+    // Use the standard path grammar before checking a relative drive prefix.
+    return !hasDrivePrefix(posix.normalize(logical));
+}
+/** Preserve a native Windows UNC root while normalizing scoped tool paths. */
+export function normalizeRuntimePathForScope(value, platform = process.platform) {
+    if (platform === "win32" && win32.isAbsolute(value)) {
+        return logicalSeparators(win32.normalize(value));
+    }
+    return posix.normalize(logicalSeparators(value));
+}
+/** A different Windows drive or share produces an absolute relative result. */
+export function isRuntimePathWithinRoot(target, root, platform = process.platform) {
+    const paths = platform === "win32" ? win32 : posix;
+    const relative = paths.relative(root, target);
+    if (paths.isAbsolute(relative))
+        return false;
+    return (relative === "" ||
+        (relative !== ".." && !relative.startsWith(`..${paths.sep}`)));
+}

package/dist/src/runtime/capabilities/runtime-target-path.d.ts

@@ -2,6 +2,7 @@ import type { RuntimeToolPathErrorCode, RuntimeToolPathResolver, ToolExecutionSh
 export declare const RUNTIME_TOOL_PATH_ERROR_CODES: Readonly<{
     readonly REQUIRED: "runtime_tool_path_required";
     readonly NULL_BYTE: "runtime_tool_path_null_byte";
+    readonly NAMESPACE_INVALID: "runtime_tool_path_namespace_invalid";
     readonly LOCATION_REQUIRED: "runtime_tool_path_location_required";
     readonly ROOT_UNAVAILABLE: "runtime_tool_path_root_unavailable";
     readonly WORKSPACE_UNAVAILABLE: "runtime_tool_path_workspace_unavailable";

package/dist/src/runtime/capabilities/runtime-target-path.js

@@ -1,8 +1,10 @@
 import { lstatSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, parse, posix, relative, resolve, sep, } from "node:path";
+import { isRuntimePathNamespaceCompatible, isRuntimePathWithinRoot, normalizeRuntimePathForScope, } from "./runtime-path-namespace.js";
 export const RUNTIME_TOOL_PATH_ERROR_CODES = Object.freeze({
     REQUIRED: "runtime_tool_path_required",
     NULL_BYTE: "runtime_tool_path_null_byte",
+    NAMESPACE_INVALID: "runtime_tool_path_namespace_invalid",
     LOCATION_REQUIRED: "runtime_tool_path_location_required",
     ROOT_UNAVAILABLE: "runtime_tool_path_root_unavailable",
     WORKSPACE_UNAVAILABLE: "runtime_tool_path_workspace_unavailable",
@@ -28,9 +30,10 @@ function configuredRoot(value) {
     const trimmed = value?.trim();
     return trimmed ? resolve(trimmed) : undefined;
 }
-function isWithinRoot(target, root) {
-    const rel = relative(root, target);
-    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`));
+function assertRuntimePathNamespace(value) {
+    if (!isRuntimePathNamespaceCompatible(value)) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.NAMESPACE_INVALID);
+    }
 }
 /**
  * Qualifies one manifest-owned operation target against the canonical Worker
@@ -40,6 +43,7 @@ function isWithinRoot(target, root) {
  * physical directory. The returned value remains a logical tool target.
  */
 export function scopeRuntimeTargetPath(params) {
+    assertRuntimePathNamespace(params.rawPath.trim());
     const workingDirectory = params.workingDirectory?.trim();
     if (!workingDirectory) {
         return params.rawPath;
@@ -48,6 +52,7 @@ export function scopeRuntimeTargetPath(params) {
     if (!requested) {
         throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.REQUIRED, "runtime_target_path_missing");
     }
+    assertRuntimePathNamespace(workingDirectory);
     const normalizedTarget = normalizeLogicalPath(requested);
     const normalizedWorkingDirectory = normalizeLogicalPath(workingDirectory);
     if (hasTraversalSegment(normalizedTarget) ||
@@ -55,7 +60,7 @@ export function scopeRuntimeTargetPath(params) {
         isAbsolute(normalizedWorkingDirectory)) {
         throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.TRAVERSAL, "runtime_target_path_traversal");
     }
-    const normalized = posix.normalize(normalizedTarget);
+    const normalized = normalizeRuntimePathForScope(requested);
     const scoped = isAbsolute(normalized) ||
         normalized === "workspace" ||
         normalized.startsWith("workspace/") ||
@@ -67,7 +72,7 @@ export function scopeRuntimeTargetPath(params) {
     // then enforce the call-owned physical scope for explicit forms as well.
     const resolvedWorkingDirectory = resolveRuntimeTargetPath(normalizedWorkingDirectory, params.sharedState);
     const resolvedTarget = resolveRuntimeTargetPath(scoped, params.sharedState);
-    if (!isWithinRoot(resolvedTarget, resolvedWorkingDirectory)) {
+    if (!isRuntimePathWithinRoot(resolvedTarget, resolvedWorkingDirectory)) {
         throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.OUTSIDE_WORKING_DIRECTORY, "runtime_target_path_outside_working_directory");
     }
     return scoped;
@@ -169,6 +174,7 @@ function resolveRuntimeToolPath(rawPath, options) {
     if (requested.includes("\0")) {
         throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.NULL_BYTE);
     }
+    assertRuntimePathNamespace(requested);
     const allowed = Object.freeze([...(options.allowedLocations ?? DEFAULT_TOOL_PATH_LOCATIONS)].filter((location, index, values) => values.indexOf(location) === index));
     if (allowed.length === 0) {
         throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.LOCATION_REQUIRED);
@@ -188,6 +194,8 @@ function resolveRuntimeToolPath(rawPath, options) {
     let selected;
     let lexicalTarget;
     if (workspaceRelative !== undefined) {
+        // Validate the alias payload before root resolution can hide its namespace.
+        assertRuntimePathNamespace(requested.slice("workspace/".length));
         const workspace = availableRoots.find(({ location }) => location === "workspace");
         if (!workspace) {
             throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.WORKSPACE_UNAVAILABLE);
@@ -198,7 +206,7 @@ function resolveRuntimeToolPath(rawPath, options) {
     else if (isAbsolute(requested)) {
         lexicalTarget = resolve(requested);
         const rootedMatch = availableRoots
-            .filter(({ root }) => isWithinRoot(lexicalTarget, root))
+            .filter(({ root }) => isRuntimePathWithinRoot(lexicalTarget, root))
             .sort((left, right) => right.root.length - left.root.length)[0];
         if (rootedMatch) {
             selected = rootedMatch;
@@ -219,12 +227,12 @@ function resolveRuntimeToolPath(rawPath, options) {
         selected = rootedDefault;
         lexicalTarget = resolve(selected.root, normalized === "." ? "" : normalized);
     }
-    if (!isWithinRoot(lexicalTarget, selected.root)) {
+    if (!isRuntimePathWithinRoot(lexicalTarget, selected.root)) {
         throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.OUTSIDE_CONFIGURED_ROOTS);
     }
     const absolutePath = resolveThroughExistingAncestor(lexicalTarget);
     const canonicalRoot = resolveThroughExistingAncestor(selected.root);
-    if (!isWithinRoot(absolutePath, canonicalRoot)) {
+    if (!isRuntimePathWithinRoot(absolutePath, canonicalRoot)) {
         throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.SYMLINK_ESCAPE);
     }
     const relativePath = relative(canonicalRoot, absolutePath).replaceAll(sep, "/");

package/dist/src/runtime/capabilities/scheduling/create-operations.d.ts

@@ -5,6 +5,7 @@ export declare const scheduleCreateOperations: readonly [Readonly<{
     selectionControlIds?: readonly string[];
     fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
     payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    attachmentInput?: import("../../../capabilities/tool-types.js").ToolNormalInvocationAttachmentInput;
     effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
     approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
 }>, Readonly<{
@@ -14,6 +15,7 @@ export declare const scheduleCreateOperations: readonly [Readonly<{
     selectionControlIds?: readonly string[];
     fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
     payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    attachmentInput?: import("../../../capabilities/tool-types.js").ToolNormalInvocationAttachmentInput;
     effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
     approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
 }>, Readonly<{
@@ -23,6 +25,7 @@ export declare const scheduleCreateOperations: readonly [Readonly<{
     selectionControlIds?: readonly string[];
     fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
     payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    attachmentInput?: import("../../../capabilities/tool-types.js").ToolNormalInvocationAttachmentInput;
     effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
     approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
 }>, Readonly<{
@@ -32,6 +35,7 @@ export declare const scheduleCreateOperations: readonly [Readonly<{
     selectionControlIds?: readonly string[];
     fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
     payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    attachmentInput?: import("../../../capabilities/tool-types.js").ToolNormalInvocationAttachmentInput;
     effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
     approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
 }>, Readonly<{
@@ -41,6 +45,7 @@ export declare const scheduleCreateOperations: readonly [Readonly<{
     selectionControlIds?: readonly string[];
     fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
     payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    attachmentInput?: import("../../../capabilities/tool-types.js").ToolNormalInvocationAttachmentInput;
     effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
     approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
 }>, Readonly<{
@@ -50,6 +55,7 @@ export declare const scheduleCreateOperations: readonly [Readonly<{
     selectionControlIds?: readonly string[];
     fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
     payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    attachmentInput?: import("../../../capabilities/tool-types.js").ToolNormalInvocationAttachmentInput;
     effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
     approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
 }>];

package/dist/src/runtime/capabilities/scheduling/job-list-page.d.ts

@@ -5,15 +5,18 @@ export declare function createSchedulerJobPage(jobs: readonly SchedulerJob[], pa
     limit?: unknown;
 }): {
     jobs: {
+        target?: Readonly<{
+            kind: "request";
+        }>;
         id: string;
         environmentId: string;
         sessionId: string;
         title: string;
         modelProfileId: string;
         agentMode: import("../../../shared/types.js").AgentMode;
-        toolPermissionMode: "full_access";
+        toolPermissionMode: import("../../scheduler/tool-permission-mode.js").SchedulerToolPermissionMode;
         timeZone: string;
-        schedule: import("../../scheduler/contracts.js").SchedulerSchedule;
+        schedule: import("../../scheduler/contracts.js").SchedulerTimedSchedule;
         state: import("../../scheduler/contracts.js").SchedulerJobState;
         createdAt: string;
         updatedAt: string;

package/dist/src/runtime/composition.d.ts

@@ -8,6 +8,8 @@ import type { LongTermMemoryService } from "./long-term-memory/contracts.js";
 import type { SchedulerRun, SchedulerService } from "./scheduler/contracts.js";
 import { SessionRequestAdmission } from "./request/session-admission.js";
 import type { RequestSteeringAppendResult } from "./request/request-steering.js";
+import type { PassiveLearningService } from "./passive-learning/contracts.js";
+import type { AutomationService } from "./automations/service.js";
 export type RuntimeEnvironmentServices = Readonly<{
     config: RuntimeConfig;
     sessions: SessionStore;
@@ -18,18 +20,21 @@ export type RuntimeEnvironmentServices = Readonly<{
     events: EventSinkFactory;
     sessionMemoryCompactor: SessionMemoryCompactor;
     longTermMemory: LongTermMemoryService;
+    passiveLearning?: PassiveLearningService;
+    automations?: AutomationService;
     scheduler?: SchedulerService;
     startScheduler?: () => Promise<void>;
     stopScheduler?: () => Promise<void>;
     requestAdmission?: SessionRequestAdmission;
 }>;
-export type RuntimeRequestOptions = Pick<RequestHandlerOptions, "toolApprovalController" | "requestSteering">;
+export type RuntimeRequestOptions = Pick<RequestHandlerOptions, "toolApprovalController" | "requestSteering" | "abortSignal" | "claimFinalization" | "durableApprovals" | "approvalExecution" | "effectPersistence">;
 export type RuntimeRequestHandler = Readonly<{
+    cancel?: (requestId: string, sessionId: string, wait?: import("./request/cancellation.js").SavedWaitCancellation) => Promise<import("./request/cancellation.js").RequestCancellationResult>;
     steer?: (requestId: string, input: Readonly<{
         steerId: string;
         text: string;
     }>) => Promise<RequestSteeringAppendResult>;
-    handle: (ws: WebSocket, message: RunRequestMessage, options?: RuntimeRequestOptions) => Promise<void>;
+    handle: (ws: WebSocket, message: RunRequestMessage, options?: RuntimeRequestOptions) => Promise<import("./request/handler.js").RequestHandlerOutcome>;
 }>;
 export type RuntimeApplication = Readonly<{
     services: RuntimeEnvironmentServices;
@@ -49,12 +54,14 @@ export type RuntimeDependencies = {
     events: EventSinkFactory;
     sessionMemoryCompactor: SessionMemoryCompactor;
     longTermMemory: LongTermMemoryService;
+    passiveLearning?: PassiveLearningService;
+    automations?: AutomationService;
     scheduler?: SchedulerService;
     startScheduler?: () => Promise<void>;
     stopScheduler?: () => Promise<void>;
     requestAdmission?: SessionRequestAdmission;
 };
-export type RuntimeDependencyOverrides = Partial<Omit<RuntimeDependencies, "config" | "scheduler" | "startScheduler" | "stopScheduler" | "requestAdmission">>;
+export type RuntimeDependencyOverrides = Partial<Omit<RuntimeDependencies, "config" | "scheduler" | "automations" | "startScheduler" | "stopScheduler" | "requestAdmission">>;
 export type RuntimeApplicationOverrides = RuntimeDependencyOverrides & {
     scheduledRequestOptions?: (run: SchedulerRun) => RuntimeRequestOptions;
 };

package/dist/src/runtime/context/canonical-capability-result.d.ts

@@ -0,0 +1,4 @@
+import { type RoleCallLedgerHead, type RoleCapabilityExecution } from "../orchestration/role-calls/index.js";
+import type { RequestToolResult } from "./request-tool-results.js";
+/** Exact validated ledger evidence, before consumer filtering or supersession. */
+export declare function projectCanonicalRequestToolResult(head: RoleCallLedgerHead, execution: RoleCapabilityExecution): RequestToolResult;

package/dist/src/runtime/context/canonical-capability-result.js

@@ -0,0 +1,80 @@
+import { isRoleCapabilityId, ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH, ROLE_CALL_RESULT_MAX_LENGTH, } from "../orchestration/role-calls/index.js";
+import { normalizeCapabilityAdapterResult } from "../orchestration/capability-adapters/result.js";
+import { projectAcceptedCapabilityAction } from "./accepted-capability-action.js";
+/** Exact validated ledger evidence, before consumer filtering or supersession. */
+export function projectCanonicalRequestToolResult(head, execution) {
+    const exactResult = normalizeCapabilityAdapterResult(execution.exactResult);
+    if (execution.status !== "settled" ||
+        typeof execution.executionId !== "string" ||
+        execution.executionId.length === 0 ||
+        typeof execution.callId !== "string" ||
+        execution.callId.length === 0 ||
+        !Number.isSafeInteger(execution.invocationAttempt) ||
+        execution.invocationAttempt < 1 ||
+        !isRoleCapabilityId(execution.capabilityId) ||
+        !isDeclaredEffect(execution.declaredEffect) ||
+        !isOutcome(execution.outcome) ||
+        !isObservedEffect(execution.observedEffect) ||
+        !isBoundedSummary(execution.summary) ||
+        !isOptionalBoundedReferenceData(execution.referenceData) ||
+        !isValidReferences(execution.references) ||
+        !exactResult.ok) {
+        throw new Error("request_tool_results_execution_invalid");
+    }
+    return Object.freeze({
+        executionId: execution.executionId,
+        callId: execution.callId,
+        invocationAttempt: execution.invocationAttempt,
+        capabilityId: execution.capabilityId,
+        declaredEffect: execution.declaredEffect,
+        outcome: execution.outcome,
+        observedEffect: execution.observedEffect,
+        summary: execution.summary,
+        ...(execution.referenceData
+            ? { referenceData: execution.referenceData }
+            : {}),
+        ...(execution.references
+            ? { references: Object.freeze([...execution.references]) }
+            : {}),
+        ...(execution.actionFingerprint
+            ? {
+                acceptedAction: projectAcceptedCapabilityAction(head, execution),
+            }
+            : {}),
+        adapterResult: exactResult.value,
+    });
+}
+function isDeclaredEffect(value) {
+    return value === "observation" || value === "mutation" || value === "mixed";
+}
+function isOutcome(value) {
+    return value === "succeeded" || value === "failed";
+}
+function isObservedEffect(value) {
+    return (value === "none" ||
+        value === "observation" ||
+        value === "mutation" ||
+        value === "indeterminate");
+}
+function isBoundedSummary(value) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        value.length <= ROLE_CALL_RESULT_MAX_LENGTH);
+}
+function isOptionalBoundedReferenceData(value) {
+    return (value === undefined ||
+        (typeof value === "string" &&
+            value.trim().length > 0 &&
+            value.length <= ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH));
+}
+function isValidReferences(value) {
+    return (value === undefined ||
+        (Array.isArray(value) &&
+            value.length <= ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX &&
+            value.every((reference) => reference.kind === "tool_target" &&
+                typeof reference.target === "string" &&
+                reference.target.trim().length > 0 &&
+                reference.target.length <=
+                    ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH) &&
+            new Set(value.map(({ target }) => target)).size === value.length));
+}

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

@@ -4,9 +4,6 @@ import { resolveCapabilityBriefMessageHeadroom } from "./capability-brief-budget
 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);
@@ -40,8 +37,8 @@ export function createCapabilityBriefReadmissionController(params) {
                 ...projected.slice(briefIndex + 1),
             ];
         },
-        prepare(messages) {
-            return controller.prepare(messages);
+        getStages() {
+            return controller.getStages();
         },
     });
 }

package/dist/src/runtime/context/capability-result-compaction-source.d.ts

@@ -0,0 +1,12 @@
+import type { RoleCallLedgerHead } from "../orchestration/role-calls/index.js";
+import type { RequestToolResult } from "./request-tool-results.js";
+import { type SemanticCompactionSource } from "./semantic-compaction/contracts.js";
+/** Capture full immutable bytes once, independently of the evidence consumer. */
+export declare function createCapabilityResultCompactionSource(result: RequestToolResult): SemanticCompactionSource;
+export declare function projectCanonicalCapabilityResultCompactionSources(params: {
+    head: RoleCallLedgerHead;
+    callId: string;
+}): readonly SemanticCompactionSource[];
+/** The existing visible Worker dedup rule also defines canonical source bytes. */
+export declare function projectSingleCopyCapabilityResult(result: RequestToolResult): RequestToolResult;
+export declare function isReferenceDataRepresentedByAdapterResult(result: Pick<RequestToolResult, "referenceData" | "adapterResult">): boolean;

package/dist/src/runtime/context/capability-result-compaction-source.js

@@ -0,0 +1,61 @@
+import { projectCanonicalRequestToolResult } from "./canonical-capability-result.js";
+import { hasSuperContextContract } from "./super-context-policy.js";
+import { createSemanticCompactionSha256Fingerprint, } from "./semantic-compaction/contracts.js";
+/** Capture full immutable bytes once, independently of the evidence consumer. */
+export function createCapabilityResultCompactionSource(result) {
+    if (!result.adapterResult)
+        throw new Error("context_compaction_source_adapter_required");
+    const exact = projectSingleCopyCapabilityResult(result);
+    const content = JSON.stringify({
+        executionId: exact.executionId,
+        callId: exact.callId,
+        invocationAttempt: exact.invocationAttempt,
+        capabilityId: exact.capabilityId,
+        declaredEffect: exact.declaredEffect,
+        outcome: exact.outcome,
+        observedEffect: exact.observedEffect,
+        summary: exact.summary,
+        ...(exact.referenceData ? { referenceData: exact.referenceData } : {}),
+        ...(exact.references ? { references: exact.references } : {}),
+        ...(exact.acceptedAction ? { acceptedAction: exact.acceptedAction } : {}),
+        adapterResult: exact.adapterResult,
+    });
+    return Object.freeze({
+        sourceRef: result.executionId,
+        sourceFingerprint: createSemanticCompactionSha256Fingerprint(content),
+        content,
+    });
+}
+export function projectCanonicalCapabilityResultCompactionSources(params) {
+    if (!hasSuperContextContract(params.head.policy.authority, "delegated.worker")) {
+        throw new Error("context_compaction_source_policy_invalid");
+    }
+    const call = params.head.state.calls.find(({ callId }) => callId === params.callId);
+    if (!call || call.roleId !== "worker")
+        throw new Error("context_compaction_source_call_invalid");
+    return Object.freeze(params.head.state.capabilityExecutions
+        .filter((execution) => execution.callId === call.callId && execution.status === "settled")
+        .map((execution) => createCapabilityResultCompactionSource(projectCanonicalRequestToolResult(params.head, execution))));
+}
+/** The existing visible Worker dedup rule also defines canonical source bytes. */
+export function projectSingleCopyCapabilityResult(result) {
+    if (!isReferenceDataRepresentedByAdapterResult(result))
+        return result;
+    const { referenceData: _referenceData, ...singleCopyResult } = result;
+    return Object.freeze(singleCopyResult);
+}
+export function isReferenceDataRepresentedByAdapterResult(result) {
+    const referenceData = result.referenceData;
+    const adapterResult = result.adapterResult;
+    if (!referenceData || !adapterResult)
+        return false;
+    if (adapterResult.kind === "registered_tool_execution_result_v1") {
+        return adapterResult.result.output === referenceData;
+    }
+    if (adapterResult.kind !== "generic_capability_result_v1")
+        return false;
+    const payload = adapterResult.payload;
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        return false;
+    return payload.referenceData === referenceData;
+}