@abot-ai/runtime 1.4.0 → 1.6.0

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

@@ -0,0 +1,95 @@
+import { assertValidSessionId } from "../record/rules.js";
+import { saveDurableSessionFile } from "../durable-session-commit.js";
+import { collectSessionContinuationBlobs, cleanupConsumedSessionContinuations, } from "./continuation-cleanup.js";
+import { assertContinuationSchema, createSessionContinuationBlobs, } from "./continuation-blobs.js";
+import { projectSessionRequestLifecycle } from "./projection.js";
+import { startSessionActivation, commitSessionApprovalWait, } from "./activation-transitions.js";
+import { commitSessionApprovalDecision } from "./approval-decisions.js";
+import { cancelSessionApprovalWait, commitSessionTerminal, interruptSessionActivation, } from "./terminal-transitions.js";
+import { acceptedLifecycle, appendLifecycleEvent, lifecycleRequest, rejectLifecycleCommand, touchLifecycle, validateActivationExpectation, validateWaitExpectation, } from "./record-operations.js";
+/** Commands share SessionService's queue and file, never a parallel checkpoint store. */
+export function createSessionRequestLifecycle(dependencies) {
+    const blobs = createSessionContinuationBlobs(dependencies.sessionsDir);
+    async function mutate(sessionId, operation) {
+        assertValidSessionId(sessionId);
+        return dependencies.enqueue(sessionId, async () => {
+            const session = await dependencies.read(sessionId);
+            if (!session)
+                return rejectLifecycleCommand("session_missing");
+            const previousBlobs = collectSessionContinuationBlobs(session);
+            const result = await operation({
+                session,
+                timestamp: dependencies.now().toISOString(),
+                createMessageId: dependencies.createMessageId,
+            });
+            if (!result.accepted || result.duplicate)
+                return result;
+            await saveDurableSessionFile(dependencies.sessionsDir, session);
+            await cleanupConsumedSessionContinuations(dependencies.sessionsDir, session, previousBlobs);
+            return result;
+        });
+    }
+    async function readRequest(sessionId, requestId) {
+        const session = await dependencies.read(sessionId);
+        return session?.requests?.find((request) => request.requestId === requestId);
+    }
+    return {
+        ...blobs,
+        startActivation: (sessionId, command) => mutate(sessionId, (context) => startSessionActivation(context, command)),
+        commitWait: (sessionId, command) => mutate(sessionId, async (context) => {
+            // Verify immutable content before acknowledging its canonical reference.
+            // The versioned continuation remains opaque to lifecycle storage.
+            assertContinuationSchema(command.continuation);
+            await blobs.readBlob(sessionId, command.continuation.blob);
+            return commitSessionApprovalWait(context, command);
+        }),
+        commitDecision: (sessionId, command) => mutate(sessionId, (context) => commitSessionApprovalDecision(context, command)),
+        cancelWait: (sessionId, command) => mutate(sessionId, (context) => cancelSessionApprovalWait(context, command)),
+        commitTerminal: (sessionId, command) => mutate(sessionId, (context) => commitSessionTerminal(context, command)),
+        interruptActivation: (sessionId, command) => mutate(sessionId, (context) => interruptSessionActivation(context, command)),
+        appendActivationEvent: (sessionId, command) => mutate(sessionId, (context) => {
+            const request = lifecycleRequest(context.session, command.expected.requestId);
+            const mismatch = validateActivationExpectation(request, command.expected);
+            if (mismatch)
+                return rejectLifecycleCommand(mismatch, request);
+            if (command.payload.type === "completed" ||
+                command.payload.type === "failed")
+                return rejectLifecycleCommand("invalid_command", request);
+            touchLifecycle(context, request);
+            return acceptedLifecycle(request, [
+                appendLifecycleEvent(context, request, command.payload),
+            ]);
+        }),
+        async get(sessionId, requestId) {
+            const request = await readRequest(sessionId, requestId);
+            return request ? (projectSessionRequestLifecycle(request) ?? null) : null;
+        },
+        async listWaiting(sessionId) {
+            const sessions = sessionId
+                ? [await dependencies.read(sessionId)]
+                : await dependencies.list();
+            return sessions.flatMap((session) => (session?.requests ?? []).flatMap((request) => {
+                if (request.status !== "awaiting_approval")
+                    return [];
+                const projected = projectSessionRequestLifecycle(request);
+                return projected ? [projected] : [];
+            }));
+        },
+        async getDecisionReceipt(sessionId, requestId, generation, commandId) {
+            const request = await readRequest(sessionId, requestId);
+            if (request?.generation !== generation)
+                return null;
+            const receipt = request.lifecycle?.decisionReceipts.find((value) => value.commandId === commandId);
+            return receipt ? structuredClone(receipt) : null;
+        },
+        async getContinuation(sessionId, expected) {
+            const session = await dependencies.read(sessionId);
+            if (!session)
+                return null;
+            const request = lifecycleRequest(session, expected.requestId);
+            if (validateWaitExpectation(request, expected))
+                return null;
+            return structuredClone(request.lifecycle.wait.continuation);
+        },
+    };
+}

package/dist/src/sessions/request-lifecycle/terminal-transitions.d.ts

@@ -0,0 +1,5 @@
+import type { SessionCancelWaitCommand, SessionCommitTerminalCommand, SessionInterruptActivationCommand, SessionLifecycleMutationResult } from "./contracts.js";
+import { type LifecycleMutationContext } from "./record-operations.js";
+export declare function commitSessionTerminal(context: LifecycleMutationContext, command: SessionCommitTerminalCommand): SessionLifecycleMutationResult;
+export declare function cancelSessionApprovalWait(context: LifecycleMutationContext, command: SessionCancelWaitCommand): SessionLifecycleMutationResult;
+export declare function interruptSessionActivation(context: LifecycleMutationContext, command: SessionInterruptActivationCommand): SessionLifecycleMutationResult;

package/dist/src/sessions/request-lifecycle/terminal-transitions.js

@@ -0,0 +1,103 @@
+import { acceptedLifecycle, appendLifecycleChangedEvent, appendLifecycleEvent, appendLifecycleMessage, hasNonemptyIdentity, lifecycleRequest, rejectLifecycleCommand, touchLifecycle, validateActivationExpectation, validateWaitExpectation, } from "./record-operations.js";
+function appendTerminalResponse(context, request, message) {
+    const { lastAgentMode, ...metadata } = message;
+    appendLifecycleMessage(context, {
+        ...metadata,
+        role: "assistant",
+        kind: "terminal",
+        requestId: request.requestId,
+        source: "request",
+        grounding: message.grounding ?? "conversation",
+    });
+    if (lastAgentMode)
+        context.session.lastAgentMode = lastAgentMode;
+}
+function hasTerminalCommandReceipt(request, commandId) {
+    if (request.status !== "completed" && request.status !== "failed")
+        return false;
+    return request.lifecycle.terminalCommandId === commandId;
+}
+export function commitSessionTerminal(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 (hasTerminalCommandReceipt(request, command.commandId))
+        return { ...acceptedLifecycle(request), duplicate: true };
+    const mismatch = validateActivationExpectation(request, command.expected);
+    if (mismatch)
+        return rejectLifecycleCommand(mismatch, request);
+    if (!hasNonemptyIdentity(command.commandId))
+        return rejectLifecycleCommand("invalid_command", request);
+    if (!hasNonemptyIdentity(command.message.content))
+        return rejectLifecycleCommand("invalid_command", request);
+    if (command.status !== "completed" && command.status !== "failed")
+        return rejectLifecycleCommand("invalid_command", request);
+    request.status = command.status;
+    request.lifecycle.terminalCommandId = command.commandId;
+    request.lifecycle.terminalCause =
+        command.status === "failed"
+            ? (command.cause ?? "request_failed")
+            : undefined;
+    delete request.lifecycle.wait;
+    touchLifecycle(context, request);
+    appendTerminalResponse(context, request, command.message);
+    const payload = command.status === "completed"
+        ? { type: "completed", output: command.message.content }
+        : {
+            type: "failed",
+            error: command.error ?? request.lifecycle.terminalCause,
+            details: {
+                stoppedResponse: command.cause === "request_cancelled"
+                    ? command.message.content
+                    : undefined,
+            },
+        };
+    const changed = appendLifecycleChangedEvent(context, request);
+    const event = appendLifecycleEvent(context, request, payload);
+    return acceptedLifecycle(request, [changed, event]);
+}
+export function cancelSessionApprovalWait(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 (hasTerminalCommandReceipt(request, command.commandId))
+        return { ...acceptedLifecycle(request), duplicate: true };
+    const mismatch = validateWaitExpectation(request, command.expected);
+    if (mismatch)
+        return rejectLifecycleCommand(mismatch, request);
+    if (!hasNonemptyIdentity(command.commandId))
+        return rejectLifecycleCommand("invalid_command", request);
+    if (!hasNonemptyIdentity(command.message.content))
+        return rejectLifecycleCommand("invalid_command", request);
+    const presentation = context.session.messages.find((message) => message.id === request.lifecycle.wait.presentationMessageId);
+    if (presentation?.approvalRequest)
+        presentation.approvalRequest = {
+            ...presentation.approvalRequest,
+            state: "cancelled",
+        };
+    request.status = "failed";
+    request.lifecycle.terminalCause = "request_cancelled";
+    request.lifecycle.terminalCommandId = command.commandId;
+    delete request.lifecycle.wait;
+    touchLifecycle(context, request);
+    appendTerminalResponse(context, request, command.message);
+    const changed = appendLifecycleChangedEvent(context, request);
+    const event = appendLifecycleEvent(context, request, {
+        type: "failed",
+        error: "request_cancelled",
+        details: { stoppedResponse: command.message.content },
+    });
+    return acceptedLifecycle(request, [changed, event]);
+}
+export function interruptSessionActivation(context, command) {
+    return commitSessionTerminal(context, {
+        ...command,
+        status: "failed",
+        cause: "request_interrupted",
+        error: "request_interrupted",
+    });
+}

package/dist/src/sessions/request-lifecycle/wait-initial-decisions.d.ts

@@ -0,0 +1,4 @@
+import type { SessionApprovalDecisionReceipt, SessionCommitWaitCommand } from "./contracts.js";
+import { type LifecycleMutationContext, type LifecycleRequest } from "./record-operations.js";
+export declare function hasValidInitialApprovalDecisions(request: LifecycleRequest, command: SessionCommitWaitCommand): boolean;
+export declare function createInitialApprovalReceipts(context: LifecycleMutationContext, request: LifecycleRequest, command: SessionCommitWaitCommand): SessionApprovalDecisionReceipt[];

package/dist/src/sessions/request-lifecycle/wait-initial-decisions.js

@@ -0,0 +1,34 @@
+import { hasNonemptyIdentity, } from "./record-operations.js";
+export function hasValidInitialApprovalDecisions(request, command) {
+    const decisions = command.initialDecisions ?? [];
+    if (decisions.length >= command.approvals.length)
+        return false;
+    const approvals = new Set(command.approvals.map((approval) => approval.approvalId));
+    const decided = new Set();
+    const commands = new Set(request.lifecycle.decisionReceipts.map((receipt) => receipt.commandId));
+    for (const decision of decisions) {
+        if (!approvals.has(decision.approvalId))
+            return false;
+        if (decided.has(decision.approvalId))
+            return false;
+        if (!hasNonemptyIdentity(decision.commandId))
+            return false;
+        if (commands.has(decision.commandId))
+            return false;
+        if (typeof decision.approved !== "boolean")
+            return false;
+        decided.add(decision.approvalId);
+        commands.add(decision.commandId);
+    }
+    return true;
+}
+export function createInitialApprovalReceipts(context, request, command) {
+    return (command.initialDecisions ?? []).map((decision) => ({
+        ...decision,
+        requestId: request.requestId,
+        generation: request.generation,
+        waitId: command.waitId,
+        committedAt: context.timestamp,
+        revision: request.lifecycle.revision,
+    }));
+}

package/dist/src/sessions/session-service.d.ts

@@ -1,3 +1,6 @@
+import { type AutomationSessionHandle, type AutomationSessionOrigin } from "./automation-session-origin.js";
+import type { SessionRequestLifecycleStore } from "./request-lifecycle/contracts.js";
+import { type CreateAssistantConversationInput } from "./assistant-initiative.js";
 import { type SessionCreationOptions } from "./project-binding.js";
 import type { SessionContextEntryKind, SessionArtifactPathInput, SessionMessageGrounding, SessionMessage, SessionMessageDeleteResult, SessionMessageObservationMeta, SessionMessageRole, SessionMessageSource, SessionMessageTaskType, SessionMessagesClearResult, SessionDeleteResult, SessionListResult, SessionRequestReplay, SessionRecord, SessionSnapshot, SessionThinkingTraceEntry } from "./types.js";
 import type { SessionMemoryCheckpointCommit, SessionMemoryCheckpointCommitResult } from "./memory/contracts.js";
@@ -8,11 +11,19 @@ type SessionServiceOptions = {
     createMessageId?: (session: SessionRecord) => string;
 };
 export declare class SessionService {
+    readonly requestLifecycle: SessionRequestLifecycleStore;
     private readonly sessionsDir;
+    private readonly automationAccess;
+    private readonly automationSessions;
     private readonly now;
     private readonly createMessageId;
     private readonly sessionMutationQueues;
     constructor(options?: SessionServiceOptions);
+    assertInteractiveSession(sessionId: string): Promise<void>;
+    createAutomationSession(sessionId: string, origin: AutomationSessionOrigin): Promise<AutomationSessionHandle>;
+    releaseAutomationSession(handle: AutomationSessionHandle): void;
+    reconcileAutomationSessions(cleanupAttachments: (sessionId: string) => Promise<void>, onError: (sessionId: string, error: unknown) => void): Promise<void>;
+    runAsAutomationSession<T>(handle: AutomationSessionHandle, task: () => Promise<T>): Promise<T>;
     getOrCreateSession(sessionId: string, options?: SessionCreationOptions): Promise<SessionRecord>;
     getAllSessions(): Promise<SessionRecord[]>;
     listSessions(params?: {
@@ -46,6 +57,8 @@ export declare class SessionService {
         triggerType?: string;
         attachments?: SessionMessage["attachments"];
     }): Promise<SessionRecord>;
+    createAssistantConversation(sessionId: string, input: CreateAssistantConversationInput): Promise<SessionRecord>;
+    appendAssistantInitiative(sessionId: string, input: CreateAssistantConversationInput): Promise<SessionRecord>;
     compareAndSwapSessionMemoryCheckpoint(sessionId: string, command: SessionMemoryCheckpointCommit): Promise<SessionMemoryCheckpointCommitResult>;
     appendContextEntry(sessionId: string, options: {
         kind: SessionContextEntryKind;

package/dist/src/sessions/session-service.js

@@ -1,4 +1,11 @@
 import { randomUUID } from "node:crypto";
+import { AutomationSessionLockedError, createAutomationSessionAccess, hasAutomationSessionOrigin, } from "./automation-session-origin.js";
+import { createAutomationSessionStore } from "./automation-session-store.js";
+import { saveDurableSessionFile } from "./durable-session-commit.js";
+import { cleanupSessionContinuations } from "./request-lifecycle/continuation-cleanup.js";
+import { createSessionRequestLifecycle } from "./request-lifecycle/service.js";
+import { projectSessionRequestLifecycle } from "./request-lifecycle/projection.js";
+import { createAssistantConversationRecord, } from "./assistant-initiative.js";
 import { assertSessionProjectUnchanged, copySessionProject, } from "./project-binding.js";
 import { getDefaultSessionsDir } from "../runtime/config/layout.js";
 import { assertValidSessionArtifactPathInputs, upsertSessionArtifactPaths, } from "./artifact-paths.js";
@@ -6,11 +13,16 @@ import { clientVisibleMessages, compactRequestEvents, filterMessagesAfter, getRe
 import { assertValidRequestId, assertValidSessionId, createContextEntryId, defaultCreateMessageId, pruneSupersededContextEntries, } from "./record/rules.js";
 import { deleteSessionFile, ensureSessionsDir, loadAllSessionFiles, loadSessionFile, saveSessionFile, } from "./session-store.js";
 import { resolveSessionMemoryCheckpointCommit } from "./memory/rules.js";
+import { assertSessionKindUnchanged, sessionKindCreationFields } from "./spark-session.js";
+import { appendAssistantInitiativeRecord } from "./assistant-initiative-append.js";
 function toIso(now) {
     return now().toISOString();
 }
 export class SessionService {
+    requestLifecycle;
     sessionsDir;
+    automationAccess = createAutomationSessionAccess();
+    automationSessions;
     now;
     createMessageId;
     sessionMutationQueues = new Map();
@@ -18,14 +30,46 @@ export class SessionService {
         this.sessionsDir =
             options.sessionsDir || getDefaultSessionsDir(process.cwd());
         this.now = options.now || (() => new Date());
+        this.automationSessions = createAutomationSessionStore({
+            sessionsDir: this.sessionsDir, now: this.now, access: this.automationAccess,
+            enqueue: this.runSessionMutation.bind(this),
+        });
         this.createMessageId = options.createMessageId || defaultCreateMessageId;
+        this.requestLifecycle = createSessionRequestLifecycle({
+            sessionsDir: this.sessionsDir,
+            now: this.now,
+            createMessageId: this.createMessageId,
+            enqueue: this.runSessionMutation.bind(this),
+            read: this.getSessionById.bind(this),
+            list: this.getAllSessions.bind(this),
+        });
+    }
+    async assertInteractiveSession(sessionId) {
+        assertValidSessionId(sessionId);
+        const session = await loadSessionFile(this.sessionsDir, sessionId);
+        if (session && hasAutomationSessionOrigin(session))
+            throw new AutomationSessionLockedError();
+    }
+    async createAutomationSession(sessionId, origin) {
+        return this.automationSessions.create(sessionId, origin);
+    }
+    releaseAutomationSession(handle) {
+        this.automationSessions.release(handle);
+    }
+    reconcileAutomationSessions(cleanupAttachments, onError) {
+        return this.automationSessions.reconcile(cleanupAttachments, onError);
+    }
+    runAsAutomationSession(handle, task) {
+        return this.automationAccess.run(handle, task);
     }
     async getOrCreateSession(sessionId, options = {}) {
         assertValidSessionId(sessionId);
         await ensureSessionsDir(this.sessionsDir);
         const existing = await loadSessionFile(this.sessionsDir, sessionId);
         if (existing) {
+            this.automationAccess.assertAccess(sessionId, existing);
             assertSessionProjectUnchanged(existing, options.project);
+            assertSessionKindUnchanged(existing, options.kind);
             return existing;
         }
         const timestamp = toIso(this.now);
@@ -34,7 +78,7 @@ export class SessionService {
             ...(options.project
                 ? { project: copySessionProject(options.project) }
                 : {}),
-            title: sessionId,
+            ...sessionKindCreationFields(sessionId, options),
             createdAt: timestamp,
             updatedAt: timestamp,
             lastAgentMode: "reasoning",
@@ -46,7 +90,9 @@ export class SessionService {
     }
     async getAllSessions() {
         const sessions = await loadAllSessionFiles(this.sessionsDir);
-        return sessions.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return sessions
+            .filter((session) => this.automationAccess.canAccess(session.id, session))
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     }
     async listSessions(params = {}) {
         const limit = normalizeLimit(params.limit);
@@ -62,7 +108,10 @@ export class SessionService {
     async getSessionById(sessionId) {
         assertValidSessionId(sessionId);
         await ensureSessionsDir(this.sessionsDir);
-        return loadSessionFile(this.sessionsDir, sessionId);
+        const session = await loadSessionFile(this.sessionsDir, sessionId);
+        return session && this.automationAccess.canAccess(sessionId, session)
+            ? session
+            : null;
     }
     async getSessionSnapshot(sessionId, options = {}) {
         const session = await this.getSessionById(sessionId);
@@ -71,6 +120,7 @@ export class SessionService {
         }
         return {
             sessionId,
+            ...(session.kind ? { kind: session.kind } : {}),
             ...(session.project ? { project: session.project } : {}),
             title: session.title,
             messages: filterMessagesAfter(clientVisibleMessages(session.messages), options.afterMessageId).map((message) => toSnapshotMessage(sessionId, message, session.requests ?? [])),
@@ -85,6 +135,8 @@ export class SessionService {
         const normalizedAfterSeq = normalizeAfterSeq(afterSeq);
         const sessions = await loadAllSessionFiles(this.sessionsDir);
         for (const session of sessions) {
+            if (!this.automationAccess.canAccess(session.id, session))
+                continue;
             const request = getSessionRequest(session, requestId);
             if (!request) {
                 continue;
@@ -92,6 +144,9 @@ export class SessionService {
             return {
                 requestId,
                 sessionId: request.sessionId,
+                ...(request.lifecycle
+                    ? { lifecycle: projectSessionRequestLifecycle(request) }
+                    : {}),
                 ...(request.generation ? { generation: request.generation } : {}),
                 events: request.events
                     .filter((event) => event.seqNo > normalizedAfterSeq)
@@ -107,15 +162,17 @@ export class SessionService {
     }
     async deleteSessionWithStats(sessionId) {
         assertValidSessionId(sessionId);
-        await ensureSessionsDir(this.sessionsDir);
-        const session = await loadSessionFile(this.sessionsDir, sessionId);
-        const deleted = await deleteSessionFile(this.sessionsDir, sessionId);
-        return {
-            sessionId,
-            deleted,
-            deletedMessages: deleted ? (session?.messages.length ?? 0) : 0,
-            deletedRequests: deleted ? (session?.requests?.length ?? 0) : 0,
-        };
+        return this.runSessionMutation(sessionId, async () => {
+            await ensureSessionsDir(this.sessionsDir);
+            const session = await loadSessionFile(this.sessionsDir, sessionId);
+            const deleted = await deleteSessionFile(this.sessionsDir, sessionId);
+            return {
+                sessionId,
+                deleted,
+                deletedMessages: deleted ? (session?.messages.length ?? 0) : 0,
+                deletedRequests: deleted ? (session?.requests?.length ?? 0) : 0,
+            };
+        });
     }
     async resetSession(sessionId) {
         const result = await this.clearSessionMessages(sessionId);
@@ -175,6 +232,7 @@ export class SessionService {
             }
             const deletedMessages = session.messages.length;
             const deletedRequests = session.requests?.length ?? 0;
+            const hadDurableRequests = session.requests?.some((request) => request.lifecycle);
             const updatedAt = toIso(this.now);
             session.messages = [];
             session.messageCount = 0;
@@ -184,7 +242,11 @@ export class SessionService {
             delete session.sessionMemoryCheckpoint;
             delete session.runtimeModeId;
             session.updatedAt = updatedAt;
-            await saveSessionFile(this.sessionsDir, session);
+            if (hadDurableRequests)
+                await saveDurableSessionFile(this.sessionsDir, session);
+            else
+                await saveSessionFile(this.sessionsDir, session);
+            await cleanupSessionContinuations(this.sessionsDir, sessionId);
             return {
                 sessionId,
                 cleared: deletedMessages > 0 || deletedRequests > 0,
@@ -226,6 +288,21 @@ export class SessionService {
             return session;
         });
     }
+    async createAssistantConversation(sessionId, input) {
+        assertValidSessionId(sessionId);
+        return this.runSessionMutation(sessionId, () => createAssistantConversationRecord({
+            directory: this.sessionsDir,
+            sessionId,
+            input,
+            now: this.now(),
+        }));
+    }
+    async appendAssistantInitiative(sessionId, input) {
+        assertValidSessionId(sessionId);
+        return this.runSessionMutation(sessionId, () => appendAssistantInitiativeRecord({
+            directory: this.sessionsDir, sessionId, input, now: this.now(),
+        }));
+    }
     async compareAndSwapSessionMemoryCheckpoint(sessionId, command) {
         assertValidSessionId(sessionId);
         return this.runSessionMutation(sessionId, async () => {
@@ -285,6 +362,8 @@ export class SessionService {
             const timestamp = toIso(this.now);
             const existing = getSessionRequest(session, requestId);
             if (existing) {
+                if (existing.lifecycle)
+                    throw new Error("request_lifecycle_command_required");
                 existing.status = "streaming";
                 existing.updatedAt = timestamp;
                 existing.events = compactRequestEvents(existing.events);
@@ -316,6 +395,8 @@ export class SessionService {
             const session = await this.getOrCreateSession(sessionId);
             const timestamp = toIso(this.now);
             let request = getSessionRequest(session, requestId);
+            if (request?.lifecycle)
+                throw new Error("request_lifecycle_command_required");
             if (!request) {
                 request = {
                     requestId,
@@ -397,6 +478,7 @@ export class SessionService {
                 };
             }
             const requestId = targetMessage.requestId;
+            const hadDurableRequests = session.requests?.some((request) => request.lifecycle);
             let deletedRequestId;
             let deletedRequestEvents;
             if (requestId) {
@@ -416,7 +498,10 @@ export class SessionService {
                 delete session.runtimeModeId;
             }
             session.updatedAt = updatedAt;
-            await saveSessionFile(this.sessionsDir, session);
+            if (hadDurableRequests)
+                await saveDurableSessionFile(this.sessionsDir, session);
+            else
+                await saveSessionFile(this.sessionsDir, session);
             return {
                 sessionId,
                 messageId,
@@ -431,7 +516,12 @@ export class SessionService {
     }
     async runSessionMutation(sessionId, mutation) {
         const previous = this.sessionMutationQueues.get(sessionId) ?? Promise.resolve();
-        const current = previous.catch(() => undefined).then(mutation);
+        const current = previous.catch(() => undefined).then(async () => {
+            const existing = await loadSessionFile(this.sessionsDir, sessionId);
+            if (existing)
+                this.automationAccess.assertAccess(sessionId, existing);
+            return mutation();
+        });
         const queued = current.then(() => undefined, () => undefined);
         this.sessionMutationQueues.set(sessionId, queued);
         try {

package/dist/src/sessions/session-store.d.ts

@@ -1,6 +1,6 @@
 import type { SessionRecord } from "./types.js";
 export declare function ensureSessionsDir(sessionsDir: string): Promise<void>;
 export declare function loadSessionFile(sessionsDir: string, sessionId: string): Promise<SessionRecord | null>;
-export declare function saveSessionFile(sessionsDir: string, session: SessionRecord): Promise<void>;
+export declare function saveSessionFile(sessionsDir: string, session: SessionRecord, assertCurrent?: () => void): Promise<void>;
 export declare function deleteSessionFile(sessionsDir: string, sessionId: string): Promise<boolean>;
 export declare function loadAllSessionFiles(sessionsDir: string): Promise<SessionRecord[]>;

package/dist/src/sessions/session-store.js

@@ -1,6 +1,8 @@
 import { mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
+import { saveDurableSessionFile, syncSessionDirectory, } from "./durable-session-commit.js";
+import { cleanupSessionContinuations } from "./request-lifecycle/continuation-cleanup.js";
 function getSessionFilePath(sessionsDir, sessionId) {
     return join(sessionsDir, `${sessionId}.json`);
 }
@@ -20,11 +22,15 @@ export async function loadSessionFile(sessionsDir, sessionId) {
         throw error;
     }
 }
-export async function saveSessionFile(sessionsDir, session) {
+export async function saveSessionFile(sessionsDir, session, assertCurrent) {
+    if (session.requests?.some((request) => request.lifecycle)) {
+        return saveDurableSessionFile(sessionsDir, session, assertCurrent);
+    }
     const filePath = getSessionFilePath(sessionsDir, session.id);
     const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
     try {
         await writeFile(tempPath, JSON.stringify(session, null, 2), "utf-8");
+        assertCurrent?.();
         await rename(tempPath, filePath);
     }
     catch (error) {
@@ -36,6 +42,8 @@ export async function deleteSessionFile(sessionsDir, sessionId) {
     const filePath = getSessionFilePath(sessionsDir, sessionId);
     try {
         await rm(filePath);
+        await syncSessionDirectory(sessionsDir);
+        await cleanupSessionContinuations(sessionsDir, sessionId);
         return true;
     }
     catch (error) {

package/dist/src/sessions/spark-handoff-brief.d.ts

@@ -0,0 +1,3 @@
+/** Fits the existing assistant conversation content bound without truncation. */
+export declare const MAX_SPARK_HANDOFF_BRIEF_CHARACTERS = 4000;
+export declare function isSparkHandoffBrief(value: unknown): value is string;

package/dist/src/sessions/spark-handoff-brief.js

@@ -0,0 +1,9 @@
+/** Fits the existing assistant conversation content bound without truncation. */
+export const MAX_SPARK_HANDOFF_BRIEF_CHARACTERS = 4000;
+export function isSparkHandoffBrief(value) {
+    if (typeof value !== "string")
+        return false;
+    if (!value.trim())
+        return false;
+    return value.length <= MAX_SPARK_HANDOFF_BRIEF_CHARACTERS;
+}

package/dist/src/sessions/spark-session.d.ts

@@ -0,0 +1,13 @@
+import type { SessionCreationOptions } from "./project-binding.js";
+import type { SessionRecord } from "./types.js";
+/** The environment's session directory owns the namespace, not the display name. */
+export declare const SPARK_SESSION_ID = "spark-companion";
+export type SessionKind = "spark";
+export declare function isSparkSession(session: {
+    kind?: SessionKind;
+}): boolean;
+export declare function assertSessionKindUnchanged(session: SessionRecord, requested?: SessionKind): void;
+export declare function sessionKindCreationFields(sessionId: string, options: SessionCreationOptions): Pick<SessionRecord, "kind" | "title">;
+export declare function ensureSparkSession(sessions: {
+    getOrCreateSession(id: string, options?: SessionCreationOptions): Promise<SessionRecord>;
+}): Promise<SessionRecord>;

package/dist/src/sessions/spark-session.js

@@ -0,0 +1,25 @@
+/** The environment's session directory owns the namespace, not the display name. */
+export const SPARK_SESSION_ID = "spark-companion";
+export function isSparkSession(session) {
+    return session.kind === "spark";
+}
+export function assertSessionKindUnchanged(session, requested) {
+    if (requested === undefined)
+        return;
+    if (session.kind !== requested)
+        throw new Error("session_kind_binding_immutable");
+}
+export function sessionKindCreationFields(sessionId, options) {
+    if (options.kind === undefined)
+        return { title: sessionId };
+    if (options.kind !== "spark")
+        throw new Error("session_kind_invalid");
+    if (sessionId !== SPARK_SESSION_ID)
+        throw new Error("spark_session_identity_invalid");
+    if (options.project)
+        throw new Error("spark_session_project_binding_unsupported");
+    return { kind: "spark", title: "ABot SPARK" };
+}
+export function ensureSparkSession(sessions) {
+    return sessions.getOrCreateSession(SPARK_SESSION_ID, { kind: "spark" });
+}