@undefineds.co/xpod 0.3.58 → 0.3.61

package/dist/api/runs/RdfRunContextRetriever.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RdfRunContextRetriever = void 0;
+const n3_1 = require("n3");
+const RdfAccessScope_1 = require("../../storage/rdf/RdfAccessScope");
+const { literal } = n3_1.DataFactory;
+/**
+ * Product-level Run context retriever backed by SolidRdfEngine/PostgresRdfEngine.
+ *
+ * The retriever keeps RDF/text/vector lookup outside durable queue events and
+ * returns runtime-neutral snippets that drivers can project into their own
+ * prompt/session format.
+ */
+class RdfRunContextRetriever {
+    constructor(options) {
+        this.options = options;
+    }
+    async retrieve(input) {
+        const prompt = input.prompt.trim();
+        if (!prompt) {
+            return undefined;
+        }
+        try {
+            const embedding = await this.options.embedding?.(input);
+            const query = this.options.buildQuery
+                ? await this.options.buildQuery(input, embedding)
+                : this.buildDefaultQuery(input, embedding);
+            const result = await this.options.rdfEngine.query(this.withAccessScope(query, input));
+            const items = result.bindings
+                .map((row) => this.bindingToContextItem(row))
+                .filter((item) => item !== undefined)
+                .slice(0, this.options.limit ?? 8);
+            if (items.length === 0) {
+                return undefined;
+            }
+            return {
+                query: prompt,
+                items,
+                generatedAt: Math.floor(Date.now() / 1000),
+                plan: result.metrics.plan,
+            };
+        }
+        catch (error) {
+            if (this.options.failOpen === true) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    buildDefaultQuery(input, embedding) {
+        const limit = this.options.limit ?? 8;
+        const scope = this.searchScope(input);
+        const cacheScope = this.cacheScope(input);
+        const normalizedEmbedding = normalizeEmbedding(embedding);
+        const hasVector = (normalizedEmbedding?.embedding.length ?? 0) > 0;
+        const textWeight = this.options.textWeight ?? 0.55;
+        const vectorWeight = this.options.vectorWeight ?? 0.45;
+        const query = {
+            patterns: [],
+            textSearch: [
+                {
+                    query: input.prompt,
+                    scope,
+                    limit,
+                    source: 'source',
+                    chunk: 'textChunk',
+                    content: 'textContent',
+                    heading: 'textHeading',
+                    score: 'textScore',
+                    workspace: 'workspace',
+                    localPath: 'localPath',
+                    contentType: 'contentType',
+                    sourceKey: 'sourceKey',
+                    retrievalPoint: 'retrievalPointKey',
+                    retrievalKind: 'retrievalKind',
+                    entityProvenance: 'entityProvenance',
+                },
+            ],
+            select: [
+                'source',
+                'workspace',
+                'localPath',
+                'contentType',
+                'textChunk',
+                'textContent',
+                'textHeading',
+                'textScore',
+                'sourceKey',
+                'retrievalPointKey',
+                'retrievalKind',
+                'entityProvenance',
+            ],
+            orderBy: [{ variable: 'textScore', direction: 'desc' }],
+            limit,
+            cache: cacheScope ? { scope: cacheScope } : undefined,
+        };
+        if (hasVector && normalizedEmbedding) {
+            query.vectorSearch = [
+                {
+                    embedding: normalizedEmbedding.embedding,
+                    vectorModel: normalizedEmbedding.model ?? this.options.vectorModel,
+                    scope,
+                    limit,
+                    source: 'source',
+                    chunk: 'vectorChunk',
+                    content: 'vectorContent',
+                    heading: 'vectorHeading',
+                    score: 'vectorScore',
+                    distance: 'vectorDistance',
+                    model: 'vectorModel',
+                },
+            ];
+            query.binds = [
+                {
+                    variable: 'fusionScore',
+                    expression: {
+                        type: 'add',
+                        expressions: [
+                            {
+                                type: 'multiply',
+                                expressions: [
+                                    { type: 'numericValue', expression: { type: 'variable', variable: 'textScore' } },
+                                    { type: 'term', term: literal(String(textWeight)) },
+                                ],
+                            },
+                            {
+                                type: 'multiply',
+                                expressions: [
+                                    { type: 'numericValue', expression: { type: 'variable', variable: 'vectorScore' } },
+                                    { type: 'term', term: literal(String(vectorWeight)) },
+                                ],
+                            },
+                        ],
+                    },
+                },
+            ];
+            query.select = [
+                ...(query.select ?? []),
+                'vectorChunk',
+                'vectorContent',
+                'vectorHeading',
+                'vectorScore',
+                'vectorDistance',
+                'vectorModel',
+                'fusionScore',
+            ];
+            query.orderBy = [
+                { variable: 'fusionScore', direction: 'desc' },
+                { variable: 'source' },
+            ];
+        }
+        return query;
+    }
+    searchScope(input) {
+        const sourcePrefix = typeof this.options.sourcePrefix === 'function'
+            ? this.options.sourcePrefix(input)
+            : this.options.sourcePrefix;
+        return {
+            workspace: input.config.workspace,
+            ...(sourcePrefix ? { sourcePrefix } : {}),
+        };
+    }
+    cacheScope(input) {
+        return typeof this.options.cacheScope === 'function'
+            ? this.options.cacheScope(input)
+            : this.options.cacheScope;
+    }
+    withAccessScope(query, input) {
+        const accessScope = typeof this.options.accessScope === 'function'
+            ? this.options.accessScope(input)
+            : this.options.accessScope;
+        if (!accessScope) {
+            this.assertAccessScopeOptional(input);
+            return query;
+        }
+        this.assertAccessScopeComplete(input, accessScope);
+        return (0, RdfAccessScope_1.applyRdfAccessScope)(query, accessScope);
+    }
+    assertAccessScopeOptional(input) {
+        if (isRemoteWorkspace(input.config.workspace)) {
+            throw new Error('RDF Run context retrieval requires an access scope for remote Pod workspaces');
+        }
+    }
+    assertAccessScopeComplete(input, accessScope) {
+        if (!isRemoteWorkspace(input.config.workspace)) {
+            return;
+        }
+        if (!accessScope.principal || !accessScope.version) {
+            throw new Error('RDF Run context retrieval requires principal and permission version for remote Pod workspaces');
+        }
+    }
+    bindingToContextItem(row) {
+        const text = termValue(row.textContent) || termValue(row.vectorContent);
+        const source = termValue(row.source);
+        if (!text || !source) {
+            return undefined;
+        }
+        const fusionScore = termNumber(row.fusionScore);
+        const textScore = termNumber(row.textScore);
+        const vectorScore = termNumber(row.vectorScore);
+        const heading = termValue(row.textHeading) || termValue(row.vectorHeading);
+        const vectorDistance = termNumber(row.vectorDistance);
+        const vectorModel = termValue(row.vectorModel);
+        const entityProvenance = parseJsonArray(termValue(row.entityProvenance));
+        const metadata = compactRecord({
+            untrustedContext: true,
+            textChunk: termValue(row.textChunk),
+            vectorChunk: termValue(row.vectorChunk),
+            sourceKey: termValue(row.sourceKey),
+            retrievalPointKey: termValue(row.retrievalPointKey),
+            retrievalKind: termValue(row.retrievalKind),
+            entityProvenance,
+            textScore,
+            vectorScore,
+            vectorDistance,
+            vectorModel,
+            contentType: termValue(row.contentType),
+        });
+        return {
+            kind: vectorScore !== undefined && textScore === undefined ? 'vector_chunk' : 'text_chunk',
+            source,
+            text,
+            score: fusionScore ?? textScore ?? vectorScore,
+            workspace: termValue(row.workspace),
+            localPath: termValue(row.localPath),
+            heading,
+            metadata,
+        };
+    }
+}
+exports.RdfRunContextRetriever = RdfRunContextRetriever;
+function isRemoteWorkspace(workspaceValue) {
+    try {
+        const workspace = new URL(workspaceValue);
+        return workspace.protocol === 'http:' || workspace.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeEmbedding(input) {
+    if (!input) {
+        return undefined;
+    }
+    if (Array.isArray(input)) {
+        return { embedding: input };
+    }
+    return input;
+}
+function termValue(term) {
+    return term?.value || undefined;
+}
+function termNumber(term) {
+    const value = term?.value;
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function compactRecord(input) {
+    const entries = Object.entries(input).filter(([, value]) => value !== undefined);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function parseJsonArray(value) {
+    if (!value) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=RdfRunContextRetriever.js.map

package/dist/api/runs/RdfRunContextRetriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RdfRunContextRetriever.js","sourceRoot":"","sources":["../../../src/api/runs/RdfRunContextRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["import { DataFactory } from 'n3';\nimport type { StoreContext } from '../chatkit/store';\nimport { applyRdfAccessScope, type RdfAccessScope } from '../../storage/rdf/RdfAccessScope';\nimport type { RdfBindingRow, RdfEngineLike, RdfQuery, RdfQueryCacheScope, RdfSearchScope } from '../../storage/rdf/types';\nimport type {\n  RunContextRetrievalInput,\n  RunContextRetriever,\n  RunRetrievedContext,\n  RunRetrievedContextItem,\n} from './RunExecutionBackend';\n\nconst { literal } = DataFactory;\n\nexport type RdfRunContextEmbedding =\n  | number[]\n  | {\n    embedding: number[];\n    model?: string;\n  };\n\nexport interface RdfRunContextRetrieverOptions<TContext = StoreContext> {\n  rdfEngine: RdfEngineLike;\n  limit?: number;\n  /**\n   * Keep normal product paths fail-closed so missing text/vector indexes are\n   * exposed at startup or request execution instead of silently degrading Run\n   * context. Tests and optional deployments can still opt into best-effort\n   * retrieval explicitly.\n   */\n  failOpen?: boolean;\n  textWeight?: number;\n  vectorWeight?: number;\n  vectorModel?: string;\n  sourcePrefix?: string | ((input: RunContextRetrievalInput<TContext>) => string | undefined);\n  cacheScope?: RdfQueryCacheScope | ((input: RunContextRetrievalInput<TContext>) => RdfQueryCacheScope | undefined);\n  accessScope?: RdfAccessScope | ((input: RunContextRetrievalInput<TContext>) => RdfAccessScope | undefined);\n  embedding?: (input: RunContextRetrievalInput<TContext>) => Promise<RdfRunContextEmbedding | undefined>;\n  buildQuery?: (input: RunContextRetrievalInput<TContext>, embedding?: RdfRunContextEmbedding) => RdfQuery | Promise<RdfQuery>;\n}\n\n/**\n * Product-level Run context retriever backed by SolidRdfEngine/PostgresRdfEngine.\n *\n * The retriever keeps RDF/text/vector lookup outside durable queue events and\n * returns runtime-neutral snippets that drivers can project into their own\n * prompt/session format.\n */\nexport class RdfRunContextRetriever<TContext = StoreContext> implements RunContextRetriever<TContext> {\n  public constructor(private readonly options: RdfRunContextRetrieverOptions<TContext>) {}\n\n  public async retrieve(input: RunContextRetrievalInput<TContext>): Promise<RunRetrievedContext | undefined> {\n    const prompt = input.prompt.trim();\n    if (!prompt) {\n      return undefined;\n    }\n\n    try {\n      const embedding = await this.options.embedding?.(input);\n      const query = this.options.buildQuery\n        ? await this.options.buildQuery(input, embedding)\n        : this.buildDefaultQuery(input, embedding);\n      const result = await this.options.rdfEngine.query(this.withAccessScope(query, input));\n      const items = result.bindings\n        .map((row) => this.bindingToContextItem(row))\n        .filter((item): item is RunRetrievedContextItem => item !== undefined)\n        .slice(0, this.options.limit ?? 8);\n\n      if (items.length === 0) {\n        return undefined;\n      }\n\n      return {\n        query: prompt,\n        items,\n        generatedAt: Math.floor(Date.now() / 1000),\n        plan: result.metrics.plan,\n      };\n    } catch (error) {\n      if (this.options.failOpen === true) {\n        return undefined;\n      }\n      throw error;\n    }\n  }\n\n  private buildDefaultQuery(\n    input: RunContextRetrievalInput<TContext>,\n    embedding?: RdfRunContextEmbedding,\n  ): RdfQuery {\n    const limit = this.options.limit ?? 8;\n    const scope = this.searchScope(input);\n    const cacheScope = this.cacheScope(input);\n    const normalizedEmbedding = normalizeEmbedding(embedding);\n    const hasVector = (normalizedEmbedding?.embedding.length ?? 0) > 0;\n    const textWeight = this.options.textWeight ?? 0.55;\n    const vectorWeight = this.options.vectorWeight ?? 0.45;\n    const query: RdfQuery = {\n      patterns: [],\n      textSearch: [\n        {\n          query: input.prompt,\n          scope,\n          limit,\n          source: 'source',\n          chunk: 'textChunk',\n          content: 'textContent',\n          heading: 'textHeading',\n          score: 'textScore',\n          workspace: 'workspace',\n          localPath: 'localPath',\n          contentType: 'contentType',\n          sourceKey: 'sourceKey',\n          retrievalPoint: 'retrievalPointKey',\n          retrievalKind: 'retrievalKind',\n          entityProvenance: 'entityProvenance',\n        },\n      ],\n      select: [\n        'source',\n        'workspace',\n        'localPath',\n        'contentType',\n        'textChunk',\n        'textContent',\n        'textHeading',\n        'textScore',\n        'sourceKey',\n        'retrievalPointKey',\n        'retrievalKind',\n        'entityProvenance',\n      ],\n      orderBy: [{ variable: 'textScore', direction: 'desc' }],\n      limit,\n      cache: cacheScope ? { scope: cacheScope } : undefined,\n    };\n\n    if (hasVector && normalizedEmbedding) {\n      query.vectorSearch = [\n        {\n          embedding: normalizedEmbedding.embedding,\n          vectorModel: normalizedEmbedding.model ?? this.options.vectorModel,\n          scope,\n          limit,\n          source: 'source',\n          chunk: 'vectorChunk',\n          content: 'vectorContent',\n          heading: 'vectorHeading',\n          score: 'vectorScore',\n          distance: 'vectorDistance',\n          model: 'vectorModel',\n        },\n      ];\n      query.binds = [\n        {\n          variable: 'fusionScore',\n          expression: {\n            type: 'add',\n            expressions: [\n              {\n                type: 'multiply',\n                expressions: [\n                  { type: 'numericValue', expression: { type: 'variable', variable: 'textScore' } },\n                  { type: 'term', term: literal(String(textWeight)) },\n                ],\n              },\n              {\n                type: 'multiply',\n                expressions: [\n                  { type: 'numericValue', expression: { type: 'variable', variable: 'vectorScore' } },\n                  { type: 'term', term: literal(String(vectorWeight)) },\n                ],\n              },\n            ],\n          },\n        },\n      ];\n      query.select = [\n        ...(query.select ?? []),\n        'vectorChunk',\n        'vectorContent',\n        'vectorHeading',\n        'vectorScore',\n        'vectorDistance',\n        'vectorModel',\n        'fusionScore',\n      ];\n      query.orderBy = [\n        { variable: 'fusionScore', direction: 'desc' },\n        { variable: 'source' },\n      ];\n    }\n\n    return query;\n  }\n\n  private searchScope(input: RunContextRetrievalInput<TContext>): RdfSearchScope {\n    const sourcePrefix = typeof this.options.sourcePrefix === 'function'\n      ? this.options.sourcePrefix(input)\n      : this.options.sourcePrefix;\n    return {\n      workspace: input.config.workspace,\n      ...(sourcePrefix ? { sourcePrefix } : {}),\n    };\n  }\n\n  private cacheScope(input: RunContextRetrievalInput<TContext>): RdfQueryCacheScope | undefined {\n    return typeof this.options.cacheScope === 'function'\n      ? this.options.cacheScope(input)\n      : this.options.cacheScope;\n  }\n\n  private withAccessScope(query: RdfQuery, input: RunContextRetrievalInput<TContext>): RdfQuery {\n    const accessScope = typeof this.options.accessScope === 'function'\n      ? this.options.accessScope(input)\n      : this.options.accessScope;\n    if (!accessScope) {\n      this.assertAccessScopeOptional(input);\n      return query;\n    }\n    this.assertAccessScopeComplete(input, accessScope);\n    return applyRdfAccessScope(query, accessScope);\n  }\n\n  private assertAccessScopeOptional(input: RunContextRetrievalInput<TContext>): void {\n    if (isRemoteWorkspace(input.config.workspace)) {\n      throw new Error('RDF Run context retrieval requires an access scope for remote Pod workspaces');\n    }\n  }\n\n  private assertAccessScopeComplete(input: RunContextRetrievalInput<TContext>, accessScope: RdfAccessScope): void {\n    if (!isRemoteWorkspace(input.config.workspace)) {\n      return;\n    }\n    if (!accessScope.principal || !accessScope.version) {\n      throw new Error('RDF Run context retrieval requires principal and permission version for remote Pod workspaces');\n    }\n  }\n\n  private bindingToContextItem(row: RdfBindingRow): RunRetrievedContextItem | undefined {\n    const text = termValue(row.textContent) || termValue(row.vectorContent);\n    const source = termValue(row.source);\n    if (!text || !source) {\n      return undefined;\n    }\n\n    const fusionScore = termNumber(row.fusionScore);\n    const textScore = termNumber(row.textScore);\n    const vectorScore = termNumber(row.vectorScore);\n    const heading = termValue(row.textHeading) || termValue(row.vectorHeading);\n    const vectorDistance = termNumber(row.vectorDistance);\n    const vectorModel = termValue(row.vectorModel);\n    const entityProvenance = parseJsonArray(termValue(row.entityProvenance));\n    const metadata = compactRecord({\n      untrustedContext: true,\n      textChunk: termValue(row.textChunk),\n      vectorChunk: termValue(row.vectorChunk),\n      sourceKey: termValue(row.sourceKey),\n      retrievalPointKey: termValue(row.retrievalPointKey),\n      retrievalKind: termValue(row.retrievalKind),\n      entityProvenance,\n      textScore,\n      vectorScore,\n      vectorDistance,\n      vectorModel,\n      contentType: termValue(row.contentType),\n    });\n    return {\n      kind: vectorScore !== undefined && textScore === undefined ? 'vector_chunk' : 'text_chunk',\n      source,\n      text,\n      score: fusionScore ?? textScore ?? vectorScore,\n      workspace: termValue(row.workspace),\n      localPath: termValue(row.localPath),\n      heading,\n      metadata,\n    };\n  }\n}\n\nfunction isRemoteWorkspace(workspaceValue: string): boolean {\n  try {\n    const workspace = new URL(workspaceValue);\n    return workspace.protocol === 'http:' || workspace.protocol === 'https:';\n  } catch {\n    return false;\n  }\n}\n\nfunction normalizeEmbedding(input: RdfRunContextEmbedding | undefined): { embedding: number[]; model?: string } | undefined {\n  if (!input) {\n    return undefined;\n  }\n  if (Array.isArray(input)) {\n    return { embedding: input };\n  }\n  return input;\n}\n\nfunction termValue(term: RdfBindingRow[string] | undefined): string | undefined {\n  return term?.value || undefined;\n}\n\nfunction termNumber(term: RdfBindingRow[string] | undefined): number | undefined {\n  const value = term?.value;\n  if (value === undefined) {\n    return undefined;\n  }\n  const parsed = Number(value);\n  return Number.isFinite(parsed) ? parsed : undefined;\n}\n\nfunction compactRecord(input: Record<string, unknown>): Record<string, unknown> | undefined {\n  const entries = Object.entries(input).filter(([, value]) => value !== undefined);\n  return entries.length > 0 ? Object.fromEntries(entries) : undefined;\n}\n\nfunction parseJsonArray(value: string | undefined): unknown[] | undefined {\n  if (!value) {\n    return undefined;\n  }\n  try {\n    const parsed = JSON.parse(value);\n    return Array.isArray(parsed) ? parsed : undefined;\n  } catch {\n    return undefined;\n  }\n}\n"]}

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

@@ -9,6 +9,37 @@ export type RunConversationMessage = {
     text: string;
     createdAt: number;
 };
+export interface RunRetrievedContextItem {
+    /**
+     * Stable Pod resource, file URI, or runtime source identifier that produced
+     * this context item.
+     */
+    source: string;
+    text: string;
+    score?: number;
+    kind?: 'rdf_literal' | 'text_chunk' | 'vector_chunk' | 'message' | 'file';
+    workspace?: string;
+    localPath?: string;
+    heading?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RunRetrievedContext {
+    query: string;
+    items: RunRetrievedContextItem[];
+    generatedAt?: number;
+    plan?: string[];
+}
+export interface RunContextRetrievalInput<TContext = StoreContext> {
+    runId: string;
+    threadId: string;
+    prompt: string;
+    conversation: RunConversationMessage[];
+    config: AgentRuntimeConfig;
+    context: TContext;
+}
+export interface RunContextRetriever<TContext = StoreContext> {
+    retrieve(input: RunContextRetrievalInput<TContext>): Promise<RunRetrievedContext | undefined>;
+}
 export interface RunExecutionInput {
     runId: string;
     threadId: string;
@@ -19,6 +50,13 @@ export interface RunExecutionInput {
      * request-scoped caches and restore from this input on every run.
      */
     conversation: RunConversationMessage[];
+    /**
+     * Optional product-level context retrieved before runtime execution starts.
+     * The retriever may use RDF facts, text chunks, vector chunks, or other
+     * derived indexes; runtime drivers only project these snippets into their
+     * prompt/session format.
+     */
+    retrievedContext?: RunRetrievedContext;
     config: AgentRuntimeConfig;
     /**
      * Server-side auth binding used by unattended/durable Run callbacks to

package/dist/api/runs/RunExecutionBackend.js.map

@@ -1 +1 @@
-{"version":3,"file":"RunExecutionBackend.js","sourceRoot":"","sources":["../../../src/api/runs/RunExecutionBackend.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  AgentRuntimeConfig,\n  AgentRuntimeEvent,\n} from './AgentRuntimeTypes';\nimport type { StoreContext } from '../chatkit/store';\n\nexport type RunConversationMessage =\n  | { role: 'user'; text: string; createdAt: number }\n  | { role: 'assistant'; text: string; createdAt: number };\n\nexport interface RunExecutionInput {\n  runId: string;\n  threadId: string;\n  prompt: string;\n  /**\n   * Durable conversation projection loaded by Xpod from Pod state before this\n   * execution starts. Runtime drivers must treat their own sessions as\n   * request-scoped caches and restore from this input on every run.\n   */\n  conversation: RunConversationMessage[];\n  config: AgentRuntimeConfig;\n  /**\n   * Server-side auth binding used by unattended/durable Run callbacks to\n   * restore Pod access without serializing secrets into queue events.\n   */\n  authBindingId?: string;\n  /**\n   * Present when a paused Run is being placed back on the execution queue.\n   * This does not create a new Run; it resumes the same message-level Run\n   * after external input such as a client tool result or approval.\n   */\n  continuation?: {\n    kind: 'client_tool_output' | 'approval' | 'user_input';\n    itemId?: string;\n  };\n  /**\n   * Optional request context for in-process enqueue adapters. Durable workers\n   * must restore Pod access from non-secret event data or service-side lookup;\n   * access tokens must not be serialized into external queues.\n   */\n  context?: StoreContext;\n}\n\n/**\n * Execution boundary for an already-created Xpod Run.\n *\n * Implementations may enqueue, kick, or execute inline, but they must not own\n * the business state for the run. Pod-backed Run/Thread/Message/RunStep state\n * stays authoritative; backend ids are diagnostics only.\n */\nexport interface RunExecutionBackend {\n  start(input: RunExecutionInput): AsyncIterable<AgentRuntimeEvent>;\n}\n\nexport interface RunEnqueueResult {\n  runId: string;\n  externalRunId?: string;\n}\n"]}
+{"version":3,"file":"RunExecutionBackend.js","sourceRoot":"","sources":["../../../src/api/runs/RunExecutionBackend.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  AgentRuntimeConfig,\n  AgentRuntimeEvent,\n} from './AgentRuntimeTypes';\nimport type { StoreContext } from '../chatkit/store';\n\nexport type RunConversationMessage =\n  | { role: 'user'; text: string; createdAt: number }\n  | { role: 'assistant'; text: string; createdAt: number };\n\nexport interface RunRetrievedContextItem {\n  /**\n   * Stable Pod resource, file URI, or runtime source identifier that produced\n   * this context item.\n   */\n  source: string;\n  text: string;\n  score?: number;\n  kind?: 'rdf_literal' | 'text_chunk' | 'vector_chunk' | 'message' | 'file';\n  workspace?: string;\n  localPath?: string;\n  heading?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface RunRetrievedContext {\n  query: string;\n  items: RunRetrievedContextItem[];\n  generatedAt?: number;\n  plan?: string[];\n}\n\nexport interface RunContextRetrievalInput<TContext = StoreContext> {\n  runId: string;\n  threadId: string;\n  prompt: string;\n  conversation: RunConversationMessage[];\n  config: AgentRuntimeConfig;\n  context: TContext;\n}\n\nexport interface RunContextRetriever<TContext = StoreContext> {\n  retrieve(input: RunContextRetrievalInput<TContext>): Promise<RunRetrievedContext | undefined>;\n}\n\nexport interface RunExecutionInput {\n  runId: string;\n  threadId: string;\n  prompt: string;\n  /**\n   * Durable conversation projection loaded by Xpod from Pod state before this\n   * execution starts. Runtime drivers must treat their own sessions as\n   * request-scoped caches and restore from this input on every run.\n   */\n  conversation: RunConversationMessage[];\n  /**\n   * Optional product-level context retrieved before runtime execution starts.\n   * The retriever may use RDF facts, text chunks, vector chunks, or other\n   * derived indexes; runtime drivers only project these snippets into their\n   * prompt/session format.\n   */\n  retrievedContext?: RunRetrievedContext;\n  config: AgentRuntimeConfig;\n  /**\n   * Server-side auth binding used by unattended/durable Run callbacks to\n   * restore Pod access without serializing secrets into queue events.\n   */\n  authBindingId?: string;\n  /**\n   * Present when a paused Run is being placed back on the execution queue.\n   * This does not create a new Run; it resumes the same message-level Run\n   * after external input such as a client tool result or approval.\n   */\n  continuation?: {\n    kind: 'client_tool_output' | 'approval' | 'user_input';\n    itemId?: string;\n  };\n  /**\n   * Optional request context for in-process enqueue adapters. Durable workers\n   * must restore Pod access from non-secret event data or service-side lookup;\n   * access tokens must not be serialized into external queues.\n   */\n  context?: StoreContext;\n}\n\n/**\n * Execution boundary for an already-created Xpod Run.\n *\n * Implementations may enqueue, kick, or execute inline, but they must not own\n * the business state for the run. Pod-backed Run/Thread/Message/RunStep state\n * stays authoritative; backend ids are diagnostics only.\n */\nexport interface RunExecutionBackend {\n  start(input: RunExecutionInput): AsyncIterable<AgentRuntimeEvent>;\n}\n\nexport interface RunEnqueueResult {\n  runId: string;\n  externalRunId?: string;\n}\n"]}

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

@@ -1,7 +1,7 @@
-import type { ChatKitStore, StoreContext } from '../chatkit/store';
+import type { ChatKitStore, ClientToolContinuationClaim, StoreContext } from '../chatkit/store';
 import type { ClientEffect, ThreadItem, ThreadMetadata, ThreadRef, UserMessageItem } from '../chatkit/types';
-import type { AgentRuntimeConfig } from './AgentRuntimeTypes';
-import type { RunExecutionBackend } from './RunExecutionBackend';
+import { type AgentRuntimeConfig } from './AgentRuntimeTypes';
+import type { RunContextRetriever, RunExecutionBackend } from './RunExecutionBackend';
 export type RunStateEvent = {
     type: 'item_added';
     item: ThreadItem;
@@ -24,6 +24,11 @@ export interface RunStateCenterOptions<TContext = StoreContext> {
     store: ChatKitStore<TContext>;
     enableAgentRuntime?: boolean;
     executionBackend?: RunExecutionBackend;
+    contextRetriever?: RunContextRetriever<TContext>;
+}
+export interface PreparedClientToolOutput {
+    claim: ClientToolContinuationClaim;
+    output: string;
 }
 /**
  * Run is the xpod-side state center for Agent execution.
@@ -37,6 +42,7 @@ export declare class RunStateCenter<TContext = StoreContext> {
     private readonly runStore?;
     private readonly enableAgentRuntime;
     private readonly executionBackend;
+    private readonly contextRetriever?;
     constructor(options: RunStateCenterOptions<TContext>);
     getAgentRuntimeConfig(thread: ThreadMetadata, context?: TContext): AgentRuntimeConfig | null;
     getDefaultAgentRuntimeConfig(context: TContext): AgentRuntimeConfig | null;
@@ -48,12 +54,21 @@ export declare class RunStateCenter<TContext = StoreContext> {
         context: TContext;
         runtimeConfig: AgentRuntimeConfig;
     }): AsyncIterable<RunStateEvent>;
+    private retrieveRunContext;
+    prepareClientToolOutput(input: {
+        threadRef: ThreadRef;
+        itemId: string;
+        output: string;
+        context: TContext;
+    }): Promise<PreparedClientToolOutput | undefined>;
+    releaseClientToolOutput(prepared: PreparedClientToolOutput, context: TContext): Promise<boolean>;
     completeClientToolOutput(input: {
         threadRef: ThreadRef;
         itemId: string;
         output: string;
         context: TContext;
     }): AsyncIterable<RunStateEvent>;
+    completePreparedClientToolOutput(prepared: PreparedClientToolOutput, context: TContext): AsyncIterable<RunStateEvent>;
     private resolveRunStore;
     private createRun;
     private markRunStarted;

package/dist/api/runs/RunStateCenter.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RunStateCenter = void 0;
 const types_1 = require("../chatkit/types");
+const AgentRuntimeTypes_1 = require("./AgentRuntimeTypes");
 const InngestRunExecutionBackend_1 = require("./InngestRunExecutionBackend");
 const types_2 = require("../workspace/types");
 const schema_1 = require("./schema");
@@ -10,6 +11,7 @@ const RUN_WAITING_STATUSES = new Set([
     schema_1.RunStatus.WAITING_INPUT,
     schema_1.RunStatus.WAITING_RUNNER,
 ]);
+const CLIENT_TOOL_CONTINUATION_LEASE_MS = 5 * 60_000;
 /**
  * Run is the xpod-side state center for Agent execution.
  *
@@ -23,6 +25,7 @@ class RunStateCenter {
         this.runStore = this.resolveRunStore(options.store);
         this.enableAgentRuntime = options.enableAgentRuntime ?? false;
         this.executionBackend = options.executionBackend ?? new InngestRunExecutionBackend_1.InngestRunExecutionBackend();
+        this.contextRetriever = options.contextRetriever;
     }
     getAgentRuntimeConfig(thread, context) {
         if (!this.enableAgentRuntime) {
@@ -46,7 +49,7 @@ class RunStateCenter {
         if (!workspace) {
             throw new Error('Invalid thread runtime: workspace reference is required');
         }
-        return {
+        return (0, AgentRuntimeTypes_1.withInvocationAiConnection)({
             ...runtime,
             workspace,
             runner: {
@@ -55,7 +58,7 @@ class RunStateCenter {
                 protocol,
             },
             agentConfig: runtime.agentConfig,
-        };
+        }, context);
     }
     getDefaultAgentRuntimeConfig(context) {
         if (!this.enableAgentRuntime) {
@@ -92,11 +95,21 @@ class RunStateCenter {
         await this.markRunStarted(run, context);
         const assistantState = { item: assistantItem, fullText: '' };
         let runtimeError;
+        const conversation = await this.loadConversation(threadRef, userMessage.id, context);
+        const retrievedContext = await this.retrieveRunContext({
+            runId: run.id,
+            threadId: thread.id,
+            prompt,
+            conversation,
+            config: runtimeConfig,
+            context,
+        });
         for await (const event of this.executionBackend.start({
             runId: run.id,
             threadId: thread.id,
             prompt,
-            conversation: await this.loadConversation(threadRef, userMessage.id, context),
+            conversation,
+            retrievedContext,
             config: runtimeConfig,
             context: context,
         })) {
@@ -128,12 +141,56 @@ class RunStateCenter {
         await this.finishRun(run, runtimeError ? schema_1.RunStatus.FAILED : schema_1.RunStatus.COMPLETED, context, runtimeError);
         yield { type: 'item_done', item: finalItem };
     }
-    async *completeClientToolOutput(input) {
+    async retrieveRunContext(input) {
+        const retrieved = await this.contextRetriever?.retrieve(input);
+        if (!retrieved || retrieved.items.length === 0) {
+            return undefined;
+        }
+        return retrieved;
+    }
+    async prepareClientToolOutput(input) {
         const { threadRef, itemId, output, context } = input;
-        const item = await this.store.loadItem(threadRef, itemId, context);
-        if (item.type !== 'client_tool_call') {
+        if (!this.store.claimClientToolContinuation) {
+            throw new Error('Durable client tool continuation claim capability is required');
+        }
+        const now = (0, types_1.nowTimestamp)();
+        const claim = await this.store.claimClientToolContinuation({
+            threadRef,
+            itemId,
+            claimId: (0, types_1.generateId)('client-tool-continuation'),
+            leaseExpiresAt: now + CLIENT_TOOL_CONTINUATION_LEASE_MS,
+            now,
+        }, context);
+        if (!claim) {
+            return undefined;
+        }
+        return { claim, output };
+    }
+    async releaseClientToolOutput(prepared, context) {
+        if (!this.store.releaseClientToolContinuation) {
+            throw new Error('Durable client tool continuation release capability is required');
+        }
+        return this.store.releaseClientToolContinuation(prepared.claim, (0, types_1.nowTimestamp)(), context);
+    }
+    async *completeClientToolOutput(input) {
+        const prepared = await this.prepareClientToolOutput(input);
+        if (!prepared) {
             return;
         }
+        let completed = false;
+        try {
+            yield* this.completePreparedClientToolOutput(prepared, input.context);
+            completed = true;
+        }
+        finally {
+            if (!completed) {
+                await this.releaseClientToolOutput(prepared, input.context);
+            }
+        }
+    }
+    async *completePreparedClientToolOutput(prepared, context) {
+        const { threadRef, item, run } = prepared.claim;
+        const { output } = prepared;
         const updatedItem = {
             ...item,
             output,
@@ -141,10 +198,6 @@ class RunStateCenter {
         };
         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,
@@ -162,8 +215,6 @@ class RunStateCenter {
             },
         });
         run.status = schema_1.RunStatus.QUEUED;
-        run.leaseOwner = undefined;
-        run.leaseExpiresAt = undefined;
         run.completedAt = undefined;
         run.error = undefined;
         run.updatedAt = now;
@@ -191,12 +242,24 @@ class RunStateCenter {
             fullText: (0, types_1.extractAssistantMessageText)(assistantItem.content),
         };
         await this.markRunStarted(run, context);
+        const continuationPrompt = this.buildContinuationPrompt(updatedItem);
+        const conversation = await this.loadConversation(threadRef, String(run.metadata?.userMessageId ?? updatedItem.id), context);
+        const runtimeConfig = this.resolveRuntimeConfigForContinuation(run, context);
+        const retrievedContext = await this.retrieveRunContext({
+            runId: run.id,
+            threadId: this.extractThreadIdFromRef(threadRef),
+            prompt: continuationPrompt,
+            conversation,
+            config: runtimeConfig,
+            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),
+            prompt: continuationPrompt,
+            conversation,
+            retrievedContext,
+            config: runtimeConfig,
             continuation: {
                 kind: 'client_tool_output',
                 itemId: updatedItem.id,
@@ -222,11 +285,7 @@ class RunStateCenter {
             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;
+            throw new Error(result.message);
         }
         const finalItem = this.finalizeAssistantMessage(assistantState.item, assistantState.fullText, 'completed');
         await this.store.saveItem(threadRef, finalItem, context);
@@ -262,7 +321,7 @@ class RunStateCenter {
             metadata: {
                 threadId: thread.id,
                 userMessageId: userMessage.id,
-                runtimeConfig,
+                runtimeConfig: (0, AgentRuntimeTypes_1.toPersistedAgentRuntimeConfig)(runtimeConfig),
             },
             createdAt: now,
             updatedAt: now,
@@ -292,6 +351,8 @@ class RunStateCenter {
         const now = (0, types_1.nowTimestamp)();
         run.status = status;
         run.completedAt = now;
+        run.leaseOwner = undefined;
+        run.leaseExpiresAt = undefined;
         run.updatedAt = now;
         run.error = error;
         await this.saveRun(run, context);
@@ -436,7 +497,7 @@ class RunStateCenter {
         return schema_1.XpodRunStepType.FAILED;
     }
     async saveRun(run, context) {
-        await this.runStore?.saveRun(run, context);
+        await this.runStore?.saveRun((0, AgentRuntimeTypes_1.deepScrubGatewayKey)(run), context);
     }
     async appendRunStep(run, type, context, options = {}) {
         const createdAt = (0, types_1.nowTimestamp)();
@@ -547,10 +608,10 @@ class RunStateCenter {
     buildContinuationPrompt(item) {
         return `Continue the previous run after client tool output.\n\nTool: ${item.name}\nOutput:\n${item.output ?? ''}`;
     }
-    resolveRuntimeConfigForContinuation(run) {
+    resolveRuntimeConfigForContinuation(run, context) {
         const runtimeConfig = run.metadata?.runtimeConfig;
         if (runtimeConfig && typeof runtimeConfig === 'object') {
-            return runtimeConfig;
+            return (0, AgentRuntimeTypes_1.withInvocationAiConnection)(runtimeConfig, context);
         }
         if (!(0, types_2.isWorkspaceRef)(run.workspace)) {
             throw new Error('Run workspace reference is required');