@north-light/api 0.3.579 → 0.3.587

package/dist/daemon/api/deferred-head.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const DEFER_HEAD_REQUEST_HEADER = "crtr-defer-head";
+export declare const DEFERRED_HEAD_CONTENT_TYPE = "application/vnd.crtr.deferred-head";
+export declare const DEFERRED_HEAD_MAGIC = "crtr-deferred-head/1\n";
+export declare const DEFER_HEAD_AFTER_MS = 40000;
+export declare const DEFER_HEAD_KEEPALIVE_MS = 15000;
+export interface DeferHeadOptions {
+    afterMs?: number;
+    keepaliveMs?: number;
+}
+/** Whether this request asked for a deferred head. */
+export declare function wantsDeferredHead(req: IncomingMessage): boolean;
+/** Arm the wrapper on `res`. A no-op unless the request carries `Crtr-Defer-Head: 1`. */
+export declare function deferHead(req: IncomingMessage, res: ServerResponse, options?: DeferHeadOptions): void;

package/dist/daemon/api/deferred-head.js

@@ -0,0 +1,117 @@
+// Deferred response head (`Crtr-Defer-Head: 1`).
+//
+// Blaxel's preview edge answers 504 when response headers take more than 60 s.
+// A request carrying `Crtr-Defer-Head: 1` whose operation has not produced its
+// response head 40 s after the request arrived gets a framing response instead:
+//
+//   200, Content-Type: application/vnd.crtr.deferred-head
+//   crtr-deferred-head/1\n
+//   \n                       (one every 15 s while the operation is still working)
+//   {"status":N,"headers":{...}}\n     (the real head, as `res.getHeaders()` shape, values as strings)
+//   <the real body bytes, unchanged and streamed>
+//
+// Fast answers pass through untouched. The wrapper sits on the `ServerResponse`
+// below every operation, so no operation changes: after the commit the response
+// object presents the *virtual* head state (headers, `headersSent`) to the
+// handlers as if nothing had been sent yet.
+export const DEFER_HEAD_REQUEST_HEADER = 'crtr-defer-head';
+export const DEFERRED_HEAD_CONTENT_TYPE = 'application/vnd.crtr.deferred-head';
+export const DEFERRED_HEAD_MAGIC = 'crtr-deferred-head/1\n';
+export const DEFER_HEAD_AFTER_MS = 40_000;
+export const DEFER_HEAD_KEEPALIVE_MS = 15_000;
+/** Whether this request asked for a deferred head. */
+export function wantsDeferredHead(req) {
+    const raw = req.headers[DEFER_HEAD_REQUEST_HEADER];
+    return (Array.isArray(raw) ? raw[0] : raw)?.trim() === '1';
+}
+/** Header values as the head line carries them: strings, or arrays of strings. */
+function stringified(headers) {
+    const out = {};
+    for (const [name, value] of headers) {
+        if (value === undefined)
+            continue;
+        out[name] = Array.isArray(value) ? value.map(String) : String(value);
+    }
+    return out;
+}
+/** Arm the wrapper on `res`. A no-op unless the request carries `Crtr-Defer-Head: 1`. */
+export function deferHead(req, res, options = {}) {
+    if (!wantsDeferredHead(req))
+        return;
+    const afterMs = options.afterMs ?? DEFER_HEAD_AFTER_MS;
+    const keepaliveMs = options.keepaliveMs ?? DEFER_HEAD_KEEPALIVE_MS;
+    const native = {
+        writeHead: res.writeHead.bind(res),
+        write: res.write.bind(res),
+        end: res.end.bind(res),
+    };
+    let virtual = null; // non-null once the framing is committed
+    let headSent = false; // the real head line is out
+    let keepalive;
+    const stop = () => { clearTimeout(timer); if (keepalive !== undefined)
+        clearInterval(keepalive); keepalive = undefined; };
+    const timer = setTimeout(() => {
+        if (res.headersSent || res.writableEnded || res.destroyed)
+            return;
+        commit();
+    }, afterMs);
+    res.once('close', stop);
+    res.once('finish', stop);
+    function commit() {
+        const status = res.statusCode;
+        const captured = new Map();
+        for (const [name, value] of Object.entries(res.getHeaders()))
+            if (value !== undefined)
+                captured.set(name, value);
+        // Entity headers describe the real body, not the framing response.
+        for (const name of ['content-length', 'transfer-encoding', 'content-type', 'content-encoding'])
+            res.removeHeader(name);
+        native.writeHead(200, { 'Content-Type': DEFERRED_HEAD_CONTENT_TYPE });
+        native.write(DEFERRED_HEAD_MAGIC);
+        res.statusCode = status; // the framing's writeHead(200) overwrote a status the handler had already set
+        virtual = captured;
+        keepalive = setInterval(() => { if (!headSent && !res.destroyed)
+            native.write('\n'); }, keepaliveMs);
+        keepalive.unref();
+        present();
+    }
+    /** Make the response object report the virtual head to the handlers. */
+    function present() {
+        const target = res;
+        Object.defineProperty(res, 'headersSent', { configurable: true, get: () => headSent });
+        target['setHeader'] = (name, value) => { virtual.set(name.toLowerCase(), value); return res; };
+        target['getHeader'] = (name) => virtual.get(name.toLowerCase());
+        target['getHeaders'] = () => Object.fromEntries(virtual);
+        target['getHeaderNames'] = () => [...virtual.keys()];
+        target['hasHeader'] = (name) => virtual.has(name.toLowerCase());
+        target['removeHeader'] = (name) => { virtual.delete(name.toLowerCase()); };
+        target['flushHeaders'] = () => undefined;
+        target['writeHead'] = (status, ...rest) => {
+            const extra = rest.find((part) => part !== null && typeof part === 'object');
+            if (Array.isArray(extra)) {
+                // The flat [name, value, ...] form.
+                const flat = extra;
+                for (let i = 0; i + 1 < flat.length; i += 2)
+                    virtual.set(String(flat[i]).toLowerCase(), flat[i + 1]);
+            }
+            else if (extra) {
+                for (const [name, value] of Object.entries(extra))
+                    virtual.set(name.toLowerCase(), value);
+            }
+            res.statusCode = status;
+            sendHead();
+            return res;
+        };
+        target['write'] = (chunk, ...rest) => { sendHead(); return native.write(chunk, ...rest); };
+        target['end'] = (...args) => { sendHead(); return native.end(...args); };
+    }
+    function sendHead() {
+        if (headSent)
+            return;
+        headSent = true;
+        if (keepalive !== undefined)
+            clearInterval(keepalive);
+        keepalive = undefined;
+        native.write(`${JSON.stringify({ status: res.statusCode, headers: stringified(virtual) })}\n`);
+    }
+}

package/dist/daemon/api/environment-of.d.ts

@@ -0,0 +1,18 @@
+import type { StartBundleRecipeDTO } from '../../api/index.js';
+/** The environment object id a node runs in: its profile's `environment_id`, or the machine environment when it has none. */
+export declare function environmentOfNode(profileId: string | null): Promise<string>;
+/** SQL predicate over `environments`: the recipe has content (a repository, a setup script or pi packages). A recipe cleared back to nothing
+ *  has none, whatever its `recipe_revision` counter says: the counter only orders edits, it does not say whether a recipe exists. */
+export declare const RECIPE_HAS_CONTENT_SQL = "(btrim(COALESCE(environments.setup_script, '')) <> '' OR btrim(COALESCE(environments.pi_packages, '')) <> ''\n  OR EXISTS (SELECT 1 FROM environment_repos r WHERE r.environment = environments.object))";
+/** The environment's recipe; null when it has no content (no repositories, no setup script, no packages). One statement, so the revision,
+ *  script, packages and repositories all come from one snapshot, never from either side of a concurrent `setEnvironmentRecipe`. */
+export declare function recipeOf(environmentId: string): Promise<StartBundleRecipeDTO | null>;
+/** True when the node runs in a Blaxel environment, where its sandbox is its worktree (D102). */
+export declare function runsOnBlaxel(profileId: string | null): Promise<boolean>;
+/** The worktree request a Blaxel node carries in its launch recipe: the recipe repository whose `/work/<name>` holds `cwd`,
+ *  a branch `crtr/<node id>`, and the base (the caller's, else that repository's default branch). */
+export declare function sandboxWorktreeRequest(profileId: string | null, cwd: string, nodeId: string, base: string | undefined): Promise<{
+    repository: string;
+    branch: string;
+    base: string;
+}>;

package/dist/daemon/api/environment-of.js

@@ -0,0 +1,40 @@
+// Which environment a node runs in, and that environment's recipe.
+import { ApiError } from '../../api/errors.js';
+import { openDb } from '../../core/canvas/db.js';
+import { machineEnvironmentId } from '../../core/environments.js';
+/** The environment object id a node runs in: its profile's `environment_id`, or the machine environment when it has none. */
+export async function environmentOfNode(profileId) {
+    if (profileId === null)
+        return machineEnvironmentId();
+    const row = await (await openDb()).prepare('SELECT environment_id FROM profiles WHERE id = ?').get(profileId);
+    return row?.environment_id ?? machineEnvironmentId();
+}
+/** SQL predicate over `environments`: the recipe has content (a repository, a setup script or pi packages). A recipe cleared back to nothing
+ *  has none, whatever its `recipe_revision` counter says: the counter only orders edits, it does not say whether a recipe exists. */
+export const RECIPE_HAS_CONTENT_SQL = `(btrim(COALESCE(environments.setup_script, '')) <> '' OR btrim(COALESCE(environments.pi_packages, '')) <> ''
+  OR EXISTS (SELECT 1 FROM environment_repos r WHERE r.environment = environments.object))`;
+/** The environment's recipe; null when it has no content (no repositories, no setup script, no packages). One statement, so the revision,
+ *  script, packages and repositories all come from one snapshot, never from either side of a concurrent `setEnvironmentRecipe`. */
+export async function recipeOf(environmentId) {
+    const env = await (await openDb()).prepare(`SELECT recipe_revision, setup_script, pi_packages, ${RECIPE_HAS_CONTENT_SQL} AS has_content,
+      (SELECT COALESCE(json_agg(json_build_object('name', r.name, 'github_full_name', r.github_full_name, 'default_branch', r.default_branch) ORDER BY r.position), '[]'::json)
+         FROM environment_repos r WHERE r.environment = environments.object) AS repositories
+    FROM environments WHERE object = ?`).get(environmentId);
+    if (env === undefined || !env.has_content)
+        return null;
+    return { revision: Number(env.recipe_revision), repositories: JSON.parse(env.repositories), setup_script: env.setup_script, pi_packages: env.pi_packages };
+}
+/** True when the node runs in a Blaxel environment, where its sandbox is its worktree (D102). */
+export async function runsOnBlaxel(profileId) {
+    const row = await (await openDb()).prepare('SELECT kind FROM environments WHERE object = ?').get(await environmentOfNode(profileId));
+    return row?.kind === 'blaxel';
+}
+/** The worktree request a Blaxel node carries in its launch recipe: the recipe repository whose `/work/<name>` holds `cwd`,
+ *  a branch `crtr/<node id>`, and the base (the caller's, else that repository's default branch). */
+export async function sandboxWorktreeRequest(profileId, cwd, nodeId, base) {
+    const repositories = (await recipeOf(await environmentOfNode(profileId)))?.repositories ?? [];
+    const repo = repositories.find((r) => cwd === `/work/${r.name}` || cwd.startsWith(`/work/${r.name}/`));
+    if (repo === undefined)
+        throw new ApiError(400, 'invalid_request', `--worktree needs a cwd inside one of the environment's repositories under /work, not ${cwd}`, { param: 'worktree' });
+    return { repository: repo.name, branch: `crtr/${nodeId}`, base: base ?? repo.default_branch };
+}

package/dist/daemon/api/handlers/git-credential.d.ts

@@ -0,0 +1,11 @@
+import type { RouteTable } from '../router.js';
+/** The GitHub app's internal route: a token limited to `repositories` for the person, and the commit author for their GitHub link (null when unlinked). */
+export declare function mintInstallationToken(sub: string, repositories: string[]): Promise<{
+    token: string;
+    expires_at: string;
+    author: {
+        name: string;
+        email: string;
+    } | null;
+}>;
+export declare const gitCredentialRoutes: RouteTable;

package/dist/daemon/api/handlers/git-credential.js

@@ -0,0 +1,64 @@
+// `POST /v1/environments/:environment_id/git-credential` — a GitHub token limited to the environment's recipe repositories.
+// The control plane asks the GitHub app's internal route with its service credential; GitHub enforces the restriction.
+import { ApiError } from '../../../api/errors.js';
+import { getNode } from '../../../core/canvas/canvas.js';
+import { environmentOfNode, recipeOf } from '../environment-of.js';
+import { invalidRequest, objectBody, optionalString, requiredString } from './validate.js';
+function requiredEnv(name) {
+    const value = process.env[name];
+    if (value === undefined || value === '')
+        throw new ApiError(500, 'github_service_unconfigured', `${name} is not set on this control plane`);
+    return value;
+}
+async function handleGitCredential(ctx) {
+    const { principal } = ctx;
+    if (principal.class !== 'broker')
+        throw new ApiError(403, 'broker_only', 'git credentials are issued to a node token');
+    const environmentId = ctx.params['environment_id'] ?? '';
+    const node = await getNode(principal.node);
+    if (node === null)
+        throw new ApiError(404, 'node_not_found', `no node ${principal.node}`);
+    if (await environmentOfNode(node.profile_id ?? null) !== environmentId)
+        throw new ApiError(403, 'not_your_environment', `this node does not run in environment ${environmentId}`);
+    const violations = [];
+    const body = objectBody(ctx.body, ['host', 'path'], violations);
+    const host = requiredString(body, 'host', violations);
+    optionalString(body, 'path', violations);
+    if (violations.length > 0)
+        invalidRequest('git credential request', violations);
+    if (host !== 'github.com')
+        throw new ApiError(400, 'unsupported_git_host', `only github.com credentials are issued, not ${host}`);
+    const repositories = (await recipeOf(environmentId))?.repositories.map((r) => r.github_full_name) ?? [];
+    if (repositories.length === 0)
+        throw new ApiError(409, 'no_recipe_repositories', `environment ${environmentId} has no recipe repositories`);
+    const minted = await mintInstallationToken(principal.sub, repositories);
+    return { status: 200, body: { username: 'x-access-token', password: minted.token, expiry: minted.expires_at } };
+}
+/** The GitHub app's internal route: a token limited to `repositories` for the person, and the commit author for their GitHub link (null when unlinked). */
+export async function mintInstallationToken(sub, repositories) {
+    const response = await fetch(`${requiredEnv('GITHUB_SERVICE_URL').replace(/\/$/, '')}/internal/installation-token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${requiredEnv('CROUTER_SERVICE_TOKEN')}` },
+        body: JSON.stringify({ sub, repositories }),
+    });
+    const text = await response.text();
+    const parsed = text === '' ? {} : JSON.parse(text);
+    if (!response.ok) {
+        const code = typeof parsed.error === 'object' ? parsed.error?.code : parsed.code;
+        const message = (typeof parsed.error === 'object' ? parsed.error?.message : parsed.message) ?? `the GitHub service answered ${response.status}`;
+        if (response.status === 409 && (code === 'repositories_span_installations' || code === 'github_not_connected'))
+            throw new ApiError(409, code, message, { repositories });
+        throw new ApiError(502, 'github_service_failed', message, { status: response.status, ...(code === undefined ? {} : { code }) });
+    }
+    if (typeof parsed.token !== 'string' || typeof parsed.expires_at !== 'string')
+        throw new ApiError(502, 'github_service_failed', 'the GitHub service answered without a token and expiry');
+    const author = parsed.author;
+    if (author === undefined)
+        throw new ApiError(502, 'github_service_failed', 'the GitHub service answered without an author field');
+    if (author !== null && (typeof author.name !== 'string' || typeof author.email !== 'string'))
+        throw new ApiError(502, 'github_service_failed', 'the GitHub service answered a malformed author');
+    return { token: parsed.token, expires_at: parsed.expires_at, author: author === null ? null : { name: author.name, email: author.email } };
+}
+export const gitCredentialRoutes = [
+    { method: 'POST', pattern: '/v1/environments/:environment_id/git-credential', handler: handleGitCredential },
+];

package/dist/daemon/api/handlers/providers.d.ts

@@ -0,0 +1,83 @@
+import type { ServerResponse } from 'node:http';
+import { type RequestPrincipal, type RouteTable } from '../router.js';
+import type { AppPrincipal } from '../principal.js';
+export declare const PROVIDER_OPERATIONS: Set<string>;
+/** Who is calling, normalized across listeners. `resolved` is the caller's
+ *  resolved scope set read at call time (the grant mirror, so a grant sync
+ *  changes the answer for a running broker, D3-TOK-21); `null` = the person,
+ *  who holds every group (contract 1 OWN-4). `nodeScopes` is a broker node's
+ *  own narrowing list (`null` = none). */
+export interface ProviderCaller {
+    class: 'person' | 'app' | 'broker';
+    /** The user on whose behalf; `null` for a person on the socket (R2 resolves it). */
+    sub: string | null;
+    grantee: string | null;
+    client_id: string | null;
+    resolved: readonly string[] | null;
+    nodeScopes: readonly string[] | null;
+    run_id: string | null;
+    node_id: string | null;
+    /** Set only for a forwarded caller: the reader's node, run and calling machine on its own machine, which this machine has no rows for. It names the reader
+     *  in `Crtr-Caller` and nothing else -- the local run and node fields above stay null, so no local run, file or approval lookup is made for it. */
+    origin?: {
+        node: string | null;
+        run: string | null;
+        machine: string;
+    };
+}
+export declare function callerFromRequest(principal: RequestPrincipal): Promise<ProviderCaller>;
+export declare function callerFromApp(principal: AppPrincipal): ProviderCaller;
+/** Does the caller hold `<provider>:<group>`? Both the resolved set and a
+ *  broker's node list must cover it. */
+export declare function callerAllows(caller: ProviderCaller, scope: string): boolean;
+/** Throws `scope_missing` naming `<provider>:<group>` unless the caller holds it (D2-PRV-10). */
+export declare function requireGroup(caller: ProviderCaller, provider: string, group: string): void;
+/** v0 = no directory configured: both rows answer `not_found` (D3-V0-1). */
+export declare function providerOperationsEnabled(): boolean;
+export interface ProviderCallInput {
+    provider: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+    version?: number;
+    /** Outside a run, the answered approval question the repeat names (R5). */
+    approval?: string;
+    /** Which device machine takes the call (a `machine_id`, `runtime:` prefix optional); only a provider served by a machine accepts it. */
+    machine?: string;
+}
+export declare function parseProvider(value: unknown): string;
+export declare function parseCallInput(body: unknown): ProviderCallInput;
+/** Per-request context the call path needs: the audit `request_id` (also the
+ *  `Crtr-Request-Id` a provider receives) and the signal that aborts the call
+ *  when the caller's socket closes (R9). `traceId` is the trace of the inbound HTTP request;
+ *  without one the call starts a fresh trace. */
+export interface ProviderRequest {
+    requestId: string;
+    traceId?: string;
+    signal: AbortSignal;
+    /** The `Crtr-Caused-By` value the call arrived with (`message:<id>`, `request:<id>`, `cron_run:<id>`); absent when none. */
+    causedBy?: string;
+}
+export interface ProviderInput {
+    params: Record<string, string>;
+    body: unknown;
+    query?: URLSearchParams;
+}
+/** Dispatch one provider operation. Throws `ProviderError`/`RunError`; the listener renders it with `providerErrorBody`. */
+export declare function handleProviderOperation(name: string, caller: ProviderCaller, input: ProviderInput, request: ProviderRequest): Promise<{
+    status: number;
+    body: unknown;
+}>;
+/** An `AbortController` tied to the response: closing the caller's socket aborts the call. */
+export declare function abortOnClose(res: ServerResponse): {
+    signal: AbortSignal;
+    release: () => void;
+};
+/** Render a thrown value as the contract-2 envelope; a non-`RunError` is logged as a 500.
+ *  `directoryCaller`: true on the app listener (a directory-token caller), false on the socket. */
+export declare function providerFailure(error: unknown, requestId: string, directoryCaller: boolean, runId?: string | null): {
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+};
+/** Socket routes (person, broker). The router has already checked the caller class. */
+export declare const providerRoutes: RouteTable;

package/dist/daemon/api/handlers/providers.js

@@ -0,0 +1,283 @@
+// `provider.tools` and `provider.call` (daemon-operations "provider.tools,
+// provider.call"; contract 3). One entry point, `handleProviderOperation`, serves
+// both listeners: the socket route table below (person and broker) and the app
+// listener's branch (app). Each listener normalizes its principal to a
+// `ProviderCaller`, then this module owns the rest: the v0 gate, input parsing,
+// the per-group scope check, and the contract-2 error envelope.
+//
+// Stage: v0 (no `runtime.issuer`) refuses both rows with `not_found` (D3-V0-1).
+// Past the gate, the bodies are filled in by later tasks — `provider.call` by
+// R4 (`core/providers/call.ts`), `provider.tools` by R8 — and answer
+// `not_implemented` until then.
+import { randomUUID } from 'node:crypto';
+import { cloudPersonScope } from '../../../core/runs/operations.js';
+import { directoryIssuer } from '../../../core/directory/issuer.js';
+import { activeGrantForApp, allGrants, grantFor, localGrants, providerIdsFromGrants } from '../../../core/grants/mirror.js';
+import { getNode } from '../../../core/canvas/canvas.js';
+import { scopeAllowed } from '../../../core/scopes.js';
+import { ProviderError, providerErrorBody, scopeMissing } from '../../../core/providers/errors.js';
+import { callProvider, providerTools as listProviderTools } from '../../../core/providers/call.js';
+import { providerInstallState } from '../../../core/providers/bundles.js';
+import { installedProviderPlugins, providerRootClaims, resolveProviderRef } from '../../../core/providers/roots.js';
+import { isCloudRole } from '../../../core/canvas/person-state.js';
+import { listAudit, writeProviderAudit } from '../../../core/providers/audit.js';
+import { emitEvent } from '../../../core/events/emit.js';
+import { resolvedScopes } from '../router.js';
+export const PROVIDER_OPERATIONS = new Set(['provider.tools', 'provider.call', 'audit.list']);
+export async function callerFromRequest(principal) {
+    // No provider row admits a forwarded or machine caller (operations.ts). A forwarded caller is mapped only for the in-process read path: a read
+    // the home machine answers for another machine's reader calls a provider read leaf as that reader.
+    if (principal.class === 'forwarded') {
+        if (principal.actor.kind === 'person')
+            return { class: 'person', sub: null, grantee: null, client_id: null, resolved: null, nodeScopes: null, run_id: null, node_id: null,
+                origin: { node: null, run: null, machine: principal.via } };
+        const grant = await grantFor(principal.actor.app, principal.sub);
+        if (!grant)
+            throw new ProviderError('grant_revoked', `app ${principal.actor.app} has no active grant`);
+        return { class: 'app', sub: principal.sub, grantee: principal.actor.app, client_id: null, resolved: grant.resolved, nodeScopes: principal.actor.node_scopes, run_id: null, node_id: null,
+            origin: { node: principal.actor.node, run: principal.actor.place?.run ?? null, machine: principal.via } };
+    }
+    if (principal.class === 'machine' || principal.class === 'import')
+        throw new ProviderError('permission_error', 'this operation is not available to the caller');
+    // A cloud role's directory person is confined to their own grants' scopes; a Mac's person carries no `sub` and holds every group.
+    if (principal.class === 'person' && principal.sub !== undefined) {
+        if (!isCloudRole())
+            throw new ProviderError('permission_error', 'provider calls are made by the install\'s person, a node or an app');
+        return { class: 'person', sub: principal.sub, grantee: null, client_id: null, resolved: await resolvedScopes(principal), nodeScopes: null, run_id: null, node_id: null };
+    }
+    if (principal.class === 'person')
+        return { class: 'person', sub: null, grantee: null, client_id: null, resolved: null, nodeScopes: null, run_id: null, node_id: null };
+    if (principal.class === 'app') {
+        const grant = await activeGrantForApp(principal.app);
+        if (!grant)
+            throw new ProviderError('grant_revoked', `app ${principal.app} has no active grant`);
+        // The scoped local token is still a ceiling; the grant supplies identity
+        // and current permissions, not authority wider than the token.
+        return { class: 'app', sub: grant.sub, grantee: principal.app, client_id: null, resolved: grant.resolved, nodeScopes: principal.scopes, run_id: null, node_id: null };
+    }
+    if (principal.class === 'cron') {
+        // A cron command is the grant's own caller: provider class `app`, bounded by the stored scopes, attributed to its origin run.
+        return { class: 'app', sub: principal.sub, grantee: principal.app, client_id: null, resolved: await resolvedScopes(principal), nodeScopes: principal.scopes,
+            run_id: principal.origin_run, node_id: null };
+    }
+    return { class: 'broker', sub: principal.sub, grantee: principal.app, client_id: principal.client_id, resolved: await resolvedScopes(principal), nodeScopes: principal.scopes,
+        run_id: principal.run ?? (await getNode(principal.node))?.run_id ?? null, node_id: principal.node };
+}
+export function callerFromApp(principal) {
+    return { class: 'app', sub: principal.sub, grantee: principal.grantee, client_id: principal.client_id, resolved: principal.resolved, nodeScopes: null, run_id: null, node_id: null };
+}
+/** A provider scope `<provider>:<group>` (the identity grammar's `provider`
+ *  selector kind). `covers()` grants such a scope only by exact equality. */
+const PROVIDER_SCOPE = /^([A-Za-z0-9_-]{1,64}):([A-Za-z0-9_-]{1,64})$/;
+function isProviderScope(scope) {
+    const match = PROVIDER_SCOPE.exec(scope);
+    return match !== null && match[1] !== 'crtr';
+}
+/** Membership sets per held-scope array. A grant's resolved list and a node's
+ *  list are fixed arrays for one request, and a provider with thousands of
+ *  groups checks every one of them against thousands of held scopes. */
+const heldSets = new WeakMap();
+function heldSet(scopes) {
+    let set = heldSets.get(scopes);
+    if (set === undefined) {
+        set = new Set(scopes);
+        heldSets.set(scopes, set);
+    }
+    return set;
+}
+/** `scopeAllowed` with the provider-scope case answered by set membership:
+ *  `covers(held, '<p>:<g>')` is true only for `held === '<p>:<g>'`, so the
+ *  answer is identical and costs O(1) instead of a selector parse per held scope. */
+function holds(scopes, scope) {
+    if (scopes === null)
+        return true;
+    if (isProviderScope(scope))
+        return heldSet(scopes).has(scope);
+    return scopeAllowed(scopes, scope);
+}
+/** Does the caller hold `<provider>:<group>`? Both the resolved set and a
+ *  broker's node list must cover it. */
+export function callerAllows(caller, scope) {
+    if (caller.class === 'person' && caller.resolved === null)
+        return true;
+    return holds(caller.resolved ?? [], scope) && holds(caller.nodeScopes, scope);
+}
+/** Throws `scope_missing` naming `<provider>:<group>` unless the caller holds it (D2-PRV-10). */
+export function requireGroup(caller, provider, group) {
+    const scope = `${provider}:${group}`;
+    if (!callerAllows(caller, scope))
+        throw scopeMissing(scope);
+}
+/** v0 = no directory configured: both rows answer `not_found` (D3-V0-1). */
+export function providerOperationsEnabled() {
+    return Boolean(directoryIssuer());
+}
+/** The scope grammar's id (`<provider>:<group>`); `crtr` is the runtime's own scope namespace. */
+const PROVIDER_ID = /^[A-Za-z0-9_-]{1,64}$/;
+function invalid(message, param) { return new ProviderError('invalid_request', message, { param }); }
+export function parseProvider(value) {
+    if (typeof value !== 'string' || !PROVIDER_ID.test(value) || value === 'crtr')
+        throw invalid('provider must be a provider id', 'provider');
+    return value;
+}
+export function parseCallInput(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        throw new ProviderError('invalid_request', 'a JSON object is required');
+    const fields = body;
+    const provider = parseProvider(fields['provider']);
+    const tool = fields['tool'];
+    if (typeof tool !== 'string' || !tool.trim())
+        throw invalid('tool must be a non-empty string', 'tool');
+    const args = fields['arguments'] ?? {};
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        throw invalid('arguments must be an object', 'arguments');
+    const version = fields['version'];
+    if (version !== undefined && (typeof version !== 'number' || !Number.isInteger(version) || version < 1))
+        throw invalid('version must be an integer >= 1', 'version');
+    const approval = fields['approval'];
+    if (approval !== undefined && (typeof approval !== 'string' || !approval))
+        throw invalid('approval must be a question id', 'approval');
+    const machine = fields['machine'];
+    if (machine !== undefined && (typeof machine !== 'string' || !machine.trim()))
+        throw invalid('machine must be a machine id', 'machine');
+    return { provider, tool: tool.trim(), arguments: args, ...(version === undefined ? {} : { version }), ...(approval === undefined ? {} : { approval }),
+        ...(machine === undefined ? {} : { machine: machine.trim() }) };
+}
+async function auditList(caller, query = new URLSearchParams()) {
+    const numeric = (name, fallback, max) => {
+        const value = query.get(name);
+        if (value === null)
+            return fallback;
+        if (!/^\d+$/.test(value) || Number(value) > max || Number(value) < 1)
+            throw invalid(`invalid ${name}`, name);
+        return Number(value);
+    };
+    const after = query.has('after') ? numeric('after', 0, Number.MAX_SAFE_INTEGER) : undefined;
+    const limit = numeric('limit', 100, 1000);
+    const filters = Object.fromEntries(['operation', 'outcome', 'run_id', 'since', 'until']
+        .filter((key) => query.has(key)).map((key) => [key, query.get(key)]));
+    // A cloud role's one audit table holds every person's rows: a caller reads only its own person's.
+    const sub = cloudPersonScope(caller.sub);
+    const person = sub === undefined ? {} : { sub };
+    return { status: 200, body: await listAudit(caller.class === 'person' ? null : caller.grantee, { after, limit, ...person, ...filters }) };
+}
+async function providerTools(caller, requested, _request) {
+    let provider = requested;
+    const started = performance.now();
+    // Installed help remains a local projection: discovery never fetches a
+    // bundle. The active grant mirror also names providers whose install failed.
+    const plugins = installedProviderPlugins();
+    // A provider whose root command another installed provider already serves is skipped, never shadowing it.
+    const { skipped } = providerRootClaims(plugins);
+    // A cloud role's installed bundles are the deployment's, shared by every person it serves, and its grant mirror holds every person's
+    // grants: what a caller sees follows the grants of the person it acts for.
+    const grants = isCloudRole() ? await allGrants() : await localGrants();
+    const people = isCloudRole() ? new Set(providerIdsFromGrants(grants.filter((grant) => grant.sub === caller.sub))) : null;
+    const shown = (id) => !skipped.has(id) && (people === null || people.has(id));
+    const installed = new Set(plugins
+        .filter((plugin) => plugin.enabled && plugin.manifest.provider?.id === plugin.name && shown(plugin.name))
+        .map((plugin) => plugin.name));
+    const granted = providerIdsFromGrants(grants).filter(shown);
+    const ids = [...new Set([...installed, ...granted])].sort();
+    // The SDK and CLI may name a provider by its bundle's root command; every key below is the id.
+    if (provider !== undefined) {
+        const resolved = resolveProviderRef(provider);
+        if (resolved === null)
+            throw new ProviderError('not_found', `provider "${provider}" is not available`);
+        provider = resolved;
+    }
+    if (provider !== undefined && !ids.includes(provider))
+        throw new ProviderError('not_found', `provider "${provider}" is not available`);
+    const candidates = provider === undefined ? ids : [provider];
+    const grantedGroups = caller.class === 'person'
+        ? grants.flatMap((grant) => grant.status === 'active' && (!isCloudRole() || grant.sub === caller.sub) ? grant.resolved_scopes.map(({ scope }) => scope) : [])
+        : caller.resolved ?? [];
+    const visible = await Promise.all(candidates.map(async (id) => {
+        // An installed provider is listed whatever the caller holds, so a client can parse a call to an ungranted leaf and the daemon refuses it.
+        if (installed.has(id))
+            return listProviderTools(caller, id);
+        // One that is not installed has no tree: only a caller holding a group of it learns its install state.
+        if (!grantedGroups.some((scope) => scope.startsWith(`${id}:`) && callerAllows(caller, scope)))
+            return null;
+        const state = providerInstallState(id);
+        if (state === undefined)
+            return null; // Installed but disabled in this person's Mac plugin settings; not an install in progress.
+        return { provider: id, display_name: id, status: state.status,
+            ...(state.error ? { error: state.error } : {}), groups: [], commands: [] };
+    })).then((entries) => entries.filter((entry) => entry !== null));
+    emitEvent({ level: 'debug', event: 'api.provider.tools', duration_ms: performance.now() - started,
+        fields: { caller: caller.class, provider: provider ?? null, providers: visible.length } });
+    if (provider !== undefined) {
+        if (visible.length === 0)
+            throw new ProviderError('not_found', `provider "${provider}" is not available`);
+        return { status: 200, body: visible[0] };
+    }
+    return { status: 200, body: { providers: visible } };
+}
+async function providerCall(caller, input, request) {
+    return callProvider(caller, input, request);
+}
+/** Dispatch one provider operation. Throws `ProviderError`/`RunError`; the listener renders it with `providerErrorBody`. */
+export async function handleProviderOperation(name, caller, input, request) {
+    if (!providerOperationsEnabled())
+        throw new ProviderError('not_found', 'provider operations need a directory-connected runtime');
+    if (name === 'audit.list')
+        return await auditList(caller, input.query);
+    if (name === 'provider.tools')
+        return providerTools(caller, input.params['provider'] === undefined ? undefined : parseProvider(input.params['provider']), request);
+    if (name === 'provider.call') {
+        let parsed;
+        try {
+            parsed = parseCallInput(input.body);
+        }
+        catch (error) {
+            const body = input.body && typeof input.body === 'object' && !Array.isArray(input.body) ? input.body : {};
+            await writeProviderAudit({ request_id: request.requestId, caller,
+                provider: typeof body['provider'] === 'string' ? body['provider'] : '',
+                tool: typeof body['tool'] === 'string' ? body['tool'] : '',
+                outcome: `refused:${error instanceof ProviderError ? error.code : 'invalid_request'}` });
+            throw error;
+        }
+        return providerCall(caller, parsed, request);
+    }
+    throw new ProviderError('not_found', 'unknown operation');
+}
+/** An `AbortController` tied to the response: closing the caller's socket aborts the call. */
+export function abortOnClose(res) {
+    const controller = new AbortController();
+    const abort = () => { if (!res.writableFinished)
+        controller.abort(); };
+    res.on('close', abort);
+    return { signal: controller.signal, release: () => res.off('close', abort) };
+}
+/** Render a thrown value as the contract-2 envelope; a non-`RunError` is logged as a 500.
+ *  `directoryCaller`: true on the app listener (a directory-token caller), false on the socket. */
+export function providerFailure(error, requestId, directoryCaller, runId) {
+    const rendered = providerErrorBody(error, requestId, directoryCaller, runId ?? undefined);
+    if (rendered.status >= 500 && !(error instanceof ProviderError)) {
+        emitEvent({ event: 'api.provider.failed', level: 'error', error: error instanceof Error ? error : new Error(String(error)), fields: { request_id: requestId } });
+    }
+    return rendered;
+}
+/** Socket routes (person, broker). The router has already checked the caller class. */
+export const providerRoutes = [
+    { method: 'GET', pattern: '/v1/audit', name: 'audit.list' },
+    { method: 'GET', pattern: '/v1/providers/tools', name: 'provider.tools' },
+    { method: 'GET', pattern: '/v1/providers/:provider/tools', name: 'provider.tools' },
+    { method: 'POST', pattern: '/v1/provider/call', name: 'provider.call' },
+].map(({ method, pattern, name }) => ({ method, pattern, handler: async (ctx) => {
+        const requestId = randomUUID();
+        const { signal, release } = abortOnClose(ctx.res);
+        let caller = null;
+        try {
+            caller = await callerFromRequest(ctx.principal);
+            const result = await handleProviderOperation(name, caller, { params: ctx.params, body: ctx.body, query: new URL(ctx.req.url ?? '/', 'http://runtime.local').searchParams }, { requestId, signal, ...(ctx.causedBy === undefined ? {} : { causedBy: ctx.causedBy }) });
+            return { ...result, headers: { 'Request-Id': requestId } };
+        }
+        catch (error) {
+            return providerFailure(error, requestId, false, caller?.run_id);
+        }
+        finally {
+            release();
+        }
+    } }));