@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/runtime/context/tool-media-projection.js

@@ -0,0 +1,97 @@
+import { isToolResultMedia } from "../../capabilities/tool-media.js";
+/** Hydrates only exact original evidence in the producing role's existing lane. */
+export function projectToolMediaMessages(params) {
+    if (!isToolMediaConsumer(params.modelStep))
+        return [...params.messages];
+    return params.messages.map((message) => projectMessage(message, params));
+}
+function isToolMediaConsumer(step) {
+    return ["execution.decision", "execution.response", "worker.decision", "worker.result"].includes(step);
+}
+function projectMessage(message, params) {
+    const content = readRecord(message.content);
+    if (!content)
+        return message;
+    const evidence = readOriginalEvidence(message, content, params.modelStep);
+    if (!evidence.length)
+        return message;
+    const mediaDelivery = {
+        kind: "runtime_tool_media_delivery_v1",
+        authority: "passive_tool_evidence_not_user_intent",
+        status: params.supportsImages ? "delivered" : "unsupported_image_input",
+        ...(params.supportsImages ? {} : { message: "This model cannot receive the tool images. Image references are not visual evidence; use available text or report this limitation." }),
+    };
+    const attachments = [];
+    for (const item of evidence) {
+        for (const reference of item.media) {
+            if (!params.store)
+                throw new Error("tool_media_store_unavailable");
+            const owner = params.store.ownerOf(item.executionId, reference);
+            if (item.callId && item.callId !== owner.callId)
+                throw new Error("tool_media_call_mismatch");
+            const data = params.store.resolve(owner, reference);
+            if (!params.supportsImages)
+                continue;
+            attachments.push({
+                id: reference.id, kind: "image", mimeType: reference.mimeType,
+                storageRef: "request-tool-media", size: reference.size, data,
+                toolEvidence: { executionId: item.executionId },
+            });
+        }
+    }
+    if (message.toolCalls)
+        throw new Error("tool_media_lane_invalid");
+    return {
+        ...message,
+        content: JSON.stringify({ ...content, mediaDelivery }),
+        ...(attachments.length ? { attachments } : {}),
+    };
+}
+function readOriginalEvidence(message, content, step) {
+    if (message.role === "tool") {
+        if (!step.startsWith("execution."))
+            return [];
+        if (content.kind !== "runtime_execution_capability_result_v1")
+            return [];
+        const result = record(content.result);
+        if (!result || result.executionId !== message.toolCallId)
+            throw new Error("tool_media_result_binding_invalid");
+        return readExecutionEvidence(result);
+    }
+    if (!step.startsWith("worker.") || message.role !== "user")
+        return [];
+    if (content.kind !== "runtime_request_tool_results_v1")
+        return [];
+    if (!Array.isArray(content.results))
+        return [];
+    return content.results.flatMap((entry) => {
+        const result = record(entry);
+        return result ? readExecutionEvidence(result) : [];
+    });
+}
+function readExecutionEvidence(result) {
+    const adapter = record(result.adapterResult);
+    if (adapter?.kind !== "registered_tool_execution_result_v1")
+        return [];
+    const original = record(adapter.result);
+    if (!original || original.media === undefined)
+        return [];
+    if (!isToolResultMedia(original.media) || typeof result.executionId !== "string")
+        throw new Error("tool_media_result_invalid");
+    if (!original.media?.length)
+        return [];
+    return [{ executionId: result.executionId, ...(typeof result.callId === "string" ? { callId: result.callId } : {}), media: original.media }];
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function readRecord(value) {
+    try {
+        return record(JSON.parse(value));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/runtime/lifecycle/request-finalizer.d.ts

@@ -5,6 +5,7 @@ import { RequestLifecycle } from "../orchestration/lifecycle/request-lifecycle.j
 import type { RequestObservation, RequestOutputTextMode } from "../request/result.js";
 import type { RequestSessionStore } from "../request/session-store.js";
 import type { LongTermMemoryService, MemoryCandidate } from "../long-term-memory/contracts.js";
+import type { SessionTerminalMessage } from "../../sessions/request-lifecycle/contracts.js";
 type RequestFinalizationResult = {
     status: "completed";
     output: string;
@@ -21,6 +22,7 @@ export declare function finalizeRequest(params: {
     outputTextMode?: RequestOutputTextMode;
     events: EventSink;
     lifecycle: RequestLifecycle;
+    claimFinalization?: () => void;
     sessionStore: Pick<RequestSessionStore, "appendMessage">;
     sessionId: string;
     requestId: string;
@@ -29,5 +31,7 @@ export declare function finalizeRequest(params: {
     finalObservation?: RequestObservation;
     memoryCandidates?: readonly MemoryCandidate[];
     longTermMemory?: LongTermMemoryService;
+    composeInvalidFinalOutput?: () => Promise<string>;
+    persistResponse?: (message: SessionTerminalMessage) => Promise<void>;
 }): Promise<RequestFinalizationResult>;
 export {};

package/dist/src/runtime/lifecycle/request-finalizer.js

@@ -1,29 +1,43 @@
+import { throwIfRequestCancelled } from "../request/cancellation.js";
 import { finalizeResponse } from "../orchestration/final-response/finalization.js";
 import { scheduleFinalResponseMemory } from "../long-term-memory/finalization.js";
+import { traceDebug } from "../observability/debug-logger.js";
 export function failRequest(params) {
     params.events.event("thinking.completed");
     params.events.failed(params.error, params.details);
 }
 export async function finalizeRequest(params) {
-    if (!params.rawOutput.trim()) {
-        failRequest({
-            events: params.events,
-            error: "invalid_final_output",
-            details: {
-                reason: "empty_final_output",
-                stage: "chat_finalization",
-            },
+    throwIfRequestCancelled(params.lifecycle.signal);
+    const hasValidFinalOutput = params.rawOutput.trim().length > 0;
+    if (!hasValidFinalOutput) {
+        params.lifecycle.signal.throwIfAborted();
+        traceDebug("runtime.request", "final_output.invalid", {
+            requestId: params.requestId,
+            code: "invalid_final_output",
+            reason: "empty_final_output",
+            stage: "chat_finalization",
+            disposition: "degraded_authoring",
         });
-        return { status: "failed" };
     }
-    const output = params.outputTextMode === "exact"
-        ? params.rawOutput
-        : params.rawOutput.trim();
+    const output = await resolveFinalizationOutput(params.rawOutput, params.outputTextMode, params.lifecycle.signal, params.composeInvalidFinalOutput);
+    if (!hasValidFinalOutput)
+        params.lifecycle.signal.throwIfAborted();
+    const finalObservation = hasValidFinalOutput
+        ? params.finalObservation
+        : undefined;
+    const memoryCandidates = hasValidFinalOutput
+        ? params.memoryCandidates
+        : undefined;
     params.lifecycle.markProgress("valid_final_output");
     const finalizationState = { stage: "finalization" };
     params.lifecycle.updateState(finalizationState);
     params.events.runtimeState(finalizationState);
+    throwIfRequestCancelled(params.lifecycle.signal);
+    params.claimFinalization?.();
     await finalizeResponse({
+        ...(params.persistResponse
+            ? { persistResponse: params.persistResponse }
+            : {}),
         events: params.events,
         sessionStore: params.sessionStore,
         sessionId: params.sessionId,
@@ -32,15 +46,15 @@ export async function finalizeRequest(params) {
         output,
         grounding: "conversation",
         thinkingTrace: params.thinkingTrace,
-        ...(params.finalObservation
+        ...(finalObservation
             ? {
-                observationMeta: params.finalObservation.observationMeta,
-                observationContent: params.finalObservation.observationContent,
+                observationMeta: finalObservation.observationMeta,
+                observationContent: finalObservation.observationContent,
             }
             : {}),
         afterPersist: () => scheduleFinalResponseMemory({
             service: params.longTermMemory,
-            candidates: params.memoryCandidates,
+            candidates: memoryCandidates,
             requestId: params.requestId,
             sessionId: params.sessionId,
             onEvent: params.events.event.bind(params.events),
@@ -48,3 +62,18 @@ export async function finalizeRequest(params) {
     });
     return { status: "completed", output };
 }
+async function resolveFinalizationOutput(rawOutput, outputTextMode, signal, composeInvalidFinalOutput) {
+    const hasValidFinalOutput = rawOutput.trim().length > 0;
+    if (hasValidFinalOutput) {
+        return outputTextMode === "exact" ? rawOutput : rawOutput.trim();
+    }
+    const canComposeInvalidFinalOutput = composeInvalidFinalOutput !== undefined;
+    if (!canComposeInvalidFinalOutput)
+        throw new Error("invalid_final_output");
+    const authored = await composeInvalidFinalOutput();
+    signal.throwIfAborted();
+    const hasValidDegradedOutput = authored.trim().length > 0;
+    if (!hasValidDegradedOutput)
+        throw new Error("invalid_final_output");
+    return outputTextMode === "exact" ? authored : authored.trim();
+}

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

@@ -8,9 +8,10 @@ export type LocalRuntimeApplicationOptions = Readonly<{
 export declare function createLocalRuntimeApplication(config?: RuntimeConfig, options?: LocalRuntimeApplicationOptions): Readonly<{
     services: Readonly<{
         longTermMemory: import("./index.js").LongTermMemoryService;
+        passiveLearning: import("./local-host/client-learning.js").PassiveLearningManagement;
         sessions: import("./ports.js").SessionStore;
         attachments: import("./index.js").RuntimeAttachmentStore;
-        scheduler: Omit<import("./scheduler/contracts.js").SchedulerService, "stop" | "start">;
+        scheduler: Omit<import("./scheduler/contracts.js").SchedulerService, "start" | "stop">;
         projects: Readonly<{
             list: () => Promise<readonly import("./projects/contracts.js").RuntimeProject[]>;
             get: (id: string) => Promise<import("./projects/contracts.js").RuntimeProject | null>;
@@ -30,11 +31,36 @@ export declare function createLocalRuntimeApplication(config?: RuntimeConfig, op
         config: RuntimeConfig;
     }>;
     requests: RuntimeRequestHandler;
+    approvals: {
+        list: (sessionId?: string) => Promise<Readonly<{
+            sessionId: string;
+            run?: SchedulerRun;
+            request: import("./ports.js").ToolApprovalRequest;
+            wait?: Readonly<{
+                generation: string;
+                waitId: string;
+                revision: number;
+            }>;
+        }>[]>;
+        decide: (input: Readonly<{
+            sessionId: string;
+            requestId: string;
+            approvalId: string;
+            approved: boolean;
+            reason?: string;
+            generation?: string;
+            waitId?: string;
+            revision?: number;
+            commandId?: string;
+        }>) => Promise<import("./local-host/request-approval-contracts.js").LocalToolApprovalDecisionResult>;
+        attach: (requestId: string, sessionId: string, ws: Parameters<(ws: import("ws").default, message: import("./request/contracts.js").RunRequestMessage, options?: RuntimeRequestOptions) => Promise<import("./request/handler.js").RequestHandlerOutcome>>[0], options?: RuntimeRequestOptions, onAccepted?: () => void) => Promise<void>;
+    };
     start: () => Promise<void>;
     stop(): Promise<void>;
     getOwnership: () => "owner" | "client" | undefined;
     isOwnerIdle: () => boolean;
     stopIfIdle(): Promise<boolean>;
     subscribeScheduledEvents: (listener: (event: Record<string, unknown>) => void) => () => void;
+    subscribeLearningEvents: (listener: (event?: import("./passive-learning/contracts.js").LearningChangedEvent) => void) => () => void;
 }>;
 export type LocalRuntimeApplication = ReturnType<typeof createLocalRuntimeApplication>;

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

@@ -6,22 +6,40 @@ import { createLocalRuntimeOwner } from "./local-host/app-owner.js";
 import { LocalRuntimeClientRequests } from "./local-host/client-requests.js";
 import { createLocalMemoryClient } from "./local-host/client-memory.js";
 import { createLocalServiceClients } from "./local-host/client-services.js";
+import { createLocalLearningClient } from "./local-host/client-learning.js";
 /** Managed library entry: attach to the environment owner or create it once. */
 export function createLocalRuntimeApplication(config = loadRuntimeConfig(), options = {}) {
     let connection;
     let startup;
+    let approvalConnection;
     let stopped = false;
     const call = async (method, args) => {
         await start();
         return connection.call(method, args);
     };
-    const client = new LocalRuntimeClientRequests(call, options.scheduledRequestOptions);
+    const client = new LocalRuntimeClientRequests(call, options.scheduledRequestOptions, async (method, args) => {
+        await start();
+        approvalConnection ??= attachApprovalConnection().finally(() => {
+            approvalConnection = undefined;
+        });
+        await approvalConnection;
+        return connection.call(method, args);
+    });
     const memory = createLocalMemoryClient(call, config.longTermMemory?.enabled === true);
+    const learning = createLocalLearningClient(call);
     const services = Object.freeze({
         config,
         ...createLocalServiceClients(call),
         longTermMemory: memory.service,
+        passiveLearning: learning.service,
     });
+    async function attachApprovalConnection() {
+        const reconnected = await connection.reconnect();
+        if (!reconnected)
+            return;
+        if (options.scheduledRequestOptions)
+            await connection.call("controls.register", []);
+    }
     async function connect() {
         const current = await createLocalRuntimeConnection({
             directory: join(config.paths.runtimeDir, "local-host"),
@@ -30,7 +48,10 @@ export function createLocalRuntimeApplication(config = loadRuntimeConfig(), opti
         });
         connection = current;
         try {
-            current.onClose(() => client.close(true));
+            current.onClose(() => {
+                client.close(true);
+                learning.close();
+            });
             current.setClientHandler(async (method, args) => {
                 if (method === "memory.event") {
                     memory.handleEvent(args);
@@ -38,7 +59,10 @@ export function createLocalRuntimeApplication(config = loadRuntimeConfig(), opti
                 }
                 return client.handleCallback(method, args);
             });
-            current.subscribe((event) => client.receive(event));
+            current.subscribe((event) => {
+                client.receive(event);
+                learning.receive(event);
+            });
             if (options.scheduledRequestOptions) {
                 await current.call("controls.register", []);
             }
@@ -64,6 +88,7 @@ export function createLocalRuntimeApplication(config = loadRuntimeConfig(), opti
     return Object.freeze({
         services,
         requests: client.requests,
+        approvals: client.approvals,
         start,
         async stop() {
             stopped = true;
@@ -72,6 +97,7 @@ export function createLocalRuntimeApplication(config = loadRuntimeConfig(), opti
             }
             finally {
                 client.close();
+                learning.close();
                 await connection?.close();
             }
         },
@@ -86,8 +112,10 @@ export function createLocalRuntimeApplication(config = loadRuntimeConfig(), opti
             const closing = connection.closeIfIdle();
             stopped = true;
             client.close();
+            learning.close();
             return closing;
         },
         subscribeScheduledEvents: client.subscribe.bind(client),
+        subscribeLearningEvents: learning.subscribe,
     });
 }

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

@@ -0,0 +1,3 @@
+import type { PassiveLearningService } from "../passive-learning/contracts.js";
+/** An explicit management surface excludes collection ingress and lifecycle RPCs. */
+export declare function dispatchLocalLearningCall(service: PassiveLearningService | undefined, method: string, args: readonly unknown[]): Promise<unknown>;

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

@@ -0,0 +1,54 @@
+import { readLearningPreferencesInput } from "./learning-preferences-input.js";
+import { isLearningEventId } from "./learning-events.js";
+/** An explicit management surface excludes collection ingress and lifecycle RPCs. */
+export function dispatchLocalLearningCall(service, method, args) {
+    if (!service)
+        throw new Error("passive_learning_unavailable");
+    if (method === "learning.status")
+        return service.status();
+    if (method === "learning.candidates") {
+        if (args.length !== 0)
+            throw new Error("passive_learning_candidates_invalid");
+        if (!service.candidates)
+            throw new Error("passive_learning_unavailable");
+        return service.candidates();
+    }
+    if (method === "learning.dismissProposal") {
+        if (args.length !== 1 || !isLearningEventId(args[0]))
+            throw new Error("passive_learning_proposal_invalid");
+        if (!service.dismissProposal)
+            throw new Error("passive_learning_unavailable");
+        return service.dismissProposal(args[0]);
+    }
+    if (method === "learning.clearPending") {
+        if (args.length !== 0)
+            throw new Error("passive_learning_clear_pending_invalid");
+        return service.clearPending();
+    }
+    if (method === "learning.restartCollection") {
+        if (args.length !== 0)
+            throw new Error("passive_learning_restart_collection_invalid");
+        if (!service.restartCollection)
+            throw new Error("passive_learning_unavailable");
+        return service.restartCollection();
+    }
+    if (method === "learning.configure") {
+        if (args.length !== 1)
+            throw new Error("passive_learning_preferences_invalid");
+        return service.configure(readLearningPreferencesInput(args[0]));
+    }
+    if (method === "learning.batches") {
+        const input = args[0];
+        if (input === undefined)
+            return service.batches();
+        if (!input || typeof input !== "object" || Array.isArray(input))
+            throw new Error("passive_learning_page_invalid");
+        return service.batches(input);
+    }
+    if (method === "learning.batch") {
+        if (typeof args[0] !== "string")
+            throw new Error("passive_learning_batch_invalid");
+        return service.batch(args[0]);
+    }
+    throw new Error("local_runtime_method_unknown");
+}

package/dist/src/runtime/local-host/app-owner.js

@@ -3,6 +3,9 @@ import { LocalMemoryDispatcher } from "./app-memory-dispatch.js";
 import { LocalRequestControls, } from "./app-request-control.js";
 import { dispatchLocalServiceCall } from "./app-service-dispatch.js";
 import { LocalRuntimeOwnerActivity } from "./owner-activity.js";
+import { dispatchLocalLearningCall } from "./app-learning-dispatch.js";
+import { projectLearningChangedEvent } from "./learning-events.js";
+import { SavedRequestApprovals } from "./saved-approvals.js";
 export async function createLocalRuntimeOwner(config, overrides = {}) {
     const listeners = new Set();
     const publish = (event) => {
@@ -22,18 +25,25 @@ export async function createLocalRuntimeOwner(config, overrides = {}) {
         scheduledRequestOptions: (run) => controls.scheduled(run),
     });
     const memory = new LocalMemoryDispatcher(application.services.longTermMemory);
+    const savedApprovals = new SavedRequestApprovals(application, controls, activity, publish);
     const unsubscribe = application.subscribeScheduledEvents((event) => {
         publish({ type: "scheduled.event", event });
         if (event.type === "completed" || event.type === "failed")
             controls.finish(String(event.requestId));
     });
+    const unsubscribeLearning = application.services.passiveLearning?.subscribe((change) => {
+        const event = projectLearningChangedEvent(change);
+        publish({ type: "learning.changed", ...(event ? { event } : {}) });
+    });
     try {
+        await savedApprovals.recover();
         await application.start();
     }
     catch (error) {
         activity.stop();
         application.services.requestAdmission?.close();
         unsubscribe();
+        unsubscribeLearning?.();
         await application.stop();
         throw error;
     }
@@ -43,12 +53,43 @@ export async function createLocalRuntimeOwner(config, overrides = {}) {
             return activity.run(async () => {
                 if (method === "controls.register")
                     return controls.register(peer);
+                if (method === "request.active")
+                    return controls.hasActiveRequest(args[0], args[1]);
+                if (method === "request.approvals")
+                    return [
+                        ...(await savedApprovals.list(args[0])),
+                        ...controls.listApprovals(args[0]),
+                    ];
+                if (method === "request.approval.decide")
+                    return ((await savedApprovals.decide(args[0], peer)) ??
+                        controls.decideApproval(args[0], peer));
+                if (method === "request.attach") {
+                    if (await savedApprovals.attach(args[0], args[1], peer))
+                        return;
+                    return controls.attach(args[0], args[1], peer);
+                }
                 if (method === "request.steer")
                     return controls.steer(args[0], args[1]);
+                if (method === "request.cancel") {
+                    if (await savedApprovals.cancel(args[0], args[1], args[2]))
+                        return { accepted: true };
+                    return controls.cancel(args[0], args[1], args[2]);
+                }
                 if (method === "request.run")
-                    return runPeerRequest(application, controls, activity, args, peer);
-                if (method.startsWith("memory."))
-                    return memory.call(method, args, peer);
+                    return savedApprovals.track(String(args[0]?.requestId), () => runPeerRequest(application, controls, activity, savedApprovals, args, peer));
+                if (method.startsWith("memory.")) {
+                    const result = await memory.call(method, args, peer);
+                    if ([
+                        "memory.create",
+                        "memory.update",
+                        "memory.delete",
+                        "memory.clear",
+                    ].includes(method))
+                        publish({ type: "learning.changed" });
+                    return result;
+                }
+                if (method.startsWith("learning."))
+                    return dispatchLocalLearningCall(application.services.passiveLearning, method, args);
                 return dispatchLocalServiceCall(application.services, method, args);
             });
         },
@@ -64,6 +105,7 @@ export async function createLocalRuntimeOwner(config, overrides = {}) {
             memory.stop();
             controls.stop();
             unsubscribe();
+            unsubscribeLearning?.();
             listeners.clear();
             shutdown = application.stop();
             return shutdown;
@@ -81,39 +123,27 @@ export async function createLocalRuntimeOwner(config, overrides = {}) {
         },
     };
 }
-async function runPeerRequest(application, controls, activity, args, peer) {
+async function runPeerRequest(application, controls, activity, savedApprovals, args, peer) {
     const message = args[0];
     if (!message || typeof message.requestId !== "string")
         throw new Error("local_runtime_request_invalid");
-    const options = controls.ordinary(message.requestId, peer, (args[1] ?? {}));
-    let connected = true;
-    const removeClose = peer.onClose(() => {
-        connected = false;
-    });
-    let delivery = Promise.resolve();
+    const options = controls.ordinary(message.requestId, peer, (args[1] ?? {}), typeof message.sessionId === "string" ? message.sessionId : "");
+    const durable = args[1]?.durableApprovals === true;
+    if (durable)
+        options.approvalExecution = { activation: savedApprovals.activation() };
     const socket = {
         send(data) {
-            if (!connected)
-                return;
-            const event = JSON.parse(data);
-            delivery = delivery
-                .then(async () => {
-                if (connected)
-                    await peer.callClient("request.event", [message.requestId, event]);
-            })
-                .catch(() => {
-                connected = false;
-            });
+            controls.send(message.requestId, JSON.parse(data));
         },
     };
     try {
         await peer.callClient("request.accepted", [message.requestId]);
         activity.assertAcceptingRequests();
-        await application.requests.handle(socket, message, options);
-        await delivery;
+        const result = await application.requests.handle(socket, message, options);
+        await controls.drain(message.requestId);
+        return result;
     }
     finally {
-        removeClose();
         controls.finish(message.requestId);
     }
 }

package/dist/src/runtime/local-host/app-request-approvals.d.ts

@@ -0,0 +1,18 @@
+import type { ToolApprovalDecision, ToolApprovalRequest } from "../ports.js";
+import type { LocalRuntimePeer } from "./contracts.js";
+import type { LocalPendingToolApproval, LocalToolApprovalDecisionInput, LocalToolApprovalDecisionResult } from "./request-approval-contracts.js";
+export declare function hasApprovalDecisionIdentity(input: unknown): input is LocalToolApprovalDecisionInput;
+/** Approval promises belong to the live request, never to a transport attempt. */
+export declare class LocalRequestApprovals {
+    private readonly pending;
+    list(sessionId?: unknown): LocalPendingToolApproval[];
+    hasPending(requestId: string): boolean;
+    decide(input: unknown): LocalToolApprovalDecisionResult;
+    wait(sessionId: string, peer: LocalRuntimePeer | undefined, request: ToolApprovalRequest, signal: AbortSignal): Promise<ToolApprovalDecision>;
+    detach(requestId: string): void;
+    attach(requestId: string, peer: LocalRuntimePeer): void;
+    cancel(requestId: string): void;
+    private offer;
+    private isCurrentOffer;
+    private detachOffer;
+}