@abot-ai/runtime 1.0.0

package/dist/src/runtime/request/execution-scope-surfaces.d.ts

@@ -0,0 +1,14 @@
+import type { RequestModelStepPort } from "../model/model-step-port.js";
+import { type RequestExecutionSeed, type RequestModelInvocationView } from "./contracts.js";
+import type { RequestSeedFacets } from "./execution-facets.js";
+import type { RequestCapabilityCompositionView, RequestCapabilityExecutionView, RequestExecutionPolicyFacet, RequestExecutionScope, RequestWorkerCapabilities } from "./execution-scope.js";
+export declare const REQUEST_EXECUTION_SCOPE: unique symbol;
+export declare function createCapabilityCompositionView(facets: RequestSeedFacets, modelSteps: RequestModelStepPort): RequestCapabilityCompositionView;
+export declare function createCapabilityExecutionView(facets: RequestSeedFacets, executionPolicySelection: RequestExecutionSeed["executionPolicySelection"], modelSteps: RequestModelStepPort): RequestCapabilityExecutionView;
+export declare function createScopeSurface(input: Readonly<{
+    facets: RequestSeedFacets;
+    policy: RequestExecutionPolicyFacet;
+    modelInvocation: RequestModelInvocationView;
+    modelSteps: RequestModelStepPort;
+    capabilities: RequestWorkerCapabilities;
+}>): RequestExecutionScope;

package/dist/src/runtime/request/execution-scope-surfaces.js

@@ -0,0 +1,138 @@
+import { BOUND_REQUEST_MODEL_INVOCATION, } from "./contracts.js";
+import { createFrozenSurface, enumerableGetter, hiddenValue, } from "./immutable-view.js";
+export const REQUEST_EXECUTION_SCOPE = Symbol("request_execution_scope");
+export function createCapabilityCompositionView(facets, modelSteps) {
+    return createFrozenSurface({
+        requestId: enumerableGetter(() => facets.identity.requestId),
+        runnerConfig: enumerableGetter(() => facets.model.runnerConfig),
+        agentMode: enumerableGetter(() => facets.input.agentMode),
+        ...(facets.model.modelPreference !== undefined
+            ? {
+                modelPreference: enumerableGetter(() => facets.model.modelPreference),
+            }
+            : {}),
+        ...(facets.model.modelPolicy !== undefined
+            ? { modelPolicy: enumerableGetter(() => facets.model.modelPolicy) }
+            : {}),
+        modelGatewayClient: enumerableGetter(() => facets.model.modelGatewayClient),
+        ...(facets.lifecycle.requestSteering !== undefined
+            ? {
+                requestSteering: enumerableGetter(() => facets.lifecycle.requestSteering),
+            }
+            : {}),
+        abortSignal: enumerableGetter(() => facets.lifecycle.abortSignal),
+        onThinkingDelta: enumerableGetter(() => facets.presentation.onThinkingDelta),
+        onThinkingTrace: enumerableGetter(() => facets.presentation.onThinkingTrace),
+        modelSteps: enumerableGetter(() => modelSteps),
+        sessionId: enumerableGetter(() => facets.identity.sessionId),
+        prompt: enumerableGetter(() => facets.input.prompt),
+        historyMessages: enumerableGetter(() => facets.session.historyMessages),
+        toolPermissionMode: enumerableGetter(() => facets.lifecycle.toolPermissionMode),
+        ...(facets.lifecycle.toolApprovalController !== undefined
+            ? {
+                toolApprovalController: enumerableGetter(() => facets.lifecycle.toolApprovalController),
+            }
+            : {}),
+        onEvent: enumerableGetter(() => facets.lifecycle.onEvent),
+        ...(facets.session.contextCompactionStore !== undefined
+            ? {
+                contextCompactionStore: enumerableGetter(() => facets.session.contextCompactionStore),
+            }
+            : {}),
+        [BOUND_REQUEST_MODEL_INVOCATION]: hiddenValue(true),
+    });
+}
+export function createCapabilityExecutionView(facets, executionPolicySelection, modelSteps) {
+    return createFrozenSurface({
+        ...requestSeedDescriptors(facets, executionPolicySelection, false),
+        modelSteps: enumerableGetter(() => modelSteps),
+        [BOUND_REQUEST_MODEL_INVOCATION]: hiddenValue(true),
+    });
+}
+export function createScopeSurface(input) {
+    const { facets, policy, modelInvocation, modelSteps, capabilities } = input;
+    return createFrozenSurface({
+        ...requestSeedDescriptors(facets, policy.selection, true),
+        ...(facets.session.sessionMemory !== undefined
+            ? {
+                sessionMemory: enumerableGetter(() => facets.session.sessionMemory),
+            }
+            : {}),
+        executionPolicy: enumerableGetter(() => policy.executionPolicy),
+        modelSteps: enumerableGetter(() => modelSteps),
+        workerCapabilities: enumerableGetter(() => capabilities),
+        identity: hiddenValue(facets.identity),
+        input: hiddenValue(facets.input),
+        session: hiddenValue(facets.session),
+        model: hiddenValue(facets.model),
+        lifecycle: hiddenValue(facets.lifecycle),
+        presentation: hiddenValue(facets.presentation),
+        policy: hiddenValue(policy),
+        modelInvocation: hiddenValue(modelInvocation),
+        capabilities: hiddenValue(capabilities),
+        [BOUND_REQUEST_MODEL_INVOCATION]: hiddenValue(true),
+        [REQUEST_EXECUTION_SCOPE]: hiddenValue(true),
+    });
+}
+function requestSeedDescriptors(facets, executionPolicySelection, includeSessionArtifactPaths) {
+    return {
+        requestId: enumerableGetter(() => facets.identity.requestId),
+        sessionId: enumerableGetter(() => facets.identity.sessionId),
+        prompt: enumerableGetter(() => facets.input.prompt),
+        ...(facets.input.temporalContext !== undefined
+            ? {
+                temporalContext: enumerableGetter(() => facets.input.temporalContext),
+            }
+            : {}),
+        historyMessages: enumerableGetter(() => facets.session.historyMessages),
+        ...(includeSessionArtifactPaths &&
+            facets.session.sessionArtifactPaths !== undefined
+            ? {
+                sessionArtifactPaths: enumerableGetter(() => facets.session.sessionArtifactPaths),
+            }
+            : {}),
+        shouldGenerateSessionTitle: enumerableGetter(() => facets.session.shouldGenerateSessionTitle),
+        runnerConfig: enumerableGetter(() => facets.model.runnerConfig),
+        ...(executionPolicySelection !== undefined
+            ? {
+                executionPolicySelection: enumerableGetter(() => executionPolicySelection),
+            }
+            : {}),
+        ...(facets.input.attachments !== undefined
+            ? { attachments: enumerableGetter(() => facets.input.attachments) }
+            : {}),
+        agentMode: enumerableGetter(() => facets.input.agentMode),
+        ...(facets.model.modelPreference !== undefined
+            ? {
+                modelPreference: enumerableGetter(() => facets.model.modelPreference),
+            }
+            : {}),
+        ...(facets.model.modelPolicy !== undefined
+            ? { modelPolicy: enumerableGetter(() => facets.model.modelPolicy) }
+            : {}),
+        modelGatewayClient: enumerableGetter(() => facets.model.modelGatewayClient),
+        ...(facets.session.contextCompactionStore !== undefined
+            ? {
+                contextCompactionStore: enumerableGetter(() => facets.session.contextCompactionStore),
+            }
+            : {}),
+        ...(facets.lifecycle.requestSteering !== undefined
+            ? {
+                requestSteering: enumerableGetter(() => facets.lifecycle.requestSteering),
+            }
+            : {}),
+        toolPermissionMode: enumerableGetter(() => facets.lifecycle.toolPermissionMode),
+        ...(facets.lifecycle.toolApprovalController !== undefined
+            ? {
+                toolApprovalController: enumerableGetter(() => facets.lifecycle.toolApprovalController),
+            }
+            : {}),
+        abortSignal: enumerableGetter(() => facets.lifecycle.abortSignal),
+        onAcknowledgement: enumerableGetter(() => facets.presentation.onAcknowledgement),
+        onSessionTitle: enumerableGetter(() => facets.presentation.onSessionTitle),
+        onThinkingDelta: enumerableGetter(() => facets.presentation.onThinkingDelta),
+        onThinkingTrace: enumerableGetter(() => facets.presentation.onThinkingTrace),
+        onAnswerToken: enumerableGetter(() => facets.presentation.onAnswerToken),
+        onEvent: enumerableGetter(() => facets.lifecycle.onEvent),
+    };
+}

package/dist/src/runtime/request/execution-scope.d.ts

@@ -0,0 +1,43 @@
+import type { WorkerCapabilityAdapterProvider } from "../orchestration/worker-capabilities/index.js";
+import type { AcceptedRequestInput, BoundRequestModelInvocationContext, RequestSessionSnapshot, RequestExecutionSeed, RequestIdentity, RequestLifecycleRuntime, RequestModelInvocationView, RequestModelRuntime, RequestPresentation } from "./contracts.js";
+import type { CompiledExecutionPolicy } from "./root-contract.js";
+/** Request fields required while the request-bound capability catalog is built. */
+export type RequestCapabilityCompositionView = BoundRequestModelInvocationContext & Readonly<Pick<RequestExecutionSeed, "sessionId" | "prompt" | "historyMessages" | "toolPermissionMode" | "toolApprovalController" | "onEvent" | "contextCompactionStore">>;
+/**
+ * Stable request-owned context delivered to capability adapters.
+ * Passive session artifact paths and request containers are excluded.
+ */
+export type RequestCapabilityExecutionView = Readonly<Omit<RequestExecutionSeed, "sessionArtifactPaths" | "sessionMemory">> & BoundRequestModelInvocationContext;
+export type RequestWorkerCapabilities = Readonly<{
+    provider: WorkerCapabilityAdapterProvider<RequestCapabilityExecutionView>;
+    executionContext: RequestCapabilityExecutionView;
+}>;
+export type RequestExecutionPolicyFacet = Readonly<{
+    selection?: RequestExecutionSeed["executionPolicySelection"];
+    executionPolicy: CompiledExecutionPolicy<RequestExecutionScope>;
+}>;
+/** The single immutable request-scoped runtime object used after composition. */
+export type RequestExecutionScope = RequestExecutionSeed & BoundRequestModelInvocationContext & Readonly<{
+    identity: RequestIdentity;
+    input: AcceptedRequestInput;
+    session: RequestSessionSnapshot;
+    model: RequestModelRuntime;
+    lifecycle: RequestLifecycleRuntime;
+    presentation: RequestPresentation;
+    policy: RequestExecutionPolicyFacet;
+    modelInvocation: RequestModelInvocationView;
+    executionPolicy: CompiledExecutionPolicy<RequestExecutionScope>;
+    capabilities: RequestWorkerCapabilities;
+    workerCapabilities: RequestWorkerCapabilities;
+}>;
+export type CompiledRequestExecutionPolicy = RequestExecutionScope["executionPolicy"];
+export type RequestWorkerCapabilityProviderSource = Pick<RequestExecutionScope, "workerCapabilities">;
+export type RequestWorkerCapabilityCatalog = Pick<WorkerCapabilityAdapterProvider<RequestCapabilityExecutionView>, "getDescriptors" | "getExecutionGuidance">;
+export declare function createRequestExecutionScope(input: Readonly<{
+    seed: RequestExecutionSeed;
+    executionPolicy: CompiledRequestExecutionPolicy;
+    createWorkerCapabilities(view: RequestCapabilityCompositionView): WorkerCapabilityAdapterProvider<RequestCapabilityExecutionView>;
+}>): RequestExecutionScope;
+export declare function resolveRequestWorkerCapabilities(input: RequestExecutionScope): RequestWorkerCapabilities;
+export declare function resolveRequestWorkerCapabilityCatalog(input: RequestWorkerCapabilityProviderSource): RequestWorkerCapabilityCatalog;
+export declare function isRequestExecutionScope(input: object): input is RequestExecutionScope;

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

@@ -0,0 +1,34 @@
+import { RequestModelStepInvoker } from "../model/invoke-step.js";
+import { createModelInvocationView, createRequestSeedFacets, } from "./execution-facets.js";
+import { createCapabilityCompositionView, createCapabilityExecutionView, createScopeSurface, REQUEST_EXECUTION_SCOPE, } from "./execution-scope-surfaces.js";
+export function createRequestExecutionScope(input) {
+    const facets = createRequestSeedFacets(input.seed);
+    const policy = createRequestExecutionPolicyFacet(input.seed.executionPolicySelection, input.executionPolicy);
+    const modelInvocation = createModelInvocationView(facets);
+    const modelSteps = Object.freeze(new RequestModelStepInvoker(modelInvocation, facets.lifecycle.onEvent));
+    const executionContext = createCapabilityExecutionView(facets, policy.selection, modelSteps);
+    const provider = input.createWorkerCapabilities(createCapabilityCompositionView(facets, modelSteps));
+    const capabilities = Object.freeze({ provider, executionContext });
+    return createScopeSurface({
+        facets,
+        policy,
+        modelInvocation,
+        modelSteps,
+        capabilities,
+    });
+}
+export function resolveRequestWorkerCapabilities(input) {
+    return input.workerCapabilities;
+}
+export function resolveRequestWorkerCapabilityCatalog(input) {
+    return input.workerCapabilities.provider;
+}
+export function isRequestExecutionScope(input) {
+    return REQUEST_EXECUTION_SCOPE in input;
+}
+function createRequestExecutionPolicyFacet(selection, executionPolicy) {
+    return Object.freeze({
+        ...(selection !== undefined ? { selection } : {}),
+        executionPolicy,
+    });
+}

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

@@ -0,0 +1,3 @@
+import type WebSocket from "ws";
+import type { RequestHandlerOptions, RunRequestMessage } from "./contracts.js";
+export declare function handleRunRequest(ws: WebSocket, msg: RunRequestMessage, options?: RequestHandlerOptions): Promise<void>;

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

@@ -0,0 +1,244 @@
+import { traceDebug } from "../observability/debug-logger.js";
+import { RequestLifecycle } from "../orchestration/lifecycle/request-lifecycle.js";
+import { createRequestContextCompactionStore } from "../context/semantic-compaction/index.js";
+import { captureRequestTemporalContext } from "../context/request-temporal-context.js";
+import { failRequest, finalizeRequest, } from "../lifecycle/request-finalizer.js";
+import { resolveModelSelection } from "../model/model-selection.js";
+import { resolveRequestDependencies } from "./dependencies.js";
+import { parseRequestInput } from "./input.js";
+import { runRequestRunner } from "./runner.js";
+import { createRequestWorkerCapabilityProvider } from "./worker-capability-composition.js";
+import { resolveRequestExecutionPolicy } from "./role-executor-composition.js";
+import { initializeRequestSession, openRequestSession, } from "../session/request-session.js";
+import { snapshotRequestHistory } from "../session/request-history.js";
+import { createRequestSessionTitleUpdater, shouldGenerateSessionTitle, } from "../session/session-title.js";
+import { createInitialRequestEvents, createRequestCallbacks, createPersistentRequestEvents, } from "../streaming/request-callbacks.js";
+import { createRequestSteeringInbox } from "./request-steering.js";
+import { snapshotSessionArtifactPathTargets } from "./session-artifact-path-persistence.js";
+import { createRequestExecutionScope } from "./execution-scope.js";
+import { createRequestSessionMemory } from "../context/session-memory/index.js";
+export async function handleRunRequest(ws, msg, options = {}) {
+    return new RequestHandlingSession(ws, msg, options).run();
+}
+/** Owns the lifecycle and mutable edge state of one accepted request. */
+class RequestHandlingSession {
+    ws;
+    options;
+    input;
+    temporalContext;
+    requestSteering;
+    dependencies;
+    lifecycle;
+    events;
+    finalized = false;
+    constructor(ws, msg, options) {
+        this.ws = ws;
+        this.options = options;
+        this.input = parseRequestInput(msg);
+        this.temporalContext = captureRequestTemporalContext();
+        this.requestSteering =
+            options.requestSteering ??
+                createRequestSteeringInbox({ requestId: this.input.requestId });
+        this.dependencies = resolveRequestDependencies(options);
+        this.lifecycle = new RequestLifecycle({
+            requestId: this.input.requestId,
+        });
+        this.events = createInitialRequestEvents({
+            eventSinkFactory: this.dependencies.eventSinkFactory,
+            requestId: this.input.requestId,
+            ws,
+        });
+    }
+    async run() {
+        try {
+            await this.execute();
+        }
+        catch (error) {
+            this.fail(error);
+        }
+        finally {
+            await this.dispose();
+        }
+    }
+    async execute() {
+        const { requestId, sessionId, prompt, rawAttachments, rawAgentMode, rawModelPreference, toolPermissionMode, } = this.input;
+        const { eventSinkFactory, modelGatewayClient, sessionStore, attachmentStore, loadDecisionEnvironment, toolApprovalController, sessionMemoryCompactor, } = this.dependencies;
+        const { runnerConfig, modelPolicy, modelExecutionPolicies } = loadDecisionEnvironment();
+        const modelSelection = resolveModelSelection({
+            agentMode: rawAgentMode,
+            modelPreference: rawModelPreference,
+            modelPolicy,
+            ...(modelExecutionPolicies ? { modelExecutionPolicies } : {}),
+        });
+        const executionPolicy = resolveRequestExecutionPolicy(modelSelection.execution.policy);
+        const openedSession = await openRequestSession({
+            sessionId,
+            requestId,
+            rawAttachments,
+            sessionStore,
+            attachmentStore,
+        });
+        const historyMessages = snapshotRequestHistory(openedSession.session);
+        const sessionMemory = createRequestSessionMemory({
+            sessionId,
+            session: openedSession.session,
+            repository: sessionStore,
+            compactor: sessionMemoryCompactor,
+        });
+        const generateSessionTitle = shouldGenerateSessionTitle(openedSession.session);
+        this.events = createPersistentRequestEvents({
+            currentEvents: this.events,
+            eventSinkFactory,
+            requestId,
+            sessionId,
+            sessionStore,
+            ws: this.ws,
+        });
+        const callbacks = createRequestCallbacks(this.events);
+        const onSessionTitle = createRequestSessionTitleUpdater({
+            shouldGenerateTitle: generateSessionTitle,
+            sessionId,
+            requestId,
+            sessionStore,
+            events: this.events,
+            abortSignal: this.lifecycle.signal,
+        });
+        const initializedRequest = await initializeRequestSession({
+            opened: openedSession,
+            sessionId,
+            requestId,
+            prompt,
+            agentMode: modelSelection.agentMode,
+            sessionStore,
+            attachmentStore,
+            events: this.events,
+        });
+        this.bindSteeringPersistence();
+        this.enterModelStage();
+        const sessionArtifactPaths = snapshotSessionArtifactPathTargets(openedSession.session.artifactPaths);
+        const runnerRequestSeed = {
+            requestId,
+            sessionId,
+            prompt: initializedRequest.prompt,
+            temporalContext: this.temporalContext,
+            historyMessages,
+            shouldGenerateSessionTitle: generateSessionTitle,
+            runnerConfig,
+            executionPolicySelection: modelSelection.execution,
+            ...(initializedRequest.modelAttachments.length > 0
+                ? { attachments: initializedRequest.modelAttachments }
+                : {}),
+            agentMode: modelSelection.agentMode,
+            ...(modelSelection.modelPreference
+                ? { modelPreference: modelSelection.modelPreference }
+                : {}),
+            ...(modelSelection.modelPolicy
+                ? { modelPolicy: modelSelection.modelPolicy }
+                : {}),
+            modelGatewayClient,
+            contextCompactionStore: createRequestContextCompactionStore(),
+            sessionMemory,
+            requestSteering: this.requestSteering,
+            toolPermissionMode,
+            ...(toolApprovalController ? { toolApprovalController } : {}),
+            abortSignal: this.lifecycle.signal,
+            onAcknowledgement: callbacks.onAcknowledgement,
+            onSessionTitle,
+            onThinkingDelta: callbacks.onThinkingDelta,
+            onThinkingTrace: callbacks.onThinkingTrace,
+            onAnswerToken: callbacks.onAnswerToken,
+            onEvent: (name, extra) => this.events.event(name, extra),
+            ...(sessionArtifactPaths.length > 0 ? { sessionArtifactPaths } : {}),
+        };
+        const runnerRequest = createRequestExecutionScope({
+            seed: runnerRequestSeed,
+            executionPolicy,
+            createWorkerCapabilities: (request) => createRequestWorkerCapabilityProvider({
+                request,
+                executionPolicyAuthority: executionPolicy.authority,
+                requestAttachments: initializedRequest.toolAttachments,
+                ...(this.options.runtimeConfig
+                    ? { runtimeConfig: this.options.runtimeConfig }
+                    : {}),
+                ...(this.options.toolRegistry
+                    ? { toolRegistryOverride: this.options.toolRegistry }
+                    : {}),
+            }),
+        });
+        const upsertArtifactPaths = sessionStore.upsertArtifactPaths?.bind(sessionStore);
+        const runnerResult = await runRequestRunner(runnerRequest, {
+            ...(upsertArtifactPaths
+                ? {
+                    persistArtifactPaths: async (inputs) => {
+                        await upsertArtifactPaths(sessionId, inputs);
+                    },
+                }
+                : {}),
+        });
+        if (this.lifecycle.timedOutReason !== null) {
+            throw new Error(this.lifecycle.timedOutReason);
+        }
+        const finalization = await finalizeRequest({
+            rawOutput: runnerResult.output,
+            ...(runnerResult.outputTextMode
+                ? { outputTextMode: runnerResult.outputTextMode }
+                : {}),
+            events: this.events,
+            lifecycle: this.lifecycle,
+            sessionStore,
+            sessionId,
+            requestId,
+            agentMode: modelSelection.agentMode,
+            thinkingTrace: callbacks.getThinkingTrace(),
+            finalObservation: runnerResult.finalObservation,
+        });
+        this.finalized = true;
+        if (finalization.status === "failed")
+            return;
+        traceDebug("runtime.request", "request.completed", {
+            requestId,
+            sessionId,
+            outputLength: finalization.output.length,
+        });
+    }
+    bindSteeringPersistence() {
+        const { requestId, sessionId } = this.input;
+        const { sessionStore } = this.dependencies;
+        this.requestSteering.bindPersistence((update) => sessionStore
+            .appendMessage(sessionId, "user", update.text, {
+            source: "user",
+            requestId,
+        })
+            .then(() => undefined));
+    }
+    enterModelStage() {
+        const modelState = { stage: "model" };
+        this.lifecycle.updateState(modelState);
+        this.events.runtimeState(modelState);
+    }
+    fail(error) {
+        const { requestId, sessionId } = this.input;
+        const timedOutReason = this.lifecycle.timedOutReason;
+        const message = timedOutReason ??
+            (error instanceof Error ? error.message : "unknown error");
+        traceDebug("runtime.request", "request.failed", {
+            requestId,
+            sessionId,
+            error: message,
+        });
+        if (this.finalized)
+            return;
+        failRequest({
+            events: this.events,
+            error: message,
+            ...(timedOutReason ? { details: { stage: "timeout" } } : {}),
+        });
+        this.finalized = true;
+    }
+    async dispose() {
+        await this.requestSteering.close();
+        await this.events.drain();
+        this.events.dispose();
+        this.lifecycle.dispose();
+    }
+}

package/dist/src/runtime/request/immutable-view.d.ts

@@ -0,0 +1,4 @@
+/** Builds a frozen getter-backed view without copying its source values. */
+export declare function createFrozenSurface<T>(descriptors: PropertyDescriptorMap): T;
+export declare function enumerableGetter<T>(get: () => T): PropertyDescriptor;
+export declare function hiddenValue<T>(value: T): PropertyDescriptor;

package/dist/src/runtime/request/immutable-view.js

@@ -0,0 +1,10 @@
+/** Builds a frozen getter-backed view without copying its source values. */
+export function createFrozenSurface(descriptors) {
+    return Object.freeze(Object.defineProperties({}, descriptors));
+}
+export function enumerableGetter(get) {
+    return Object.freeze({ enumerable: true, get });
+}
+export function hiddenValue(value) {
+    return Object.freeze({ enumerable: false, value });
+}

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

@@ -0,0 +1,10 @@
+import type { RunRequestMessage } from "./contracts.js";
+export declare function parseRequestInput(msg: RunRequestMessage): {
+    requestId: string;
+    sessionId: string;
+    prompt: string;
+    rawAttachments: unknown;
+    rawAgentMode: unknown;
+    rawModelPreference: unknown;
+    toolPermissionMode: "full_access" | "ask";
+};

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

@@ -0,0 +1,21 @@
+export function parseRequestInput(msg) {
+    return {
+        requestId: msg.requestId,
+        sessionId: typeof msg.sessionId === "string" ? msg.sessionId.trim() : "",
+        prompt: typeof msg.input === "string"
+            ? msg.input
+            : typeof msg.text === "string"
+                ? msg.text
+                : "",
+        rawAttachments: msg.attachments,
+        rawAgentMode: msg.agentMode,
+        rawModelPreference: msg.modelPreference,
+        toolPermissionMode: resolveToolPermissionMode(msg.toolPermissionMode),
+    };
+}
+function resolveToolPermissionMode(value) {
+    const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+    return normalized === "full_access" || normalized === "full"
+        ? "full_access"
+        : "ask";
+}

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

@@ -0,0 +1,61 @@
+export type PlanItemStatus = "pending" | "in_progress" | "done" | "blocked";
+type ProjectablePlan = Readonly<{
+    definition: Readonly<{
+        summary: string;
+        items: readonly Readonly<{
+            itemId: string;
+            title: string;
+        }>[];
+    }>;
+    itemStates: readonly Readonly<{
+        itemId: string;
+        status: PlanItemStatus;
+    }>[];
+}>;
+export type RequestPlanProjectionState = Readonly<{
+    plan?: ProjectablePlan;
+}>;
+export type RequestPlanEventPhase = "created" | "updated";
+export type RequestPlanEventItem = Readonly<{
+    id: string;
+    title: string;
+    status: PlanItemStatus;
+    order: number;
+    total: number;
+}>;
+export type RequestPlanEventSnapshot = Readonly<{
+    summary: string;
+    total: number;
+    completed: number;
+    blocked: number;
+    pending: number;
+    inProgress: number;
+    items: readonly RequestPlanEventItem[];
+}>;
+export type RequestPlanItemChange = Readonly<{
+    item: RequestPlanEventItem;
+    previousStatus?: PlanItemStatus;
+}>;
+export type RequestPlanCommitProjection = Readonly<{
+    phase: RequestPlanEventPhase;
+    plan: RequestPlanEventSnapshot;
+    previousPlan?: RequestPlanEventSnapshot;
+    itemChanges: readonly RequestPlanItemChange[];
+}>;
+export type RequestPlanClientEvent = Readonly<{
+    name: string;
+    payload: Readonly<Record<string, unknown>>;
+}>;
+export type RequestPlanEventPresentation<TEvent extends RequestPlanClientEvent> = Readonly<{
+    project(projection: RequestPlanCommitProjection): readonly TEvent[];
+}>;
+/**
+ * Projects one already-committed request plan transition. The caller owns
+ * presentation and emission; this function only detects canonical changes.
+ */
+export declare function projectRequestPlanCommit<TState extends RequestPlanProjectionState, TEvent extends RequestPlanClientEvent>(params: Readonly<{
+    previousState: TState;
+    state: TState;
+    presentation: RequestPlanEventPresentation<TEvent>;
+}>): readonly TEvent[];
+export {};

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

@@ -0,0 +1,64 @@
+/**
+ * Projects one already-committed request plan transition. The caller owns
+ * presentation and emission; this function only detects canonical changes.
+ */
+export function projectRequestPlanCommit(params) {
+    const currentPlan = params.state.plan;
+    if (!currentPlan)
+        return Object.freeze([]);
+    const current = buildRequestPlanSnapshot(currentPlan);
+    const previous = params.previousState.plan
+        ? buildRequestPlanSnapshot(params.previousState.plan)
+        : undefined;
+    if (previous && sameSnapshot(previous, current)) {
+        return Object.freeze([]);
+    }
+    const previousStatusById = new Map(previous?.items.map((item) => [item.id, item.status]));
+    const itemChanges = Object.freeze(current.items.flatMap((item) => {
+        const previousStatus = previousStatusById.get(item.id);
+        if (item.status === previousStatus)
+            return [];
+        return [
+            Object.freeze({
+                item,
+                ...(previousStatus ? { previousStatus } : {}),
+            }),
+        ];
+    }));
+    const projection = Object.freeze({
+        phase: previous ? "updated" : "created",
+        plan: current,
+        ...(previous ? { previousPlan: previous } : {}),
+        itemChanges,
+    });
+    return Object.freeze([...params.presentation.project(projection)]);
+}
+function buildRequestPlanSnapshot(plan) {
+    const statusById = new Map(plan.itemStates.map((item) => [item.itemId, item.status]));
+    const total = plan.definition.items.length;
+    const items = plan.definition.items.map((definition, index) => {
+        const status = statusById.get(definition.itemId);
+        if (!status) {
+            throw new TypeError("Canonical plan projection requires one status for every item.");
+        }
+        return Object.freeze({
+            id: definition.itemId,
+            title: definition.title,
+            status,
+            order: index + 1,
+            total,
+        });
+    });
+    return Object.freeze({
+        summary: plan.definition.summary,
+        total,
+        completed: items.filter((item) => item.status === "done").length,
+        blocked: items.filter((item) => item.status === "blocked").length,
+        pending: items.filter((item) => item.status === "pending").length,
+        inProgress: items.filter((item) => item.status === "in_progress").length,
+        items: Object.freeze(items),
+    });
+}
+function sameSnapshot(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}

package/dist/src/runtime/request/planner-plan-events.d.ts

@@ -0,0 +1,6 @@
+import type { RequestPlanClientEvent, RequestPlanEventPresentation } from "./plan-event-projection.js";
+export declare const REQUEST_PLAN_EVENT_STAGE: "development_plan";
+/** Preserves the existing client Planner event contract. */
+export declare function createRequestPlanEventPresentation(params: Readonly<{
+    emissionFailureMessage: string;
+}>): RequestPlanEventPresentation<RequestPlanClientEvent>;