@skrr-ai/cli 0.1.48 → 0.1.50

package/dist/lib/login.js

@@ -83,6 +83,22 @@ async function cliLogin(opts = {}) {
             baseURL: serverUrl,
         });
         if (brokerResult.ok) {
+            if (brokerResult.brokered) {
+                // Broker-mode hand-off: the daemon served a short-lived access token
+                // from a family IT owns. Nothing credential-shaped is persisted here
+                // — the token lives for this process and the next `skrr` re-redeems
+                // over loopback. An explicit PKCE/device-code login further down
+                // still writes a real user-owned family, unchanged.
+                console.log('');
+                console.log("  This machine is signed in through the platform's managed hand-off.");
+                return {
+                    token: brokerResult.accessToken,
+                    ...(brokerResult.accessExpiresAt !== undefined
+                        ? { expiresAt: brokerResult.accessExpiresAt }
+                        : {}),
+                    flow: 'daemon-broker',
+                };
+            }
             console.log('');
             console.log('  Authorized via the skrr background service on this computer (no browser needed).');
             return {

package/dist/lib/machine-spend-cap.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The figures behind a machine monthly-cap refusal, for every machine product.
+ *
+ * `RUNTIME_SPENDING_LIMIT_EXCEEDED` carries the cap, this month's spend and
+ * where the refused action would take it, as integer cents in `details`. The
+ * dedicated CLI learned to print them in OSK-9552; the hosted CLI kept printing
+ * the bare sentence, "Projected Hosted Machine usage would exceed the monthly
+ * cap." A person who had just watched `skrr balance show` report a large
+ * balance with overage on then read that as "you have money but we won't take
+ * it" (OSK-11946). The machine cap is a SEPARATE ceiling from the plan
+ * allowance and the credits, and overage does not raise it; without figures and
+ * that sentence nothing on the screen says so.
+ */
+export declare function formatCapCents(cents: number): string;
+/**
+ * `Cap $500.00; spent this month $12.22; this would bring it to $512.22`, or ''
+ * when the body is not a cap refusal or carries no figures.
+ */
+export declare function describeMonthlyCapFigures(body: string | undefined): string;
+/** Whether `body` is a machine monthly-cap refusal at all. */
+export declare function isMonthlyCapRefusal(body: string | undefined): boolean;
+/** The one sentence that says which ceiling this is — and which it is not. */
+export declare const MONTHLY_CAP_IS_SEPARATE = "This is the machine monthly cap, separate from your plan allowance and credits; overage does not raise it.";

package/dist/lib/machine-spend-cap.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * The figures behind a machine monthly-cap refusal, for every machine product.
+ *
+ * `RUNTIME_SPENDING_LIMIT_EXCEEDED` carries the cap, this month's spend and
+ * where the refused action would take it, as integer cents in `details`. The
+ * dedicated CLI learned to print them in OSK-9552; the hosted CLI kept printing
+ * the bare sentence, "Projected Hosted Machine usage would exceed the monthly
+ * cap." A person who had just watched `skrr balance show` report a large
+ * balance with overage on then read that as "you have money but we won't take
+ * it" (OSK-11946). The machine cap is a SEPARATE ceiling from the plan
+ * allowance and the credits, and overage does not raise it; without figures and
+ * that sentence nothing on the screen says so.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MONTHLY_CAP_IS_SEPARATE = void 0;
+exports.formatCapCents = formatCapCents;
+exports.describeMonthlyCapFigures = describeMonthlyCapFigures;
+exports.isMonthlyCapRefusal = isMonthlyCapRefusal;
+function formatCapCents(cents) {
+    const sign = cents < 0 ? '-' : '';
+    return `${sign}$${(Math.abs(cents) / 100).toFixed(2)}`;
+}
+/** The refusal's `code` and `details`, when the body is JSON; null otherwise. */
+function parseRefusal(body) {
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        const details = parsed?.details && typeof parsed.details === 'object' && !Array.isArray(parsed.details)
+            ? parsed.details
+            : undefined;
+        return { code: typeof parsed?.code === 'string' ? parsed.code : undefined, details };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `Cap $500.00; spent this month $12.22; this would bring it to $512.22`, or ''
+ * when the body is not a cap refusal or carries no figures.
+ */
+function describeMonthlyCapFigures(body) {
+    const refusal = parseRefusal(body);
+    if (refusal?.code !== 'RUNTIME_SPENDING_LIMIT_EXCEEDED' || !refusal.details)
+        return '';
+    const details = refusal.details;
+    const cents = (key) => {
+        const value = details[key];
+        return typeof value === 'number' && Number.isFinite(value) ? value : null;
+    };
+    const limit = cents('limitCents');
+    const spent = cents('currentSpendCents');
+    const projected = cents('projectedCents');
+    return [
+        limit !== null ? `Cap ${formatCapCents(limit)}` : '',
+        spent !== null ? `spent this month ${formatCapCents(spent)}` : '',
+        projected !== null ? `this would bring it to ${formatCapCents(projected)}` : '',
+    ]
+        .filter(Boolean)
+        .join('; ');
+}
+/** Whether `body` is a machine monthly-cap refusal at all. */
+function isMonthlyCapRefusal(body) {
+    return parseRefusal(body)?.code === 'RUNTIME_SPENDING_LIMIT_EXCEEDED';
+}
+/** The one sentence that says which ceiling this is — and which it is not. */
+exports.MONTHLY_CAP_IS_SEPARATE = 'This is the machine monthly cap, separate from your plan allowance and credits; overage does not raise it.';

package/dist/lib/node-adapter.js

@@ -271,10 +271,22 @@ function createNodeAdapter(opts = {}) {
             }
         }
         // Refresh the in-process override so the retry on the SAME request
-        // sees the new token. writeToBackend (called inside the broker)
-        // already wrote to the keychain/file — but the adapter caches the
-        // credential and only re-reads when explicitly told to.
+        // sees the new token. For a durable mint, writeToBackend (called inside
+        // the broker) already wrote to the keychain/file — but the adapter
+        // caches the credential and only re-reads when explicitly told to.
         const accessToken = outcome.outcome.accessToken;
+        if (outcome.outcome.brokered) {
+            // Broker-mode hand-off: an in-memory access token, nothing persisted.
+            // 'env-token' keeps `ensureFreshCliCredential` from trying to rotate a
+            // stored family that does not exist; renewal re-redeems the descriptor.
+            setAdapterCredentialOverride({
+                token: accessToken,
+                source: 'env-token',
+                kind: (0, auth_core_1.classifyTokenKind)(accessToken),
+            });
+            onTokenRefresh?.(accessToken);
+            return true;
+        }
         setAdapterCredentialOverride({
             token: accessToken,
             source: outcome.outcome.storedIn === 'keychain' ? 'keychain' : 'file',

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/cliHandoffWire.d.ts

@@ -0,0 +1,90 @@
+/**
+ * cliHandoffWire.ts — the ONE declaration of the CLI↔daemon hand-off wire
+ * contracts, shared by the daemon (writer/server) and the CLI (reader).
+ *
+ * Two contracts live here:
+ *
+ *   1. The hand-off descriptor file (`descriptor.json` on Dedicated guests,
+ *      `daemon-island.<profile>.json` on laptops). Until now the shape was
+ *      declared twice — `DedicatedCliHandoffDescriptor` daemon-side and
+ *      `LocalBootstrap` CLI-side — two type declarations for one file format,
+ *      the same drift disease `sessionPermissionAuthority` fixed.
+ *   2. The broker-mode redeem exchange: `POST /v1/auth/cli-handoff-token`
+ *      request/response plus its error codes.
+ *
+ * Readers stay loose (unknown fields ignored, absent `handoffModes` reads as
+ * refresh-family-only) so a new field never breaks an older peer; writers
+ * must produce the full shape.
+ */
+/**
+ * What a caller may redeem the descriptor secret for.
+ *  - `refresh_family`: the legacy durable mint (90-day cli-scope family).
+ *  - `access_token`:   broker mode — a short-lived access token from a
+ *                      daemon-owned family; nothing durable leaves the daemon.
+ */
+export declare const CLI_HANDOFF_MODES: readonly ["refresh_family", "access_token"];
+export type CliHandoffMode = (typeof CLI_HANDOFF_MODES)[number];
+/** Broker-mode redeem route on the daemon's loopback server. */
+export declare const CLI_HANDOFF_TOKEN_PATH = "/v1/auth/cli-handoff-token";
+/** Error codes this contract emits. String literals so both ends compare
+ *  without importing a symbol they may not have. */
+export declare const CLI_HANDOFF_TOKEN_ERROR_UNAVAILABLE = "HANDOFF_TOKEN_UNAVAILABLE";
+/** Emitted by the LEGACY /v1/auth/cli-handoff route when a hand-off-secret
+ *  caller asks for a refresh family the daemon no longer mints for it. */
+export declare const CLI_HANDOFF_ERROR_BROKER_ONLY = "HANDOFF_BROKER_ONLY";
+/**
+ * The descriptor file format. `version` is absent on the oldest island files
+ * and `1` on the first dedicated-guest descriptors; `handoffModes` first
+ * appears at version 2. Every field the CLI needs to dial is validated; the
+ * rest ride along untyped.
+ */
+export interface CliHandoffDescriptor {
+    version?: number;
+    pid?: number;
+    daemonId?: string;
+    host?: string;
+    port?: number;
+    /** Base64 handshake secret — hand-off-only on guests, island on laptops. */
+    secret?: string;
+    /** Server URL the daemon is authenticated against. Older daemons omit it;
+     *  readers refuse to broker without it (never mint against an unknown
+     *  server). */
+    serverUrl?: string;
+    /** Daemon-authored epoch counter; bumped when the descriptor is republished. */
+    epoch?: number;
+    handoffModes?: CliHandoffMode[];
+}
+/**
+ * Parse an untrusted descriptor JSON value. Returns null when the fields the
+ * caller cannot proceed without — host, port, secret — are absent or
+ * mistyped. Unknown fields and future `version` values are tolerated: the
+ * reader ignores them, which is what makes additive evolution safe.
+ */
+export declare function parseCliHandoffDescriptor(value: unknown): CliHandoffDescriptor | null;
+/**
+ * Untrusted `handoffModes` input → known literals only, deduped. An
+ * unrecognized future mode is dropped rather than widening by coercion.
+ */
+export declare function normalizeHandoffModes(value: unknown): CliHandoffMode[];
+/**
+ * The versioned-default rule: a descriptor that never declares modes offers
+ * only the durable mint it has always offered. Mode negotiation is purely
+ * additive — a daemon advertises the new mode, it never un-advertises the
+ * old one by accident.
+ */
+export declare function advertisedHandoffModes(d: CliHandoffDescriptor): CliHandoffMode[];
+export declare function descriptorOffersAccessToken(d: CliHandoffDescriptor): boolean;
+export interface CliHandoffTokenRequest {
+    /** Bypass the daemon broker's cached token (the 401-recovery path). */
+    forceRefresh?: boolean;
+}
+export interface CliHandoffTokenResponse {
+    accessToken: string;
+    /** Absolute expiry in ms since epoch, when the daemon knows it. */
+    accessExpiresAt?: number;
+    /** Server the minted credential belongs to — lets the caller verify it is
+     *  about to use a token for the API it thinks it is talking to. */
+    serverUrl?: string;
+}
+/** Parse the redeem response; null when the token itself is absent. */
+export declare function parseCliHandoffTokenResponse(value: unknown): CliHandoffTokenResponse | null;

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/cliHandoffWire.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * cliHandoffWire.ts — the ONE declaration of the CLI↔daemon hand-off wire
+ * contracts, shared by the daemon (writer/server) and the CLI (reader).
+ *
+ * Two contracts live here:
+ *
+ *   1. The hand-off descriptor file (`descriptor.json` on Dedicated guests,
+ *      `daemon-island.<profile>.json` on laptops). Until now the shape was
+ *      declared twice — `DedicatedCliHandoffDescriptor` daemon-side and
+ *      `LocalBootstrap` CLI-side — two type declarations for one file format,
+ *      the same drift disease `sessionPermissionAuthority` fixed.
+ *   2. The broker-mode redeem exchange: `POST /v1/auth/cli-handoff-token`
+ *      request/response plus its error codes.
+ *
+ * Readers stay loose (unknown fields ignored, absent `handoffModes` reads as
+ * refresh-family-only) so a new field never breaks an older peer; writers
+ * must produce the full shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_HANDOFF_ERROR_BROKER_ONLY = exports.CLI_HANDOFF_TOKEN_ERROR_UNAVAILABLE = exports.CLI_HANDOFF_TOKEN_PATH = exports.CLI_HANDOFF_MODES = void 0;
+exports.parseCliHandoffDescriptor = parseCliHandoffDescriptor;
+exports.normalizeHandoffModes = normalizeHandoffModes;
+exports.advertisedHandoffModes = advertisedHandoffModes;
+exports.descriptorOffersAccessToken = descriptorOffersAccessToken;
+exports.parseCliHandoffTokenResponse = parseCliHandoffTokenResponse;
+/**
+ * What a caller may redeem the descriptor secret for.
+ *  - `refresh_family`: the legacy durable mint (90-day cli-scope family).
+ *  - `access_token`:   broker mode — a short-lived access token from a
+ *                      daemon-owned family; nothing durable leaves the daemon.
+ */
+exports.CLI_HANDOFF_MODES = ['refresh_family', 'access_token'];
+/** Broker-mode redeem route on the daemon's loopback server. */
+exports.CLI_HANDOFF_TOKEN_PATH = '/v1/auth/cli-handoff-token';
+/** Error codes this contract emits. String literals so both ends compare
+ *  without importing a symbol they may not have. */
+exports.CLI_HANDOFF_TOKEN_ERROR_UNAVAILABLE = 'HANDOFF_TOKEN_UNAVAILABLE';
+/** Emitted by the LEGACY /v1/auth/cli-handoff route when a hand-off-secret
+ *  caller asks for a refresh family the daemon no longer mints for it. */
+exports.CLI_HANDOFF_ERROR_BROKER_ONLY = 'HANDOFF_BROKER_ONLY';
+/**
+ * Parse an untrusted descriptor JSON value. Returns null when the fields the
+ * caller cannot proceed without — host, port, secret — are absent or
+ * mistyped. Unknown fields and future `version` values are tolerated: the
+ * reader ignores them, which is what makes additive evolution safe.
+ */
+function parseCliHandoffDescriptor(value) {
+    if (value == null || typeof value !== 'object')
+        return null;
+    const v = value;
+    if (typeof v.host !== 'string' || v.host.length === 0)
+        return null;
+    if (typeof v.port !== 'number' || !Number.isInteger(v.port) || v.port <= 0)
+        return null;
+    if (typeof v.secret !== 'string' || v.secret.length === 0)
+        return null;
+    return {
+        ...(typeof v.version === 'number' ? { version: v.version } : {}),
+        ...(typeof v.pid === 'number' ? { pid: v.pid } : {}),
+        ...(typeof v.daemonId === 'string' ? { daemonId: v.daemonId } : {}),
+        host: v.host,
+        port: v.port,
+        secret: v.secret,
+        ...(typeof v.serverUrl === 'string' ? { serverUrl: v.serverUrl } : {}),
+        ...(typeof v.epoch === 'number' ? { epoch: v.epoch } : {}),
+        ...(Array.isArray(v.handoffModes)
+            ? { handoffModes: normalizeHandoffModes(v.handoffModes) }
+            : {}),
+    };
+}
+/**
+ * Untrusted `handoffModes` input → known literals only, deduped. An
+ * unrecognized future mode is dropped rather than widening by coercion.
+ */
+function normalizeHandoffModes(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const m of value) {
+        if (exports.CLI_HANDOFF_MODES.includes(m) &&
+            !out.includes(m)) {
+            out.push(m);
+        }
+    }
+    return out;
+}
+/**
+ * The versioned-default rule: a descriptor that never declares modes offers
+ * only the durable mint it has always offered. Mode negotiation is purely
+ * additive — a daemon advertises the new mode, it never un-advertises the
+ * old one by accident.
+ */
+function advertisedHandoffModes(d) {
+    const declared = normalizeHandoffModes(d.handoffModes);
+    return declared.length > 0 ? declared : ['refresh_family'];
+}
+function descriptorOffersAccessToken(d) {
+    return advertisedHandoffModes(d).includes('access_token');
+}
+/** Parse the redeem response; null when the token itself is absent. */
+function parseCliHandoffTokenResponse(value) {
+    if (value == null || typeof value !== 'object')
+        return null;
+    const v = value;
+    if (typeof v.accessToken !== 'string' || v.accessToken.length === 0)
+        return null;
+    return {
+        accessToken: v.accessToken,
+        ...(typeof v.accessExpiresAt === 'number' ? { accessExpiresAt: v.accessExpiresAt } : {}),
+        ...(typeof v.serverUrl === 'string' ? { serverUrl: v.serverUrl } : {}),
+    };
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/credentialSession.d.ts

@@ -0,0 +1,47 @@
+/**
+ * credentialSession.ts — the shared credential-lifecycle kernel (policy half).
+ *
+ * A credential lifecycle is policy × mechanism. The policy — serve a cached
+ * token until its expiry-skew window, collapse concurrent acquires onto one
+ * in-flight operation, invalidate on a resource-side 401 — is identical for
+ * every surface and was being re-implemented per consumer (task token-broker,
+ * delegated-cli redemption, the human CLI refresh path). The mechanism —
+ * WHERE the durable secret lives and HOW a token is acquired — legitimately
+ * differs (in-memory daemon family vs file+envelope+lock vs loopback redeem)
+ * and stays behind the `acquire` seam.
+ *
+ * Deliberately thin: no persistence, no retry policy, no logging. Callers
+ * own their store and their error surfaces; this owns the cache/single-
+ * flight/invalidate invariants so they cannot drift between surfaces.
+ */
+/** What an acquire returns. `expiresAtMs` absent means "no known expiry" —
+ *  the token is served until `invalidate()` or an acquire replaces it. */
+export interface AcquiredCredential {
+    accessToken: string;
+    /** Absolute expiry in ms since epoch, when the issuer tells us. */
+    expiresAtMs?: number;
+}
+export interface CredentialSessionOptions {
+    /**
+     * The mechanism. Called with `forceRefresh: true` when the caller asked to
+     * bypass the cache (the 401-recovery path) — implementations should renew
+     * rather than serve their own cache. A rejected promise propagates to every
+     * waiter and is never cached.
+     */
+    acquire: (forceRefresh: boolean) => Promise<AcquiredCredential>;
+    /** Serve the cached token until this many ms before expiry. Default 30s. */
+    skewMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+export interface CredentialSession {
+    /**
+     * Resolves a usable access token: the cached one while it is inside its
+     * freshness window, otherwise a single shared acquire. `forceRefresh`
+     * discards the cache first (use after a resource 401).
+     */
+    getToken(forceRefresh?: boolean): Promise<string>;
+    /** Drop the cached token; the next getToken() acquires. */
+    invalidate(): void;
+}
+export declare function createCredentialSession(opts: CredentialSessionOptions): CredentialSession;

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/credentialSession.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * credentialSession.ts — the shared credential-lifecycle kernel (policy half).
+ *
+ * A credential lifecycle is policy × mechanism. The policy — serve a cached
+ * token until its expiry-skew window, collapse concurrent acquires onto one
+ * in-flight operation, invalidate on a resource-side 401 — is identical for
+ * every surface and was being re-implemented per consumer (task token-broker,
+ * delegated-cli redemption, the human CLI refresh path). The mechanism —
+ * WHERE the durable secret lives and HOW a token is acquired — legitimately
+ * differs (in-memory daemon family vs file+envelope+lock vs loopback redeem)
+ * and stays behind the `acquire` seam.
+ *
+ * Deliberately thin: no persistence, no retry policy, no logging. Callers
+ * own their store and their error surfaces; this owns the cache/single-
+ * flight/invalidate invariants so they cannot drift between surfaces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCredentialSession = createCredentialSession;
+const DEFAULT_SKEW_MS = 30_000;
+function createCredentialSession(opts) {
+    const skewMs = opts.skewMs ?? DEFAULT_SKEW_MS;
+    const now = opts.now ?? Date.now;
+    let cached = null;
+    let inFlight = null;
+    let inFlightForced = false;
+    // Monotonic generation so a superseded in-flight acquire (a forceRefresh
+    // launched while a plain acquire was still running) cannot write its stale
+    // result back over the newer one.
+    let generation = 0;
+    const fresh = (t) => t.expiresAtMs == null || now() < t.expiresAtMs - skewMs;
+    const acquireShared = (force) => {
+        // A forced acquire must not join a non-forced in-flight one — that would
+        // serve the very credential a 401 just invalidated. A forced in-flight
+        // DOES satisfy non-forced waiters: it is already renewing.
+        if (inFlight && (inFlightForced || !force))
+            return inFlight;
+        const gen = ++generation;
+        const p = opts.acquire(force).then((t) => {
+            if (gen === generation)
+                cached = t;
+            return t;
+        });
+        inFlight = p;
+        inFlightForced = force;
+        // `then(cleanup, cleanup)` not `.finally(cleanup)`: finally propagates the
+        // rejection into a derived promise nobody awaits — an unhandledRejection.
+        const cleanup = () => {
+            if (inFlight === p) {
+                inFlight = null;
+                inFlightForced = false;
+            }
+        };
+        p.then(cleanup, cleanup);
+        return p;
+    };
+    return {
+        async getToken(forceRefresh = false) {
+            if (forceRefresh)
+                cached = null;
+            if (cached && fresh(cached))
+                return cached.accessToken;
+            return (await acquireShared(forceRefresh)).accessToken;
+        },
+        invalidate() {
+            cached = null;
+        },
+    };
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/daemonToolApproval.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Server-attested tool approval (OSK-11975 follow-up to the `manual` mode
+ * refusal on `daemon:tool:request`).
+ *
+ * A daemon category in `manual` mode means "a PERSON approves each call". On
+ * the harness-session path the daemon asks through the permission bridge; on
+ * the daemon-tool path a cloud agent's call used to be refused outright,
+ * because the request carried no approval and there was no channel back to a
+ * person. The attested-approval protocol closes that gap without weakening
+ * the guarantee:
+ *
+ *   1. The daemon announces `daemon_tool_attested_approval_v1` and its
+ *      resolved per-category posture (`toolPermissionModes`) at register time.
+ *   2. Before proxying a call, the server reads the announced posture for the
+ *      tool's category. `manual` means it must ask first — through the same
+ *      permission surface (`canUseTool` → `permission:request`) an in-process
+ *      SDK turn would have used — and only then dispatch, carrying an
+ *      `attestedApproval` object on the request.
+ *   3. The daemon verifies the attestation's SHAPE and BINDING — it is bound
+ *      to this exact (toolUseId, toolName, toolInput digest) and expires
+ *      quickly — and allows the call. A missing or malformed attestation gets
+ *      the same named refusal as before.
+ *
+ * What the daemon verifies is the binding, not the server's honesty: the
+ * request already arrives over the daemon's authenticated server channel, so
+ * the field IS the attestation. What the binding buys is that the model —
+ * which authors `toolInput` — cannot mint an approval, and an approval for
+ * one call cannot be replayed onto another.
+ */
+/** Announced by a daemon that honours `attestedApproval` on daemon:tool:request. */
+export declare const DAEMON_TOOL_ATTESTED_APPROVAL_CAPABILITY = "daemon_tool_attested_approval_v1";
+/**
+ * Announced by a daemon that honours `toolPosture: 'read_only'` on
+ * daemon:tool:request — the daemon-tool-path expression of the wire `plan`
+ * session mode: reads run, every mutating category is refused with a named
+ * reason. Carries INTENT like `browserPolicy: 'read_only'` — the daemon owns
+ * what read-only means, so the server cannot widen the fence by shipping a
+ * wider value.
+ */
+export declare const DAEMON_TOOL_READ_ONLY_CAPABILITY = "daemon_tool_read_only_v1";
+/**
+ * Tool categories the daemon recognizes for permission purposes. This is the
+ * wire vocabulary the daemon's announced `toolPermissionModes` is keyed on —
+ * shared so the server's pre-dispatch check and the daemon's own enforcement
+ * classify a tool name identically (a third map was exactly the drift this
+ * package exists to prevent).
+ */
+export type DaemonToolCategory = 'read' | 'write' | 'bash' | 'browser' | 'claude_session' | 'native_ui';
+export declare const DAEMON_TOOL_CATEGORIES: readonly DaemonToolCategory[];
+/** Map a tool name to its category. Unknown tools take the restrictive answer. */
+export declare function categoryForDaemonTool(toolName: string): DaemonToolCategory;
+/**
+ * The posture a daemon announces per category for the daemon-tool path:
+ *  - `auto`      — the call runs once guardrails pass; no attestation needed
+ *  - `manual`    — the call needs a person; the server must attach a fresh
+ *                  `attestedApproval` or the daemon refuses it
+ *  - `delegated` — the category's own policy decides per action (browser,
+ *                  native UI); asking up front would ask the wrong question
+ */
+export type DaemonToolPathPosture = 'auto' | 'manual' | 'delegated';
+export type DaemonToolPermissionModes = Readonly<Partial<Record<DaemonToolCategory, DaemonToolPathPosture>>>;
+/** The wire field values `toolPosture` accepts. Unknown values must be ignored. */
+export type DaemonToolPosture = 'read_only';
+/**
+ * How long an attestation stays valid. Short: it answers ONE person, about
+ * THIS call, moments ago — it is not a standing grant. The server asks and
+ * dispatches back-to-back, so the window only has to outlive publish latency.
+ */
+export declare const ATTESTED_TOOL_APPROVAL_TTL_MS: number;
+export interface AttestedToolApproval {
+    v: 1;
+    /** Binds the approval to this exact call — a different call gets nothing. */
+    toolUseId: string;
+    toolName: string;
+    /** SHA-256 of the canonical tool input (see `canonicalToolInputDigest`). */
+    inputSha256: string;
+    /** Who answered on the server's permission surface. */
+    decidedBy: 'user';
+    issuedAt: number;
+    expiresAt: number;
+}
+/** The digest both sides compute over `toolInput`. */
+export declare function canonicalToolInputDigest(toolInput: unknown): string;
+/** Server side: mint the attestation after a person approved THIS call. */
+export declare function mintAttestedToolApproval(args: {
+    toolUseId: string;
+    toolName: string;
+    toolInput: unknown;
+    now?: number;
+    ttlMs?: number;
+}): AttestedToolApproval;
+export type AttestedToolApprovalVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'absent' | 'malformed' | 'binding' | 'expired';
+};
+/**
+ * Daemon side: verify an attestation against the call it claims to approve.
+ * Untrusted wire input — every field is checked, and any mismatch is a plain
+ * "no approval", never a partial credit. `reason` is for daemon logs; the
+ * refusal text stays generic so a probing caller learns nothing new.
+ */
+export declare function verifyAttestedToolApproval(approval: unknown, call: {
+    toolUseId: string;
+    toolName: string;
+    toolInput: unknown;
+    now?: number;
+}): AttestedToolApprovalVerdict;