@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/sessions/request-lifecycle/approval-decisions.js

@@ -0,0 +1,109 @@
+import { acceptedLifecycle, appendLifecycleChangedEvent, appendLifecycleEvent, hasNonemptyIdentity, lifecycleRequest, rejectLifecycleCommand, touchLifecycle, validateWaitExpectation, } from "./record-operations.js";
+function sameDecision(receipt, command) {
+    if (receipt.waitId !== command.expected.waitId)
+        return false;
+    if (receipt.approvalId !== command.approvalId)
+        return false;
+    if (receipt.approved !== command.approved)
+        return false;
+    return receipt.reason === command.reason;
+}
+function replayDecision(request, command) {
+    const commandReceipt = request.lifecycle.decisionReceipts.find((receipt) => receipt.commandId === command.commandId);
+    if (commandReceipt && !sameDecision(commandReceipt, command))
+        return rejectLifecycleCommand("decision_command_conflict", request);
+    const receipt = commandReceipt ??
+        request.lifecycle.decisionReceipts.find((value) => value.approvalId === command.approvalId &&
+            value.waitId === command.expected.waitId);
+    if (!receipt)
+        return undefined;
+    if (!sameDecision(receipt, command))
+        return rejectLifecycleCommand("approval_already_decided", request);
+    return {
+        ...acceptedLifecycle(request),
+        duplicate: true,
+        receipt: structuredClone(receipt),
+    };
+}
+function isLastApprovalDecision(request, approvalId) {
+    const wait = request.lifecycle.wait;
+    return wait.approvals.every((approval) => approval.approvalId === approvalId ||
+        request.lifecycle.decisionReceipts.some((receipt) => receipt.waitId === wait.waitId &&
+            receipt.approvalId === approval.approvalId));
+}
+function hasResumeActivation(command) {
+    if (!hasNonemptyIdentity(command.resumeActivation?.activationId))
+        return false;
+    return hasNonemptyIdentity(command.resumeActivation?.ownerEpoch);
+}
+export function commitSessionApprovalDecision(context, command) {
+    const request = lifecycleRequest(context.session, command.expected.requestId);
+    if (!request)
+        return rejectLifecycleCommand("lifecycle_missing");
+    if (request.generation !== command.expected.generation)
+        return rejectLifecycleCommand("generation_mismatch", request);
+    if (!hasNonemptyIdentity(command.commandId))
+        return rejectLifecycleCommand("invalid_command", request);
+    if (typeof command.approved !== "boolean")
+        return rejectLifecycleCommand("invalid_command", request);
+    const replay = replayDecision(request, command);
+    if (replay)
+        return replay;
+    const mismatch = validateWaitExpectation(request, command.expected);
+    if (mismatch)
+        return rejectLifecycleCommand(mismatch, request);
+    const wait = request.lifecycle.wait;
+    const approval = wait.approvals.find((entry) => entry.approvalId === command.approvalId);
+    if (!approval)
+        return rejectLifecycleCommand("approval_missing", request);
+    const final = isLastApprovalDecision(request, command.approvalId);
+    if (final && !hasResumeActivation(command))
+        return rejectLifecycleCommand("resume_activation_required", request);
+    if (final &&
+        command.resumeActivation.activationId ===
+            request.lifecycle.activation.activationId)
+        return rejectLifecycleCommand("activation_mismatch", request);
+    touchLifecycle(context, request);
+    const receipt = {
+        commandId: command.commandId,
+        requestId: request.requestId,
+        generation: request.generation,
+        waitId: wait.waitId,
+        approvalId: command.approvalId,
+        approved: command.approved,
+        ...(command.reason !== undefined ? { reason: command.reason } : {}),
+        committedAt: context.timestamp,
+        revision: request.lifecycle.revision,
+        ...(final
+            ? { activation: structuredClone(command.resumeActivation) }
+            : {}),
+    };
+    request.lifecycle.decisionReceipts.push(receipt);
+    const message = context.session.messages.find((entry) => entry.id === wait.presentationMessageId);
+    if (message?.approvalRequest)
+        message.approvalRequest = {
+            ...message.approvalRequest,
+            state: final ? "consumed" : "pending",
+            decisions: request.lifecycle.decisionReceipts.filter((value) => value.waitId === wait.waitId),
+        };
+    if (final) {
+        request.status = "streaming";
+        request.lifecycle.activation = structuredClone(command.resumeActivation);
+        delete request.lifecycle.wait;
+    }
+    const event = appendLifecycleEvent(context, request, {
+        ...approval.presentation,
+        type: "event",
+        name: command.approved ? "tool.approval.granted" : "tool.approval.rejected",
+        approvalId: approval.approvalId,
+        waitId: wait.waitId,
+        ...(command.reason !== undefined ? { reason: command.reason } : {}),
+    });
+    return {
+        ...acceptedLifecycle(request, [
+            event,
+            appendLifecycleChangedEvent(context, request),
+        ]),
+        receipt: structuredClone(receipt),
+    };
+}

package/dist/src/sessions/request-lifecycle/continuation-blobs.d.ts

@@ -0,0 +1,13 @@
+import type { SessionBlobReference, SessionContinuationReference } from "./contracts.js";
+export declare function assertContinuationSchema(reference: Pick<SessionContinuationReference, "schema" | "version">): void;
+/** Immutable content only. These files never contain approval or lifecycle authority. */
+export declare function createSessionContinuationBlobs(sessionsDir: string): {
+    writeBlob: (sessionId: string, value: Uint8Array) => Promise<SessionBlobReference>;
+    readBlob: (sessionId: string, reference: SessionBlobReference) => Promise<Uint8Array>;
+    writeContinuation(sessionId: string, input: Readonly<{
+        schema: string;
+        version: number;
+        value: unknown;
+    }>): Promise<SessionContinuationReference>;
+    readContinuation(sessionId: string, reference: SessionContinuationReference): Promise<unknown>;
+};

package/dist/src/sessions/request-lifecycle/continuation-blobs.js

@@ -0,0 +1,114 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, mkdir, open, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { assertValidSessionId } from "../record/rules.js";
+import { syncSessionDirectory } from "../durable-session-commit.js";
+function isContentAddressedReference(value) {
+    if (!value || !/^[a-f0-9]{64}$/.test(value.sha256))
+        return false;
+    return Number.isSafeInteger(value.byteLength) && value.byteLength >= 0;
+}
+function hashBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function assertContinuationJson(value, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number" && Number.isFinite(value))
+        return;
+    if (!value || typeof value !== "object")
+        throw new Error("continuation_value_not_serializable");
+    if (ancestors.has(value))
+        throw new Error("continuation_value_not_serializable");
+    const prototype = Object.getPrototypeOf(value);
+    const plainObject = prototype === Object.prototype || prototype === null;
+    if (!Array.isArray(value) && !plainObject)
+        throw new Error("continuation_value_not_serializable");
+    if (Object.getOwnPropertySymbols(value).length)
+        throw new Error("continuation_value_not_serializable");
+    ancestors.add(value);
+    for (const entry of Array.isArray(value) ? value : Object.values(value))
+        assertContinuationJson(entry, ancestors);
+    ancestors.delete(value);
+}
+function encodeContinuationJson(value) {
+    assertContinuationJson(value, new Set());
+    return Buffer.from(JSON.stringify(value), "utf8");
+}
+export function assertContinuationSchema(reference) {
+    if (typeof reference.schema !== "string" || !reference.schema.trim())
+        throw new Error("continuation_schema_required");
+    if (!Number.isSafeInteger(reference.version) || reference.version < 1)
+        throw new Error("continuation_version_invalid");
+}
+/** Immutable content only. These files never contain approval or lifecycle authority. */
+export function createSessionContinuationBlobs(sessionsDir) {
+    function directory(sessionId) {
+        assertValidSessionId(sessionId);
+        return join(sessionsDir, ".request-continuations", encodeURIComponent(sessionId));
+    }
+    async function readBlob(sessionId, reference) {
+        if (!isContentAddressedReference(reference))
+            throw new Error("continuation_blob_reference_invalid");
+        const bytes = await readFile(join(directory(sessionId), `${reference.sha256}.blob`));
+        if (bytes.byteLength !== reference.byteLength ||
+            hashBytes(bytes) !== reference.sha256)
+            throw new Error("continuation_blob_integrity_mismatch");
+        return bytes;
+    }
+    async function writeBlob(sessionId, value) {
+        if (!(value instanceof Uint8Array))
+            throw new Error("continuation_blob_bytes_required");
+        const bytes = Buffer.from(value);
+        const reference = {
+            sha256: hashBytes(bytes),
+            byteLength: bytes.byteLength,
+        };
+        const parent = directory(sessionId);
+        await mkdir(parent, { recursive: true });
+        const target = join(parent, `${reference.sha256}.blob`);
+        const temporary = join(parent, `${reference.sha256}.${randomUUID()}.tmp`);
+        try {
+            const file = await open(temporary, "wx", 0o600);
+            try {
+                await file.writeFile(bytes);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            try {
+                await link(temporary, target);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+            await readBlob(sessionId, reference);
+            await syncSessionDirectory(parent);
+            // A new session's directory entries must survive with its saved reference.
+            await syncSessionDirectory(join(sessionsDir, ".request-continuations"));
+            await syncSessionDirectory(sessionsDir);
+            return reference;
+        }
+        finally {
+            await rm(temporary, { force: true }).catch(() => undefined);
+        }
+    }
+    return {
+        writeBlob,
+        readBlob,
+        async writeContinuation(sessionId, input) {
+            assertContinuationSchema(input);
+            return {
+                schema: input.schema,
+                version: input.version,
+                blob: await writeBlob(sessionId, encodeContinuationJson(input.value)),
+            };
+        },
+        async readContinuation(sessionId, reference) {
+            assertContinuationSchema(reference);
+            return JSON.parse(Buffer.from(await readBlob(sessionId, reference.blob)).toString("utf8"));
+        },
+    };
+}

package/dist/src/sessions/request-lifecycle/continuation-cleanup.d.ts

@@ -0,0 +1,7 @@
+import type { SessionRecord } from "../types.js";
+import type { SessionBlobReference } from "./contracts.js";
+export declare function collectSessionContinuationBlobs(session: SessionRecord): SessionBlobReference[];
+/** Only remove references retired by a confirmed commit, preserving shared blobs. */
+export declare function cleanupConsumedSessionContinuations(sessionsDir: string, session: SessionRecord, previous: readonly SessionBlobReference[]): Promise<void>;
+/** Run after invalidating the session's references; cleanup cannot change its outcome. */
+export declare function cleanupSessionContinuations(sessionsDir: string, sessionId: string): Promise<void>;

package/dist/src/sessions/request-lifecycle/continuation-cleanup.js

@@ -0,0 +1,49 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { assertValidSessionId } from "../record/rules.js";
+export function collectSessionContinuationBlobs(session) {
+    return (session.requests ?? []).flatMap((request) => {
+        const blob = request.lifecycle?.wait?.continuation.blob;
+        return blob ? [blob] : [];
+    });
+}
+function isConsumedContinuationBlob(sha256, retained) {
+    if (retained.has(sha256))
+        return false;
+    return /^[a-f0-9]{64}$/.test(sha256);
+}
+/** Only remove references retired by a confirmed commit, preserving shared blobs. */
+export async function cleanupConsumedSessionContinuations(sessionsDir, session, previous) {
+    assertValidSessionId(session.id);
+    const retained = new Set(collectSessionContinuationBlobs(session).map((blob) => blob.sha256));
+    const consumed = new Set(previous.map((blob) => blob.sha256));
+    for (const sha256 of consumed) {
+        if (!isConsumedContinuationBlob(sha256, retained))
+            continue;
+        try {
+            await rm(join(sessionsDir, ".request-continuations", encodeURIComponent(session.id), `${sha256}.blob`), { force: true });
+        }
+        catch (error) {
+            console.warn("Consumed session continuation cleanup remains pending.", {
+                sessionId: session.id,
+                error: error instanceof Error ? error.name : "unknown",
+            });
+        }
+    }
+}
+/** Run after invalidating the session's references; cleanup cannot change its outcome. */
+export async function cleanupSessionContinuations(sessionsDir, sessionId) {
+    assertValidSessionId(sessionId);
+    try {
+        await rm(join(sessionsDir, ".request-continuations", encodeURIComponent(sessionId)), {
+            recursive: true,
+            force: true,
+        });
+    }
+    catch (error) {
+        console.warn("Session continuation cleanup remains pending.", {
+            sessionId,
+            error: error instanceof Error ? error.name : "unknown",
+        });
+    }
+}

package/dist/src/sessions/request-lifecycle/contracts.d.ts

@@ -0,0 +1,169 @@
+import type { SessionRequestStatus } from "../types.js";
+export type SessionBlobReference = Readonly<{
+    sha256: string;
+    byteLength: number;
+}>;
+export type SessionContinuationReference = Readonly<{
+    schema: string;
+    version: number;
+    blob: SessionBlobReference;
+}>;
+export type SessionActivation = Readonly<{
+    activationId: string;
+    ownerEpoch: string;
+}>;
+export type SessionActivationExpectation = SessionActivation & Readonly<{
+    requestId: string;
+    generation: string;
+    revision: number;
+}>;
+export type SessionWaitExpectation = Readonly<{
+    requestId: string;
+    generation: string;
+    waitId: string;
+    revision: number;
+}>;
+/** Disclosure only. Executable actions belong to the opaque continuation. */
+export type SessionApprovalDescription = Readonly<{
+    approvalId: string;
+    actionFingerprint: string;
+    presentation: Readonly<Record<string, unknown>>;
+}>;
+export type SessionApprovalDecisionReceipt = Readonly<{
+    commandId: string;
+    requestId: string;
+    generation: string;
+    waitId: string;
+    approvalId: string;
+    approved: boolean;
+    reason?: string;
+    committedAt: string;
+    revision: number;
+    activation?: SessionActivation;
+}>;
+export type SessionApprovalPresentation = Readonly<{
+    kind: "tool_approval_request";
+    waitId: string;
+    state: "pending" | "consumed" | "cancelled";
+    approvals: readonly SessionApprovalDescription[];
+    decisions: readonly SessionApprovalDecisionReceipt[];
+}>;
+export type SessionApprovalWait = Readonly<{
+    waitId: string;
+    createdAt: string;
+    presentationMessageId: string;
+    approvals: readonly SessionApprovalDescription[];
+    continuation: SessionContinuationReference;
+}>;
+export type SessionRequestTerminalCause = "request_cancelled" | "request_interrupted" | "request_failed";
+/** Stored within SessionRequestRecord; request.status is the sole phase authority. */
+export type SessionRequestLifecycleRecord = {
+    schemaVersion: 1;
+    revision: number;
+    activation: SessionActivation;
+    wait?: SessionApprovalWait;
+    decisionReceipts: SessionApprovalDecisionReceipt[];
+    terminalCause?: SessionRequestTerminalCause;
+    terminalCommandId?: string;
+};
+/** Client-safe projection: deliberately excludes continuation references and bytes. */
+export type SessionRequestLifecycleSnapshot = Readonly<{
+    schemaVersion: 1;
+    sessionId: string;
+    requestId: string;
+    generation: string;
+    status: SessionRequestStatus;
+    revision: number;
+    activation?: SessionActivation;
+    wait?: Omit<SessionApprovalWait, "continuation">;
+    decisionReceipts: readonly SessionApprovalDecisionReceipt[];
+    terminalCause?: SessionRequestTerminalCause;
+}>;
+export type SessionLifecycleRejectionReason = "session_missing" | "request_missing" | "lifecycle_missing" | "generation_mismatch" | "revision_mismatch" | "activation_mismatch" | "request_not_running" | "request_not_waiting" | "request_already_started" | "wait_mismatch" | "approval_missing" | "approval_already_decided" | "decision_command_conflict" | "resume_activation_required" | "invalid_command";
+export type SessionLifecycleMutationResult = Readonly<{
+    accepted: true;
+    current: SessionRequestLifecycleSnapshot;
+    events: readonly Record<string, unknown>[];
+    receipt?: SessionApprovalDecisionReceipt;
+    duplicate?: boolean;
+}> | Readonly<{
+    accepted: false;
+    reason: SessionLifecycleRejectionReason;
+    current?: SessionRequestLifecycleSnapshot;
+}>;
+export type SessionStartActivationCommand = SessionActivation & Readonly<{
+    requestId: string;
+    /** Required when adopting a stream already initialized by the request handler. */
+    expectedGeneration?: string;
+}>;
+export type SessionCommitWaitCommand = Readonly<{
+    expected: SessionActivationExpectation;
+    waitId: string;
+    approvals: readonly SessionApprovalDescription[];
+    continuation: SessionContinuationReference;
+    presentationText: string;
+    initialDecisions?: readonly Readonly<{
+        approvalId: string;
+        approved: boolean;
+        reason?: string;
+        commandId: string;
+    }>[];
+}>;
+export type SessionCommitDecisionCommand = Readonly<{
+    expected: SessionWaitExpectation;
+    commandId: string;
+    approvalId: string;
+    approved: boolean;
+    reason?: string;
+    /** Supplied only after the caller's retirement and hydration preflight. */
+    resumeActivation?: SessionActivation;
+}>;
+export type SessionTerminalMessage = Readonly<{
+    content: string;
+    thinkingTrace?: import("../types.js").SessionThinkingTraceEntry[];
+}> & Readonly<Pick<import("../types.js").SessionMessage, "grounding" | "observationMeta" | "observationContent" | "attachments" | "taskType">> & Readonly<{
+    lastAgentMode?: import("../../shared/types.js").AgentMode;
+}>;
+export type SessionCancelWaitCommand = Readonly<{
+    expected: SessionWaitExpectation;
+    commandId: string;
+    message: SessionTerminalMessage;
+}>;
+export type SessionCommitTerminalCommand = Readonly<{
+    expected: SessionActivationExpectation;
+    commandId: string;
+    status: "completed" | "failed";
+    cause?: SessionRequestTerminalCause;
+    message: SessionTerminalMessage;
+    error?: string;
+}>;
+export type SessionInterruptActivationCommand = Readonly<{
+    expected: SessionActivationExpectation;
+    commandId: string;
+    message: SessionTerminalMessage;
+}>;
+export interface SessionRequestLifecycleStore {
+    startActivation(sessionId: string, command: SessionStartActivationCommand): Promise<SessionLifecycleMutationResult>;
+    commitWait(sessionId: string, command: SessionCommitWaitCommand): Promise<SessionLifecycleMutationResult>;
+    commitDecision(sessionId: string, command: SessionCommitDecisionCommand): Promise<SessionLifecycleMutationResult>;
+    cancelWait(sessionId: string, command: SessionCancelWaitCommand): Promise<SessionLifecycleMutationResult>;
+    interruptActivation(sessionId: string, command: SessionInterruptActivationCommand): Promise<SessionLifecycleMutationResult>;
+    commitTerminal(sessionId: string, command: SessionCommitTerminalCommand): Promise<SessionLifecycleMutationResult>;
+    appendActivationEvent(sessionId: string, command: Readonly<{
+        expected: SessionActivationExpectation;
+        payload: Record<string, unknown>;
+    }>): Promise<SessionLifecycleMutationResult>;
+    get(sessionId: string, requestId: string): Promise<SessionRequestLifecycleSnapshot | null>;
+    listWaiting(sessionId?: string): Promise<readonly SessionRequestLifecycleSnapshot[]>;
+    getDecisionReceipt(sessionId: string, requestId: string, generation: string, commandId: string): Promise<SessionApprovalDecisionReceipt | null>;
+    /** Trusted runtime reads only: no Web list/snapshot response may expose this reference. */
+    getContinuation(sessionId: string, expected: SessionWaitExpectation): Promise<SessionContinuationReference | null>;
+    writeContinuation(sessionId: string, input: Readonly<{
+        schema: string;
+        version: number;
+        value: unknown;
+    }>): Promise<SessionContinuationReference>;
+    readContinuation(sessionId: string, reference: SessionContinuationReference): Promise<unknown>;
+    writeBlob(sessionId: string, bytes: Uint8Array): Promise<SessionBlobReference>;
+    readBlob(sessionId: string, reference: SessionBlobReference): Promise<Uint8Array>;
+}

package/dist/src/sessions/request-lifecycle/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/src/sessions/request-lifecycle/projection.d.ts

@@ -0,0 +1,4 @@
+import type { SessionRequestRecord } from "../types.js";
+import type { SessionRequestLifecycleSnapshot } from "./contracts.js";
+/** Lifecycle metadata is decoded independently of the versioned continuation bytes. */
+export declare function projectSessionRequestLifecycle(request: SessionRequestRecord): SessionRequestLifecycleSnapshot | undefined;

package/dist/src/sessions/request-lifecycle/projection.js

@@ -0,0 +1,30 @@
+/** Lifecycle metadata is decoded independently of the versioned continuation bytes. */
+export function projectSessionRequestLifecycle(request) {
+    const lifecycle = request.lifecycle;
+    if (!lifecycle || lifecycle.schemaVersion !== 1 || !request.generation)
+        return undefined;
+    const wait = lifecycle.wait;
+    return structuredClone({
+        schemaVersion: 1,
+        sessionId: request.sessionId,
+        requestId: request.requestId,
+        generation: request.generation,
+        status: request.status,
+        revision: lifecycle.revision,
+        activation: lifecycle.activation,
+        ...(request.status === "awaiting_approval" && wait
+            ? {
+                wait: {
+                    waitId: wait.waitId,
+                    createdAt: wait.createdAt,
+                    presentationMessageId: wait.presentationMessageId,
+                    approvals: wait.approvals,
+                },
+            }
+            : {}),
+        decisionReceipts: lifecycle.decisionReceipts,
+        ...(lifecycle.terminalCause
+            ? { terminalCause: lifecycle.terminalCause }
+            : {}),
+    });
+}

package/dist/src/sessions/request-lifecycle/record-operations.d.ts

@@ -0,0 +1,27 @@
+import type { SessionMessage, SessionRecord, SessionRequestRecord } from "../types.js";
+import type { SessionActivationExpectation, SessionLifecycleMutationResult, SessionLifecycleRejectionReason, SessionRequestLifecycleRecord, SessionWaitExpectation } from "./contracts.js";
+export type LifecycleMutationContext = Readonly<{
+    session: SessionRecord;
+    timestamp: string;
+    createMessageId(session: SessionRecord): string;
+}>;
+export type LifecycleRequest = SessionRequestRecord & {
+    generation: string;
+    lifecycle: SessionRequestLifecycleRecord;
+};
+export declare function rejectLifecycleCommand(reason: SessionLifecycleRejectionReason, request?: SessionRequestRecord): SessionLifecycleMutationResult;
+export declare function lifecycleRequest(session: SessionRecord, requestId: string): LifecycleRequest | undefined;
+export declare function hasNonemptyIdentity(value: unknown): value is string;
+export declare function validateRequestExpectation(request: LifecycleRequest | undefined, expected: Readonly<{
+    generation: string;
+    revision: number;
+}>): SessionLifecycleRejectionReason | undefined;
+export declare function validateActivationExpectation(request: LifecycleRequest | undefined, expected: SessionActivationExpectation): SessionLifecycleRejectionReason | undefined;
+export declare function validateWaitExpectation(request: LifecycleRequest | undefined, expected: SessionWaitExpectation): SessionLifecycleRejectionReason | undefined;
+export declare function touchLifecycle(context: LifecycleMutationContext, request: LifecycleRequest): void;
+export declare function appendLifecycleEvent(context: LifecycleMutationContext, request: LifecycleRequest, payload: Record<string, unknown>): Record<string, unknown>;
+export declare function appendLifecycleMessage(context: LifecycleMutationContext, input: Omit<SessionMessage, "id" | "createdAt">): SessionMessage;
+export declare function acceptedLifecycle(request: LifecycleRequest, events?: readonly Record<string, unknown>[]): SessionLifecycleMutationResult & {
+    accepted: true;
+};
+export declare function appendLifecycleChangedEvent(context: LifecycleMutationContext, request: LifecycleRequest): Record<string, unknown>;

package/dist/src/sessions/request-lifecycle/record-operations.js

@@ -0,0 +1,109 @@
+import { compactRequestEvents, toClientReplayEvent, toSnapshotMessage, } from "../record/projection.js";
+import { projectSessionRequestLifecycle } from "./projection.js";
+export function rejectLifecycleCommand(reason, request) {
+    const current = request ? projectSessionRequestLifecycle(request) : undefined;
+    return { accepted: false, reason, ...(current ? { current } : {}) };
+}
+export function lifecycleRequest(session, requestId) {
+    const request = session.requests?.find((entry) => entry.requestId === requestId);
+    if (!request?.generation || request.lifecycle?.schemaVersion !== 1)
+        return undefined;
+    return request;
+}
+export function hasNonemptyIdentity(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function validateRequestExpectation(request, expected) {
+    if (!request)
+        return "lifecycle_missing";
+    if (request.generation !== expected.generation)
+        return "generation_mismatch";
+    if (request.lifecycle.revision !== expected.revision)
+        return "revision_mismatch";
+    return undefined;
+}
+export function validateActivationExpectation(request, expected) {
+    const mismatch = validateRequestExpectation(request, expected);
+    if (mismatch)
+        return mismatch;
+    if (request.status !== "streaming")
+        return "request_not_running";
+    if (request.lifecycle.activation.activationId !== expected.activationId)
+        return "activation_mismatch";
+    if (request.lifecycle.activation.ownerEpoch !== expected.ownerEpoch)
+        return "activation_mismatch";
+    return undefined;
+}
+export function validateWaitExpectation(request, expected) {
+    const mismatch = validateRequestExpectation(request, expected);
+    if (mismatch)
+        return mismatch;
+    if (request.status !== "awaiting_approval")
+        return "request_not_waiting";
+    if (request.lifecycle.wait?.waitId !== expected.waitId)
+        return "wait_mismatch";
+    return undefined;
+}
+export function touchLifecycle(context, request) {
+    request.lifecycle.revision += 1;
+    request.updatedAt = context.timestamp;
+    context.session.updatedAt = context.timestamp;
+}
+export function appendLifecycleEvent(context, request, payload) {
+    const seqNo = request.lastSeqNo + 1;
+    const type = typeof payload.type === "string" ? payload.type : "event";
+    const event = {
+        ...structuredClone(payload),
+        type,
+        sessionId: request.sessionId,
+        requestId: request.requestId,
+        generation: request.generation,
+        activationId: request.lifecycle.activation.activationId,
+        seqNo,
+        eventSequence: seqNo,
+        timestamp: context.timestamp,
+    };
+    request.lastSeqNo = seqNo;
+    const stored = {
+        seqNo,
+        type,
+        requestId: request.requestId,
+        timestamp: context.timestamp,
+        payload: event,
+    };
+    request.events.push(stored);
+    request.events = compactRequestEvents(request.events);
+    return toClientReplayEvent(stored);
+}
+export function appendLifecycleMessage(context, input) {
+    const message = {
+        ...structuredClone(input),
+        id: context.createMessageId(context.session),
+        createdAt: context.timestamp,
+    };
+    context.session.messages.push(message);
+    context.session.messageCount = context.session.messages.length;
+    return message;
+}
+export function acceptedLifecycle(request, events = []) {
+    return {
+        accepted: true,
+        current: projectSessionRequestLifecycle(request),
+        events,
+    };
+}
+export function appendLifecycleChangedEvent(context, request) {
+    const message = [...context.session.messages]
+        .reverse()
+        .find((entry) => entry.role === "assistant" && entry.requestId === request.requestId);
+    return appendLifecycleEvent(context, request, {
+        type: "event",
+        name: "request.lifecycle.changed",
+        lifecycle: projectSessionRequestLifecycle(request),
+        ...(message
+            ? {
+                message: toSnapshotMessage(context.session.id, message, context.session.requests ?? []),
+            }
+            : {}),
+    });
+}

package/dist/src/sessions/request-lifecycle/service.d.ts

@@ -0,0 +1,12 @@
+import type { SessionRecord } from "../types.js";
+import type { SessionRequestLifecycleStore } from "./contracts.js";
+export type SessionLifecycleServiceDependencies = Readonly<{
+    sessionsDir: string;
+    now(): Date;
+    createMessageId(session: SessionRecord): string;
+    enqueue<T>(sessionId: string, operation: () => Promise<T>): Promise<T>;
+    read(sessionId: string): Promise<SessionRecord | null>;
+    list(): Promise<SessionRecord[]>;
+}>;
+/** Commands share SessionService's queue and file, never a parallel checkpoint store. */
+export declare function createSessionRequestLifecycle(dependencies: SessionLifecycleServiceDependencies): SessionRequestLifecycleStore;