@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/runtime/scheduler/scheduler-service.js

@@ -1,10 +1,15 @@
+import { changeAutomationSchedulerJobState, createAutomationSchedulerJob, requestAutomationSchedulerRunNow, updateAutomationSchedulerJob, } from "./automation-job-management.js";
+import { stopAutomationSchedulerRun } from "./automation-run-control.js";
+import { requestAutomationSchedulerRerun } from "./automation-rerun.js";
 import { changeSchedulerJobState, createSchedulerJob, deleteSchedulerSession, matchesSchedulerFilter, requestSchedulerRunNow, updateSchedulerJob, } from "./job-management.js";
 import { tickScheduler } from "./scheduler-engine.js";
 import { requireRunningScheduler, } from "./service-context.js";
 import { recoverSchedulerSnapshot } from "./startup-recovery.js";
 import { querySchedulerRuns } from "./run-list-query.js";
 import { createSchedulerWorkingStore } from "./working-store.js";
+import { observeAutomationRunChanges } from "./automation-run-change-events.js";
 import { SchedulerSessionDeletionState } from "./session-deletion-state.js";
+import { isAutomationSchedulerJob, isAutomationSchedulerRun, isRequestSchedulerJob, isRequestSchedulerRun, } from "./scheduler-target.js";
 export function createSchedulerService(options) {
     let tail = Promise.resolve();
     let releaseOwner;
@@ -12,8 +17,11 @@ export function createSchedulerService(options) {
     let ticking;
     const context = {
         environmentId: options.environmentId,
-        store: createSchedulerWorkingStore(options.store),
+        store: options.onAutomationRunChange
+            ? observeAutomationRunChanges(createSchedulerWorkingStore(options.store), options.onAutomationRunChange)
+            : createSchedulerWorkingStore(options.store),
         executor: options.executor,
+        automationExecutor: options.automationExecutor,
         now: options.now ?? Date.now,
         running: false,
         generation: 0,
@@ -21,6 +29,7 @@ export function createSchedulerService(options) {
         pendingJobMutations: new Set(),
         deletedSessions: new SchedulerSessionDeletionState(),
         pendingCompletions: new Map(),
+        pendingAutomationCompletions: new Map(),
         enqueue: (operation) => {
             const result = tail.then(operation);
             tail = result.catch(() => undefined);
@@ -39,9 +48,25 @@ export function createSchedulerService(options) {
                 const release = await options.store.acquire();
                 releaseOwner = release;
                 try {
-                    await context.store.update((state) => {
-                        recoverSchedulerSnapshot(state, options.environmentId, context.now());
-                    });
+                    const automationExecutor = options.automationExecutor;
+                    if (automationExecutor) {
+                        const update = context.store.updateWithAutomations;
+                        if (!update)
+                            throw new Error("automation_store_unavailable");
+                        await update((state, automations) => {
+                            const recovered = recoverSchedulerSnapshot(state, options.environmentId, context.now());
+                            automationExecutor.recover(state, automations, recovered);
+                            requireRecoveredAutomationReports(state, automations, recovered);
+                        });
+                        await automationExecutor.reconcileSessions?.().catch(context.onError);
+                    }
+                    else {
+                        await context.store.update((state) => {
+                            if (state.jobs.some(isAutomationSchedulerJob))
+                                throw new Error("automation_executor_unavailable");
+                            recoverSchedulerSnapshot(state, options.environmentId, context.now());
+                        });
+                    }
                     if (requestedGeneration !== context.generation) {
                         await release();
                         releaseOwner = undefined;
@@ -65,6 +90,7 @@ export function createSchedulerService(options) {
             context.generation += 1;
             context.running = false;
             context.pendingCompletions.clear();
+            context.pendingAutomationCompletions.clear();
             if (timer)
                 clearInterval(timer);
             timer = undefined;
@@ -90,11 +116,13 @@ export function createSchedulerService(options) {
         create: (input) => createSchedulerJob(context, input),
         list: (filter = {}) => context.enqueue(async () => {
             requireRunningScheduler(context);
-            return (await context.store.read()).jobs.filter((job) => matchesSchedulerFilter(job, filter));
+            return (await context.store.read()).jobs
+                .filter(isRequestSchedulerJob)
+                .filter((job) => matchesSchedulerFilter(job, filter));
         }),
         get: (jobId) => context.enqueue(async () => {
             requireRunningScheduler(context);
-            return ((await context.store.read()).jobs.find((job) => job.id === jobId) ??
+            return ((await context.store.read()).jobs.find((job) => isRequestSchedulerJob(job) && job.id === jobId) ??
                 null);
         }),
         update: (jobId, patch) => updateSchedulerJob(context, jobId, patch),
@@ -105,11 +133,56 @@ export function createSchedulerService(options) {
         deleteSession: (sessionId) => deleteSchedulerSession(context, sessionId),
         listRuns: (jobId, query) => context.enqueue(async () => {
             requireRunningScheduler(context);
-            if (options.store.readRuns)
-                return options.store.readRuns(jobId, query);
-            const runs = (await options.store.read()).runs;
-            return querySchedulerRuns(runs, jobId, query);
+            const runs = options.store.readRuns
+                ? await options.store.readRuns(jobId, query, "request")
+                : (await options.store.read()).runs;
+            return querySchedulerRuns(runs.filter(isRequestSchedulerRun), jobId, options.store.readRuns ? undefined : query);
+        }),
+        createAutomationJob: (input, commitPublication) => createAutomationSchedulerJob(context, input, commitPublication),
+        getAutomationJob: (automationId) => context.enqueue(async () => {
+            requireRunningScheduler(context);
+            return ((await context.store.read()).jobs.find((job) => isAutomationSchedulerJob(job) &&
+                job.target.automationId === automationId) ?? null);
+        }),
+        listAutomationJobs: () => context.enqueue(async () => {
+            requireRunningScheduler(context);
+            return (await context.store.read()).jobs.filter(isAutomationSchedulerJob);
+        }),
+        updateAutomationJob: (jobId, patch, commitPublication) => updateAutomationSchedulerJob(context, jobId, patch, commitPublication),
+        pauseAutomationJob: (jobId) => changeAutomationSchedulerJobState(context, jobId, "paused"),
+        resumeAutomationJob: (jobId) => changeAutomationSchedulerJobState(context, jobId, "active"),
+        runNowAutomation: (jobId, runOptions) => requestAutomationSchedulerRunNow(context, jobId, runOptions),
+        rerunAutomationRun: (previousRunId, runOptions) => requestAutomationSchedulerRerun(context, previousRunId, runOptions),
+        stopAutomationRun: (runId) => stopAutomationSchedulerRun(context, runId),
+        listAutomationRuns: (automationId, query) => context.enqueue(async () => {
+            requireRunningScheduler(context);
+            const job = (await context.store.read()).jobs.find((item) => isAutomationSchedulerJob(item) &&
+                item.target.automationId === automationId);
+            if (!job)
+                return [];
+            const boundedQuery = query ?? { limit: 100 };
+            const runs = options.store.readRuns
+                ? await options.store.readRuns(job.id, boundedQuery, "automation")
+                : (await options.store.read()).runs;
+            return querySchedulerRuns(runs.filter(isAutomationSchedulerRun), job.id, options.store.readRuns ? undefined : boundedQuery);
+        }),
+        getAutomationRun: (runId) => context.enqueue(async () => {
+            requireRunningScheduler(context);
+            const run = options.store.readRun
+                ? await options.store.readRun(runId)
+                : (await options.store.read()).runs.find((item) => item.id === runId);
+            return run && isAutomationSchedulerRun(run) ? run : null;
         }),
     };
     return service;
 }
+function requireRecoveredAutomationReports(scheduler, automations, runIds) {
+    for (const runId of runIds) {
+        const run = scheduler.runs.find((item) => item.id === runId);
+        if (!run || !isAutomationSchedulerRun(run) || !run.reportRef)
+            throw new Error("automation_report_missing");
+        const execution = automations.executions.find((item) => item.id === runId);
+        if (execution?.reportRef !== run.reportRef)
+            throw new Error("automation_report_missing");
+    }
+}

package/dist/src/runtime/scheduler/scheduler-target.d.ts

@@ -0,0 +1,9 @@
+import type { SchedulerAutomationJob, SchedulerAutomationRun, SchedulerJob, SchedulerRun, SchedulerStoredJob, SchedulerStoredRun } from "./contracts.js";
+export declare function isAutomationSchedulerJob(job: SchedulerStoredJob): job is SchedulerAutomationJob;
+export declare function isRequestSchedulerJob(job: SchedulerStoredJob): job is SchedulerJob;
+export declare function isAutomationSchedulerRun(run: SchedulerStoredRun): run is SchedulerAutomationRun;
+export declare function isRequestSchedulerRun(run: SchedulerStoredRun): run is SchedulerRun;
+export declare function requireRequestSchedulerJob(job: SchedulerStoredJob): SchedulerJob;
+export declare function requireRequestSchedulerRun(run: SchedulerStoredRun): SchedulerRun;
+export declare function sameSchedulerTarget(job: SchedulerStoredJob, run: SchedulerStoredRun): boolean;
+export declare function schedulerTargetKey(value: SchedulerStoredJob | SchedulerStoredRun): string;

package/dist/src/runtime/scheduler/scheduler-target.js

@@ -0,0 +1,41 @@
+export function isAutomationSchedulerJob(job) {
+    return job.target?.kind === "automation";
+}
+export function isRequestSchedulerJob(job) {
+    return !isAutomationSchedulerJob(job);
+}
+export function isAutomationSchedulerRun(run) {
+    return run.target?.kind === "automation";
+}
+export function isRequestSchedulerRun(run) {
+    return !isAutomationSchedulerRun(run);
+}
+export function requireRequestSchedulerJob(job) {
+    if (!isRequestSchedulerJob(job))
+        throw new Error("scheduler_request_job_required");
+    return job;
+}
+export function requireRequestSchedulerRun(run) {
+    if (!isRequestSchedulerRun(run))
+        throw new Error("scheduler_request_run_required");
+    return run;
+}
+export function sameSchedulerTarget(job, run) {
+    if (isAutomationSchedulerJob(job)) {
+        if (!isAutomationSchedulerRun(run))
+            return false;
+        if (job.target.automationId !== run.target.automationId)
+            return false;
+        return run.target.definitionRevision <= job.target.definitionRevision;
+    }
+    if (!isRequestSchedulerRun(run))
+        return false;
+    return job.sessionId === run.sessionId;
+}
+export function schedulerTargetKey(value) {
+    if (value.target?.kind === "automation")
+        return `automation:${value.target.automationId}`;
+    if (!("sessionId" in value))
+        throw new Error("scheduler_store_corrupt");
+    return `session:${value.sessionId}`;
+}

package/dist/src/runtime/scheduler/service-context.d.ts

@@ -1,10 +1,12 @@
-import type { SchedulerExecutor, SchedulerStore } from "./contracts.js";
+import type { SchedulerAutomationExecutor, SchedulerExecutor, SchedulerStore } from "./contracts.js";
 import type { SchedulerRunCompletion } from "./run-completion.js";
+import type { AutomationSchedulerRunCompletion } from "./automation-run-completion.js";
 import type { SchedulerSessionDeletionState } from "./session-deletion-state.js";
 export interface SchedulerContext {
     environmentId: string;
     store: SchedulerStore;
     executor: SchedulerExecutor;
+    automationExecutor?: SchedulerAutomationExecutor;
     now(): number;
     running: boolean;
     generation: number;
@@ -12,10 +14,12 @@ export interface SchedulerContext {
     pendingJobMutations: Set<string>;
     deletedSessions: SchedulerSessionDeletionState;
     pendingCompletions: Map<string, SchedulerRunCompletion>;
+    pendingAutomationCompletions: Map<string, AutomationSchedulerRunCompletion>;
     enqueue<T>(operation: () => Promise<T>): Promise<T>;
     onError(error: unknown): void;
 }
 export declare function requireRunningScheduler(context: SchedulerContext): void;
 export declare function jobEpoch(context: SchedulerContext, jobId: string): number;
 export declare function invalidateJob(context: SchedulerContext, jobId: string): () => void;
-export declare function canBeginSchedulerRun(context: SchedulerContext, jobId: string, sessionId: string, epoch: number): boolean;
+export declare function canBeginSchedulerRun(context: SchedulerContext, jobId: string, epoch: number): boolean;
+export declare function canBeginRequestSchedulerRun(context: SchedulerContext, jobId: string, sessionId: string, epoch: number): boolean;

package/dist/src/runtime/scheduler/service-context.js

@@ -15,12 +15,15 @@ export function invalidateJob(context, jobId) {
         context.pendingJobMutations.delete(jobId);
     };
 }
-export function canBeginSchedulerRun(context, jobId, sessionId, epoch) {
+export function canBeginSchedulerRun(context, jobId, epoch) {
     if (!context.running)
         return false;
-    if (context.deletedSessions.has(sessionId))
-        return false;
     if (context.pendingJobMutations.has(jobId))
         return false;
     return jobEpoch(context, jobId) === epoch;
 }
+export function canBeginRequestSchedulerRun(context, jobId, sessionId, epoch) {
+    if (context.deletedSessions.has(sessionId))
+        return false;
+    return canBeginSchedulerRun(context, jobId, epoch);
+}

package/dist/src/runtime/scheduler/snapshot-validation.d.ts

@@ -1,4 +1,4 @@
-import type { SchedulerJob, SchedulerRun, SchedulerSnapshot } from "./contracts.js";
-export declare function parseStoredJob(value: unknown): SchedulerJob;
-export declare function parseStoredRun(value: unknown): SchedulerRun;
+import type { SchedulerSnapshot, SchedulerStoredJob, SchedulerStoredRun } from "./contracts.js";
+export declare function parseStoredJob(value: unknown): SchedulerStoredJob;
+export declare function parseStoredRun(value: unknown): SchedulerStoredRun;
 export declare function parseSchedulerSnapshot(value: unknown): SchedulerSnapshot;

package/dist/src/runtime/scheduler/snapshot-validation.js

@@ -1,3 +1,5 @@
+import { parseStoredAutomationJob, parseStoredAutomationRun, } from "./automation-snapshot-validation.js";
+import { sameSchedulerTarget } from "./scheduler-target.js";
 import { normalizeStoredSchedulerSchedule, validateSchedulerJobInput, validateTimeZone, } from "./schedule-validation.js";
 import { isSchedulerToolPermissionMode, requireSchedulerToolPermissionMode, } from "./tool-permission-mode.js";
 function isRecord(value) {
@@ -17,6 +19,10 @@ function requireSnapshotInstant(value) {
 export function parseStoredJob(value) {
     if (!isRecord(value))
         failSnapshot();
+    if (isAutomationTarget(value.target))
+        return parseStoredAutomationJob(value);
+    if (!isRequestTarget(value.target))
+        failSnapshot();
     const job = value;
     validateSchedulerJobInput(job);
     if (!job.id || !job.environmentId)
@@ -37,11 +43,17 @@ export function parseStoredJob(value) {
     if (job.schedule?.kind === "interval" && !job.schedule.anchorAt)
         failSnapshot();
     const normalized = normalizeStoredSchedulerSchedule(job.schedule);
+    if (normalized.kind === "manual")
+        failSnapshot();
     return { ...job, schedule: normalized };
 }
 export function parseStoredRun(value) {
     if (!isRecord(value))
         failSnapshot();
+    if (isAutomationTarget(value.target))
+        return parseStoredAutomationRun(value);
+    if (!isRequestTarget(value.target))
+        failSnapshot();
     for (const field of [
         "id",
         "jobId",
@@ -103,7 +115,7 @@ export function parseSchedulerSnapshot(value) {
         const owner = jobs.find((job) => job.id === run.jobId);
         if (!owner)
             failSnapshot();
-        if (owner.sessionId !== run.sessionId)
+        if (!sameSchedulerTarget(owner, run))
             failSnapshot();
         if (owner.environmentId !== run.environmentId)
             failSnapshot();
@@ -112,3 +124,11 @@ export function parseSchedulerSnapshot(value) {
     }
     return { schemaVersion: 1, jobs, runs };
 }
+function isAutomationTarget(value) {
+    return isRecord(value) && value.kind === "automation";
+}
+function isRequestTarget(value) {
+    if (value === undefined)
+        return true;
+    return isRecord(value) && value.kind === "request";
+}

package/dist/src/runtime/scheduler/startup-recovery.d.ts

@@ -1,2 +1,2 @@
 import type { SchedulerSnapshot } from "./contracts.js";
-export declare function recoverSchedulerSnapshot(state: SchedulerSnapshot, environmentId: string, now: number): void;
+export declare function recoverSchedulerSnapshot(state: SchedulerSnapshot, environmentId: string, now: number): string[];

package/dist/src/runtime/scheduler/startup-recovery.js

@@ -1,16 +1,22 @@
+import { randomUUID } from "node:crypto";
+import { makeAutomationSchedulerRun } from "./automation-run-records.js";
 import { nextSchedulerOccurrence } from "./next-occurrence.js";
 import { makeSchedulerRun } from "./run-records.js";
+import { isAutomationSchedulerJob, isAutomationSchedulerRun, } from "./scheduler-target.js";
 export function recoverSchedulerSnapshot(state, environmentId, now) {
     const at = new Date(now).toISOString();
+    const recoveredAutomationRuns = [];
     for (const job of state.jobs) {
         if (job.environmentId !== environmentId)
             throw new Error("scheduler_environment_mismatch");
     }
     for (const run of state.runs) {
-        if (run.status === "running") {
+        if (run.status === "running" || run.status === "stopping") {
             run.status = "interrupted";
             run.finishedAt = at;
             run.error = "scheduler_process_stopped";
+            if (isAutomationSchedulerRun(run))
+                recoveredAutomationRuns.push(run.id);
             continue;
         }
         if (run.status !== "pending")
@@ -18,6 +24,8 @@ export function recoverSchedulerSnapshot(state, environmentId, now) {
         run.status = "missed";
         run.finishedAt = at;
         run.error = "scheduler_offline_no_catchup";
+        if (isAutomationSchedulerRun(run))
+            recoveredAutomationRuns.push(run.id);
     }
     for (const job of state.jobs) {
         if (job.state !== "active")
@@ -26,13 +34,18 @@ export function recoverSchedulerSnapshot(state, environmentId, now) {
             continue;
         if (Date.parse(job.nextRunAt) > now)
             continue;
-        const missed = makeSchedulerRun(job, job.nextRunAt, "schedule");
+        const missed = isAutomationSchedulerJob(job)
+            ? makeAutomationSchedulerRun(job, randomUUID(), job.nextRunAt, "schedule")
+            : makeSchedulerRun(job, job.nextRunAt, "schedule");
         missed.status = "missed";
         missed.finishedAt = at;
         missed.error = "scheduler_offline_no_catchup";
         state.runs.push(missed);
+        if (isAutomationSchedulerRun(missed))
+            recoveredAutomationRuns.push(missed.id);
         job.nextRunAt = nextSchedulerOccurrence(job.schedule, job.timeZone, now);
         if (!job.nextRunAt)
             job.state = "completed";
     }
+    return recoveredAutomationRuns;
 }

package/dist/src/runtime/scheduler/working-store.js

@@ -3,6 +3,14 @@ export function createSchedulerWorkingStore(store) {
     return {
         acquire: () => store.acquire(),
         read: () => store.read("active"),
+        readRun: store.readRun?.bind(store),
+        readAutomationRunByKey: store.readAutomationRunByKey?.bind(store),
+        countAutomationRunsOnDay: store.countAutomationRunsOnDay?.bind(store),
         update: (mutate) => store.update(mutate, "active"),
+        readAutomations: store.readAutomations?.bind(store),
+        updateAutomations: store.updateAutomations?.bind(store),
+        updateWithAutomations: store.updateWithAutomations
+            ? (mutate) => store.updateWithAutomations(mutate, "active")
+            : undefined,
     };
 }

package/dist/src/runtime/session/request-session.d.ts

@@ -28,6 +28,7 @@ export declare function initializeRequestSession(params: {
     sessionStore: RequestSessionStore;
     attachmentStore?: RuntimeAttachmentStore;
     events: EventSink;
+    onUserMessagePersisted?(): void;
     schedule?: import("../../sessions/schedule-metadata.js").ScheduleMessageReference;
 }): Promise<Readonly<{
     prompt: string;

package/dist/src/runtime/session/request-session.js

@@ -37,6 +37,7 @@ export async function initializeRequestSession(params) {
             ? { attachments: params.opened.attachments }
             : {}),
     });
+    params.onUserMessagePersisted?.();
     params.events.event("session.messages.updated", {
         sessionId: params.sessionId,
     });

package/dist/src/runtime/session/session-deletion-boundary.d.ts

@@ -3,7 +3,7 @@ import type { SessionStore } from "../ports.js";
 import { type SessionDeletionFinalizer } from "./session-deletion-finalization.js";
 import type { SessionMutationQueue } from "./session-mutation-queue.js";
 /** Shared transaction for managed stores and compatibility deletion adapters. */
-export declare function createSessionDeletionBoundary(base: Pick<SessionStore, "deleteSessionWithStats">, enqueue: SessionMutationQueue, finalize?: SessionDeletionFinalizer): {
+export declare function createSessionDeletionBoundary(base: Pick<SessionStore, "deleteSessionWithStats">, enqueue: SessionMutationQueue, finalize?: SessionDeletionFinalizer, beforeDelete?: (sessionId: string) => Promise<void>): {
     deleteSessionWithStats: (sessionId: string) => Promise<SessionDeleteResult>;
     isDeleted: (sessionId: string) => boolean;
     onDeleted: (listener: import("./session-deletion-cleanup.js").SessionDeletionListener) => () => void;

package/dist/src/runtime/session/session-deletion-boundary.js

@@ -3,7 +3,7 @@ import { createSessionDeletionCleanup } from "./session-deletion-cleanup.js";
 import { createSessionDeletionFinalization, } from "./session-deletion-finalization.js";
 import { createSessionDeletionReceipts } from "./session-deletion-receipts.js";
 /** Shared transaction for managed stores and compatibility deletion adapters. */
-export function createSessionDeletionBoundary(base, enqueue, finalize) {
+export function createSessionDeletionBoundary(base, enqueue, finalize, beforeDelete) {
     const cleanup = createSessionDeletionCleanup();
     const receipts = createSessionDeletionReceipts(base);
     const finalization = finalize
@@ -11,13 +11,17 @@ export function createSessionDeletionBoundary(base, enqueue, finalize) {
         : undefined;
     if (finalization)
         cleanup.onDeleted(finalization.finalizeDeletedSession);
+    async function removePhysicalSession(sessionId) {
+        await beforeDelete?.(sessionId);
+        return receipts.remove(sessionId);
+    }
     async function deleteSessionWithStats(sessionId) {
         assertValidSessionId(sessionId);
         const settlePhysical = finalization?.prepare(sessionId);
         let notification;
         // Reserve before invoking listeners: synchronous reentry must queue behind us.
         const result = enqueue(sessionId, async () => {
-            const [deletion] = await Promise.allSettled([receipts.remove(sessionId)]);
+            const [deletion] = await Promise.allSettled([removePhysicalSession(sessionId)]);
             settlePhysical?.(deletion);
             const [notified] = await notification;
             if (deletion.status === "rejected")

package/dist/src/runtime/session/session-lifecycle-store.d.ts

@@ -1,6 +1,7 @@
 import type { SessionStore } from "../ports.js";
 import type { SessionDeletionListener } from "./session-deletion-cleanup.js";
 import type { SessionDeletionFinalizer } from "./session-deletion-finalization.js";
+import type { SessionClearBoundary } from "./spark-session-clear.js";
 export type { SessionDeletionListener } from "./session-deletion-cleanup.js";
 export declare class SessionDeletedError extends Error {
     readonly sessionId: string;
@@ -18,4 +19,6 @@ export type SessionLifecycleStore = Readonly<{
  * an in-flight write finishes before deletion, while queued and later writes fail.
  * Tombstones last for this application lifetime; deleted IDs cannot be reused.
  */
-export declare function createSessionLifecycleStore(base: SessionStore, finalizeDeletion?: SessionDeletionFinalizer): SessionLifecycleStore;
+export declare function createSessionLifecycleStore(base: SessionStore, finalizeDeletion?: SessionDeletionFinalizer, 
+/** Runs inside the deletion queue after the tombstone, before the transcript is removed. */
+beforeDelete?: (sessionId: string) => Promise<void>, clearBoundary?: SessionClearBoundary): SessionLifecycleStore;

package/dist/src/runtime/session/session-lifecycle-store.js

@@ -17,9 +17,11 @@ export function isSessionDeletedError(error) {
  * an in-flight write finishes before deletion, while queued and later writes fail.
  * Tombstones last for this application lifetime; deleted IDs cannot be reused.
  */
-export function createSessionLifecycleStore(base, finalizeDeletion) {
+export function createSessionLifecycleStore(base, finalizeDeletion, 
+/** Runs inside the deletion queue after the tombstone, before the transcript is removed. */
+beforeDelete, clearBoundary) {
     const enqueueSessionMutation = createSessionMutationQueue();
-    const deletion = createSessionDeletionBoundary(base, enqueueSessionMutation, finalizeDeletion);
+    const deletion = createSessionDeletionBoundary(base, enqueueSessionMutation, finalizeDeletion, beforeDelete);
     function assertSessionNotDeleted(sessionId) {
         if (deletion.isDeleted(sessionId)) {
             throw new SessionDeletedError(sessionId);
@@ -35,6 +37,21 @@ export function createSessionLifecycleStore(base, finalizeDeletion) {
         };
     }
     const store = {
+        ...(base.assertInteractiveSession
+            ? { assertInteractiveSession: base.assertInteractiveSession.bind(base) }
+            : {}),
+        ...(base.createAutomationSession
+            ? {
+                createAutomationSession: wrapSessionMutation(base.createAutomationSession),
+            }
+            : {}),
+        ...(base.runAsAutomationSession
+            ? { runAsAutomationSession: base.runAsAutomationSession.bind(base) }
+            : {}),
+        ...(base.releaseAutomationSession
+            ? { releaseAutomationSession: base.releaseAutomationSession.bind(base) } : {}),
+        ...(base.reconcileAutomationSessions
+            ? { reconcileAutomationSessions: base.reconcileAutomationSessions.bind(base) } : {}),
         ...(base.requestLifecycle
             ? {
                 requestLifecycle: {
@@ -55,6 +72,9 @@ export function createSessionLifecycleStore(base, finalizeDeletion) {
             }
             : {}),
         getAllSessions: base.getAllSessions.bind(base),
+        ...(base.appendAssistantInitiative
+            ? { appendAssistantInitiative: wrapSessionMutation(base.appendAssistantInitiative) }
+            : {}),
         listSessions: base.listSessions.bind(base),
         getSessionById: base.getSessionById.bind(base),
         getSessionSnapshot: base.getSessionSnapshot.bind(base),
@@ -65,8 +85,8 @@ export function createSessionLifecycleStore(base, finalizeDeletion) {
         startRequestStream: wrapSessionMutation(base.startRequestStream),
         appendRequestEvent: wrapSessionMutation(base.appendRequestEvent),
         compareAndSwapSessionMemoryCheckpoint: wrapSessionMutation(base.compareAndSwapSessionMemoryCheckpoint),
-        resetSession: wrapSessionMutation(base.resetSession),
-        clearSessionMessages: wrapSessionMutation(base.clearSessionMessages),
+        resetSession: wrapSessionClear(base.resetSession),
+        clearSessionMessages: wrapSessionClear(base.clearSessionMessages),
         deleteMessage: wrapSessionMutation(base.deleteMessage),
         deleteMessageWithStats: wrapSessionMutation(base.deleteMessageWithStats),
         deleteSession: async (sessionId) => (await deletion.deleteSessionWithStats(sessionId)).deleted,
@@ -88,4 +108,12 @@ export function createSessionLifecycleStore(base, finalizeDeletion) {
         isDeleted: deletion.isDeleted,
         onDeleted: deletion.onDeleted,
     };
+    function wrapSessionClear(operation) {
+        const mutate = wrapSessionMutation(operation);
+        return (sessionId) => {
+            if (!clearBoundary)
+                return mutate(sessionId);
+            return clearBoundary(sessionId, () => mutate(sessionId));
+        };
+    }
 }

package/dist/src/runtime/session/spark-session-attachments.d.ts

@@ -0,0 +1,4 @@
+import type { SessionRecord } from "../../sessions/types.js";
+import type { RuntimeAttachmentStore } from "../attachments/store.js";
+/** Capture only transcript-owned files; a simultaneous new upload is a different reference. */
+export declare function prepareSparkAttachmentCleanup(attachments: RuntimeAttachmentStore | undefined, session: SessionRecord | null, runtimeDirectory?: string): Promise<() => Promise<void>>;

package/dist/src/runtime/session/spark-session-attachments.js

@@ -0,0 +1,28 @@
+import { createSparkCleanupReceipt } from "./spark-session-cleanup-receipt.js";
+/** Capture only transcript-owned files; a simultaneous new upload is a different reference. */
+export async function prepareSparkAttachmentCleanup(attachments, session, runtimeDirectory) {
+    const receipt = runtimeDirectory ? createSparkCleanupReceipt(runtimeDirectory) : undefined;
+    const pending = await receipt?.read() ?? [];
+    const captured = (session?.messages ?? []).flatMap((message) => message.attachments ?? []);
+    const references = [...new Map([...pending, ...captured]
+            .map((attachment) => [attachment.storageRef, attachment])).values()];
+    if (references.length === 0)
+        return async () => { };
+    const deleteAttachment = attachments?.deleteAttachment?.bind(attachments);
+    if (!deleteAttachment)
+        throw new Error("spark_chat_attachment_cleanup_unavailable");
+    if (!receipt)
+        throw new Error("spark_chat_cleanup_receipt_unavailable");
+    // Persist before transcript removal. A failed deletion never loses its retry reference.
+    await receipt.save(references);
+    return async () => {
+        const outcomes = await Promise.allSettled(references.map((reference) => deleteAttachment(reference, { sessionId: session.id })));
+        const failed = outcomes.find(isAttachmentCleanupFailure);
+        if (failed)
+            throw failed.reason;
+        await receipt.complete();
+    };
+}
+function isAttachmentCleanupFailure(outcome) {
+    return outcome.status === "rejected";
+}

package/dist/src/runtime/session/spark-session-cleanup-receipt.d.ts

@@ -0,0 +1,7 @@
+import { type RuntimeAttachmentReference } from "../attachments/store.js";
+/** Exact pending deletions, accessed only while the owner holds SPARK admission. */
+export declare function createSparkCleanupReceipt(runtimeDirectory: string): {
+    read(): Promise<RuntimeAttachmentReference[]>;
+    save(references: RuntimeAttachmentReference[]): Promise<void>;
+    complete(): Promise<void>;
+};

package/dist/src/runtime/session/spark-session-cleanup-receipt.js

@@ -0,0 +1,61 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { syncSessionDirectory } from "../../sessions/durable-session-commit.js";
+import { SPARK_SESSION_ID } from "../../sessions/spark-session.js";
+import { parseRuntimeAttachmentReferences } from "../attachments/store.js";
+function isMissingCleanupReceipt(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function parseCleanupReceipt(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("spark_chat_cleanup_receipt_invalid");
+    if (!("schemaVersion" in value) || value.schemaVersion !== 1)
+        throw new Error("spark_chat_cleanup_receipt_invalid");
+    if (!("sessionId" in value) || value.sessionId !== SPARK_SESSION_ID)
+        throw new Error("spark_chat_cleanup_receipt_invalid");
+    if (!("references" in value) || !Array.isArray(value.references))
+        throw new Error("spark_chat_cleanup_receipt_invalid");
+    return parseRuntimeAttachmentReferences(value.references);
+}
+/** Exact pending deletions, accessed only while the owner holds SPARK admission. */
+export function createSparkCleanupReceipt(runtimeDirectory) {
+    const directory = join(runtimeDirectory, "spark-chat");
+    const path = join(directory, "attachment-cleanup.json");
+    return {
+        async read() {
+            try {
+                return parseCleanupReceipt(JSON.parse(await readFile(path, "utf8")));
+            }
+            catch (error) {
+                if (isMissingCleanupReceipt(error))
+                    return [];
+                throw error;
+            }
+        },
+        async save(references) {
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            await syncSessionDirectory(dirname(directory));
+            const temporary = `${path}.${randomUUID()}.tmp`;
+            try {
+                const handle = await open(temporary, "wx", 0o600);
+                try {
+                    await handle.writeFile(JSON.stringify({ schemaVersion: 1, sessionId: SPARK_SESSION_ID, references }));
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await rename(temporary, path);
+                await syncSessionDirectory(directory);
+            }
+            finally {
+                await rm(temporary, { force: true }).catch(() => undefined);
+            }
+        },
+        async complete() {
+            await rm(path, { force: true });
+            await syncSessionDirectory(directory);
+        },
+    };
+}

package/dist/src/runtime/session/spark-session-clear.d.ts

@@ -0,0 +1,6 @@
+import type { SessionStore } from "../ports.js";
+import type { SessionRequestAdmission } from "../request/session-admission.js";
+import type { RuntimeAttachmentStore } from "../attachments/store.js";
+export type SessionClearBoundary = <T>(sessionId: string, clear: () => Promise<T>) => Promise<T>;
+/** Protect the permanent conversation without changing ordinary session clearing. */
+export declare function createSparkSessionClearBoundary(sessions: Pick<SessionStore, "getSessionById" | "requestLifecycle">, admission: () => SessionRequestAdmission, attachments?: RuntimeAttachmentStore, runtimeDirectory?: string): SessionClearBoundary;