@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/api/runs/PiAgentRuntimeDriver.js

@@ -24,16 +24,22 @@ var __importStar = (this && this.__importStar) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PI_AGENT_WORKER_EVENT_PREFIX = exports.PiAgentRuntimeDriver = void 0;
+exports.classifyAssistantFailure = classifyAssistantFailure;
 const fs = __importStar(require("node:fs"));
+const task_model_diagnostics_1 = require("../../util/task-model-diagnostics");
 const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
 const crypto = __importStar(require("node:crypto"));
+const node_url_1 = require("node:url");
 const node_readline_1 = require("node:readline");
+const global_logger_factory_1 = require("global-logger-factory");
 const GitWorktreeService_1 = require("../chatkit/runtime/GitWorktreeService");
 const sandbox_1 = require("../../terminal/sandbox");
 const safe_env_1 = require("../../runtime/safe-env");
+const package_root_1 = require("../../runtime/package-root");
 const solidfs_1 = require("../../solidfs");
 const RdfSearchIndexingSolidFsSyncer_1 = require("../service/RdfSearchIndexingSolidFsSyncer");
+const xpodVersion = JSON.parse(fs.readFileSync(path.join(package_root_1.PACKAGE_ROOT, 'package.json'), 'utf8')).version;
 /**
  * Request-scoped adapter around pi's AgentSession primitives.
  *
@@ -44,18 +50,25 @@ const RdfSearchIndexingSolidFsSyncer_1 = require("../service/RdfSearchIndexingSo
 class PiAgentRuntimeDriver {
     constructor(options = {}) {
         this.options = options;
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
         this.git = new GitWorktreeService_1.GitWorktreeService();
         this.warmRuntimes = new Map();
+        const mapping = options.podWorkspaceMapping ?? (process.env.CSS_BASE_URL && process.env.CSS_ROOT_FILE_PATH
+            ? { baseUrl: process.env.CSS_BASE_URL, rootFilePath: process.env.CSS_ROOT_FILE_PATH }
+            : undefined);
+        this.podWorkspaceMapping = mapping
+            ? { baseUrl: mapping.baseUrl, rootFilePath: path.resolve(mapping.rootFilePath) }
+            : undefined;
         this.solidfs = options.solidfs ?? new solidfs_1.LocalSolidFS({
             syncer: new solidfs_1.WorkspaceJournaledSolidFsSyncer({
                 syncer: this.createDefaultSolidFsSyncer(),
                 journalRoot: options.solidfsJournalRootDir,
             }),
-            hydrator: new solidfs_1.PodSolidFsHydrator(),
+            hydrator: new solidfs_1.PodSolidFsHydrator({ podAccess: options.podAccess }),
         });
     }
     createDefaultSolidFsSyncer() {
-        const syncers = [new solidfs_1.PodSolidFsSyncer()];
+        const syncers = [new solidfs_1.PodSolidFsSyncer({ podAccess: this.options.podAccess })];
         if (this.options.rdfSearchIndexingService) {
             syncers.push(new RdfSearchIndexingSolidFsSyncer_1.RdfSearchIndexingSolidFsSyncer({
                 service: this.options.rdfSearchIndexingService,
@@ -67,20 +80,38 @@ class PiAgentRuntimeDriver {
             : new solidfs_1.CompositeSolidFsSyncer({ syncers });
     }
     async *start(input) {
+        if (input.signal?.aborted)
+            return;
+        const connection = input.config.aiConnection;
+        const binding = this.options.gatewayTransport;
+        if (connection && binding && connection.baseUrl === binding.canonicalBaseUrl) {
+            input = { ...input, config: { ...input.config,
+                    aiConnection: { ...connection, baseUrl: binding.baseUrl },
+                } };
+        }
         if (this.options.agentLoopIsolation === 'sandboxed-process') {
             let workspace;
             let completed = false;
             try {
                 workspace = await this.prepareWorkspace(input);
+                if (input.signal?.aborted)
+                    return;
                 const runner = this.options.sandboxedLoopRunner
                     ?? ((runInput, runWorkdir) => this.startSandboxedAgentLoop(runInput, runWorkdir));
                 for await (const event of runner(input, workspace.cwd)) {
+                    if (event.type === 'tool_call' && event.approval) {
+                        await workspace.commit();
+                        completed = true;
+                    }
                     yield event;
                     if (event.type === 'error') {
                         return;
                     }
                 }
-                await workspace.commit();
+                if (input.signal?.aborted)
+                    return;
+                if (!completed)
+                    await workspace.commit();
                 completed = true;
             }
             catch (error) {
@@ -103,10 +134,86 @@ class PiAgentRuntimeDriver {
         let workspace;
         let completed = false;
         let failed = false;
+        let releaseApprovalTool;
+        let pausedForApproval = false;
+        const sessionHeader = `xpod-${crypto.createHash('sha256').update(input.threadId).digest('hex')}`;
+        let stage = 'not_invoked';
+        let api = 'other';
+        let credentialPresent = false;
+        let retryCount = 0;
+        let failureLogged = false;
+        const logFailure = (stopReason, errorMessage) => {
+            if (failureLogged || pausedForApproval || input.signal?.aborted)
+                return;
+            failureLogged = true;
+            // The SDK discards the structured provider response; only its formatted
+            // error message survives, so record a bounded hint and never the raw text.
+            const sdkErrorHint = (0, task_model_diagnostics_1.classifyTaskModelSdkErrorHint)(errorMessage);
+            const receipt = (0, task_model_diagnostics_1.selectTaskModelDiagnosticReceipt)({ event: 'xpod.task-model-diagnostic', schemaVersion: 1,
+                scope: 'session', stage, api, stopReason, retryCount,
+                correlationHash: (0, task_model_diagnostics_1.hashTaskModelDiagnosticSession)(sessionHeader), httpStatus: null, credentialPresent,
+                ...(sdkErrorHint ? { sdkErrorHint } : {}) });
+            if (receipt) {
+                try {
+                    this.logger.error(JSON.stringify(receipt));
+                }
+                catch { /* Diagnostics cannot alter run failure semantics. */ }
+            }
+        };
+        let releaseLifecycleWait;
+        const onAbort = () => {
+            failed = true;
+            releaseLifecycleWait?.();
+            void session?.abort().catch(() => undefined);
+            queue.close();
+        };
+        input.signal?.addEventListener('abort', onAbort, { once: true });
         try {
             workspace = await this.prepareWorkspace(input);
             const runtime = await this.getWarmRuntime(input, workspace);
+            api = runtime.piConfig.api === 'openai-completions' || runtime.piConfig.api === 'openai-responses'
+                ? runtime.piConfig.api : 'other';
+            credentialPresent = Boolean(runtime.piConfig.apiKey);
             const sessionManager = this.createSessionManager(runtime.pi, input.runId, runtime.workdir);
+            const approvalTool = {
+                name: 'request_approval', label: 'Request approval',
+                description: 'Pause this run and ask its owner to approve a specific action before you perform it. This tool does not execute the action. Use only when human approval is needed. After resuming, follow the persisted decision; do not request the same approval again.',
+                // Pi validates tool.parameters with AJV (pi-ai/utils/validation), so plain JSON Schema
+                // is sufficient here and avoids loading a second copy of its TypeBox/provider modules.
+                parameters: {
+                    type: 'object', additionalProperties: false,
+                    required: ['target', 'action', 'risk', 'description'],
+                    properties: {
+                        target: { type: 'string', minLength: 1, description: 'Absolute Pod resource URI that the proposed action affects.' },
+                        action: { type: 'string', minLength: 1, description: 'Absolute policy action URI, for example http://www.w3.org/ns/odrl/2/write.' },
+                        risk: { type: 'string', enum: ['low', 'medium', 'high'] },
+                        description: { type: 'string', minLength: 1, description: 'Explain exactly what will happen if the owner approves.' },
+                    },
+                },
+                execute: async (toolCallId, params, signal) => {
+                    if (pausedForApproval || signal?.aborted || input.signal?.aborted)
+                        throw new Error('Run is already paused or cancelled');
+                    const approval = params;
+                    for (const uri of [approval.target, approval.action]) {
+                        const parsed = new URL(uri);
+                        if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password)
+                            throw new Error('Approval requires absolute Pod and policy URIs');
+                    }
+                    // Keep work already performed before asking; the requested action itself is untouched.
+                    await workspace.commit();
+                    completed = true;
+                    pausedForApproval = true;
+                    releaseLifecycleWait?.();
+                    const paused = new Promise((_resolve, reject) => {
+                        const finish = () => { signal?.removeEventListener('abort', finish); reject(new Error('Run paused for owner approval')); };
+                        releaseApprovalTool = finish;
+                        signal?.addEventListener('abort', finish, { once: true });
+                    });
+                    queue.push({ type: 'tool_call', requestId: toolCallId, name: 'request_approval', arguments: JSON.stringify(approval), approval });
+                    queue.close();
+                    return paused;
+                },
+            };
             const result = await runtime.pi.createAgentSession({
                 cwd: runtime.workdir,
                 authStorage: runtime.authStorage,
@@ -114,11 +221,40 @@ class PiAgentRuntimeDriver {
                 settingsManager: runtime.settingsManager,
                 sessionManager,
                 resourceLoader: runtime.resourceLoader,
-                model: runtime.piConfig.model,
+                model: { ...runtime.piConfig.model, headers: {
+                        'user-agent': `Xpod/${xpodVersion}`,
+                        'x-opencode-session': sessionHeader,
+                    } },
                 thinkingLevel: runtime.thinkingLevel,
                 tools: runtime.tools,
+                customTools: [approvalTool],
             });
             session = result.session;
+            const originalStreamFn = session.agent.streamFn.bind(session.agent);
+            session.agent.streamFn = (model, context, options) => {
+                stage = 'model_invoked';
+                credentialPresent = Boolean(options?.apiKey);
+                const response = originalStreamFn(model, context, { ...options,
+                    onPayload: payload => {
+                        stage = 'payload_prepared';
+                        return options?.onPayload?.(payload);
+                    },
+                });
+                const observe = (stream) => {
+                    const iterate = stream[Symbol.asyncIterator].bind(stream);
+                    stream[Symbol.asyncIterator] = async function* () {
+                        for await (const event of { [Symbol.asyncIterator]: iterate }) {
+                            if (event.type === 'start')
+                                stage = 'stream_open';
+                            yield event;
+                        }
+                    };
+                    return stream;
+                };
+                return response instanceof Promise ? response.then(observe) : observe(response);
+            };
+            if (input.signal?.aborted)
+                return;
             session.agent.replaceMessages(this.toPiMessages(input, runtime.piConfig));
             const streamState = {
                 lastAssistantText: '',
@@ -126,18 +262,50 @@ class PiAgentRuntimeDriver {
             };
             const unsubscribe = session.subscribe((event) => {
                 this.projectPiEvent(event, queue, streamState);
+                if (event.type === 'auto_retry_start')
+                    retryCount += 1;
+                if (event.type === 'agent_start' || event.type === 'auto_retry_end')
+                    releaseLifecycleWait?.();
             });
-            void session.prompt(input.prompt, { expandPromptTemplates: false, source: 'rpc' }).then(() => {
-                if (!streamState.assistantTextStreamed && streamState.lastAssistantText.length > 0) {
+            void session.prompt(input.prompt, { expandPromptTemplates: false, source: 'rpc' }).then(async () => {
+                // A recovered retry can resolve prompt before its tools and subsequent turns finish.
+                // Wait on SDK lifecycle promises; approval/cancellation closes the queue and aborts the session.
+                while (!pausedForApproval && !input.signal?.aborted && (session?.isStreaming || session?.isRetrying)) {
+                    if (session?.isStreaming) {
+                        await session.agent.waitForIdle();
+                    }
+                    else {
+                        await new Promise(resolve => {
+                            releaseLifecycleWait = resolve;
+                            // Register before checking state so an already-started retry cannot lose its wakeup.
+                            if (pausedForApproval || input.signal?.aborted || !session?.isRetrying || session.isStreaming)
+                                resolve();
+                        });
+                        releaseLifecycleWait = undefined;
+                    }
+                }
+                // Pi also resolves failed prompts, including errors with no message_end.
+                const lastAssistant = (session?.messages ?? []).slice().reverse().find(message => message.role === 'assistant');
+                if (!pausedForApproval && !input.signal?.aborted && lastAssistant?.role === 'assistant' &&
+                    (lastAssistant.stopReason === 'error' || lastAssistant.stopReason === 'aborted')) {
+                    // The feature structured receipt is the single diagnostic sink for one failure; the
+                    // pushed message carries only allowlisted wire facts (class/protocol/provider/model),
+                    // never the provider body or credential material.
+                    logFailure(lastAssistant.stopReason, lastAssistant.errorMessage);
+                    queue.push({ type: 'error', message: `Pi assistant ended with ${lastAssistant.stopReason}${describeAssistantFailure(lastAssistant)}` });
+                }
+                else if (!streamState.assistantTextStreamed && streamState.lastAssistantText.length > 0) {
                     queue.push({ type: 'text', text: streamState.lastAssistantText });
                 }
                 queue.close();
             }).catch((error) => {
-                queue.push({ type: 'error', message: this.formatError(error) });
+                if (!pausedForApproval) {
+                    logFailure('unknown', error);
+                    queue.push({ type: 'error', message: this.formatError(error) });
+                }
                 queue.close();
             }).finally(() => {
                 unsubscribe();
-                session?.dispose();
             });
             for await (const event of queue.iterate()) {
                 if (event.type === 'error') {
@@ -145,16 +313,24 @@ class PiAgentRuntimeDriver {
                 }
                 yield event;
             }
-            if (!failed) {
+            if (!completed && !failed && !input.signal?.aborted) {
                 await workspace.commit();
                 completed = true;
             }
         }
         catch (error) {
-            session?.dispose();
-            yield this.startupErrorToEvent(error);
+            const event = this.startupErrorToEvent(error);
+            if (event.type === 'error')
+                logFailure('unknown');
+            yield event;
         }
         finally {
+            input.signal?.removeEventListener('abort', onAbort);
+            releaseLifecycleWait?.();
+            releaseApprovalTool?.();
+            if (!completed || pausedForApproval)
+                await session?.abort().catch(() => undefined);
+            session?.dispose();
             if (!completed) {
                 await workspace?.rollback().catch((error) => {
                     this.logWorkspaceRollbackError(error);
@@ -176,6 +352,7 @@ class PiAgentRuntimeDriver {
             args: [this.resolveWorkerPath()],
             env: this.workerEnv(),
             isolateNetwork: false,
+            readonlyPaths: this.workerReadonlyPaths(),
         });
         if (requireSandbox && !child.sandboxed) {
             child.process.kill();
@@ -193,11 +370,21 @@ class PiAgentRuntimeDriver {
             closed = true;
             queue.close();
         };
+        const onAbort = () => { child.process.kill(); };
+        input.signal?.addEventListener('abort', onAbort, { once: true });
+        if (input.signal?.aborted)
+            onAbort();
+        const { signal: _signal, ...serializableInput } = input;
         child.process.stdin?.end(JSON.stringify({
-            input,
+            // The host already prepared this workspace and owns all Pod writes. The worker
+            // receives only its isolated file view, never the restored Pod credential context.
+            input: { ...serializableInput, context: {}, config: {
+                    ...serializableInput.config, workspace: (0, node_url_1.pathToFileURL)(workdir).href, worktree: undefined,
+                } },
             options: {
                 persistPiSessions: this.options.persistPiSessions === true,
                 sessionRootDir: this.options.sessionRootDir,
+                gatewayTransport: this.options.gatewayTransport,
             },
         }));
         const rl = (0, node_readline_1.createInterface)({ input: child.process.stdout });
@@ -223,6 +410,7 @@ class PiAgentRuntimeDriver {
             closeOnce();
         });
         child.process.on('close', (code, signal) => {
+            input.signal?.removeEventListener('abort', onAbort);
             rl.close();
             if (code !== 0) {
                 const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
@@ -664,11 +852,10 @@ class PiAgentRuntimeDriver {
         return authority === configured || authority === os.hostname();
     }
     mapPodUrlToLocalPath(rootUrl) {
-        const rootFilePath = process.env.CSS_ROOT_FILE_PATH;
-        const baseUrl = process.env.CSS_BASE_URL;
-        if (!rootFilePath || !baseUrl) {
+        if (!this.podWorkspaceMapping) {
             return undefined;
         }
+        const { rootFilePath, baseUrl } = this.podWorkspaceMapping;
         try {
             const base = new URL(baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
             const pod = new URL(rootUrl.endsWith('/') ? rootUrl : `${rootUrl}/`);
@@ -707,6 +894,25 @@ class PiAgentRuntimeDriver {
         }
         return path.join(__dirname, `PiAgentRuntimeWorker${path.extname(__filename)}`);
     }
+    workerReadonlyPaths() {
+        const paths = [
+            path.join(package_root_1.PACKAGE_ROOT, path.extname(this.resolveWorkerPath()) === '.ts' ? 'src' : 'dist'),
+            path.join(package_root_1.PACKAGE_ROOT, 'node_modules'),
+            path.join(package_root_1.PACKAGE_ROOT, 'package.json'),
+        ];
+        // Workspace symlinks resolve outside node_modules. Expose only published code and metadata.
+        const workspaceRoot = path.join(package_root_1.PACKAGE_ROOT, 'packages');
+        if (fs.existsSync(workspaceRoot)) {
+            for (const entry of fs.readdirSync(workspaceRoot, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    paths.push(path.join(workspaceRoot, entry.name, 'dist'), path.join(workspaceRoot, entry.name, 'package.json'));
+                }
+            }
+        }
+        if (this.options.gatewayTransport?.socketPath)
+            paths.push(this.options.gatewayTransport.socketPath);
+        return paths;
+    }
     workerEnv() {
         const env = (0, safe_env_1.sanitizeRuntimeEnv)(process.env);
         env.XPOD_AGENT_LOOP_WORKER = '1';
@@ -767,6 +973,59 @@ function pushMetadataTag(tags, key, value) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/** A short, non-secret protocol/provider/model label for logs. */
+function safeLabel(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 && trimmed.length <= 64 ? trimmed : undefined;
+}
+/**
+ * Coarse classification of a provider failure, derived only from the shape of the message.
+ *
+ * Never returns any part of the message text: it exists so an operator can tell an auth failure
+ * from a rate limit from a transport problem without reading a body that may hold credentials.
+ */
+function classifyAssistantFailure(errorMessage) {
+    if (typeof errorMessage !== 'string' || errorMessage.trim().length === 0) {
+        return 'unclassified';
+    }
+    const text = errorMessage.toLowerCase();
+    const status = text.match(/\b(4\d\d|5\d\d)\b/)?.[1];
+    if (status === '401' || status === '403' || /\bunauthoriz|\bforbidden|invalid[_ ]?api[_ ]?key|\binvalid[_ ]?token\b|\bauthentication\b/.test(text)) {
+        return 'auth';
+    }
+    if (status === '429' || /rate[_ ]?limit|too many requests|\bquota\b/.test(text)) {
+        return 'rate_limited';
+    }
+    if (status === '404' || /model[_ ]?not[_ ]?found|\bdoes not exist\b|unknown[_ ]?model/.test(text)) {
+        return 'model_unavailable';
+    }
+    if (status !== undefined && status.startsWith('4')) {
+        return `client_${status}`;
+    }
+    if (status !== undefined && status.startsWith('5')) {
+        return `server_${status}`;
+    }
+    if (/timeout|timed out|\babort/.test(text)) {
+        return 'timeout';
+    }
+    if (/fetch failed|network|econnrefused|econnreset|socket|dns|enotfound/.test(text)) {
+        return 'transport';
+    }
+    return 'provider_error';
+}
+/** Allowlisted wire facts appended to a failed-turn message; never the provider body. */
+function describeAssistantFailure(message) {
+    const parts = [`class=${classifyAssistantFailure(message.errorMessage)}`];
+    if (safeLabel(message.api))
+        parts.push(`api=${safeLabel(message.api)}`);
+    if (safeLabel(message.provider))
+        parts.push(`provider=${safeLabel(message.provider)}`);
+    if (safeLabel(message.model))
+        parts.push(`model=${safeLabel(message.model)}`);
+    return ` (${parts.join(', ')})`;
+}
 exports.PI_AGENT_WORKER_EVENT_PREFIX = 'XPOD_AGENT_EVENT ';
 class WaitingRunnerError extends Error {
     constructor(workspace, message) {

package/dist/api/runs/PiAgentRuntimeWorker.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const socket_shim_1 = require("../../runtime/socket-shim");
 const PiAgentRuntimeDriver_1 = require("./PiAgentRuntimeDriver");
 async function readStdin() {
     const chunks = [];
@@ -17,8 +18,17 @@ async function main() {
         ...payload.options,
         agentLoopIsolation: 'in-process',
     });
-    for await (const event of driver.start(payload.input)) {
-        emit(event);
+    const binding = payload.options?.gatewayTransport;
+    const unregisterSocket = binding?.socketPath
+        ? (0, socket_shim_1.registerSocketOriginShims)(binding.baseUrl, binding.socketPath)
+        : undefined;
+    try {
+        for await (const event of driver.start(payload.input)) {
+            emit(event);
+        }
+    }
+    finally {
+        await unregisterSocket?.();
     }
 }
 if (require.main === module) {

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

@@ -0,0 +1,16 @@
+import type { RdfAccessScope } from '../../storage/rdf/RdfAccessScope';
+import type { RdfEngineLike } from '../../storage/rdf/types';
+import type { StoreContext } from '../chatkit/store';
+import type { PodAccessFetchProvider } from '../ai-gateway/pod/OwnerPodAccess';
+import { type PodBaseUrlResolver } from '../ai-gateway/pod/PodBaseUrlResolver';
+import type { RunContextRetrievalInput } from './RunExecutionBackend';
+/** CSS remains the authorization authority; the API only records successful Read probes. */
+export declare class PodRdfAccessScopeResolver {
+    private readonly options;
+    constructor(options: {
+        rdfEngine: Pick<RdfEngineLike, 'listTextSources'>;
+        podAccess: PodAccessFetchProvider;
+        podBaseUrlResolver?: PodBaseUrlResolver;
+    });
+    resolve(input: RunContextRetrievalInput<StoreContext>): Promise<RdfAccessScope | undefined>;
+}

package/dist/api/runs/PodRdfAccessScopeResolver.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PodRdfAccessScopeResolver = void 0;
+const node_crypto_1 = require("node:crypto");
+const PodBaseUrlResolver_1 = require("../ai-gateway/pod/PodBaseUrlResolver");
+/** CSS remains the authorization authority; the API only records successful Read probes. */
+class PodRdfAccessScopeResolver {
+    constructor(options) {
+        this.options = options;
+    }
+    async resolve(input) {
+        const workspace = new URL(input.config.workspace);
+        if (workspace.protocol === 'file:')
+            return undefined;
+        const auth = input.context.auth;
+        if (auth?.type !== 'solid')
+            throw new Error('RDF Run context requires an authenticated Pod principal');
+        const pod = new URL(await (0, PodBaseUrlResolver_1.resolveOwnerPodBaseUrl)(auth.webId, this.options.podBaseUrlResolver));
+        if (!isPodResource(workspace, pod) || workspace.hash || workspace.search) {
+            throw new Error('RDF Run workspace must belong to the authenticated Pod');
+        }
+        const fetch = await this.options.podAccess.getPodFetch(auth.webId, { auth, podBaseUrl: pod.href });
+        if (!fetch)
+            throw new Error('RDF Run context Pod credential is unavailable');
+        const workspaceRead = await readPermission(fetch, workspace.href);
+        if (!workspaceRead.allowed)
+            throw new Error('RDF Run workspace Read access is unavailable');
+        if (!this.options.rdfEngine.listTextSources)
+            throw new Error('RDF Run source enumeration is unavailable');
+        const allowedSourceUrls = [];
+        const observations = [[workspace.href, workspaceRead]];
+        const seen = new Set();
+        const pageSize = 100;
+        for (let offset = 0;; offset += pageSize) {
+            const page = await this.options.rdfEngine.listTextSources({ workspace: workspace.href, sourcePrefix: workspace.href, limit: pageSize, offset });
+            for (const entry of page) {
+                let resource;
+                try {
+                    resource = new URL(entry.source);
+                }
+                catch {
+                    continue;
+                }
+                if (entry.workspace !== workspace.href || !isPodResource(resource, pod) || resource.hash || resource.search
+                    || !isWithinWorkspace(resource.href, workspace.href) || seen.has(resource.href))
+                    continue;
+                seen.add(resource.href);
+                const read = await readPermission(fetch, resource.href);
+                observations.push([resource.href, read]);
+                if (read.allowed)
+                    allowedSourceUrls.push(resource.href);
+            }
+            if (page.length < pageSize)
+                break;
+        }
+        return {
+            basePath: workspace.href, mode: 'read', resolved: true, principal: auth.webId,
+            // Text sources do not prove named-graph ownership. The default Run query
+            // reads text/vector projections only; a future fact query needs a graph grant.
+            allowedGraphUrls: [], allowedSourceUrls: allowedSourceUrls.sort(),
+            version: `pod-read:${(0, node_crypto_1.createHash)('sha256').update(JSON.stringify(observations)).digest('hex')}`,
+        };
+    }
+}
+exports.PodRdfAccessScopeResolver = PodRdfAccessScopeResolver;
+function isPodResource(resource, pod) {
+    return ['http:', 'https:'].includes(resource.protocol) && !resource.username && !resource.password
+        && resource.origin === pod.origin && resource.href.startsWith(pod.href);
+}
+function isWithinWorkspace(resource, workspace) {
+    return resource === workspace || resource.startsWith(workspace.endsWith('/') ? workspace : `${workspace}/`);
+}
+async function readPermission(fetch, resource) {
+    try {
+        const response = await fetch(resource, { method: 'HEAD', redirect: 'manual' });
+        return { allowed: response.ok && !response.redirected && (!response.url || response.url === resource),
+            status: response.status, etag: response.headers.get('etag') ?? undefined };
+    }
+    catch {
+        return { allowed: false, status: 0 };
+    }
+}
+//# sourceMappingURL=PodRdfAccessScopeResolver.js.map

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

@@ -36,7 +36,7 @@ export interface RdfRunContextRetrieverOptions<TContext = StoreContext> {
     vectorProjectionPolicyVersion?: string;
     sourcePrefix?: string | ((input: RunContextRetrievalInput<TContext>) => string | undefined);
     cacheScope?: RdfQueryCacheScope | ((input: RunContextRetrievalInput<TContext>) => RdfQueryCacheScope | undefined);
-    accessScope?: RdfAccessScope | ((input: RunContextRetrievalInput<TContext>) => RdfAccessScope | undefined);
+    accessScope?: RdfAccessScope | ((input: RunContextRetrievalInput<TContext>) => RdfAccessScope | undefined | Promise<RdfAccessScope | undefined>);
     embedding?: (input: RunContextRetrievalInput<TContext>) => Promise<RdfRunContextEmbedding | undefined>;
     buildQuery?: (input: RunContextRetrievalInput<TContext>, embedding?: RdfRunContextEmbedding) => RdfQuery | Promise<RdfQuery>;
 }

package/dist/api/runs/RdfRunContextRetriever.js

@@ -23,14 +23,16 @@ class RdfRunContextRetriever {
             return undefined;
         }
         try {
+            const accessScope = typeof this.options.accessScope === 'function'
+                ? await this.options.accessScope(input) : this.options.accessScope;
             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 result = await this.options.rdfEngine.query(this.withAccessScope(query, input, accessScope));
             const rows = result.bindings.length > 0 || !query.vectorSearch?.length
                 ? result
-                : await this.options.rdfEngine.query(this.withAccessScope(this.vectorOnlyQuery(query), input));
+                : await this.options.rdfEngine.query(this.withAccessScope(this.vectorOnlyQuery(query), input, accessScope));
             const items = rows.bindings
                 .map((row) => this.bindingToContextItem(row))
                 .filter((item) => item !== undefined)
@@ -213,10 +215,7 @@ class RdfRunContextRetriever {
             ? this.options.cacheScope(input)
             : this.options.cacheScope;
     }
-    withAccessScope(query, input) {
-        const accessScope = typeof this.options.accessScope === 'function'
-            ? this.options.accessScope(input)
-            : this.options.accessScope;
+    withAccessScope(query, input, accessScope) {
         if (!accessScope) {
             this.assertAccessScopeOptional(input);
             return query;

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

@@ -0,0 +1,17 @@
+import { type ApprovalInsert, type SessionInsert, type SessionStatus } from '@undefineds.co/models';
+import type { AgentRuntimeEvent } from './AgentRuntimeTypes';
+import type { RunRecordData } from './store';
+export interface RunApprovalStore<TContext> {
+    writeTaskApproval?(approval: ApprovalInsert, context: TContext): Promise<string>;
+    saveRunApprovalSession?(session: SessionInsert, context: TContext): Promise<string>;
+}
+/** Persist the human-authority request only after its client-tool checkpoint exists. */
+export declare function persistRunApproval<TContext>(input: {
+    store: RunApprovalStore<TContext>;
+    run: RunRecordData;
+    event: Extract<AgentRuntimeEvent, {
+        type: 'tool_call';
+    }>;
+    context: TContext;
+}): Promise<string | undefined>;
+export declare function updateRunApprovalSession<TContext>(store: RunApprovalStore<TContext>, run: RunRecordData, status: SessionStatus, context: TContext): Promise<string | undefined>;