@undefineds.co/xpod 0.2.45 → 0.3.1

package/dist/api/runs/RunStateCenter.js

@@ -0,0 +1,665 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunStateCenter = void 0;
+const types_1 = require("../chatkit/types");
+const InngestRunExecutionBackend_1 = require("./InngestRunExecutionBackend");
+const types_2 = require("../workspace/types");
+const schema_1 = require("./schema");
+const store_1 = require("./store");
+const RUN_WAITING_STATUSES = new Set([
+    schema_1.RunStatus.WAITING_INPUT,
+    schema_1.RunStatus.WAITING_RUNNER,
+]);
+/**
+ * Run is the xpod-side state center for Agent execution.
+ *
+ * ChatKit and Task APIs are command surfaces. They hand execution to this
+ * center, which persists first-class Run/RunStep facts through the configured
+ * RunStore while projecting visible output back to Thread/Message.
+ */
+class RunStateCenter {
+    constructor(options) {
+        this.store = options.store;
+        this.runStore = this.resolveRunStore(options.store);
+        this.enableAgentRuntime = options.enableAgentRuntime ?? false;
+        this.executionBackend = options.executionBackend ?? new InngestRunExecutionBackend_1.InngestRunExecutionBackend();
+    }
+    getAgentRuntimeConfig(thread, context) {
+        if (!this.enableAgentRuntime) {
+            return null;
+        }
+        const runtime = thread.metadata?.runtime;
+        if (!runtime) {
+            return null;
+        }
+        if (!runtime.runner) {
+            throw new Error('Invalid thread.metadata.runtime: runner is required');
+        }
+        const runnerType = runtime.runner.type;
+        if (!runnerType) {
+            throw new Error('Invalid thread.metadata.runtime.runner.type');
+        }
+        const protocol = this.resolveRunnerProtocol(runtime.runner.protocol);
+        const allowCustomArgv = runtime.runner.allowCustomArgv === true;
+        const argv = allowCustomArgv ? runtime.runner.argv : undefined;
+        const workspace = this.resolveWorkspaceUri(runtime.workspace, thread.workspace);
+        if (!workspace) {
+            throw new Error('Invalid thread runtime: workspace URI is required');
+        }
+        return {
+            ...runtime,
+            workspace,
+            runner: {
+                ...runtime.runner,
+                argv,
+                protocol,
+            },
+            agentConfig: runtime.agentConfig,
+        };
+    }
+    getDefaultAgentRuntimeConfig(context) {
+        if (!this.enableAgentRuntime) {
+            return null;
+        }
+        return null;
+    }
+    resolveRunnerProtocol(protocol) {
+        if (protocol === 'acp' || protocol === 'pi') {
+            return protocol;
+        }
+        return 'pi';
+    }
+    resolveWorkspaceUri(runtimeWorkspace, threadWorkspace) {
+        if ((0, types_2.isWorkspaceUri)(runtimeWorkspace)) {
+            return runtimeWorkspace;
+        }
+        return (0, types_2.isWorkspaceUri)(threadWorkspace) ? threadWorkspace : undefined;
+    }
+    async *startAgentRun(input) {
+        const { thread, userMessage, context, runtimeConfig } = input;
+        const prompt = (0, types_1.extractUserMessageText)(userMessage.content);
+        if (!prompt.trim()) {
+            return;
+        }
+        const threadRef = this.threadRefFromThread(thread);
+        const assistantItem = await this.createAssistantMessage(thread, context);
+        const run = await this.createRun({
+            thread,
+            userMessage,
+            prompt,
+            runtimeConfig,
+            context,
+        });
+        await this.store.addThreadItem(threadRef, assistantItem, context);
+        yield { type: 'item_added', item: assistantItem };
+        await this.markRunStarted(run, context);
+        const assistantState = { item: assistantItem, fullText: '' };
+        let runtimeError;
+        for await (const event of this.executionBackend.start({
+            runId: run.id,
+            threadId: thread.id,
+            prompt,
+            conversation: await this.loadConversation(threadRef, userMessage.id, context),
+            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;
+        }
+        const finalStatus = runtimeError ? 'incomplete' : 'completed';
+        const finalItem = this.finalizeAssistantMessage(assistantState.item, assistantState.fullText, finalStatus);
+        await this.store.saveItem(threadRef, finalItem, context);
+        await this.finishRun(run, runtimeError ? schema_1.RunStatus.FAILED : schema_1.RunStatus.COMPLETED, context, runtimeError);
+        yield { type: 'item_done', item: finalItem };
+    }
+    async *completeClientToolOutput(input) {
+        const { threadRef, itemId, output, context } = input;
+        const item = await this.store.loadItem(threadRef, itemId, context);
+        if (item.type !== 'client_tool_call') {
+            return;
+        }
+        const updatedItem = {
+            ...item,
+            output,
+            status: 'completed',
+        };
+        await this.store.saveItem(threadRef, updatedItem, context);
+        yield { type: 'item_done', item: updatedItem };
+        const run = await this.resolveWaitingRunForToolOutput(updatedItem, threadRef, context);
+        if (!run) {
+            return;
+        }
+        const now = (0, types_1.nowTimestamp)();
+        await this.appendRunStep(run, schema_1.XpodRunStepType.CLIENT_TOOL_OUTPUT, context, {
+            message: updatedItem.name,
+            data: {
+                itemId: updatedItem.id,
+                callId: updatedItem.call_id,
+                output,
+            },
+        });
+        await this.appendRunStep(run, schema_1.XpodRunStepType.CONTINUE_REQUESTED, context, {
+            message: 'Run continuation requested',
+            data: {
+                kind: 'client_tool_output',
+                itemId: updatedItem.id,
+            },
+        });
+        run.status = schema_1.RunStatus.QUEUED;
+        run.leaseOwner = undefined;
+        run.leaseExpiresAt = undefined;
+        run.completedAt = undefined;
+        run.error = undefined;
+        run.updatedAt = now;
+        run.metadata = {
+            ...(run.metadata ?? {}),
+            continuation: {
+                kind: 'client_tool_output',
+                itemId: updatedItem.id,
+                output,
+                queuedAt: now,
+            },
+        };
+        await this.saveRun(run, context);
+        const thread = await this.store.loadThread(threadRef, context);
+        const assistantItemId = typeof run.metadata?.assistantItemId === 'string' ? run.metadata.assistantItemId : undefined;
+        const assistantItem = assistantItemId
+            ? await this.store.loadItem(threadRef, assistantItemId, context)
+            : await this.createAssistantMessage(thread, context);
+        if (!assistantItemId) {
+            await this.store.addThreadItem(threadRef, assistantItem, context);
+            yield { type: 'item_added', item: assistantItem };
+        }
+        const assistantState = {
+            item: assistantItem,
+            fullText: (0, types_1.extractAssistantMessageText)(assistantItem.content),
+        };
+        await this.markRunStarted(run, context);
+        for await (const event of this.executionBackend.start({
+            runId: run.id,
+            threadId: this.extractThreadIdFromRef(threadRef),
+            prompt: this.buildContinuationPrompt(updatedItem),
+            conversation: await this.loadConversation(threadRef, String(run.metadata?.userMessageId ?? updatedItem.id), context),
+            config: this.resolveRuntimeConfigForContinuation(run),
+            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' };
+                return;
+            }
+            const result = yield* this.projectRuntimeEvent(event, {
+                run,
+                thread,
+                threadRef,
+                assistant: assistantState,
+                context,
+            });
+            if (result.action === 'continue') {
+                continue;
+            }
+            if (result.action === 'return') {
+                return;
+            }
+            const finalItem = this.finalizeAssistantMessage(assistantState.item, assistantState.fullText, 'incomplete');
+            await this.store.saveItem(threadRef, finalItem, context);
+            await this.finishRun(run, schema_1.RunStatus.FAILED, context, result.message);
+            yield { type: 'item_done', item: finalItem };
+            return;
+        }
+        const finalItem = this.finalizeAssistantMessage(assistantState.item, assistantState.fullText, 'completed');
+        await this.store.saveItem(threadRef, finalItem, context);
+        await this.finishRun(run, schema_1.RunStatus.COMPLETED, context);
+        yield { type: 'item_done', item: finalItem };
+    }
+    resolveRunStore(store) {
+        if (typeof store.saveRun === 'function'
+            && typeof store.loadRun === 'function'
+            && typeof store.listRuns === 'function'
+            && typeof store.appendRunStep === 'function'
+            && typeof store.loadRunSteps === 'function') {
+            return store;
+        }
+        return undefined;
+    }
+    async createRun(input) {
+        const { thread, userMessage, prompt, runtimeConfig, context } = input;
+        const now = (0, types_1.nowTimestamp)();
+        const commandKind = thread.metadata?.commandKind === 'task' ? 'task' : 'chat';
+        const surfaceId = this.resolveSurfaceId(thread);
+        const run = {
+            id: (0, store_1.generateRunResourceId)({
+                key: (0, types_1.generateId)('run'),
+                commandKind,
+                surfaceId,
+                createdAt: now,
+            }),
+            thread: this.resolveThreadUri(thread, context),
+            workspace: runtimeConfig.workspace,
+            commandKind,
+            surfaceId,
+            status: schema_1.RunStatus.QUEUED,
+            runner: `${runtimeConfig.runner.protocol ?? 'pi'}:${runtimeConfig.runner.type}`,
+            prompt,
+            metadata: {
+                threadId: thread.id,
+                userMessageId: userMessage.id,
+                runtimeConfig,
+                surfaceId,
+            },
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.saveRun(run, context);
+        await this.appendRunStep(run, schema_1.XpodRunStepType.CREATED, context, {
+            message: 'Run created',
+            data: {
+                commandKind: run.commandKind,
+                thread: run.thread,
+                workspace: run.workspace,
+                runner: run.runner,
+            },
+        });
+        return run;
+    }
+    async markRunStarted(run, context) {
+        const now = (0, types_1.nowTimestamp)();
+        run.status = schema_1.RunStatus.RUNNING;
+        run.startedAt = now;
+        run.updatedAt = now;
+        await this.saveRun(run, context);
+        await this.appendRunStep(run, schema_1.XpodRunStepType.STARTED, context, {
+            message: 'Run started',
+        });
+    }
+    async finishRun(run, status, context, error) {
+        const now = (0, types_1.nowTimestamp)();
+        run.status = status;
+        run.completedAt = now;
+        run.updatedAt = now;
+        run.error = error;
+        await this.saveRun(run, context);
+        await this.appendRunStep(run, this.stepTypeForTerminalStatus(status), context, {
+            message: error ?? `Run ${status}`,
+            data: { status },
+        });
+    }
+    async pauseRun(run, status, context, message) {
+        const now = (0, types_1.nowTimestamp)();
+        run.status = status;
+        run.completedAt = undefined;
+        run.heartbeatAt = now;
+        run.leaseOwner = undefined;
+        run.leaseExpiresAt = undefined;
+        run.updatedAt = now;
+        run.error = message;
+        await this.saveRun(run, context);
+    }
+    async *projectRuntimeEvent(event, input) {
+        const { run, thread, threadRef, assistant, context } = input;
+        if (event.type === 'text') {
+            assistant.fullText += event.text;
+            await this.appendRunStep(run, schema_1.XpodRunStepType.TEXT_DELTA, context, {
+                message: event.text,
+                data: { delta: event.text },
+            });
+            yield { type: 'item_updated', itemId: assistant.item.id, delta: event.text };
+            return { action: 'continue' };
+        }
+        if (event.type === 'auth_required') {
+            await this.appendRunStep(run, schema_1.XpodRunStepType.AUTH_REQUIRED, context, {
+                message: event.message,
+                data: {
+                    method: event.method,
+                    url: event.url,
+                    options: event.options,
+                },
+            });
+            yield {
+                type: 'client_effect',
+                effect: {
+                    effect_type: 'runtime.auth_required',
+                    data: {
+                        method: event.method,
+                        url: event.url,
+                        message: event.message,
+                        options: event.options,
+                    },
+                },
+            };
+            return { action: 'continue' };
+        }
+        if (event.type === 'tool_call') {
+            await this.appendRunStep(run, schema_1.XpodRunStepType.TOOL_CALL, context, {
+                message: event.name,
+                data: {
+                    requestId: event.requestId,
+                    name: event.name,
+                    arguments: event.arguments,
+                },
+            });
+            const toolItem = {
+                id: this.store.generateItemId('client_tool_call', thread, context),
+                thread_id: thread.id,
+                type: 'client_tool_call',
+                name: event.name,
+                arguments: event.arguments,
+                call_id: event.requestId,
+                status: 'pending',
+                metadata: {
+                    runId: run.id,
+                    assistantItemId: assistant.item.id,
+                },
+                created_at: (0, types_1.nowTimestamp)(),
+            };
+            await this.store.addThreadItem(threadRef, toolItem, context);
+            yield { type: 'item_added', item: toolItem };
+            const incomplete = this.finalizeAssistantMessage(assistant.item, assistant.fullText, 'incomplete');
+            assistant.item = incomplete;
+            await this.store.saveItem(threadRef, incomplete, context);
+            yield { type: 'item_done', item: incomplete };
+            run.metadata = {
+                ...(run.metadata ?? {}),
+                assistantItemId: assistant.item.id,
+                waitingTool: {
+                    itemId: toolItem.id,
+                    requestId: event.requestId,
+                    name: event.name,
+                },
+            };
+            await this.pauseRun(run, schema_1.RunStatus.WAITING_INPUT, context, `Waiting for client tool output: ${event.name}`);
+            yield {
+                type: 'error',
+                code: 'runtime_waiting_input',
+                message: `Run is waiting for client tool output: ${event.name}`,
+            };
+            return { action: 'return' };
+        }
+        if (event.type === 'waiting_runner') {
+            await this.appendRunStep(run, schema_1.XpodRunStepType.WAITING_RUNNER, context, {
+                message: event.message,
+                data: {
+                    workspace: event.workspace,
+                },
+            });
+            yield { type: 'error', code: 'waiting_runner', message: event.message };
+            await this.finishRun(run, schema_1.RunStatus.WAITING_RUNNER, context, event.message);
+            return { action: 'return' };
+        }
+        await this.appendRunStep(run, schema_1.XpodRunStepType.ERROR, context, {
+            message: event.message,
+        });
+        yield { type: 'error', code: 'runtime_error', message: event.message };
+        return { action: 'error', message: event.message };
+    }
+    async checkCancellation(run, threadRef, assistant, context) {
+        if (!this.runStore?.loadRun) {
+            return undefined;
+        }
+        const latest = await this.runStore.loadRun(run.id, context);
+        if (!latest.cancelRequestedAt) {
+            return undefined;
+        }
+        run.cancelRequestedAt = latest.cancelRequestedAt;
+        const finalItem = this.finalizeAssistantMessage(assistant.item, assistant.fullText, 'incomplete');
+        assistant.item = finalItem;
+        await this.store.saveItem(threadRef, finalItem, context);
+        await this.finishRun(run, schema_1.RunStatus.CANCELLED, context, 'Run cancellation requested');
+        return finalItem;
+    }
+    stepTypeForTerminalStatus(status) {
+        if (status === schema_1.RunStatus.COMPLETED) {
+            return schema_1.XpodRunStepType.COMPLETED;
+        }
+        if (status === schema_1.RunStatus.CANCELLED) {
+            return schema_1.XpodRunStepType.CANCELLED;
+        }
+        if (RUN_WAITING_STATUSES.has(status)) {
+            return status === schema_1.RunStatus.WAITING_RUNNER ? schema_1.XpodRunStepType.WAITING_RUNNER : schema_1.XpodRunStepType.WAITING_INPUT;
+        }
+        return schema_1.XpodRunStepType.FAILED;
+    }
+    async saveRun(run, context) {
+        await this.runStore?.saveRun(run, context);
+    }
+    async appendRunStep(run, type, context, options = {}) {
+        const createdAt = (0, types_1.nowTimestamp)();
+        await this.runStore?.appendRunStep({
+            id: (0, store_1.generateRunStepResourceId)({
+                key: (0, types_1.generateId)('run-step'),
+                runId: run.id,
+                commandKind: run.commandKind,
+                surfaceId: run.surfaceId,
+                createdAt,
+            }),
+            commandKind: run.commandKind,
+            surfaceId: run.surfaceId,
+            runId: run.id,
+            run: this.resolveRunUri(run, context),
+            type,
+            message: options.message,
+            data: options.data,
+            createdAt,
+        }, context);
+    }
+    resolveThreadUri(thread, context) {
+        const threadId = thread.id;
+        if (/^https?:\/\//.test(threadId)) {
+            return threadId;
+        }
+        const commandKind = thread.metadata?.commandKind === 'task' ? 'task' : 'chat';
+        const surfaceId = this.resolveSurfaceId(thread);
+        const podBaseUrl = this.resolvePodBaseUrl(context);
+        if (podBaseUrl) {
+            if (threadId.includes('#') && !threadId.startsWith('#')) {
+                return (0, store_1.resolveDataResourceIri)(podBaseUrl, threadId);
+            }
+            return `${podBaseUrl}/.data/${commandKind}/${surfaceId}/index.ttl#${threadId}`;
+        }
+        return `urn:xpod:thread:${commandKind}:${encodeURIComponent(surfaceId)}:${encodeURIComponent(threadId)}`;
+    }
+    resolveRunUri(run, context) {
+        const podBaseUrl = this.resolvePodBaseUrl(context);
+        if (podBaseUrl) {
+            return (0, store_1.resolveDataResourceIri)(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) {
+            const run = await this.runStore.loadRun(metadataRunId, context);
+            if (run.status === schema_1.RunStatus.WAITING_INPUT) {
+                return run;
+            }
+        }
+        if (!this.runStore?.listRuns) {
+            return undefined;
+        }
+        const threadCandidates = this.threadCandidatesForRunLookup(threadRef, context);
+        for (const thread of threadCandidates) {
+            const candidates = await this.runStore.listRuns({
+                thread,
+                status: schema_1.RunStatus.WAITING_INPUT,
+                limit: 10,
+            }, context);
+            const match = candidates.find((run) => {
+                const tool = run.metadata?.waitingTool;
+                return !tool || typeof tool !== 'object' || tool.itemId === item.id;
+            }) ?? candidates[0];
+            if (match) {
+                return match;
+            }
+        }
+        return undefined;
+    }
+    extractThreadIdFromRef(threadRef) {
+        if ('chat_id' in threadRef) {
+            return threadRef.thread_id;
+        }
+        return threadRef.thread_id;
+    }
+    threadCandidatesForRunLookup(threadRef, context) {
+        const candidates = [];
+        const add = (value) => {
+            if (value && !candidates.includes(value)) {
+                candidates.push(value);
+            }
+        };
+        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.resolveDataResourceIri)(podBaseUrl, relative));
+        }
+        return candidates;
+    }
+    extractBaseRelativeThreadId(threadId) {
+        if (/^(chat|task)\/[^/]+\/index\.ttl#[^#]+$/.test(threadId)) {
+            return threadId;
+        }
+        if (!/^https?:\/\//.test(threadId)) {
+            return undefined;
+        }
+        try {
+            const url = new URL(threadId);
+            const marker = '/.data/';
+            const index = url.pathname.indexOf(marker);
+            if (index >= 0 && url.hash) {
+                return `${url.pathname.slice(index + marker.length)}${url.hash}`;
+            }
+        }
+        catch {
+            return undefined;
+        }
+        return undefined;
+    }
+    buildContinuationPrompt(item) {
+        return `Continue the previous run after client tool output.\n\nTool: ${item.name}\nOutput:\n${item.output ?? ''}`;
+    }
+    resolveRuntimeConfigForContinuation(run) {
+        const runtimeConfig = run.metadata?.runtimeConfig;
+        if (runtimeConfig && typeof runtimeConfig === 'object') {
+            return runtimeConfig;
+        }
+        if (!(0, types_2.isWorkspaceUri)(run.workspace)) {
+            throw new Error('Run workspace URI is required');
+        }
+        const [protocol, type] = run.runner.split(':');
+        return {
+            workspace: run.workspace,
+            runner: {
+                protocol: protocol === 'acp' ? 'acp' : 'pi',
+                type: this.isRunnerType(type) ? type : 'pi',
+            },
+        };
+    }
+    isRunnerType(value) {
+        return value === 'pi' || value === 'codex' || value === 'claude' || value === 'codebuddy';
+    }
+    resolveSurfaceId(thread) {
+        if (typeof thread.metadata?.surface_id === 'string') {
+            return thread.metadata.surface_id;
+        }
+        if (typeof thread.metadata?.chat_id === 'string') {
+            return thread.metadata.chat_id;
+        }
+        return types_1.DEFAULT_THREAD_CHAT_ID;
+    }
+    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),
+            thread_id: thread.id,
+            type: 'assistant_message',
+            content: [{ type: 'output_text', text: '' }],
+            status: 'in_progress',
+            created_at: (0, types_1.nowTimestamp)(),
+        };
+    }
+    finalizeAssistantMessage(item, text, status) {
+        return {
+            ...item,
+            content: [{ type: 'output_text', text }],
+            status,
+        };
+    }
+    threadRefFromThread(thread) {
+        return (0, types_1.toThreadRef)({
+            thread_id: thread.id,
+            chat_id: typeof thread.metadata?.chat_id === 'string' ? thread.metadata.chat_id : types_1.DEFAULT_THREAD_CHAT_ID,
+        });
+    }
+    async loadConversation(threadRef, currentUserMessageId, context) {
+        const items = await this.store.loadThreadItems(threadRef, undefined, 1000, 'asc', context);
+        const conversation = [];
+        for (const item of items.data) {
+            if (item.id === currentUserMessageId) {
+                break;
+            }
+            if (item.type === 'user_message') {
+                const text = (0, types_1.extractUserMessageText)(item.content).trim();
+                if (text) {
+                    conversation.push({ role: 'user', text, createdAt: item.created_at });
+                }
+                continue;
+            }
+            if (item.type === 'assistant_message' && item.status !== 'in_progress') {
+                const text = (0, types_1.extractAssistantMessageText)(item.content).trim();
+                if (text) {
+                    conversation.push({ role: 'assistant', text, createdAt: item.created_at });
+                }
+            }
+        }
+        return conversation;
+    }
+}
+exports.RunStateCenter = RunStateCenter;
+//# sourceMappingURL=RunStateCenter.js.map