@undefineds.co/xpod 0.4.25 → 0.4.28

package/dist/api/runs/PiAgentRuntimeDriver.js

@@ -26,6 +26,7 @@ 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"));
@@ -135,6 +136,30 @@ class PiAgentRuntimeDriver {
         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;
@@ -146,6 +171,9 @@ class PiAgentRuntimeDriver {
         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',
@@ -195,13 +223,36 @@ class PiAgentRuntimeDriver {
                 resourceLoader: runtime.resourceLoader,
                 model: { ...runtime.piConfig.model, headers: {
                         'user-agent': `Xpod/${xpodVersion}`,
-                        'x-opencode-session': `xpod-${crypto.createHash('sha256').update(input.threadId).digest('hex')}`,
+                        '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));
@@ -211,6 +262,8 @@ 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?.();
             });
@@ -235,9 +288,10 @@ class PiAgentRuntimeDriver {
                 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')) {
-                    // Provider errorMessage can contain credentials or response bodies. Expose only a stable
-                    // classification plus allowlisted wire facts (protocol/provider/model), never the body.
-                    this.logAssistantFailure(lastAssistant);
+                    // 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) {
@@ -245,8 +299,10 @@ class PiAgentRuntimeDriver {
                 }
                 queue.close();
             }).catch((error) => {
-                if (!pausedForApproval)
+                if (!pausedForApproval) {
+                    logFailure('unknown', error);
                     queue.push({ type: 'error', message: this.formatError(error) });
+                }
                 queue.close();
             }).finally(() => {
                 unsubscribe();
@@ -263,7 +319,10 @@ class PiAgentRuntimeDriver {
             }
         }
         catch (error) {
-            yield this.startupErrorToEvent(error);
+            const event = this.startupErrorToEvent(error);
+            if (event.type === 'error')
+                logFailure('unknown');
+            yield event;
         }
         finally {
             input.signal?.removeEventListener('abort', onAbort);
@@ -878,21 +937,6 @@ class PiAgentRuntimeDriver {
     formatError(error) {
         return error instanceof Error ? error.message : String(error);
     }
-    /**
-     * Record a failed assistant turn with allowlisted wire facts only.
-     *
-     * The provider `errorMessage` can contain credentials, prompts, or response bodies, so it never
-     * leaves this method. What is kept is enough to place the failure: the protocol/provider/model
-     * and a stable coarse classification derived from the shape of the message (never its text).
-     */
-    logAssistantFailure(message) {
-        this.logger.warn(`Pi assistant turn failed ${JSON.stringify({
-            api: safeLabel(message.api),
-            provider: safeLabel(message.provider),
-            model: safeLabel(message.model),
-            class: classifyAssistantFailure(message.errorMessage),
-        })}`);
-    }
     startupErrorToEvent(error) {
         if (error instanceof WaitingRunnerError) {
             return {

package/dist/api/runs/RunStateCenter.js

@@ -295,6 +295,7 @@ class RunStateCenter {
                     kind: 'client_tool_output',
                     itemId: updatedItem.id,
                 },
+                authBindingId: (0, store_1.resolveRunAuthBindingId)(run),
                 context: context,
             })) {
                 const cancellation = await this.checkCancellation(run, threadRef, assistantState, context);

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

@@ -25,6 +25,7 @@ export interface RunRecordData {
     completedAt?: number;
     updatedAt: number;
 }
+export declare function resolveRunAuthBindingId(run: RunRecordData): string | undefined;
 export interface RunStepRecordData {
     /** Base-relative Solid resource id, e.g. `chat/default/2026/05/18/runs.ttl#step_x`. */
     id: string;

package/dist/api/runs/store.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRunAuthBindingId = resolveRunAuthBindingId;
 exports.isClaimableRunStatus = isClaimableRunStatus;
 exports.hasActiveRunLease = hasActiveRunLease;
 exports.canClaimRun = canClaimRun;
@@ -15,6 +16,18 @@ exports.buildRunStepResourceId = buildRunStepResourceId;
 exports.resolveBoundPodBaseUrl = resolveBoundPodBaseUrl;
 exports.resolveRunUrn = resolveRunUrn;
 exports.resolveDataResource = resolveDataResource;
+function resolveRunAuthBindingId(run) {
+    const authBindingId = run.metadata?.authBindingId;
+    if (typeof authBindingId === 'string' && authBindingId.length > 0) {
+        return authBindingId;
+    }
+    const authBinding = run.metadata?.authBinding;
+    if (authBinding && typeof authBinding === 'object') {
+        const id = authBinding.id;
+        return typeof id === 'string' && id.length > 0 ? id : undefined;
+    }
+    return undefined;
+}
 function isClaimableRunStatus(status) {
     return status === 'queued' || status === 'running';
 }

package/dist/api/tasks/TaskMaterializer.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TaskMaterializer = void 0;
+const TaskResumeDiagnostics_1 = require("./TaskResumeDiagnostics");
 const RunCancellation_1 = require("../runs/RunCancellation");
 const global_logger_factory_1 = require("global-logger-factory");
 const RunApproval_1 = require("../runs/RunApproval");
@@ -98,22 +99,28 @@ class TaskMaterializer {
         };
     }
     async resumeClientToolOutput(run, itemId, output, approval, context) {
-        const executionContext = await this.withInvocationAiConnections(context);
-        const prepared = await this.continuation.prepareClientToolOutput({
-            threadRef: (0, types_1.toThreadRef)({ thread_id: run.thread }), itemId, output, context: executionContext,
+        const executionContext = await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('invocation_issue', () => this.withInvocationAiConnections(context));
+        const prepared = await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('continuation_prepare', async () => {
+            const prepared = await this.continuation.prepareClientToolOutput({
+                threadRef: (0, types_1.toThreadRef)({ thread_id: run.thread }), itemId, output, context: executionContext,
+            });
+            if (prepared)
+                prepared.claim.item.metadata = { ...prepared.claim.item.metadata, approval };
+            return prepared;
         });
         if (!prepared)
             return false;
-        prepared.claim.item.metadata = { ...prepared.claim.item.metadata, approval };
         let completed = false;
         try {
-            for await (const _event of this.continuation.completePreparedClientToolOutput(prepared, executionContext)) { /* Durable state is the result. */ }
+            await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('continuation_complete', async () => {
+                for await (const _event of this.continuation.completePreparedClientToolOutput(prepared, executionContext)) { /* Durable state is the result. */ }
+            });
             completed = true;
             return true;
         }
         finally {
             if (!completed)
-                await this.continuation.releaseClientToolOutput(prepared, executionContext);
+                await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('continuation_release', () => this.continuation.releaseClientToolOutput(prepared, executionContext));
         }
     }
     async executeRun(input) {

package/dist/api/tasks/TaskResumeDiagnostics.d.ts

@@ -0,0 +1,28 @@
+/** Fixed resume boundaries, never derived from error prose or caller metadata. */
+export declare const TASK_RESUME_STAGES: readonly ["route_request", "route_validation", "route_run_read", "run_read", "approval_validation", "checkpoint_validation", "task_lookup", "task_auth_restore", "invocation_issue", "continuation_prepare", "continuation_complete", "continuation_release", "run_result_read"];
+export type TaskResumeStage = typeof TASK_RESUME_STAGES[number];
+export declare function getTaskResumeStage(error: unknown): TaskResumeStage | undefined;
+/** First inner boundary wins; frozen errors and original throw semantics are preserved. */
+export declare function withTaskResumeStage<T>(stage: TaskResumeStage, operation: () => Promise<T>): Promise<T>;
+export declare const TASK_RESUME_ERROR_TYPES: readonly ["error", "type_error", "range_error", "syntax_error", "non_error"];
+export type TaskResumeErrorType = typeof TASK_RESUME_ERROR_TYPES[number];
+export declare function getTaskResumeErrorType(error: unknown): TaskResumeErrorType;
+export declare const TASK_RESUME_FAILURE_NAMES: readonly ["Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError", "EvalError", "URIError", "AggregateError"];
+export declare const TASK_RESUME_FAILURE_CODES: readonly ["ENOSPC", "ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "ENOTFOUND", "EACCES", "ERR_INVALID_URL"];
+export declare const TASK_RESUME_SITE_MODULES: readonly ["api/runs/RunStateCenter", "api/runs/InngestRunExecutionBackend", "api/runs/ConditionalResourceDocument", "api/runs/RunApproval", "api/runs/RunCancellation", "api/runs/ManagedRunWorker", "api/runs/store", "api/chatkit/pod-store", "api/tasks/TaskMaterializer", "api/tasks/TaskService", "api/handlers/TaskHandler"];
+export interface TaskResumeFailure {
+    name: typeof TASK_RESUME_FAILURE_NAMES[number];
+    code?: typeof TASK_RESUME_FAILURE_CODES[number];
+    causeCode?: typeof TASK_RESUME_FAILURE_CODES[number];
+    site?: {
+        module: typeof TASK_RESUME_SITE_MODULES[number];
+        line: number;
+        column: number;
+        coordinate: 'compiled_js' | 'source_ts';
+        kind: 'first_project_frame';
+    };
+}
+/** The same strict schema is used for HTTP evidence; unknown fields are never copied. */
+export declare function selectTaskResumeFailure(value: unknown): TaskResumeFailure | undefined;
+/** Attribution only: a whitelisted project frame may be a caller of an external origin. */
+export declare function getTaskResumeFailure(error: unknown): TaskResumeFailure | undefined;

package/dist/api/tasks/TaskResumeDiagnostics.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_RESUME_SITE_MODULES = exports.TASK_RESUME_FAILURE_CODES = exports.TASK_RESUME_FAILURE_NAMES = exports.TASK_RESUME_ERROR_TYPES = exports.TASK_RESUME_STAGES = void 0;
+exports.getTaskResumeStage = getTaskResumeStage;
+exports.withTaskResumeStage = withTaskResumeStage;
+exports.getTaskResumeErrorType = getTaskResumeErrorType;
+exports.selectTaskResumeFailure = selectTaskResumeFailure;
+exports.getTaskResumeFailure = getTaskResumeFailure;
+const node_util_1 = require("node:util");
+/** Fixed resume boundaries, never derived from error prose or caller metadata. */
+exports.TASK_RESUME_STAGES = [
+    'route_request', 'route_validation', 'route_run_read', 'run_read', 'approval_validation',
+    'checkpoint_validation', 'task_lookup', 'task_auth_restore', 'invocation_issue',
+    'continuation_prepare', 'continuation_complete', 'continuation_release', 'run_result_read',
+];
+const stages = new WeakMap();
+function getTaskResumeStage(error) {
+    return error instanceof Error ? stages.get(error) : undefined;
+}
+/** First inner boundary wins; frozen errors and original throw semantics are preserved. */
+async function withTaskResumeStage(stage, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof Error && exports.TASK_RESUME_STAGES.includes(stage) && !stages.has(error))
+            stages.set(error, stage);
+        throw error;
+    }
+}
+exports.TASK_RESUME_ERROR_TYPES = ['error', 'type_error', 'range_error', 'syntax_error', 'non_error'];
+function getTaskResumeErrorType(error) {
+    if (error instanceof TypeError)
+        return 'type_error';
+    if (error instanceof RangeError)
+        return 'range_error';
+    if (error instanceof SyntaxError)
+        return 'syntax_error';
+    return error instanceof Error ? 'error' : 'non_error';
+}
+exports.TASK_RESUME_FAILURE_NAMES = ['Error', 'TypeError', 'RangeError', 'SyntaxError',
+    'ReferenceError', 'EvalError', 'URIError', 'AggregateError'];
+exports.TASK_RESUME_FAILURE_CODES = ['ENOSPC', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT',
+    'ENOTFOUND', 'EACCES', 'ERR_INVALID_URL'];
+exports.TASK_RESUME_SITE_MODULES = [
+    'api/runs/RunStateCenter', 'api/runs/InngestRunExecutionBackend', 'api/runs/ConditionalResourceDocument',
+    'api/runs/RunApproval', 'api/runs/RunCancellation', 'api/runs/ManagedRunWorker', 'api/runs/store',
+    'api/chatkit/pod-store', 'api/tasks/TaskMaterializer', 'api/tasks/TaskService', 'api/handlers/TaskHandler',
+];
+function ownValue(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor && 'value' in descriptor ? descriptor.value : undefined;
+}
+function allowed(value, values) {
+    return typeof value === 'string' && values.some(entry => entry === value);
+}
+function coordinate(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= 1_000_000;
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+/** The same strict schema is used for HTTP evidence; unknown fields are never copied. */
+function selectTaskResumeFailure(value) {
+    try {
+        if (!record(value) || Object.keys(value).some(key => !['name', 'code', 'causeCode', 'site'].includes(key)))
+            return undefined;
+        const name = ownValue(value, 'name');
+        if (!allowed(name, exports.TASK_RESUME_FAILURE_NAMES))
+            return undefined;
+        const result = { name };
+        for (const key of ['code', 'causeCode']) {
+            const code = ownValue(value, key);
+            if (Object.prototype.hasOwnProperty.call(value, key)) {
+                if (!allowed(code, exports.TASK_RESUME_FAILURE_CODES))
+                    return undefined;
+                result[key] = code;
+            }
+        }
+        if (Object.prototype.hasOwnProperty.call(value, 'site')) {
+            const site = ownValue(value, 'site');
+            if (!record(site) || Object.keys(site).some(key => !['module', 'line', 'column', 'coordinate', 'kind'].includes(key)))
+                return undefined;
+            const module = ownValue(site, 'module');
+            const line = ownValue(site, 'line');
+            const column = ownValue(site, 'column');
+            const location = ownValue(site, 'coordinate');
+            if (!allowed(module, exports.TASK_RESUME_SITE_MODULES) || !coordinate(line) || !coordinate(column)
+                || !allowed(location, ['compiled_js', 'source_ts']) || ownValue(site, 'kind') !== 'first_project_frame')
+                return undefined;
+            result.site = { module, line, column, coordinate: location, kind: 'first_project_frame' };
+        }
+        return result;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Attribution only: a whitelisted project frame may be a caller of an external origin. */
+function getTaskResumeFailure(error) {
+    try {
+        if (!node_util_1.types.isNativeError(error))
+            return undefined;
+        const native = error;
+        const name = native instanceof TypeError ? 'TypeError'
+            : native instanceof RangeError ? 'RangeError' : native instanceof SyntaxError ? 'SyntaxError'
+                : native instanceof ReferenceError ? 'ReferenceError' : native instanceof EvalError ? 'EvalError'
+                    : native instanceof URIError ? 'URIError' : native instanceof AggregateError ? 'AggregateError' : 'Error';
+        const result = { name };
+        const code = ownValue(native, 'code');
+        if (allowed(code, exports.TASK_RESUME_FAILURE_CODES))
+            result.code = code;
+        const cause = ownValue(native, 'cause');
+        const causeCode = node_util_1.types.isNativeError(cause) ? ownValue(cause, 'code') : undefined;
+        if (allowed(causeCode, exports.TASK_RESUME_FAILURE_CODES))
+            result.causeCode = causeCode;
+        for (const field of ['message', 'name']) {
+            const descriptor = Object.getOwnPropertyDescriptor(native, field);
+            if (descriptor && (!('value' in descriptor) || typeof descriptor.value !== 'string'
+                || descriptor.value.length > 8192 || /[\r\n]/.test(descriptor.value)))
+                return result;
+        }
+        const stack = ownValue(native, 'stack');
+        if (typeof stack !== 'string' || stack.length > 8192)
+            return result;
+        // Ignore the message line; parse only bounded V8/Bun frame lines, never eval or user paths.
+        for (const frame of stack.split('\n').slice(1, 17)) {
+            const match = /^\s+at (?:async )?(?:[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)* \()?((?:file:\/\/)?\/app\/(dist|src)\/(api\/[A-Za-z0-9/_-]+)\.(js|ts)):(\d{1,7}):(\d{1,7})\)?$/.exec(frame);
+            if (frame.includes('(') !== frame.endsWith(')'))
+                continue;
+            if (!match || (match[2] === 'dist' ? match[4] !== 'js' : match[4] !== 'ts'))
+                continue;
+            const module = match[3];
+            const line = Number(match[5]);
+            const column = Number(match[6]);
+            if (!allowed(module, exports.TASK_RESUME_SITE_MODULES) || !coordinate(line) || !coordinate(column))
+                continue;
+            result.site = { module, line, column, coordinate: match[2] === 'dist' ? 'compiled_js' : 'source_ts', kind: 'first_project_frame' };
+            break;
+        }
+        return result;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=TaskResumeDiagnostics.js.map

package/dist/api/tasks/TaskService.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TaskService = void 0;
+const TaskResumeDiagnostics_1 = require("./TaskResumeDiagnostics");
 const RunApproval_1 = require("../runs/RunApproval");
 const RunCancellation_1 = require("../runs/RunCancellation");
 const cron_1 = require("./cron");
@@ -146,23 +147,29 @@ class TaskService {
         return this.materializer.materialize({ task, context, trigger: { kind: 'manual' }, background: true });
     }
     async resumeApprovedRun(input, context, resolveExecutionContext) {
-        const run = await this.store.loadRun(input.runId, context);
-        const approval = await this.store.readTaskApproval?.(input.approval, context);
-        if (!approval || !['approved', 'rejected'].includes(approval.status)
-            || approval.decisionBy !== input.owner || (approval.assignedTo && approval.assignedTo !== input.owner) || !approval.resolvedAt
-            || approval.thread !== run.thread)
-            throw new Error('Approval does not authorize this run');
+        const run = await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('run_read', () => this.store.loadRun(input.runId, context));
+        const approval = await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('approval_validation', async () => {
+            const approval = await this.store.readTaskApproval?.(input.approval, context);
+            if (!approval || !['approved', 'rejected'].includes(approval.status)
+                || approval.decisionBy !== input.owner || (approval.assignedTo && approval.assignedTo !== input.owner) || !approval.resolvedAt
+                || approval.thread !== run.thread)
+                throw new Error('Approval does not authorize this run');
+            return approval;
+        });
         const threadRef = (0, types_1.toThreadRef)({ thread_id: run.thread });
         const output = JSON.stringify({ kind: 'approval_decision', approval: input.approval, decision: approval.status, actionExecuted: false });
         const waiting = run.metadata?.waitingTool;
         // Bind the checkpoint to this Run through the durable waiting-tool receipt. The receipt
         // lives on the Run row, independent of the client_tool_call item's free-form metadata;
         // `metadata.runId` remains only as a fallback for runs that predate the receipt.
-        const items = await this.store.loadThreadItems(threadRef, undefined, 1000, 'asc', context);
-        const item = items.data.find(item => item.type === 'client_tool_call' && item.call_id === approval.toolCallId
-            && (waiting?.itemId !== undefined ? item.id === waiting.itemId : item.metadata?.runId === run.id));
-        if (!item || item.type !== 'client_tool_call' || item.name !== approval.toolName)
-            throw new Error('Approval does not match the pending tool checkpoint');
+        const item = await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('checkpoint_validation', async () => {
+            const items = await this.store.loadThreadItems(threadRef, undefined, 1000, 'asc', context);
+            const item = items.data.find(item => item.type === 'client_tool_call' && item.call_id === approval.toolCallId
+                && (waiting?.itemId !== undefined ? item.id === waiting.itemId : item.metadata?.runId === run.id));
+            if (!item || item.type !== 'client_tool_call' || item.name !== approval.toolName)
+                throw new Error('Approval does not match the pending tool checkpoint');
+            return item;
+        });
         const atCheckpoint = waiting?.itemId === item.id && waiting.requestId === approval.toolCallId;
         if (item.status === 'completed' && item.output === output) {
             if (approval.status === 'rejected' && atCheckpoint && run.status === 'waiting_input') {
@@ -173,10 +180,14 @@ class TaskService {
                 await (0, RunApproval_1.updateRunApprovalSession)(this.store, run, 'completed', context);
             return { run, resumed: false, duplicate: true };
         }
-        if (approval.expiresAt && new Date(approval.expiresAt).getTime() <= Date.now())
-            throw new Error('Approval has expired');
-        if (run.status !== 'waiting_input' || waiting?.itemId !== item.id || waiting.requestId !== approval.toolCallId)
-            throw new Error('Run is not waiting at this approval checkpoint');
+        await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('approval_validation', async () => {
+            if (approval.expiresAt && new Date(approval.expiresAt).getTime() <= Date.now())
+                throw new Error('Approval has expired');
+        });
+        await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('checkpoint_validation', async () => {
+            if (run.status !== 'waiting_input' || waiting?.itemId !== item.id || waiting.requestId !== approval.toolCallId)
+                throw new Error('Run is not waiting at this approval checkpoint');
+        });
         if (approval.status === 'rejected') {
             await this.store.saveItem(threadRef, { ...item, status: 'completed', output, metadata: { ...item.metadata, approval: input.approval } }, context);
             const cancelled = await (0, RunCancellation_1.cancelRun)({ store: this.store, runId: run.id, context, resourceIri: () => run.id });
@@ -186,17 +197,23 @@ class TaskService {
         // must still restore their separately granted execution credential.
         let execution = context;
         if (run.task) {
-            const tasks = await this.store.listTasks({}, context);
-            const task = tasks.find(task => task.id === run.task);
-            if (!task)
-                throw new Error('Task not found for this run');
-            const granted = await resolveExecutionContext?.(task, context);
-            if (!granted)
-                throw new Error('Agent execution credential is unavailable');
+            const task = await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('task_lookup', async () => {
+                const tasks = await this.store.listTasks({}, context);
+                const task = tasks.find(task => task.id === run.task);
+                if (!task)
+                    throw new Error('Task not found for this run');
+                return task;
+            });
+            const granted = await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('task_auth_restore', async () => {
+                const granted = await resolveExecutionContext?.(task, context);
+                if (!granted)
+                    throw new Error('Agent execution credential is unavailable');
+                return granted;
+            });
             execution = granted;
         }
         const resumed = await this.materializer.resumeClientToolOutput(run, item.id, output, input.approval, execution);
-        return { run: await this.store.loadRun(run.id, context), resumed, ...(!resumed ? { duplicate: true } : {}) };
+        return { run: await (0, TaskResumeDiagnostics_1.withTaskResumeStage)('run_result_read', () => this.store.loadRun(run.id, context)), resumed, ...(!resumed ? { duplicate: true } : {}) };
     }
     async materializeDueTasks(context, options = {}) {
         const now = options.now ?? (0, types_1.nowTimestamp)();

package/dist/storage/conditions/StorageETagHandler.d.ts

@@ -1,5 +1,5 @@
 import { type ETagHandler, type RepresentationMetadata } from '@solid/community-server';
-/** Render an operational storage revision for the negotiated representation. */
+/** Finalize an isolated response copy with its negotiated HTTP tag. */
 export declare function getStorageETag(metadata: RepresentationMetadata): string | undefined;
 /** Persisted revision authority for reads, conditional mutations and notifications. */
 export declare class StorageETagHandler implements ETagHandler {

package/dist/storage/conditions/StorageETagHandler.js

@@ -2,20 +2,29 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageETagHandler = void 0;
 exports.getStorageETag = getStorageETag;
+const community_server_1 = require("@solid/community-server");
+const n3_1 = require("n3");
 const StorageVersion_1 = require("../StorageVersion");
-/** Render an operational storage revision for the negotiated representation. */
-function getStorageETag(metadata) {
+function renderStorageETag(metadata) {
     const revision = (0, StorageVersion_1.getStorageVersion)(metadata);
     if (revision && metadata.contentType) {
         return `"xpod-${revision}-${Buffer.from(metadata.contentType).toString('base64url')}"`;
     }
-    // Uninitialized metadata cannot establish a safe write baseline.
     return undefined;
 }
+/** Finalize an isolated response copy with its negotiated HTTP tag. */
+function getStorageETag(metadata) {
+    const tag = renderStorageETag(metadata);
+    // CSS merges response metadata into a 304 error that already contains this tag. Keeping the raw
+    // revision here creates two ETag values; the persisted revision remains recoverable from the tag.
+    if (tag)
+        metadata.set(community_server_1.HH.terms.etag, n3_1.DataFactory.literal(tag));
+    return tag;
+}
 /** Persisted revision authority for reads, conditional mutations and notifications. */
 class StorageETagHandler {
     getETag(metadata) {
-        return getStorageETag(metadata);
+        return renderStorageETag(metadata);
     }
     matchesETag(metadata, eTag, strict) {
         const parsed = StorageVersion_1.STORAGE_ETAG_PATTERN.exec(eTag);

package/dist/util/task-model-diagnostics.d.ts

@@ -0,0 +1,67 @@
+export declare const TASK_MODEL_DIAGNOSTIC_STAGES: readonly ["not_invoked", "model_invoked", "payload_prepared", "stream_open"];
+export declare const TASK_MODEL_DIAGNOSTIC_APIS: readonly ["openai-completions", "openai-responses", "other"];
+export declare const TASK_MODEL_DIAGNOSTIC_STOP_REASONS: readonly ["error", "aborted", "unknown"];
+export declare const TASK_GATEWAY_DIAGNOSTIC_ROUTES: readonly ["chat_completions", "responses", "anthropic_messages"];
+export declare const TASK_GATEWAY_DIAGNOSTIC_CODES: readonly ["invalid_request", "invalid_tool_arguments", "unsupported_protocol_event", "service_access_missing", "credential_unavailable", "model_not_available", "no_model_available", "embedding_model_not_allowed", "provider_error", "internal_error"];
+export declare const TASK_MODEL_SDK_ERROR_KINDS: readonly ["http_status", "connection", "timeout", "aborted", "length_limit", "content_filter", "unknown"];
+export type TaskModelSdkErrorKind = typeof TASK_MODEL_SDK_ERROR_KINDS[number];
+/**
+ * Bounded classification of the SDK-formatted provider error message. The SDK
+ * discards the structured HTTP response, so this is explicitly a hint and never
+ * a measured HTTP status; the raw message (which may embed a response body) is
+ * never retained.
+ */
+export interface TaskModelSdkErrorHint {
+    kind: TaskModelSdkErrorKind;
+    /** Present only for kind 'http_status'; parsed from the SDK's fixed "<status> <message>" prefix. */
+    status?: number;
+}
+export interface TaskModelDiagnosticReceipt {
+    event: 'xpod.task-model-diagnostic';
+    schemaVersion: 1;
+    /** The existing invocation header identifies a session, not a unique Run. */
+    scope: 'session';
+    correlationHash: string;
+    stage: typeof TASK_MODEL_DIAGNOSTIC_STAGES[number];
+    api: typeof TASK_MODEL_DIAGNOSTIC_APIS[number];
+    stopReason: typeof TASK_MODEL_DIAGNOSTIC_STOP_REASONS[number];
+    retryCount: number;
+    credentialPresent: boolean;
+    /** The SDK discards the structured HTTP status before emitting an error. */
+    httpStatus: null;
+    /** Bounded hint derived from the SDK error message; never the raw text. */
+    sdkErrorHint?: TaskModelSdkErrorHint;
+}
+export interface TaskGatewayDiagnosticReceipt {
+    event: 'xpod.task-gateway-diagnostic';
+    schemaVersion: 1;
+    scope: 'session';
+    correlationHash: string;
+    route: typeof TASK_GATEWAY_DIAGNOSTIC_ROUTES[number];
+    callerHTTPstatus: number;
+    code: typeof TASK_GATEWAY_DIAGNOSTIC_CODES[number];
+    underlyingErrorStatus?: number;
+    streamOpen: boolean;
+    durationMs: number;
+}
+export interface TaskGatewayHttpDiagnosticReceipt {
+    event: 'xpod.task-gateway-http-diagnostic';
+    schemaVersion: 1;
+    scope: 'session';
+    correlationHash: string;
+    route: typeof TASK_GATEWAY_DIAGNOSTIC_ROUTES[number];
+    callerHTTPstatus: number;
+    statusSource: 'response_finished' | 'response_closed';
+    durationMs: number;
+}
+export type TaskModelFailureDiagnostic = TaskModelDiagnosticReceipt | TaskGatewayDiagnosticReceipt | TaskGatewayHttpDiagnosticReceipt;
+/** Hash the exact header bytes; malformed headers never enter a diagnostic receipt. */
+export declare function hashTaskModelDiagnosticSession(sessionHeader: unknown): string | undefined;
+/**
+ * Classify the installed SDK's provider error message into a fixed enum.
+ * Only the SDK's own leading status prefix and exact error constants are
+ * recognized; embedded response text is never inspected or retained.
+ */
+export declare function classifyTaskModelSdkErrorHint(message: unknown): TaskModelSdkErrorHint | undefined;
+/** The sole field allowlist used by producers and the candidate artifact projector. */
+export declare function selectTaskModelDiagnosticReceipt(value: unknown): TaskModelFailureDiagnostic | undefined;