@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/tunnel/TunnelDeclaredOrigin.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDeclaredIngressOrigin = readDeclaredIngressOrigin;
+exports.readCloudflareRemoteOrigin = readCloudflareRemoteOrigin;
+const node_child_process_1 = require("node:child_process");
+const LocalTunnelProvider_1 = require("./LocalTunnelProvider");
+const SakuraFrpTunnelProvider_1 = require("./SakuraFrpTunnelProvider");
+const TunnelClientResolver_1 = require("./TunnelClientResolver");
+const TunnelProviderCatalog_1 = require("./TunnelProviderCatalog");
+const DEFAULT_CLOUDFLARE_READ_TIMEOUT_MS = 20_000;
+/**
+ * Reads the origin the active profile's console declares, using that provider's own reader.
+ *
+ * A provider that owns the origin at runtime (`originOwner: 'runtime'`) has nothing to read:
+ * the port is ours to choose, and pretending otherwise would invent a console value.
+ */
+async function readDeclaredIngressOrigin(profile, options = {}) {
+    const provider = (0, TunnelProviderCatalog_1.parseTunnelProvider)(profile.provider);
+    const descriptor = (0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(provider);
+    if (!provider || !descriptor) {
+        return { error: `profile ${profile.id} declares unknown provider ${profile.provider}` };
+    }
+    if (descriptor.originOwner !== 'console') {
+        return { error: `provider ${descriptor.id} chooses its own origin port, so it declares none` };
+    }
+    const env = options.env ?? process.env;
+    const token = (profile.credentialEnvKey ? env[profile.credentialEnvKey] : undefined)
+        ?? env[descriptor.legacyCredentialEnvKey];
+    if (!token?.trim()) {
+        return { error: `${descriptor.id} profile ${profile.id} has no credential configured` };
+    }
+    if (descriptor.id === 'sakura_frp') {
+        const readSakura = options.readSakura ?? SakuraFrpTunnelProvider_1.resolveSakuraAssignedLocalPort;
+        const port = await readSakura(token, {
+            ...(options.sakuraApiBaseUrl ? { apiBaseUrl: options.sakuraApiBaseUrl } : {}),
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        });
+        if (port === undefined) {
+            return { error: 'the SakuraFrp console reported no local_port for this credential (GET /v4/tunnels)' };
+        }
+        return { origin: { port, readBack: 'sakura_frp:GET /v4/tunnels local_port' } };
+    }
+    if (descriptor.id === 'cloudflare') {
+        if (options.active === false) {
+            return {
+                error: 'the Cloudflare dashboard origin is only read back for the active profile '
+                    + '(reading it starts a connector, and an inactive profile must not start one)',
+            };
+        }
+        const readCloudflare = options.readCloudflare ?? readCloudflareRemoteOrigin;
+        const resolved = await readCloudflare(token, {
+            command: resolveCloudflaredCommand(options),
+            timeoutMs: options.timeoutMs ?? DEFAULT_CLOUDFLARE_READ_TIMEOUT_MS,
+            env,
+        });
+        if (!resolved.origin) {
+            return { error: resolved.error };
+        }
+        return { origin: resolved.origin };
+    }
+    return { error: `provider ${descriptor.id} has no console origin reader` };
+}
+function resolveCloudflaredCommand(options) {
+    try {
+        return (0, TunnelClientResolver_1.resolveTunnelClient)('cloudflare', {
+            ...(options.cloudflaredPath ? { explicitPath: options.cloudflaredPath } : {}),
+            ...(options.env ? { env: options.env } : {}),
+        }).command;
+    }
+    catch {
+        // A configured-but-missing path must surface through the spawn error path, which reuses
+        // the same `binary-missing:<provider>:<binary>` message the providers report.
+        return options.cloudflaredPath ?? 'cloudflared';
+    }
+}
+/**
+ * Reads the remote configuration of a named tunnel from the connector that fetches it.
+ *
+ * A named tunnel's ingress is stored at Cloudflare, and the connector token is not a
+ * Cloudflare API credential, so the only local read-back is what cloudflared itself echoes
+ * when it fetches that configuration. The parser is `readDashboardOrigin` — the same one
+ * `LocalTunnelProvider` uses for its `origin-mismatch` diagnostic — so the two cannot drift.
+ *
+ * The probe connector is short-lived and is always terminated; the runtime's real connector
+ * starts later, and a tunnel tolerates several connectors while it is up.
+ */
+async function readCloudflareRemoteOrigin(token, options) {
+    const spawnImpl = options.spawnImpl ?? node_child_process_1.spawn;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CLOUDFLARE_READ_TIMEOUT_MS;
+    const log = [];
+    return await new Promise((resolve) => {
+        let settled = false;
+        let child;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            terminate(child);
+            resolve({ ...result, log });
+        };
+        const timer = setTimeout(() => {
+            finish({
+                error: `cloudflared did not report the tunnel's remote configuration within ${timeoutMs}ms `
+                    + '(a locally-managed tunnel keeps its ingress in a config file, which is not read back)',
+            });
+        }, timeoutMs);
+        timer.unref?.();
+        try {
+            child = spawnImpl(options.command, [
+                'tunnel',
+                '--no-autoupdate',
+                '--protocol', 'http2',
+                'run',
+                '--token',
+                token,
+            ], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: options.env,
+            });
+        }
+        catch (error) {
+            finish({ error: `cloudflared could not be started: ${error.message}` });
+            return;
+        }
+        const consume = (chunk) => {
+            for (const line of chunk.toString().split('\n')) {
+                if (!line.includes('service')) {
+                    continue;
+                }
+                log.push(line.trim().slice(0, 400));
+                const declared = (0, LocalTunnelProvider_1.readDashboardOrigin)(line);
+                if (declared) {
+                    finish({
+                        origin: {
+                            port: declared.port,
+                            scheme: declared.scheme,
+                            readBack: 'cloudflare:connector remote-config',
+                        },
+                    });
+                    return;
+                }
+            }
+        };
+        child.stdout?.on('data', consume);
+        child.stderr?.on('data', consume);
+        child.once('error', (error) => {
+            finish({ error: describeCloudflaredFailure(options.command, error) });
+        });
+        child.once('exit', (code) => {
+            finish({
+                error: `cloudflared exited with code ${code} before reporting the tunnel's remote configuration`,
+            });
+        });
+    });
+}
+function describeCloudflaredFailure(command, error) {
+    const code = error.code;
+    if (code === 'ENOENT') {
+        return `binary-missing:cloudflare:${command} (cloudflared is not installed or not on PATH)`;
+    }
+    return `cloudflared could not be started: ${error.message}`;
+}
+function terminate(child) {
+    if (!child || child.exitCode !== null) {
+        return;
+    }
+    try {
+        child.kill('SIGTERM');
+    }
+    catch {
+        return;
+    }
+    const killTimer = setTimeout(() => {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            // Already gone.
+        }
+    }, 2_000);
+    killTimer.unref?.();
+}
+//# sourceMappingURL=TunnelDeclaredOrigin.js.map

package/dist/tunnel/TunnelLifecycle.d.ts

@@ -10,5 +10,13 @@ import type { TunnelStage, TunnelStatus } from './TunnelProvider';
 export declare function createTunnelStatus(stage: TunnelStage, patch?: Partial<TunnelStatus>): TunnelStatus;
 /** Keeps the previous error visible while a provider transitions through a restart. */
 export declare function mergeTunnelError(previous: string | undefined, next: string | undefined): string | undefined;
-/** Recognizes a missing client binary, which is a deployment fact, not a network failure. */
+/**
+ * Recognizes a missing client binary, which is a deployment fact, not a network failure.
+ *
+ * The prefix stays `binary-missing:<provider>:<binary>` (callers and acceptance assert on it);
+ * `<provider>` is resolved to the catalog id first, so an implementation that calls itself
+ * `sakura-frp` cannot put a provider id into the message that no catalog lookup resolves.
+ * The install hint from the provider catalog is appended so an operator reading the failure
+ * knows what to install instead of having to search (audit N16).
+ */
 export declare function describeSpawnError(provider: string, binary: string, error: unknown): string;

package/dist/tunnel/TunnelLifecycle.js

@@ -1,8 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTunnelStatus = createTunnelStatus;
 exports.mergeTunnelError = mergeTunnelError;
 exports.describeSpawnError = describeSpawnError;
+const node_path_1 = __importDefault(require("node:path"));
+const TunnelClientResolver_1 = require("./TunnelClientResolver");
+const TunnelProviderCatalog_1 = require("./TunnelProviderCatalog");
 /**
  * Tunnel readiness is a sequence, not a boolean.
  *
@@ -23,12 +29,27 @@ function createTunnelStatus(stage, patch = {}) {
 function mergeTunnelError(previous, next) {
     return next ?? previous;
 }
-/** Recognizes a missing client binary, which is a deployment fact, not a network failure. */
+/**
+ * Recognizes a missing client binary, which is a deployment fact, not a network failure.
+ *
+ * The prefix stays `binary-missing:<provider>:<binary>` (callers and acceptance assert on it);
+ * `<provider>` is resolved to the catalog id first, so an implementation that calls itself
+ * `sakura-frp` cannot put a provider id into the message that no catalog lookup resolves.
+ * The install hint from the provider catalog is appended so an operator reading the failure
+ * knows what to install instead of having to search (audit N16).
+ */
 function describeSpawnError(provider, binary, error) {
     const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : '';
+    // `spawn-failed` is a plain diagnostic, but its provider segment is normalized the same way
+    // so both families of message name the same provider.
+    const id = (0, TunnelProviderCatalog_1.canonicalTunnelProviderId)(provider) ?? provider;
     if (code === 'ENOENT') {
-        return `binary-missing:${provider}:${binary}`;
+        // The prefix stays `binary-missing:<provider>:<binary name>` because callers assert on it;
+        // when the command was an absolute path, which file was tried is appended for the operator.
+        const name = node_path_1.default.basename(binary);
+        const message = (0, TunnelClientResolver_1.describeTunnelClientMissing)(id, name);
+        return name === binary ? message : `${message} (tried: ${binary})`;
     }
-    return `spawn-failed:${provider}:${error?.message ?? String(error)}`;
+    return `spawn-failed:${id}:${error?.message ?? String(error)}`;
 }
 //# sourceMappingURL=TunnelLifecycle.js.map

package/dist/tunnel/TunnelProviderCatalog.d.ts

@@ -21,9 +21,32 @@ export interface TunnelProviderParameterField {
     key: string;
     label: string;
 }
+/**
+ * The local client this provider needs (audit N16).
+ *
+ * Declared here so there is one place that knows the executable name, how an operator points at
+ * a specific build, whether the artifact may ship the binary at all, and what to tell them when
+ * it is missing. Providers consume it instead of each keeping its own default string.
+ */
+export interface TunnelProviderClient {
+    /** Executable name; also the name reported in `binary-missing:<provider>:<binary>`. */
+    binary: string;
+    /** Env var that names an explicit path; highest precedence, and never silently ignored. */
+    envKey: string;
+    /** Where an operator can get it (shown next to a missing-binary failure). */
+    installHint: string;
+    /**
+     * Whether the release artifact may ship this binary. ngrok and the natfrp frpc fork are not
+     * ours to redistribute; cloudflared and upstream frpc are Apache-2.0 and could be bundled.
+     */
+    redistributable: boolean;
+    /** Upstream licence / redistribution note, for whoever changes that decision later. */
+    license: string;
+}
 export interface TunnelProviderDescriptor {
     id: TunnelProviderId;
     label: string;
+    client: TunnelProviderClient;
     /** Legacy provider-scoped credential key, still honoured for single-profile setups. */
     legacyCredentialEnvKey: string;
     /** Legacy env keys that used to declare this provider's public entry. */
@@ -52,6 +75,15 @@ export interface TunnelProviderDescriptor {
 export declare const TUNNEL_PROVIDERS: readonly TunnelProviderDescriptor[];
 /** Normalizes any stored/legacy spelling onto the canonical provider vocabulary. */
 export declare function parseTunnelProvider(value: unknown): ActiveTunnelProvider | undefined;
+/**
+ * The one spelling of a provider that may appear in machine-readable messages.
+ *
+ * Provider implementations and callers historically used their own hyphenated names
+ * (`sakura-frp`), which is how a failure detail ended up carrying a provider id that no
+ * catalog lookup could resolve. Anything that renders a provider into a message resolves it
+ * here first, so the catalog id is the only one that can reach an operator.
+ */
+export declare function canonicalTunnelProviderId(value: unknown): TunnelProviderId | undefined;
 export declare function isTunnelProviderId(value: unknown): value is TunnelProviderId;
 export declare function tunnelProviderDescriptor(id: unknown): TunnelProviderDescriptor | undefined;
 export declare function tunnelProviderIds(): TunnelProviderId[];

package/dist/tunnel/TunnelProviderCatalog.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TUNNEL_PROFILE_CREDENTIAL_PREFIX = exports.TUNNEL_PROVIDERS = exports.TUNNEL_PROVIDER_IDS = void 0;
 exports.parseTunnelProvider = parseTunnelProvider;
+exports.canonicalTunnelProviderId = canonicalTunnelProviderId;
 exports.isTunnelProviderId = isTunnelProviderId;
 exports.tunnelProviderDescriptor = tunnelProviderDescriptor;
 exports.tunnelProviderIds = tunnelProviderIds;
@@ -32,6 +33,14 @@ exports.TUNNEL_PROVIDERS = [
     {
         id: 'ngrok',
         label: 'ngrok',
+        client: {
+            binary: 'ngrok',
+            envKey: 'NGROK_BIN',
+            installHint: 'install the ngrok agent and put it on PATH (or set NGROK_BIN)',
+            // ngrok's agent is proprietary: bundling it in our artifact needs their permission.
+            redistributable: false,
+            license: 'proprietary (ngrok terms of service)',
+        },
         legacyCredentialEnvKey: 'NGROK_AUTHTOKEN',
         legacyPublicUrlKeys: ['NGROK_URL'],
         endpointSource: 'discovered',
@@ -46,6 +55,13 @@ exports.TUNNEL_PROVIDERS = [
     {
         id: 'cloudflare',
         label: 'Cloudflare Tunnel',
+        client: {
+            binary: 'cloudflared',
+            envKey: 'CLOUDFLARED_BIN',
+            installHint: 'install cloudflared and put it on PATH (or set CLOUDFLARED_BIN)',
+            redistributable: true,
+            license: 'Apache-2.0',
+        },
         legacyCredentialEnvKey: 'CLOUDFLARE_TUNNEL_TOKEN',
         legacyPublicUrlKeys: ['CLOUDFLARE_TUNNEL_URL', 'XPOD_TUNNEL_PUBLIC_URL'],
         // The hostname is configured in the Cloudflare dashboard and cloudflared is only
@@ -61,6 +77,14 @@ exports.TUNNEL_PROVIDERS = [
     {
         id: 'sakura_frp',
         label: 'Sakura FRP',
+        client: {
+            binary: 'frpc',
+            envKey: 'FRPC_BIN',
+            // The official client is required: upstream frpc cannot express `-f <token>`.
+            installHint: 'install the natfrp client (its frpc accepts `-f <token>`) and put it on PATH',
+            redistributable: false,
+            license: 'natfrp fork (no published source; redistribution needs their permission)',
+        },
         legacyCredentialEnvKey: 'SAKURA_TUNNEL_TOKEN',
         legacyPublicUrlKeys: ['SAKURA_TUNNEL_URL', 'XPOD_TUNNEL_PUBLIC_URL'],
         // The console only asks for a node and a local port: the public entry (node host +
@@ -76,6 +100,13 @@ exports.TUNNEL_PROVIDERS = [
     {
         id: 'frp',
         label: 'FRP',
+        client: {
+            binary: 'frpc',
+            envKey: 'FRPC_BIN',
+            installHint: 'install upstream frpc and put it on PATH (or set FRPC_BIN)',
+            redistributable: true,
+            license: 'Apache-2.0',
+        },
         legacyCredentialEnvKey: 'FRP_TUNNEL_TOKEN',
         legacyPublicUrlKeys: ['FRP_TUNNEL_URL'],
         endpointSource: 'declared',
@@ -101,6 +132,18 @@ function parseTunnelProvider(value) {
     }
     return PROVIDER_ALIASES[value.trim().toLowerCase()];
 }
+/**
+ * The one spelling of a provider that may appear in machine-readable messages.
+ *
+ * Provider implementations and callers historically used their own hyphenated names
+ * (`sakura-frp`), which is how a failure detail ended up carrying a provider id that no
+ * catalog lookup could resolve. Anything that renders a provider into a message resolves it
+ * here first, so the catalog id is the only one that can reach an operator.
+ */
+function canonicalTunnelProviderId(value) {
+    const provider = parseTunnelProvider(value);
+    return provider && provider !== 'none' ? provider : undefined;
+}
 function isTunnelProviderId(value) {
     return parseTunnelProvider(value) !== undefined && parseTunnelProvider(value) !== 'none';
 }

package/dist/util/identifiers/ClusterIdentifierStrategy.d.ts

@@ -10,6 +10,7 @@ export interface ClusterIdentifierStrategyOptions {
      */
     allowedHosts?: string[] | string;
 }
+export declare const SERVER_ROOT_SEGMENTS: Set<string>;
 /**
  * Identifier strategy that accepts both the primary cluster host and any
  * node subdomain under the same base domain.

package/dist/util/identifiers/ClusterIdentifierStrategy.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClusterIdentifierStrategy = void 0;
+exports.ClusterIdentifierStrategy = exports.SERVER_ROOT_SEGMENTS = void 0;
 const node_url_1 = require("node:url");
 const global_logger_factory_1 = require("global-logger-factory");
 const community_server_1 = require("@solid/community-server");
 const PathUtil_1 = require("@solid/community-server/dist/util/PathUtil");
-const SERVER_ROOT_SEGMENTS = new Set([
+exports.SERVER_ROOT_SEGMENTS = new Set([
     '.account',
     '.oidc',
     '.well-known',
@@ -104,7 +104,7 @@ class ClusterIdentifierStrategy extends community_server_1.BaseIdentifierStrateg
                 }
                 const relative = pathname.slice(basePath.length).replace(/^\/+/, '');
                 const segments = relative.split('/').filter(Boolean);
-                return segments.length === 1 && !SERVER_ROOT_SEGMENTS.has(segments[0].toLowerCase());
+                return segments.length === 1 && !exports.SERVER_ROOT_SEGMENTS.has(segments[0].toLowerCase());
             }
             return target.pathname === '/' || target.pathname === '';
         }

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;

package/dist/util/task-model-diagnostics.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_MODEL_SDK_ERROR_KINDS = exports.TASK_GATEWAY_DIAGNOSTIC_CODES = exports.TASK_GATEWAY_DIAGNOSTIC_ROUTES = exports.TASK_MODEL_DIAGNOSTIC_STOP_REASONS = exports.TASK_MODEL_DIAGNOSTIC_APIS = exports.TASK_MODEL_DIAGNOSTIC_STAGES = void 0;
+exports.hashTaskModelDiagnosticSession = hashTaskModelDiagnosticSession;
+exports.classifyTaskModelSdkErrorHint = classifyTaskModelSdkErrorHint;
+exports.selectTaskModelDiagnosticReceipt = selectTaskModelDiagnosticReceipt;
+const node_crypto_1 = require("node:crypto");
+exports.TASK_MODEL_DIAGNOSTIC_STAGES = [
+    'not_invoked', 'model_invoked', 'payload_prepared', 'stream_open',
+];
+exports.TASK_MODEL_DIAGNOSTIC_APIS = ['openai-completions', 'openai-responses', 'other'];
+exports.TASK_MODEL_DIAGNOSTIC_STOP_REASONS = ['error', 'aborted', 'unknown'];
+exports.TASK_GATEWAY_DIAGNOSTIC_ROUTES = ['chat_completions', 'responses', 'anthropic_messages'];
+exports.TASK_GATEWAY_DIAGNOSTIC_CODES = [
+    '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',
+];
+exports.TASK_MODEL_SDK_ERROR_KINDS = [
+    'http_status', 'connection', 'timeout', 'aborted', 'length_limit', 'content_filter', 'unknown',
+];
+/** Hash the exact header bytes; malformed headers never enter a diagnostic receipt. */
+function hashTaskModelDiagnosticSession(sessionHeader) {
+    if (typeof sessionHeader !== 'string'
+        || !/^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$/u.test(sessionHeader))
+        return undefined;
+    return (0, node_crypto_1.createHash)('sha256').update(sessionHeader).digest('hex');
+}
+function member(value, allowed) {
+    return typeof value === 'string' && allowed.some(entry => entry === value);
+}
+function boundedInteger(value, min, max) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= min && value <= max;
+}
+const SDK_ERROR_MESSAGE_LIMIT = 8192;
+// openai/core/error.mjs APIError.makeMessage prefixes "<status> " to the body message.
+const SDK_HTTP_STATUS_PREFIX = /^([45]\d{2}) \S/u;
+const SDK_EXACT_ERROR_KINDS = new Map([
+    ['Connection error.', 'connection'],
+    ['Request timed out.', 'timeout'],
+    ['Request was aborted.', 'aborted'],
+    ['Could not parse response content as the length limit was reached', 'length_limit'],
+    ['Could not parse response content as the request was rejected by the content filter', 'content_filter'],
+]);
+/**
+ * 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.
+ */
+function classifyTaskModelSdkErrorHint(message) {
+    if (typeof message !== 'string' || message.length === 0)
+        return undefined;
+    const head = message.slice(0, SDK_ERROR_MESSAGE_LIMIT);
+    const status = SDK_HTTP_STATUS_PREFIX.exec(head);
+    if (status) {
+        const code = Number(status[1]);
+        if (code >= 400 && code <= 599)
+            return { kind: 'http_status', status: code };
+    }
+    return { kind: SDK_EXACT_ERROR_KINDS.get(head) ?? 'unknown' };
+}
+function selectTaskModelSdkErrorHint(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const row = value;
+    if (!member(row.kind, exports.TASK_MODEL_SDK_ERROR_KINDS))
+        return undefined;
+    if (row.kind === 'http_status') {
+        return boundedInteger(row.status, 400, 599) ? { kind: 'http_status', status: row.status } : undefined;
+    }
+    return row.status === undefined ? { kind: row.kind } : undefined;
+}
+/** The sole field allowlist used by producers and the candidate artifact projector. */
+function selectTaskModelDiagnosticReceipt(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const row = value;
+    if (row.schemaVersion !== 1 || row.scope !== 'session'
+        || typeof row.correlationHash !== 'string' || !/^[a-f0-9]{64}$/u.test(row.correlationHash))
+        return undefined;
+    const common = { schemaVersion: 1, scope: 'session', correlationHash: row.correlationHash };
+    if (row.event === 'xpod.task-gateway-http-diagnostic') {
+        if (!member(row.route, exports.TASK_GATEWAY_DIAGNOSTIC_ROUTES) || !boundedInteger(row.callerHTTPstatus, 400, 599)
+            || (row.statusSource !== 'response_finished' && row.statusSource !== 'response_closed')
+            || !boundedInteger(row.durationMs, 0, 2147483647))
+            return undefined;
+        return { event: row.event, ...common, route: row.route, callerHTTPstatus: row.callerHTTPstatus,
+            statusSource: row.statusSource, durationMs: row.durationMs };
+    }
+    if (row.event === 'xpod.task-model-diagnostic') {
+        if (!member(row.stage, exports.TASK_MODEL_DIAGNOSTIC_STAGES) || !member(row.api, exports.TASK_MODEL_DIAGNOSTIC_APIS)
+            || !member(row.stopReason, exports.TASK_MODEL_DIAGNOSTIC_STOP_REASONS)
+            || !boundedInteger(row.retryCount, 0, Number.MAX_SAFE_INTEGER)
+            || typeof row.credentialPresent !== 'boolean' || row.httpStatus !== null)
+            return undefined;
+        const receipt = { event: row.event, ...common, stage: row.stage, api: row.api,
+            stopReason: row.stopReason, retryCount: row.retryCount, credentialPresent: row.credentialPresent, httpStatus: null };
+        if (row.sdkErrorHint !== undefined) {
+            const sdkErrorHint = selectTaskModelSdkErrorHint(row.sdkErrorHint);
+            if (!sdkErrorHint)
+                return undefined;
+            receipt.sdkErrorHint = sdkErrorHint;
+        }
+        return receipt;
+    }
+    if (row.event === 'xpod.task-gateway-diagnostic') {
+        if (!member(row.route, exports.TASK_GATEWAY_DIAGNOSTIC_ROUTES) || !member(row.code, exports.TASK_GATEWAY_DIAGNOSTIC_CODES)
+            || !boundedInteger(row.callerHTTPstatus, 100, 599) || typeof row.streamOpen !== 'boolean'
+            || !boundedInteger(row.durationMs, 0, 2147483647)
+            || (row.underlyingErrorStatus !== undefined && !boundedInteger(row.underlyingErrorStatus, 100, 599)))
+            return undefined;
+        return { event: row.event, ...common, route: row.route, callerHTTPstatus: row.callerHTTPstatus,
+            code: row.code, ...(row.underlyingErrorStatus === undefined ? {} : { underlyingErrorStatus: row.underlyingErrorStatus }),
+            streamOpen: row.streamOpen, durationMs: row.durationMs };
+    }
+    return undefined;
+}
+//# sourceMappingURL=task-model-diagnostics.js.map

package/node_modules/@inrupt/solid-client-authn-core/dist/authenticatedFetch/dpopUtils.d.ts

@@ -12,5 +12,7 @@ export type KeyPair = {
  * @param dpopKey Key used to sign the token.
  * @returns A JWT that can be used as a DPoP Authorization header.
  */
-export declare function createDpopHeader(audience: string, method: string, dpopKey: KeyPair): Promise<string>;
+export declare function createDpopHeader(audience: string, method: string, dpopKey: KeyPair, accessToken?: string): Promise<string>;
 export declare function generateDpopKeyPair(): Promise<KeyPair>;
+
+// XPOD_INRUPT_RESOURCE_DPOP_ATH