@north-light/api 0.3.580 → 0.3.588

package/dist/core/provider-credential.d.ts

@@ -0,0 +1,6 @@
+import type { ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';
+/** Whether the provider has a credential crouter can use. This is the same
+ * configured predicate shown by the setup Providers panel. */
+export declare function isProviderCredentialConfigured(providerId: string, registry: ModelRegistry): boolean;
+/** Whether any provider in the setup catalog has a usable configured credential. */
+export declare function hasProviderCredential(runtime: ModelRuntime, registry: ModelRegistry): Promise<boolean>;

package/dist/core/provider-credential.js

@@ -0,0 +1,17 @@
+/** Whether the provider has a credential crouter can use. This is the same
+ * configured predicate shown by the setup Providers panel. */
+export function isProviderCredentialConfigured(providerId, registry) {
+    // The credential store reads a managed provider's accounts, so the registry's status already counts them.
+    return registry.getProviderAuthStatus(providerId).configured;
+}
+/** Whether any provider in the setup catalog has a usable configured credential. */
+export async function hasProviderCredential(runtime, registry) {
+    const providerIds = new Set([
+        ...runtime.getProviders().map((provider) => provider.id),
+        ...registry.getAll().map((model) => model.provider),
+    ]);
+    for (const providerId of providerIds)
+        if (isProviderCredentialConfigured(providerId, registry))
+            return true;
+    return false;
+}

package/dist/core/provider-error-recognition.d.ts

@@ -0,0 +1,30 @@
+export type ProviderErrorSignalKind = 'rate-limit' | 'auth' | 'protocol' | 'context-overflow' | 'overloaded' | 'overloaded-only' | 'transient-http' | 'connection' | 'connection-only' | 'socket' | 'service-unavailable' | 'other';
+export type ProviderErrorMatchedOn = 'errno' | 'status' | 'websocket-close' | 'text' | 'none';
+export interface ProviderErrorTextMatch {
+    kind: ProviderErrorSignalKind;
+    match: string;
+}
+export interface ProviderErrorSignal {
+    kind: ProviderErrorSignalKind;
+    matchedOn: ProviderErrorMatchedOn;
+    status?: number;
+    retryAfterMs?: number;
+    match?: string;
+    textKind?: ProviderErrorSignalKind;
+    textMatch?: string;
+    textMatches?: readonly ProviderErrorTextMatch[];
+}
+export interface ProviderErrorRecognitionInput {
+    status?: unknown;
+    retryAfterMs?: number;
+    code?: unknown;
+    errno?: unknown;
+    wsCloseCode?: unknown;
+    wsCloseReason?: unknown;
+    message?: string;
+}
+/** The wording of the two subscription-refresh errors (`RefreshBusyError`, `RefreshTimeoutError` in `subscription-state.ts`), which build their messages from these phrases so the patterns below cannot drift from them. */
+export declare const REFRESH_BUSY_PHRASE = "is being refreshed by another process";
+export declare const REFRESH_TIMEOUT_PHRASE = "refresh did not answer within";
+/** Recognizes provider failure facts. Consumers apply their own retry policy. */
+export declare function recognizeProviderError(input: ProviderErrorRecognitionInput): ProviderErrorSignal;

package/dist/core/provider-error-recognition.js

@@ -0,0 +1,82 @@
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function signal(kind, matchedOn, options = {}) {
+    return { kind, matchedOn, ...options };
+}
+function withTextMatch(signal, textSignal) {
+    return textSignal.matchedOn === 'text'
+        ? { ...signal, textKind: textSignal.kind, textMatch: textSignal.match, textMatches: textSignal.textMatches }
+        : signal;
+}
+/** The wording of the two subscription-refresh errors (`RefreshBusyError`, `RefreshTimeoutError` in `subscription-state.ts`), which build their messages from these phrases so the patterns below cannot drift from them. */
+export const REFRESH_BUSY_PHRASE = 'is being refreshed by another process';
+export const REFRESH_TIMEOUT_PHRASE = 'refresh did not answer within';
+const TEXT_PATTERNS = [
+    // Anthropic's 400 for an exhausted workspace spend cap is a permanent refusal until the stated date, not a resettable usage window.
+    ['protocol', /workspace api usage limits?/i],
+    ['rate-limit', /rate.?limit|\b429\b|too many requests|usage[ _]limit|usage_not_included|usagelimiterror|insufficient_quota|quota exceeded/i],
+    ['protocol', /\b413\b|payload too large|entity too large|request too large|entity\.too\.large|body exceeds/i],
+    ['auth', /invalid_grant|refresh token|unauthori[sz]ed|invalid.?api.?key|authentication failed|\b401\b|\b403\b/i],
+    ['context-overflow', /context overflow recovery failed/i],
+    ['protocol', /websocket.*(?:closed.*\b(?:1002|1003|1007|1008|1009|1010)\b|protocol error|policy violation|unsupported data|invalid (?:frame|payload)|message too big|mandatory extension)/i],
+    ['overloaded-only', /lock file is already being held/i],
+    // A refresh of the same Claude/ChatGPT subscription is in flight in another process or its vendor exchange outlasted the exchange timeout: both end on their own, so retry.
+    ['overloaded', new RegExp(REFRESH_BUSY_PHRASE, 'i')],
+    ['connection', new RegExp(REFRESH_TIMEOUT_PHRASE, 'i')],
+    ['overloaded', /overloaded|temporarily unavailable/i],
+    ['service-unavailable', /service.?unavailable/i],
+    ['overloaded-only', /internal server error|api.?error|\b5\d\d\b|capacity|server.{0,3}busy/i],
+    ['connection', /connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout|websocket\s+(?:was\s+)?closed|websocket stream closed before response\.completed|websocket\s+error|websocket.*interrupt/i],
+    ['socket', /socket/i],
+    ['connection-only', /eai_again|epipe|ehostunreach|enetunreach|\bterminated\b|other side closed|premature close/i],
+];
+function recognizeText(message) {
+    // The order preserves the canonical taxonomy: size wins over wrapped 5xx prose,
+    // and auth wins over a generic API-error wrapper. Every match remains available
+    // because rotation deliberately gives transient text priority over rate-limit text.
+    const matches = TEXT_PATTERNS.flatMap(([kind, pattern]) => {
+        const match = message.match(pattern);
+        return match ? [{ kind, match: match[0] }] : [];
+    });
+    const first = matches[0];
+    return first === undefined ? signal('other', 'none') : { ...signal(first.kind, 'text', { match: first.match }), textMatches: matches };
+}
+/** Recognizes provider failure facts. Consumers apply their own retry policy. */
+export function recognizeProviderError(input) {
+    const retryAfterMs = input.retryAfterMs;
+    const textSignal = recognizeText(input.message ?? '');
+    const errno = text(input.code) || text(input.errno);
+    if (/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOENT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/i.test(errno)) {
+        return withTextMatch(signal('connection', 'errno', { retryAfterMs }), textSignal);
+    }
+    if (/^ELOCKED$/i.test(errno))
+        return withTextMatch(signal('overloaded', 'errno', { retryAfterMs }), textSignal);
+    const status = typeof input.status === 'number' ? input.status : undefined;
+    if (status !== undefined) {
+        if (status === 401 || status === 403)
+            return withTextMatch(signal('auth', 'status', { status, retryAfterMs }), textSignal);
+        if (status === 429)
+            return withTextMatch(signal('rate-limit', 'status', { status, retryAfterMs }), textSignal);
+        if (status === 500 || status === 502 || status === 503 || status === 504)
+            return withTextMatch(signal('transient-http', 'status', { status, retryAfterMs }), textSignal);
+        if (status >= 500 && status <= 599)
+            return withTextMatch(signal('overloaded', 'status', { status, retryAfterMs }), textSignal);
+        if (status >= 400 && status <= 499)
+            return withTextMatch(signal('protocol', 'status', { status, retryAfterMs }), textSignal);
+    }
+    const wsCloseCode = typeof input.wsCloseCode === 'number' ? input.wsCloseCode : undefined;
+    if (wsCloseCode === 1008)
+        return withTextMatch(signal('protocol', 'websocket-close', { retryAfterMs }), textSignal);
+    if (wsCloseCode === 1006)
+        return withTextMatch(signal('connection', 'websocket-close', { retryAfterMs }), textSignal);
+    if (wsCloseCode === 1011) {
+        const reason = text(input.wsCloseReason);
+        const reasonSignal = recognizeText(reason);
+        if (/no running broker/i.test(reason) || reasonSignal.kind === 'connection' || reasonSignal.kind === 'connection-only') {
+            return withTextMatch(signal('connection', 'websocket-close', { retryAfterMs }), textSignal);
+        }
+        return withTextMatch(signal('other', 'websocket-close', { retryAfterMs }), textSignal);
+    }
+    return retryAfterMs === undefined ? textSignal : { ...textSignal, retryAfterMs };
+}

package/dist/core/provider-failure.d.ts

@@ -0,0 +1,42 @@
+import type { AssistantMessageDiagnostic } from '@earendil-works/pi-ai';
+export declare const PROVIDER_FAILURE_DIAGNOSTIC = "crtr:provider-failure";
+export interface ProviderFailureCause {
+    message?: string;
+    status?: number;
+    code?: string | number;
+    errno?: string;
+    body?: string;
+}
+/** A 429's rate-limit facts: which scope it cooled and its rate-limit headers (no auth material). */
+export interface ProviderRateLimitDetails {
+    /** `account`, or `model:<family>` when only one model family on the account was cooled. */
+    scope?: string;
+    /** `anthropic-ratelimit-unified-representative-claim`, when the response carried one. */
+    claim?: string;
+    /** The account label that was rate-limited, for managed subscription pools. */
+    account?: string;
+    /** `provider/model` the 429 answered, when it differs from the fault's own model. */
+    model?: string;
+    headers: Record<string, string>;
+}
+export interface ProviderFailureDetails {
+    status?: number;
+    code?: string | number;
+    errno?: string;
+    body?: string;
+    causes?: ProviderFailureCause[];
+    ratelimit?: ProviderRateLimitDetails;
+}
+export interface NormalizedProviderFailure extends ProviderFailureDetails {
+    message: string;
+}
+/** Converts an arbitrary provider failure into serializable facts before an SDK stream flattens it to `errorMessage`. */
+export declare function normalizeProviderFailure(error: unknown, observed?: {
+    status?: number;
+}): NormalizedProviderFailure;
+/** The stable diagnostic carrier for normalized provider error facts on an assistant error message. */
+export declare function providerFailureDiagnostic(details: ProviderFailureDetails): AssistantMessageDiagnostic;
+/** Strictly parse a recorded rate-limit block: string headers only, capped, unknown keys dropped. */
+export declare function parseProviderRateLimit(value: unknown): ProviderRateLimitDetails | undefined;
+/** Reads provider facts from the assistant-message diagnostic without trusting arbitrary nested error objects. */
+export declare function extractProviderFailureDetails(message: unknown): ProviderFailureDetails | undefined;

package/dist/core/provider-failure.js

@@ -0,0 +1,145 @@
+import { isRecord } from '../shared/predicates.js';
+export const PROVIDER_FAILURE_DIAGNOSTIC = 'crtr:provider-failure';
+const CAUSE_LIMIT = 8;
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function status(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function code(value) {
+    return typeof value === 'string' || typeof value === 'number' ? value : undefined;
+}
+function record(value) {
+    return isRecord(value) ? value : undefined;
+}
+function failureCause(value) {
+    const message = text(value['errorMessage']) ?? text(value['message']) ?? text(value['reason']) ?? text(value['statusText']);
+    const cause = {
+        ...(message === undefined ? {} : { message }),
+        ...(status(value['status']) === undefined ? {} : { status: status(value['status']) }),
+        ...(code(value['code']) === undefined ? {} : { code: code(value['code']) }),
+        ...(text(value['errno']) === undefined ? {} : { errno: text(value['errno']) }),
+        ...(text(value['body']) === undefined ? {} : { body: text(value['body']) }),
+    };
+    return Object.keys(cause).length === 0 ? undefined : cause;
+}
+/** Converts an arbitrary provider failure into serializable facts before an SDK stream flattens it to `errorMessage`. */
+export function normalizeProviderFailure(error, observed = {}) {
+    const root = record(error);
+    const rootCause = root === undefined ? undefined : failureCause(root);
+    const causes = [];
+    const seen = new Set([error]);
+    let current = root === undefined ? undefined : record(root['cause']);
+    while (current !== undefined && !seen.has(current) && causes.length < CAUSE_LIMIT) {
+        seen.add(current);
+        const cause = failureCause(current);
+        if (cause !== undefined)
+            causes.push(cause);
+        current = record(current['cause']);
+    }
+    const message = rootCause?.message ?? (error instanceof Error ? error.message : undefined) ?? String(error ?? 'Provider request failed');
+    return {
+        message,
+        ...((observed.status ?? rootCause?.status) === undefined ? {} : { status: observed.status ?? rootCause?.status }),
+        ...(rootCause?.code === undefined ? {} : { code: rootCause.code }),
+        ...(rootCause?.errno === undefined ? {} : { errno: rootCause.errno }),
+        ...(rootCause?.body === undefined ? {} : { body: rootCause.body }),
+        ...(causes.length === 0 ? {} : { causes }),
+    };
+}
+/** The stable diagnostic carrier for normalized provider error facts on an assistant error message. */
+export function providerFailureDiagnostic(details) {
+    return { type: PROVIDER_FAILURE_DIAGNOSTIC, timestamp: Date.now(), details: jsonDetails(details) };
+}
+/** pi types diagnostic details as strict JSON, which excludes `undefined`; every
+ *  field here is a JSON scalar or a list of them by declaration, so dropping the
+ *  absent keys is the only conversion needed. */
+function jsonDetails(details) {
+    const out = jsonCause(details);
+    if (details.causes !== undefined)
+        out['causes'] = details.causes.map(jsonCause);
+    if (details.ratelimit !== undefined) {
+        const ratelimit = { headers: { ...details.ratelimit.headers } };
+        if (details.ratelimit.scope !== undefined)
+            ratelimit['scope'] = details.ratelimit.scope;
+        if (details.ratelimit.claim !== undefined)
+            ratelimit['claim'] = details.ratelimit.claim;
+        if (details.ratelimit.account !== undefined)
+            ratelimit['account'] = details.ratelimit.account;
+        if (details.ratelimit.model !== undefined)
+            ratelimit['model'] = details.ratelimit.model;
+        out['ratelimit'] = ratelimit;
+    }
+    return out;
+}
+const RATELIMIT_HEADER_LIMIT = 48;
+const RATELIMIT_VALUE_LIMIT = 256;
+/** Strictly parse a recorded rate-limit block: string headers only, capped, unknown keys dropped. */
+export function parseProviderRateLimit(value) {
+    const raw = record(value);
+    const rawHeaders = record(raw?.['headers']);
+    if (raw === undefined || rawHeaders === undefined)
+        return undefined;
+    const headers = {};
+    for (const [name, header] of Object.entries(rawHeaders)) {
+        if (Object.keys(headers).length >= RATELIMIT_HEADER_LIMIT)
+            break;
+        if (typeof header === 'string')
+            headers[name.toLowerCase()] = header.slice(0, RATELIMIT_VALUE_LIMIT);
+    }
+    return {
+        ...(text(raw['scope']) === undefined ? {} : { scope: text(raw['scope']) }),
+        ...(text(raw['claim']) === undefined ? {} : { claim: text(raw['claim']) }),
+        ...(text(raw['account']) === undefined ? {} : { account: text(raw['account']) }),
+        ...(text(raw['model']) === undefined ? {} : { model: text(raw['model']) }),
+        headers,
+    };
+}
+function jsonCause(cause) {
+    const out = {};
+    if (cause.message !== undefined)
+        out['message'] = cause.message;
+    if (cause.status !== undefined)
+        out['status'] = cause.status;
+    if (cause.code !== undefined)
+        out['code'] = cause.code;
+    if (cause.errno !== undefined)
+        out['errno'] = cause.errno;
+    if (cause.body !== undefined)
+        out['body'] = cause.body;
+    return out;
+}
+function providerFailureDetails(value) {
+    const diagnostics = record(value)?.['diagnostics'];
+    if (!Array.isArray(diagnostics))
+        return undefined;
+    for (const diagnostic of diagnostics) {
+        const diagnosticRecord = record(diagnostic);
+        if (diagnosticRecord?.['type'] !== PROVIDER_FAILURE_DIAGNOSTIC)
+            continue;
+        const details = record(diagnosticRecord['details']);
+        if (details === undefined)
+            continue;
+        const causes = Array.isArray(details['causes'])
+            ? details['causes'].flatMap((item) => {
+                const cause = record(item);
+                const normalized = cause === undefined ? undefined : failureCause(cause);
+                return normalized === undefined ? [] : [normalized];
+            })
+            : undefined;
+        return {
+            ...(status(details['status']) === undefined ? {} : { status: status(details['status']) }),
+            ...(code(details['code']) === undefined ? {} : { code: code(details['code']) }),
+            ...(text(details['errno']) === undefined ? {} : { errno: text(details['errno']) }),
+            ...(text(details['body']) === undefined ? {} : { body: text(details['body']) }),
+            ...(causes === undefined || causes.length === 0 ? {} : { causes }),
+            ...(parseProviderRateLimit(details['ratelimit']) === undefined ? {} : { ratelimit: parseProviderRateLimit(details['ratelimit']) }),
+        };
+    }
+    return undefined;
+}
+/** Reads provider facts from the assistant-message diagnostic without trusting arbitrary nested error objects. */
+export function extractProviderFailureDetails(message) {
+    return providerFailureDetails(message);
+}

package/dist/core/provider-management.d.ts

@@ -0,0 +1,11 @@
+import type { CrtrClient } from '../api/client.js';
+/** The minimal shape of a Providers-panel row the removal router needs. */
+export interface RemovableProviderRow {
+    providerId: string;
+    name: string;
+    managed: boolean;
+    configured?: boolean;
+    label?: string;
+}
+/** Route a row's removal through the daemon and return the truthful panel notice. A managed account row removes that account only; a managed header row or a non-managed provider removes every credential for the provider. May throw (e.g. an unknown account) — callers surface that as the notice. */
+export declare function removeProviderRow(client: CrtrClient, row: RemovableProviderRow): Promise<string>;

package/dist/core/provider-management.js

@@ -0,0 +1,9 @@
+/** Route a row's removal through the daemon and return the truthful panel notice. A managed account row removes that account only; a managed header row or a non-managed provider removes every credential for the provider. May throw (e.g. an unknown account) — callers surface that as the notice. */
+export async function removeProviderRow(client, row) {
+    if (row.managed && row.label !== undefined) {
+        await client.removeModelAuthAccount(row.providerId, row.label);
+        return `Removed ${row.name} account`;
+    }
+    await client.removeCredential(row.providerId);
+    return `Removed ${row.name}`;
+}

package/dist/core/providers/approval.d.ts

@@ -0,0 +1,23 @@
+import type { ProviderCaller, ProviderCallInput } from '../../daemon/api/handlers/providers.js';
+import type { PreparedFileCall } from './files.js';
+export interface ApprovalQuestion {
+    title: string;
+    body: string;
+    options: Array<{
+        option_id: string;
+        label: string;
+    }>;
+}
+/** A runless repeat consumes an answer exactly once, before any provider request. */
+export declare function consumeApproval(caller: ProviderCaller, input: ProviderCallInput, callShape: string): Promise<{
+    option: string;
+    requestId: string;
+    prepared: PreparedFileCall | null;
+}>;
+/** Called when the human ticket settles (answer or cancel), in the settlement transaction. */
+export declare function notifyProviderApproval(questionId: string): void;
+/** Create a page and either suspend a run or return its durable id to an app. */
+export declare function requireProviderApproval(caller: ProviderCaller, input: ProviderCallInput, requestId: string, question: unknown, signal: AbortSignal, callShape?: string, prepared?: PreparedFileCall): Promise<{
+    option: string;
+    questionId: string;
+}>;

package/dist/core/providers/approval.js

@@ -0,0 +1,146 @@
+// Provider approval is a durable page ticket. The approval row binds the
+// answer to its calling app, tool and original arguments, not to caller prose.
+import { createHash } from 'node:crypto';
+import { openDb } from '../canvas/db.js';
+import { newNodeId } from '../runtime/nodes.js';
+import { createPageRequest, getRequest } from '../human/requests.js';
+import { providerApprovalPage } from '../runs/questions.js';
+import { ProviderError } from './errors.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value !== null && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)]));
+    return value;
+}
+function hashArgs(args) {
+    return createHash('sha256').update(JSON.stringify(canonical(args))).digest('hex');
+}
+function invalidApproval() {
+    return new ProviderError('invalid_request', 'approval is not an answered question for this call', { param: 'approval' });
+}
+function denied() { return new ProviderError('user_denied', 'the user did not approve this call'); }
+function canceled(signal) { if (signal.aborted)
+    throw denied(); }
+async function row(questionId) {
+    return await (await openDb()).prepare('SELECT * FROM provider_approvals WHERE question_id = ?').get(questionId);
+}
+/** A runless repeat consumes an answer exactly once, before any provider request. */
+export async function consumeApproval(caller, input, callShape) {
+    const questionId = input.approval;
+    if (!questionId || caller.run_id !== null || caller.grantee === null || caller.sub === null)
+        throw invalidApproval();
+    const approval = await row(questionId);
+    if (!approval || approval.grantee !== caller.grantee || approval.sub !== caller.sub || approval.provider !== input.provider || approval.tool !== input.tool || approval.version !== (input.version ?? null) || approval.args_hash !== hashArgs(input.arguments) || approval.call_shape !== callShape)
+        throw invalidApproval();
+    // The human ticket is the authoritative settlement when someone answered
+    // through a different page surface. A canceled/open ticket is never reusable.
+    const ticket = await getRequest(questionId);
+    if (!ticket || ticket.state !== 'settled' || ticket.outcome !== 'answered' || approval.status !== 'answered')
+        throw invalidApproval();
+    const option = approval.option_id;
+    if (!option)
+        throw invalidApproval();
+    const changed = (await (await openDb()).prepare("UPDATE provider_approvals SET status = 'consumed' WHERE question_id = ? AND status = 'answered'").run(questionId)).changes;
+    if (changed !== 1)
+        throw invalidApproval();
+    if (option === 'deny')
+        throw denied();
+    return { option, requestId: approval.request_id, prepared: approval.prepared_files ? JSON.parse(approval.prepared_files) : null };
+}
+function validateQuestion(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ProviderError('provider_error', 'provider approval question is invalid', { origin: 'provider' });
+    const q = value;
+    const options = q['options'];
+    if (typeof q['title'] !== 'string' || !q['title'].trim() || typeof q['body'] !== 'string' || !Array.isArray(options) || options.length === 0 || options.some((o) => !o || typeof o !== 'object' || typeof o.option_id !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(o.option_id) || o.option_id === 'deny' || typeof o.label !== 'string' || !o.label.trim()) || new Set(options.map((o) => o.option_id)).size !== options.length) {
+        throw new ProviderError('provider_error', 'provider approval question is invalid', { origin: 'provider' });
+    }
+    return q;
+}
+const waiters = new Map();
+/** Called when the human ticket settles (answer or cancel), in the settlement transaction. */
+export function notifyProviderApproval(questionId) {
+    for (const notify of waiters.get(questionId) ?? [])
+        queueMicrotask(notify);
+}
+async function waitForApproval(questionId, signal) {
+    const read = async () => {
+        const approval = await row(questionId);
+        if (!approval)
+            throw denied();
+        if (approval.status === 'canceled')
+            throw denied();
+        if (approval.status === 'answered')
+            return approval.option_id;
+        return null;
+    };
+    if (signal.aborted)
+        throw denied();
+    let option = await read();
+    if (option === 'deny')
+        throw denied();
+    if (option !== null)
+        return option;
+    await new Promise(async (resolve) => {
+        const listeners = waiters.get(questionId) ?? new Set();
+        const wake = () => { signal.removeEventListener('abort', wake); listeners.delete(wake); if (!listeners.size)
+            waiters.delete(questionId); resolve(); };
+        listeners.add(wake);
+        waiters.set(questionId, listeners);
+        signal.addEventListener('abort', wake, { once: true });
+        // Close the registration race: an answer may have arrived between the
+        // first row read and installing the waiter.
+        if (signal.aborted || (await row(questionId))?.status !== 'open')
+            wake();
+    });
+    if (signal.aborted)
+        throw denied();
+    option = await read();
+    if (option === null || option === 'deny')
+        throw denied();
+    return option;
+}
+/** Create a page and either suspend a run or return its durable id to an app. */
+export async function requireProviderApproval(caller, input, requestId, question, signal, callShape, prepared) {
+    const parsed = validateQuestion(question);
+    if (!caller.sub || !caller.grantee)
+        throw new ProviderError('grant_revoked', 'caller has no active grant');
+    canceled(signal);
+    const questionId = await newNodeId();
+    await (await openDb()).prepare(`INSERT INTO provider_approvals
+    (question_id, grantee, sub, provider, tool, version, args_hash, request_id, status, call_shape, prepared_files)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'open', ?, ?)`).run(questionId, caller.grantee, caller.sub, input.provider, input.tool, input.version ?? null, hashArgs(input.arguments), requestId, callShape ?? null, prepared && (prepared.copies.length || prepared.upload) ? JSON.stringify(prepared) : null);
+    try {
+        await createPageRequest({ request_id: questionId, requester_node_id: caller.run_id ? caller.node_id : null,
+            prepared: providerApprovalPage(parsed) });
+    }
+    catch (error) {
+        await (await openDb()).prepare("DELETE FROM provider_approvals WHERE question_id = ? AND status = 'open'").run(questionId);
+        throw error;
+    }
+    if (!caller.run_id) {
+        if (signal.aborted) {
+            const { cancelHumanTicket } = await import('../../daemon/human/finish.js');
+            await cancelHumanTicket(questionId, { reason: 'the provider call was canceled' });
+            throw denied();
+        }
+        throw new ProviderError('approval_pending', 'the provider requires the user to answer a question', { question_id: questionId });
+    }
+    try {
+        const option = await waitForApproval(questionId, signal);
+        if (signal.aborted)
+            throw denied();
+        return { option, questionId };
+    }
+    catch (error) {
+        if (signal.aborted) {
+            // A canceled run cannot leave behind a page that could later authorize a
+            // provider request. Settlement is first-writer-wins if the answer raced.
+            const { cancelHumanTicket } = await import('../../daemon/human/finish.js');
+            await cancelHumanTicket(questionId, { reason: 'the provider call was canceled' });
+            throw denied();
+        }
+        throw error;
+    }
+}

package/dist/core/providers/audit.d.ts

@@ -0,0 +1,30 @@
+import type { ProviderCaller } from '../../daemon/api/handlers/providers.js';
+export interface ProviderAudit {
+    request_id: string;
+    caller: ProviderCaller;
+    provider: string;
+    tool: string;
+    scope_checked?: string;
+    outcome: string;
+    jti?: string;
+    receipt_id?: string;
+    responder?: string;
+    question_id?: string;
+}
+/** One row per authorization, including refusals before a token is minted. */
+export declare function writeProviderAudit(row: ProviderAudit): Promise<void>;
+export interface AuditFilters {
+    after?: number;
+    limit: number;
+    operation?: string;
+    outcome?: string;
+    run_id?: string;
+    since?: string;
+    until?: string;
+    /** Only rows written for this person (the `sub` column). */
+    sub?: string;
+}
+export declare function listAudit(grantee: string | null, filters: AuditFilters): Promise<{
+    rows: Record<string, unknown>[];
+    next: string | null;
+}>;

package/dist/core/providers/audit.js

@@ -0,0 +1,52 @@
+import { openDb } from '../canvas/db.js';
+import { runtimeId } from '../grants/sync.js';
+import { callerTerminalGrant } from '../grants/terminal.js';
+/** One row per authorization, including refusals before a token is minted. */
+export async function writeProviderAudit(row) {
+    const { caller } = row;
+    const sub = caller.sub ?? (caller.class === 'person' ? (await callerTerminalGrant())?.sub ?? null : null);
+    const grantee = caller.grantee ?? sub;
+    const chain = sub && grantee ? [sub, grantee, `runtime:${runtimeId()}`] : null;
+    await (await openDb()).prepare(`INSERT INTO audit_rows
+    (request_id, time, grantee, sub, client_id, class, operation, scope_checked,
+     outcome, node_id, run_id, resource, initiator_chain, provider, tool, jti, receipt_id, responder, question_id)
+    VALUES (?, ?, ?, ?, ?, ?, 'provider.call', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.request_id, new Date().toISOString(), grantee, sub, caller.client_id, caller.class, row.scope_checked ?? null, row.outcome, caller.node_id, caller.run_id, `${row.provider} ${row.tool}`, chain ? JSON.stringify(chain) : null, row.provider, row.tool, row.jti ?? null, row.receipt_id ?? null, row.responder ?? null, row.question_id ?? null);
+}
+export async function listAudit(grantee, filters) {
+    const where = [];
+    const args = [];
+    if (grantee !== null) {
+        where.push('grantee = ?');
+        args.push(grantee);
+    }
+    if (filters.sub !== undefined) {
+        where.push('sub = ?');
+        args.push(filters.sub);
+    }
+    if (filters.after !== undefined) {
+        where.push('id < ?');
+        args.push(filters.after);
+    }
+    for (const field of ['operation', 'outcome', 'run_id']) {
+        if (filters[field] !== undefined) {
+            where.push(`${field} = ?`);
+            args.push(filters[field]);
+        }
+    }
+    if (filters.since !== undefined) {
+        where.push('time >= ?');
+        args.push(filters.since);
+    }
+    if (filters.until !== undefined) {
+        where.push('time <= ?');
+        args.push(filters.until);
+    }
+    const rows = await (await openDb()).prepareUncached(`SELECT * FROM audit_rows ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY id DESC LIMIT ?`)
+        .all(...args, filters.limit + 1);
+    const more = rows.length > filters.limit;
+    if (more)
+        rows.pop();
+    const next = more ? String(rows.at(-1)?.id) : null;
+    return { rows: rows.map(({ id, initiator_chain, ...row }) => ({ ...row,
+            initiator_chain: typeof initiator_chain === 'string' ? JSON.parse(initiator_chain) : null })), next };
+}