@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/api/runs/RunApproval.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.persistRunApproval = persistRunApproval;
+exports.updateRunApprovalSession = updateRunApprovalSession;
+const node_crypto_1 = require("node:crypto");
+const models_1 = require("@undefineds.co/models");
+/** Persist the human-authority request only after its client-tool checkpoint exists. */
+async function persistRunApproval(input) {
+    const { store, run, event, context } = input;
+    if (!event.approval)
+        return undefined;
+    if (event.name !== 'request_approval' || !store.writeTaskApproval || !store.saveRunApprovalSession) {
+        throw new Error('Durable approval storage is unavailable');
+    }
+    const owner = approvalOwner(context);
+    const now = new Date();
+    const key = `approval_${(0, node_crypto_1.createHash)('sha256').update(`${run.id}\0${event.requestId}`).digest('hex').slice(0, 32)}`;
+    run.metadata = { ...run.metadata, approvalSessionKey: `run_${(0, node_crypto_1.createHash)('sha256').update(run.id).digest('hex').slice(0, 32)}` };
+    const session = await updateRunApprovalSession(store, run, 'paused', context);
+    const id = models_1.approvalResource.buildId({ id: key, createdAt: now });
+    return store.writeTaskApproval({
+        id, session: session, thread: run.thread, toolCallId: event.requestId, toolName: event.name,
+        target: event.approval.target, action: event.approval.action, risk: event.approval.risk,
+        context: event.approval.description, assignedTo: owner, status: 'pending',
+        createdAt: now, expiresAt: new Date(now.getTime() + 24 * 60 * 60 * 1000),
+    }, context);
+}
+async function updateRunApprovalSession(store, run, status, context) {
+    const key = run.metadata?.approvalSessionKey;
+    if (typeof key !== 'string')
+        return undefined;
+    if (!store.saveRunApprovalSession)
+        throw new Error('Durable approval session storage is unavailable');
+    const owner = approvalOwner(context);
+    const createdAt = new Date(run.createdAt * 1000);
+    const id = models_1.sessionResource.buildId({ id: key, createdAt });
+    return store.saveRunApprovalSession({ id, owner, thread: run.thread, tool: 'pi', status, createdAt, updatedAt: new Date() }, context);
+}
+function approvalOwner(context) {
+    const auth = context.auth;
+    if (typeof auth?.webId !== 'string' || !/^https?:\/\//.test(auth.webId))
+        throw new Error('Approval requires an authenticated Pod owner');
+    return auth.webId;
+}
+//# sourceMappingURL=RunApproval.js.map

package/dist/api/runs/RunCancellation.d.ts

@@ -0,0 +1,20 @@
+import { type RunRecordData, type RunStore } from './store';
+import { type RunApprovalStore } from './RunApproval';
+/** Keep a silent provider/tool execution connected to the durable Stop request. */
+export declare function monitorRunCancellation<TContext>(input: {
+    store: Pick<RunStore<TContext>, 'loadRun'>;
+    runId: string;
+    context: TContext;
+}): Promise<{
+    signal: AbortSignal;
+    readonly error: unknown;
+    readonly cancelRequestedAt: number | undefined;
+    dispose(): void;
+}>;
+/** Waiting runs have no claimant; cancelling them must reach a terminal state here. */
+export declare function cancelRun<TContext>(input: {
+    store: RunStore<TContext> & RunApprovalStore<TContext>;
+    runId: string;
+    context: TContext;
+    resourceIri: (run: RunRecordData) => string;
+}): Promise<RunRecordData>;

package/dist/api/runs/RunCancellation.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.monitorRunCancellation = monitorRunCancellation;
+exports.cancelRun = cancelRun;
+const types_1 = require("../chatkit/types");
+const store_1 = require("./store");
+const RunApproval_1 = require("./RunApproval");
+/** Keep a silent provider/tool execution connected to the durable Stop request. */
+async function monitorRunCancellation(input) {
+    const controller = new AbortController();
+    let error;
+    let cancelRequestedAt;
+    let stopped = false;
+    let checking = false;
+    const check = async () => {
+        if (stopped || checking || controller.signal.aborted)
+            return;
+        checking = true;
+        try {
+            const latest = await input.store.loadRun(input.runId, input.context);
+            if (!stopped && latest.cancelRequestedAt) {
+                cancelRequestedAt = latest.cancelRequestedAt;
+                controller.abort();
+            }
+        }
+        catch (cause) {
+            if (!stopped) {
+                error = cause;
+                controller.abort(cause);
+            }
+        }
+        finally {
+            checking = false;
+        }
+    };
+    await check();
+    const timer = controller.signal.aborted ? undefined : setInterval(() => { void check(); }, 500);
+    return {
+        signal: controller.signal,
+        get error() { return error; },
+        get cancelRequestedAt() { return cancelRequestedAt; },
+        dispose() {
+            stopped = true;
+            if (timer !== undefined)
+                clearInterval(timer);
+            controller.abort();
+        },
+    };
+}
+/** Waiting runs have no claimant; cancelling them must reach a terminal state here. */
+async function cancelRun(input) {
+    const { store, runId, context } = input;
+    const run = await store.loadRun(runId, context);
+    if (!['queued', 'running', 'waiting_input', 'waiting_runner'].includes(run.status)) {
+        if (run.status === 'cancelled')
+            await (0, RunApproval_1.updateRunApprovalSession)(store, run, 'completed', context);
+        return run;
+    }
+    const now = (0, types_1.nowTimestamp)();
+    const firstRequest = !run.cancelRequestedAt;
+    const terminal = run.status !== 'running';
+    run.cancelRequestedAt ??= now;
+    run.updatedAt = now;
+    if (terminal) {
+        run.status = 'cancelled';
+        run.completedAt = now;
+        run.leaseOwner = undefined;
+        run.leaseExpiresAt = undefined;
+    }
+    await store.saveRun(run, context);
+    const append = async (type, message) => store.appendRunStep({
+        id: (0, store_1.generateRunStepResourceId)({ key: (0, types_1.generateId)('run-step'), runId, createdAt: now }),
+        runId, run: input.resourceIri(run), type, message, data: { status: run.status }, createdAt: now,
+    }, context);
+    if (firstRequest)
+        await append('run.cancel_requested', 'Run cancellation requested');
+    if (terminal)
+        await append('run.cancelled', 'Run cancelled while waiting for execution or input');
+    if (terminal)
+        await (0, RunApproval_1.updateRunApprovalSession)(store, run, 'completed', context);
+    return run;
+}
+//# sourceMappingURL=RunCancellation.js.map

package/dist/api/runs/RunExecutionBackend.d.ts

@@ -41,6 +41,8 @@ export interface RunContextRetriever<TContext = StoreContext> {
     retrieve(input: RunContextRetrievalInput<TContext>): Promise<RunRetrievedContext | undefined>;
 }
 export interface RunExecutionInput {
+    /** In-process cancellation only; never serialized into durable queue events. */
+    signal?: AbortSignal;
     runId: string;
     threadId: string;
     prompt: string;

package/dist/api/runs/RunStateCenter.d.ts

@@ -79,8 +79,6 @@ export declare class RunStateCenter<TContext = StoreContext> {
     private stepTypeForTerminalStatus;
     private saveRun;
     private appendRunStep;
-    private resolveThreadResource;
-    private resolveRunResource;
     private resolveWaitingRunForToolOutput;
     private extractThreadIdFromRef;
     private threadCandidatesForRunLookup;
@@ -89,7 +87,6 @@ export declare class RunStateCenter<TContext = StoreContext> {
     private resolveRuntimeConfigForContinuation;
     private isRunnerType;
     private resolveThreadStorageParent;
-    private resolvePodBaseUrl;
     private createAssistantMessage;
     private finalizeAssistantMessage;
     private threadRefFromThread;

package/dist/api/runs/RunStateCenter.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RunStateCenter = void 0;
+const RunCancellation_1 = require("./RunCancellation");
+const RunApproval_1 = require("./RunApproval");
 const types_1 = require("../chatkit/types");
 const AgentRuntimeTypes_1 = require("./AgentRuntimeTypes");
 const InngestRunExecutionBackend_1 = require("./InngestRunExecutionBackend");
@@ -104,36 +106,57 @@ class RunStateCenter {
             config: runtimeConfig,
             context,
         });
-        for await (const event of this.executionBackend.start({
-            runId: run.id,
-            threadId: thread.id,
-            prompt,
-            conversation,
-            retrievedContext,
-            config: runtimeConfig,
-            context: context,
-        })) {
-            const cancellation = await this.checkCancellation(run, threadRef, assistantState, context);
-            if (cancellation) {
-                yield { type: 'item_done', item: cancellation };
-                yield { type: 'error', code: 'runtime_cancelled', message: 'Run cancellation requested' };
-                return;
-            }
-            const result = yield* this.projectRuntimeEvent(event, {
-                run,
-                thread,
-                threadRef,
-                assistant: assistantState,
-                context,
-            });
-            if (result.action === 'continue') {
-                continue;
-            }
-            if (result.action === 'return') {
-                return;
+        const monitor = this.runStore ? await (0, RunCancellation_1.monitorRunCancellation)({ store: this.runStore, runId: run.id, context }) : undefined;
+        try {
+            for await (const event of this.executionBackend.start({
+                signal: monitor?.signal,
+                runId: run.id,
+                threadId: thread.id,
+                prompt,
+                conversation,
+                retrievedContext,
+                config: runtimeConfig,
+                context: context,
+            })) {
+                const cancellation = await this.checkCancellation(run, threadRef, assistantState, context);
+                if (cancellation) {
+                    yield { type: 'item_done', item: cancellation };
+                    yield { type: 'error', code: 'runtime_cancelled', message: 'Run cancellation requested' };
+                    return;
+                }
+                const result = yield* this.projectRuntimeEvent(event, {
+                    run,
+                    thread,
+                    threadRef,
+                    assistant: assistantState,
+                    context,
+                });
+                if (result.action === 'continue') {
+                    continue;
+                }
+                if (result.action === 'return') {
+                    return;
+                }
+                runtimeError = result.message;
+                break;
             }
-            runtimeError = result.message;
-            break;
+        }
+        catch (error) {
+            const cancelled = await this.checkCancellation(run, threadRef, assistantState, context);
+            if (!cancelled)
+                throw error;
+            yield { type: 'item_done', item: cancelled };
+            return;
+        }
+        finally {
+            monitor?.dispose();
+        }
+        if (monitor?.error)
+            throw monitor.error;
+        const cancellation = await this.checkCancellation(run, threadRef, assistantState, context);
+        if (cancellation) {
+            yield { type: 'item_done', item: cancellation };
+            return;
         }
         const finalStatus = runtimeError ? 'incomplete' : 'completed';
         const finalItem = this.finalizeAssistantMessage(assistantState.item, assistantState.fullText, finalStatus);
@@ -243,7 +266,7 @@ class RunStateCenter {
         };
         await this.markRunStarted(run, context);
         const continuationPrompt = this.buildContinuationPrompt(updatedItem);
-        const conversation = await this.loadConversation(threadRef, String(run.metadata?.userMessageId ?? updatedItem.id), context);
+        const conversation = await this.loadConversation(threadRef, undefined, context);
         const runtimeConfig = this.resolveRuntimeConfigForContinuation(run, context);
         const retrievedContext = await this.retrieveRunContext({
             runId: run.id,
@@ -253,39 +276,66 @@ class RunStateCenter {
             config: runtimeConfig,
             context,
         });
-        for await (const event of this.executionBackend.start({
-            runId: run.id,
-            threadId: this.extractThreadIdFromRef(threadRef),
-            prompt: continuationPrompt,
-            conversation,
-            retrievedContext,
-            config: runtimeConfig,
-            continuation: {
-                kind: 'client_tool_output',
-                itemId: updatedItem.id,
-            },
-            context: context,
-        })) {
-            const cancellation = await this.checkCancellation(run, threadRef, assistantState, context);
-            if (cancellation) {
-                yield { type: 'item_done', item: cancellation };
-                yield { type: 'error', code: 'runtime_cancelled', message: 'Run cancellation requested' };
+        const monitor = this.runStore ? await (0, RunCancellation_1.monitorRunCancellation)({ store: this.runStore, runId: run.id, context }) : undefined;
+        try {
+            const initialCancellation = await this.checkCancellation(run, threadRef, assistantState, context);
+            if (initialCancellation) {
+                yield { type: 'item_done', item: initialCancellation };
                 return;
             }
-            const result = yield* this.projectRuntimeEvent(event, {
-                run,
-                thread,
-                threadRef,
-                assistant: assistantState,
-                context,
-            });
-            if (result.action === 'continue') {
-                continue;
-            }
-            if (result.action === 'return') {
-                return;
+            for await (const event of this.executionBackend.start({
+                signal: monitor?.signal,
+                runId: run.id,
+                threadId: this.extractThreadIdFromRef(threadRef),
+                prompt: continuationPrompt,
+                conversation,
+                retrievedContext,
+                config: runtimeConfig,
+                continuation: {
+                    kind: 'client_tool_output',
+                    itemId: updatedItem.id,
+                },
+                authBindingId: (0, store_1.resolveRunAuthBindingId)(run),
+                context: context,
+            })) {
+                const cancellation = await this.checkCancellation(run, threadRef, assistantState, context);
+                if (cancellation) {
+                    yield { type: 'item_done', item: cancellation };
+                    yield { type: 'error', code: 'runtime_cancelled', message: 'Run cancellation requested' };
+                    return;
+                }
+                const result = yield* this.projectRuntimeEvent(event, {
+                    run,
+                    thread,
+                    threadRef,
+                    assistant: assistantState,
+                    context,
+                });
+                if (result.action === 'continue') {
+                    continue;
+                }
+                if (result.action === 'return') {
+                    return;
+                }
+                throw new Error(result.message);
             }
-            throw new Error(result.message);
+        }
+        catch (error) {
+            const cancelled = await this.checkCancellation(run, threadRef, assistantState, context);
+            if (!cancelled)
+                throw error;
+            yield { type: 'item_done', item: cancelled };
+            return;
+        }
+        finally {
+            monitor?.dispose();
+        }
+        if (monitor?.error)
+            throw monitor.error;
+        const cancellation = await this.checkCancellation(run, threadRef, assistantState, context);
+        if (cancellation) {
+            yield { type: 'item_done', item: cancellation };
+            return;
         }
         const finalItem = this.finalizeAssistantMessage(assistantState.item, assistantState.fullText, 'completed');
         await this.store.saveItem(threadRef, finalItem, context);
@@ -313,7 +363,7 @@ class RunStateCenter {
                 parentKey: parent.parentKey,
                 createdAt: now,
             }),
-            thread: this.resolveThreadResource(thread, context),
+            thread: thread.id,
             workspace: runtimeConfig.workspace,
             status: schema_1.RunStatus.QUEUED,
             runner: `${runtimeConfig.runner.protocol ?? 'pi'}:${runtimeConfig.runner.type}`,
@@ -343,6 +393,9 @@ class RunStateCenter {
         run.startedAt = now;
         run.updatedAt = now;
         await this.saveRun(run, context);
+        await (0, RunApproval_1.updateRunApprovalSession)(this.store, run, run.status === schema_1.RunStatus.CANCELLED ? 'completed' : 'active', context);
+        if (run.status === schema_1.RunStatus.CANCELLED || run.cancelRequestedAt !== undefined)
+            return;
         await this.appendRunStep(run, schema_1.XpodRunStepType.STARTED, context, {
             message: 'Run started',
         });
@@ -356,6 +409,9 @@ class RunStateCenter {
         run.updatedAt = now;
         run.error = error;
         await this.saveRun(run, context);
+        status = run.status;
+        error = run.error;
+        await (0, RunApproval_1.updateRunApprovalSession)(this.store, run, status === 'waiting_input' || status === 'waiting_runner' ? 'paused' : status === 'failed' ? 'error' : 'completed', context);
         await this.appendRunStep(run, this.stepTypeForTerminalStatus(status), context, {
             message: error ?? `Run ${status}`,
             data: { status },
@@ -371,6 +427,7 @@ class RunStateCenter {
         run.updatedAt = now;
         run.error = message;
         await this.saveRun(run, context);
+        await (0, RunApproval_1.updateRunApprovalSession)(this.store, run, run.status === schema_1.RunStatus.CANCELLED ? 'completed' : 'paused', context);
     }
     async *projectRuntimeEvent(event, input) {
         const { run, thread, threadRef, assistant, context } = input;
@@ -430,6 +487,7 @@ class RunStateCenter {
                 created_at: (0, types_1.nowTimestamp)(),
             };
             await this.store.addThreadItem(threadRef, toolItem, context);
+            await (0, RunApproval_1.persistRunApproval)({ store: this.store, run, event, context });
             yield { type: 'item_added', item: toolItem };
             const incomplete = this.finalizeAssistantMessage(assistant.item, assistant.fullText, 'incomplete');
             assistant.item = incomplete;
@@ -497,7 +555,9 @@ class RunStateCenter {
         return schema_1.XpodRunStepType.FAILED;
     }
     async saveRun(run, context) {
-        await this.runStore?.saveRun((0, AgentRuntimeTypes_1.deepScrubApiKey)(run), context);
+        const persisted = (0, AgentRuntimeTypes_1.deepScrubApiKey)(run);
+        await this.runStore?.saveRun(persisted, context);
+        Object.assign(run, persisted);
     }
     async appendRunStep(run, type, context, options = {}) {
         const createdAt = (0, types_1.nowTimestamp)();
@@ -508,35 +568,13 @@ class RunStateCenter {
                 createdAt,
             }),
             runId: run.id,
-            run: this.resolveRunResource(run, context),
+            run: run.id,
             type,
             message: options.message,
             data: options.data,
             createdAt,
         }, context);
     }
-    resolveThreadResource(thread, context) {
-        const threadId = thread.id;
-        if (/^https?:\/\//.test(threadId)) {
-            return threadId;
-        }
-        const parent = this.resolveThreadStorageParent(thread);
-        const podBaseUrl = this.resolvePodBaseUrl(context);
-        if (podBaseUrl) {
-            if (threadId.includes('#') && !threadId.startsWith('#')) {
-                return (0, store_1.resolveDataResource)(podBaseUrl, threadId);
-            }
-            return `${podBaseUrl}/.data/${parent.parentKind}/${parent.parentKey}/index.ttl#${threadId}`;
-        }
-        return `urn:xpod:thread:${parent.parentKind}:${encodeURIComponent(parent.parentKey)}:${encodeURIComponent(threadId)}`;
-    }
-    resolveRunResource(run, context) {
-        const podBaseUrl = this.resolvePodBaseUrl(context);
-        if (podBaseUrl) {
-            return (0, store_1.resolveDataResource)(podBaseUrl, run.id);
-        }
-        return (0, store_1.resolveRunUrn)(run.id);
-    }
     async resolveWaitingRunForToolOutput(item, threadRef, context) {
         const metadataRunId = item.metadata?.runId;
         if (typeof metadataRunId === 'string' && this.runStore?.loadRun) {
@@ -548,7 +586,7 @@ class RunStateCenter {
         if (!this.runStore?.listRuns) {
             return undefined;
         }
-        const threadCandidates = this.threadCandidatesForRunLookup(threadRef, context);
+        const threadCandidates = await this.threadCandidatesForRunLookup(threadRef, context);
         for (const thread of threadCandidates) {
             const candidates = await this.runStore.listRuns({
                 thread,
@@ -568,7 +606,7 @@ class RunStateCenter {
     extractThreadIdFromRef(threadRef) {
         return threadRef.thread_id;
     }
-    threadCandidatesForRunLookup(threadRef, context) {
+    async threadCandidatesForRunLookup(threadRef, context) {
         const candidates = [];
         const add = (value) => {
             if (value && !candidates.includes(value)) {
@@ -577,12 +615,7 @@ class RunStateCenter {
         };
         const threadId = this.extractThreadIdFromRef(threadRef);
         add(threadId);
-        const relative = this.extractBaseRelativeThreadId(threadId);
-        add(relative);
-        const podBaseUrl = this.resolvePodBaseUrl(context);
-        if (podBaseUrl && relative) {
-            add((0, store_1.resolveDataResource)(podBaseUrl, relative));
-        }
+        add(this.extractBaseRelativeThreadId(threadId));
         return candidates;
     }
     extractBaseRelativeThreadId(threadId) {
@@ -606,6 +639,9 @@ class RunStateCenter {
         return undefined;
     }
     buildContinuationPrompt(item) {
+        if (item.metadata?.approval) {
+            return `Continue this same run from its approval checkpoint. The following is an authorization decision, not a tool result; the requested action has NOT been executed. Carry out only the approved action, preserving prior completed work.\n\nRequested tool: ${item.name}\nArguments: ${item.arguments}\nApproval decision: ${item.output ?? ''}`;
+        }
         return `Continue the previous run after client tool output.\n\nTool: ${item.name}\nOutput:\n${item.output ?? ''}`;
     }
     resolveRuntimeConfigForContinuation(run, context) {
@@ -635,28 +671,6 @@ class RunStateCenter {
             parentKey: parent?.key ?? 'default',
         };
     }
-    resolvePodBaseUrl(context) {
-        const auth = context.auth;
-        const webId = typeof auth?.webId === 'string' ? auth.webId : undefined;
-        if (!webId) {
-            return undefined;
-        }
-        try {
-            const url = new URL(webId);
-            url.hash = '';
-            url.search = '';
-            const normalizedPath = url.pathname.replace(/\/+$/, '');
-            if (!normalizedPath.endsWith('/profile/card')) {
-                return undefined;
-            }
-            const podPath = normalizedPath.slice(0, -'/profile/card'.length) || '/';
-            url.pathname = podPath;
-            return url.toString().replace(/\/$/, '');
-        }
-        catch {
-            return undefined;
-        }
-    }
     async createAssistantMessage(thread, context) {
         return {
             id: this.store.generateItemId('assistant_message', thread, context),
@@ -683,7 +697,7 @@ class RunStateCenter {
         const items = await this.store.loadThreadItems(threadRef, undefined, 1000, 'asc', context);
         const conversation = [];
         for (const item of items.data) {
-            if (item.id === currentUserMessageId) {
+            if (currentUserMessageId !== undefined && item.id === currentUserMessageId) {
                 break;
             }
             if (item.type === 'user_message') {

package/dist/api/runs/RunStateMerge.d.ts

@@ -0,0 +1,4 @@
+import type { RunRecordData } from './store';
+export type PersistedRunState = Pick<RunRecordData, 'status' | 'cancelRequestedAt' | 'completedAt' | 'updatedAt' | 'leaseOwner' | 'leaseExpiresAt'>;
+/** Cancellation is monotonic across independent, stale API/runner writers. */
+export declare function mergeRunCancellation(proposed: RunRecordData, current?: PersistedRunState): RunRecordData;

package/dist/api/runs/RunStateMerge.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeRunCancellation = mergeRunCancellation;
+/** Cancellation is monotonic across independent, stale API/runner writers. */
+function mergeRunCancellation(proposed, current) {
+    const cancelRequestedAt = current?.cancelRequestedAt ?? proposed.cancelRequestedAt;
+    if (cancelRequestedAt === undefined && current?.status !== 'cancelled')
+        return { ...proposed };
+    const cancelled = current?.status === 'cancelled' || proposed.status !== 'running' || current?.status !== 'running';
+    return {
+        ...proposed,
+        cancelRequestedAt,
+        ...(cancelled ? {
+            status: 'cancelled', error: undefined, leaseOwner: undefined, leaseExpiresAt: undefined,
+            completedAt: current?.completedAt ?? proposed.completedAt ?? Math.floor(Date.now() / 1000),
+        } : {}),
+    };
+}
+//# sourceMappingURL=RunStateMerge.js.map

package/dist/api/runs/store.d.ts

@@ -25,6 +25,7 @@ export interface RunRecordData {
     completedAt?: number;
     updatedAt: number;
 }
+export declare function resolveRunAuthBindingId(run: RunRecordData): string | undefined;
 export interface RunStepRecordData {
     /** Base-relative Solid resource id, e.g. `chat/default/2026/05/18/runs.ttl#step_x`. */
     id: string;
@@ -49,6 +50,9 @@ export interface RunCommandProjection {
     surfaceId: string;
 }
 export interface RunStore<TContext> {
+    /** Resolve owned storage before constructing current-Pod relations. */
+    getPodBaseUrl?(context: TContext): Promise<string | undefined>;
+    /** Atomically preserve cancellation and replace the caller's row with the committed state. */
     saveRun(run: RunRecordData, context: TContext): Promise<void>;
     loadRun(id: string, context: TContext): Promise<RunRecordData>;
     listRuns(options: RunListOptions, context: TContext): Promise<RunRecordData[]>;
@@ -63,7 +67,7 @@ export interface RunStore<TContext> {
 }
 export declare function isClaimableRunStatus(status: RunRecordData['status']): boolean;
 export declare function hasActiveRunLease(run: Pick<RunRecordData, 'leaseOwner' | 'leaseExpiresAt'>, now: number): boolean;
-export declare function canClaimRun(run: Pick<RunRecordData, 'status' | 'leaseOwner' | 'leaseExpiresAt'>, input: {
+export declare function canClaimRun(run: Pick<RunRecordData, 'status' | 'leaseOwner' | 'leaseExpiresAt' | 'cancelRequestedAt'>, input: {
     leaseOwner: string;
     now: number;
 }): boolean;
@@ -102,5 +106,7 @@ export declare function buildRunStepResourceId(input: string | {
     runId?: string;
     createdAt?: number;
 }): string;
+/** Internal stores/contexts carry selected storage bindings; identity URLs are never storage. */
+export declare function resolveBoundPodBaseUrl<TContext>(store: Pick<RunStore<TContext>, 'getPodBaseUrl'> | undefined, context: TContext): Promise<string | undefined>;
 export declare function resolveRunUrn(runId: string): string;
 export declare function resolveDataResource(podBaseUrl: string, resourceId: string): string;