@openplan/dsh-fuse 0.1.0 → 0.2.0

package/README.md

@@ -15,12 +15,12 @@ O pacote declara `dsh.bundle`, que é o que faz `dsh plugin add` ativar a
 camada. Sem essa declaração o pnpm instalaria uma biblioteca inerte.
 
 ```bash
-# npm — a forma canônica de instalação (publicado, v0.1.0)
+# npm — a forma canônica de instalação (publicado)
 dsh plugin --profile <perfil> add @openplan/dsh-fuse
 
 # tarball (sem depender de registry)
 pnpm pack                       # gera openplan-dsh-fuse-<versão>.tgz
-dsh plugin --profile <perfil> add ./openplan-dsh-fuse-0.1.0.tgz
+dsh plugin --profile <perfil> add ./openplan-dsh-fuse-<versão>.tgz
 
 # direto do git (exige allowlist de build do pnpm >= 10 — veja a doc do harness)
 dsh plugin --profile <perfil> add github:<org>/<repo>#<sha>
@@ -53,7 +53,9 @@ que duplicaria o id e faria o loader falhar com `duplicate loader entry id`):
   config:
     project: meu-projeto
     dev: eu@empresa.com
-    # Segredo nunca em texto puro no YAML — a tag !!js resolve no load.
+    # Caminho headless/CI (máquinas sem navegador). O padrão para humanos é
+    # `dsh plugin … exec dsh-fuse-connect` (device flow) — ver acima. Segredo
+    # nunca em texto puro no YAML — a tag !!js resolve no load.
     orgKey: !!js process.env.DSH_ORG_KEY
     baseUrl: https://dsh-api.openplan.cc
     # Orçamento local (o fuse corta offline antes de gastar):
@@ -99,6 +101,31 @@ ou uma `cascade` que não intersecta `policies.allowedModels` são recusados no
 boot. Preço **não** é exigido — o plugin resolve genericamente (abaixo); um
 modelo sem preço é um estado visível (`unpriced`), não um boot falho.
 
+## Conectar ao painel (device flow — o caminho padrão)
+
+Para humanos atachando uma máquina à sua org, o jeito moderno é o **RFC 8628
+device flow** (o mesmo padrão de `gh auth login`, `wrangler login`, Stripe):
+
+```bash
+dsh plugin --profile <perfil> exec dsh-fuse-connect
+```
+
+O comando imprime uma URL + código, você aprova no navegador (login no painel),
+e o token fica salvo com permissões `0600` em
+`$DSH_HOME/dsh-fuse/credentials.json` — o plugin passa a sincronizar com o
+SaaS **sem colar chave nenhuma**:
+
+- o token é **bound ao usuário** que aprovou (auditoria: quem conectou a
+  máquina) e **revogável** no painel ("Sessões conectadas") — revogação cai no
+  próximo sync (`401` → o plugin volta a local-only e mantém as linhas).
+- escopos mínimos (`usage:write`, `policy:read`) — o que o batch precisa.
+- cabeçalho de autenticação: `Authorization: Bearer <token>` (o `x-org-key`
+  continua aceito para máquinas/CI).
+
+Se o seu fluxo é headless (CI, container, máquina sem navegador), o caminho
+disponível é a **org key** no config (abaixo) — a API aceita os dois; o device
+flow é o padrão para humanos.
+
 ## Como o preço é resolvido
 
 O harness reporta o modelo com o id do **adapter** (normalmente com prefixo de

package/dist/connect.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * `dsh plugin connect` — the RFC 8628 device-flow CLI (ADR-0020 default).
+ *
+ * Runs in the user's terminal, never on the boot path:
+ *   1. calls `POST {base}/v1/device-auth` and prints the verification URI;
+ *   2. polls `POST {base}/v1/device-auth/token` until the user approves in
+ *      the browser (or the code expires/denies);
+ *   3. persists the returned device token via `saveCredentials`
+ *      (0600 file under ~/.dsh/dsh-fuse/, keychain documented as a future
+ *      backend), so the plugin's next boot syncs with the SaaS.
+ *
+ * The org key (`orgKey` in config/env) remains the headless/CI path — this
+ * command is the interactive default. Standard CLI hygiene: only prints the
+ * verifiable URI + code, never the token; supports `--clipboard` to copy the
+ * code (like `gh auth login -c`).
+ */
+declare function main(argv: string[]): Promise<void>;
+export { main };

package/dist/connect.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * `dsh plugin connect` — the RFC 8628 device-flow CLI (ADR-0020 default).
+ *
+ * Runs in the user's terminal, never on the boot path:
+ *   1. calls `POST {base}/v1/device-auth` and prints the verification URI;
+ *   2. polls `POST {base}/v1/device-auth/token` until the user approves in
+ *      the browser (or the code expires/denies);
+ *   3. persists the returned device token via `saveCredentials`
+ *      (0600 file under ~/.dsh/dsh-fuse/, keychain documented as a future
+ *      backend), so the plugin's next boot syncs with the SaaS.
+ *
+ * The org key (`orgKey` in config/env) remains the headless/CI path — this
+ * command is the interactive default. Standard CLI hygiene: only prints the
+ * verifiable URI + code, never the token; supports `--clipboard` to copy the
+ * code (like `gh auth login -c`).
+ */
+import { spawnSync } from "node:child_process";
+import { saveCredentials } from "./credentials.js";
+const DEFAULT_BASE_URL = "https://dsh-api.openplan.cc";
+const POLL_INTERVAL_MS = 5_000;
+function usage() {
+    console.error([
+        "usage: dsh plugin --profile <perfil> exec connect [options]",
+        "",
+        "options:",
+        `  --base-url <url>   SaaS API base (default ${DEFAULT_BASE_URL})`,
+        "  --clipboard        copy the device code to the clipboard",
+        "  --help             show this help",
+    ].join("\n"));
+    process.exit(2);
+}
+function parseArgs(argv) {
+    let baseUrl = DEFAULT_BASE_URL;
+    let clipboard = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--base-url") {
+            const value = argv[i + 1];
+            if (!value || value.startsWith("-"))
+                usage();
+            baseUrl = value;
+            i += 1;
+        }
+        else if (arg === "--clipboard") {
+            clipboard = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            usage();
+        }
+        else {
+            usage();
+        }
+    }
+    return { baseUrl, clipboard };
+}
+async function copyToClipboard(text) {
+    try {
+        const command = process.platform === "darwin"
+            ? "pbcopy"
+            : process.platform === "win32"
+                ? "clip"
+                : "xclip";
+        const result = spawnSync(command, [], {
+            input: text,
+            encoding: "utf8",
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Poll the token endpoint following RFC 8628 §3.3 until it yields. */
+async function pollToken(baseUrl, deviceCode) {
+    for (;;) {
+        const res = await fetch(`${baseUrl}/v1/device-auth/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ device_code: deviceCode }),
+        });
+        if (res.status === 200) {
+            const body = (await res.json());
+            if (!body.access_token) {
+                throw new Error("token exchange returned no access_token");
+            }
+            return { token: body.access_token };
+        }
+        const body = (await res.json().catch(() => ({})));
+        if (body.error === "authorization_pending") {
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+            continue;
+        }
+        if (body.error === "slow_down") {
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS + 5_000));
+            continue;
+        }
+        throw new Error(body.error === "expired"
+            ? "o código expirou — rode `dsh plugin connect` de novo"
+            : body.error === "denied"
+                ? "autorização negada"
+                : `falha na troca do código (${body.error ?? res.status})`);
+    }
+}
+async function main(argv) {
+    const { baseUrl, clipboard } = parseArgs(argv);
+    const issued = (await (await fetch(`${baseUrl}/v1/device-auth`, { method: "POST" })).json());
+    if (!issued.device_code || !issued.user_code) {
+        throw new Error("device-auth não retornou códigos — API compatível?");
+    }
+    process.stdout.write([
+        "",
+        "┌────────────────────────────────────────────────────────┐",
+        "│  Conecte esta máquina ao dsh.openplan.cc              │",
+        "└────────────────────────────────────────────────────────┘",
+        "",
+        `  1. Abra no navegador:  ${issued.verification_uri_complete ?? issued.verification_uri}`,
+        `  2. Confirme o código:   ${issued.user_code}`,
+        "",
+    ].join("\n"));
+    if (clipboard) {
+        const copied = await copyToClipboard(issued.user_code);
+        process.stdout.write(copied
+            ? "  → código copiado para a área de transferência.\n\n"
+            : "  → (clipboard indisponível — copie manualmente)\n\n");
+    }
+    // Prove we're alive while the browser approval is pending (the harness
+    // turn may be the terminal that runs this — dot feedback is friendlier).
+    let dots = 0;
+    const pulse = setInterval(() => {
+        dots += 1;
+        process.stdout.write(`  aguardando aprovação${".".repeat(dots)}\r`);
+    }, POLL_INTERVAL_MS);
+    try {
+        const { token } = await pollToken(baseUrl, issued.device_code);
+        clearInterval(pulse);
+        process.stdout.write("\n  ✓ conectado — token salvo com segurança.\n\n");
+        const userHint = undefined; // the API returns no name yet
+        saveCredentials({
+            baseUrl,
+            token,
+            connectedAt: new Date().toISOString(),
+            ...(userHint ? { userHint } : {}),
+        });
+    }
+    finally {
+        clearInterval(pulse);
+    }
+}
+// Run only when executed directly (`node dist/connect.js` / the bin entry),
+// never when the module is imported by the plugin or tests.
+const isDirectRun = process.argv[1] !== undefined &&
+    import.meta.url === new URL(`file://${process.argv[1]}`).href;
+if (isDirectRun) {
+    main(process.argv.slice(2)).catch((error) => {
+        console.error(`conexão falhou: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    });
+}
+export { main };

package/dist/credentials.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Machine credentials for the SaaS (ADR-0020): the device token minted by
+ * `dsh plugin connect`. Stored as a 0600 JSON file under the harness home —
+ * the same directory that already owns the ledger (`local.db`) and the same
+ * degradation gh uses when no OS keychain exists. An OS-keychain backend
+ * (e.g. @napi-rs/keyring) is a documented future option; the plugin's
+ * zero-native-build distribution promise is why the file store ships first.
+ *
+ * Resolution order in the runtime: credentials file → configured
+ * `orgKey`/`baseUrl` (env or YAML) → local-only. The file wins because it is
+ * the human-attached identity; the config pair stays the headless/CI path.
+ */
+/** What the connect command persists after a successful device flow. */
+export interface DeviceCredentials {
+    baseUrl: string;
+    token: string;
+    /** Human-readable hint of who authorized (display only, from the API). */
+    userHint?: string;
+    connectedAt: string;
+}
+/** Resolve the harness home the same way the store does (DSH_HOME → ~/.dsh). */
+export declare function dshHome(): string;
+/** The credentials file the plugin and the connect CLI both use. */
+export declare function credentialsFile(): string;
+/** Read the machine credentials; `null` when absent or unreadable. */
+export declare function loadCredentials(): DeviceCredentials | null;
+/**
+ * Persist machine credentials atomically (temp + rename) with 0600 perms —
+ * the write path for `dsh plugin connect`.
+ */
+export declare function saveCredentials(input: DeviceCredentials): void;
+/** Clear the machine credentials — the `disconnect` command / 401 path. */
+export declare function clearCredentials(): void;

package/dist/credentials.js

@@ -0,0 +1,78 @@
+/**
+ * Machine credentials for the SaaS (ADR-0020): the device token minted by
+ * `dsh plugin connect`. Stored as a 0600 JSON file under the harness home —
+ * the same directory that already owns the ledger (`local.db`) and the same
+ * degradation gh uses when no OS keychain exists. An OS-keychain backend
+ * (e.g. @napi-rs/keyring) is a documented future option; the plugin's
+ * zero-native-build distribution promise is why the file store ships first.
+ *
+ * Resolution order in the runtime: credentials file → configured
+ * `orgKey`/`baseUrl` (env or YAML) → local-only. The file wins because it is
+ * the human-attached identity; the config pair stays the headless/CI path.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Resolve the harness home the same way the store does (DSH_HOME → ~/.dsh). */
+export function dshHome() {
+    const override = process.env.DSH_HOME?.trim();
+    return override ? override : homedir();
+}
+/** The credentials file the plugin and the connect CLI both use. */
+export function credentialsFile() {
+    return join(dshHome(), ".dsh", "dsh-fuse", "credentials.json");
+}
+/** Read the machine credentials; `null` when absent or unreadable. */
+export function loadCredentials() {
+    const file = credentialsFile();
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const { baseUrl, token } = parsed;
+        if (typeof baseUrl !== "string" || !baseUrl)
+            return null;
+        if (typeof token !== "string" || !token)
+            return null;
+        const connectedAt = typeof parsed.connectedAt === "string"
+            ? parsed.connectedAt
+            : new Date().toISOString();
+        const userHint = typeof parsed.userHint === "string"
+            ? parsed.userHint
+            : undefined;
+        return { baseUrl, token, connectedAt, ...(userHint ? { userHint } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist machine credentials atomically (temp + rename) with 0600 perms —
+ * the write path for `dsh plugin connect`.
+ */
+export function saveCredentials(input) {
+    const file = credentialsFile();
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(input, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, file);
+    // renameSync keeps the temp's mode, but re-assert for filesystems that
+    // lose it on move.
+    chmodSync(file, 0o600);
+}
+/** Clear the machine credentials — the `disconnect` command / 401 path. */
+export function clearCredentials() {
+    try {
+        const file = credentialsFile();
+        if (existsSync(file))
+            renameSync(file, `${file}.revoked`);
+    }
+    catch {
+        // Nothing to do if the file (or dir) is gone.
+    }
+}

package/dist/harness.js

@@ -33,6 +33,7 @@
  */
 import { createBudgetStatusTool, } from "./budget-tool.js";
 import { assertUsableConfig } from "./config.js";
+import { clearCredentials, loadCredentials } from "./credentials.js";
 import { fuseDecision } from "./fuse.js";
 import { hashSessionId, projectCall } from "./meter.js";
 import { createPricingCache, estimateCostUsd, fetchPricingTable, } from "./pricing.js";
@@ -98,6 +99,65 @@ export function apply(ctx, config) {
     const logger = ctx.logger;
     const tokenMeter = () => ctx.get?.("tokenMeter") ?? undefined;
     const llm = () => ctx.get?.("llm") ?? undefined;
+    /**
+     * In-session cut notices: when the fuse blocks a step, the harness ends the
+     * turn as `{ kind: "blocked" }` with no visible explanation — the user is
+     * told nothing. The harness's convention for "something just happened" is a
+     * plugin-producer `notice`-form user message on the SESSION LOG (the same
+     * `session.append("user/message", …, { surfaceOp: "append" })` the agent
+     * loop itself uses at every message boundary), which the client
+     * conversation renders as a collapsed one-line row expandable to the full
+     * text. One notice per (rule, window) per process: a budget that stays
+     * tripped must not restate itself on every blocked step, and a new window
+     * that re-trips it should announce that again.
+     *
+     * NOT `agent.inject`: that writes into the model's inbox (context for the
+     * NEXT step — invisible to the GUI), it never touches the session log. A
+     * turn that ends blocked has no next step, so an injected notice would sit
+     * in the inbox forever, never rendered. This bug is why the 0.1.1 cut
+     * alerts were silent in the panel.
+     */
+    const cutNotices = new Set();
+    /** Set when a bearer 401 revokes the device token mid-sync; the next step
+     * announces it to the session once (the timer has no agent to address). */
+    let revocationNoticePending = false;
+    /**
+     * Append a plugin-producer `notice`-form user message to the session log —
+     * the GUI renders it as a collapsed row. Shared by the fuse cut notice and
+     * the revocation announcement.
+     */
+    function appendSessionNotice(agent, input) {
+        try {
+            agent.session.append("user/message", {
+                id: crypto.randomUUID(),
+                role: "user",
+                content: [{ type: "text", text: input.detail }],
+                source: {
+                    kind: "plugin",
+                    plugin: "@openplan/dsh-fuse",
+                    form: "notice",
+                    summary: input.summary,
+                },
+            }, { surfaceOp: "append" });
+        }
+        catch (error) {
+            // A notice must never break the reject/sync path — the underlying
+            // event (cut or revocation) already landed; the UI alert is
+            // best-effort.
+            logger.warn("[dsh] session notice not delivered", {
+                summary: input.summary,
+                error: String(error),
+            });
+        }
+    }
+    function notifyCut(agent, input) {
+        const window = windowStart(new Date(), "day");
+        const key = `${input.rule}\u0000${window}`;
+        if (cutNotices.has(key))
+            return;
+        cutNotices.add(key);
+        appendSessionNotice(agent, input);
+    }
     /**
      * Documented load-time rule: *"A plugin should also reject schema-valid
      * config that names an unavailable resource or provider as soon as it can
@@ -151,7 +211,11 @@ export function apply(ctx, config) {
         gatewayProvider: config.pricingGatewayProvider || undefined,
         gatewayApiKeyEnv: config.pricingGatewayApiKeyEnv || undefined,
         override: config.pricingTable,
-    }), 3_600_000, (table) => void store.setPricingTable(table));
+    }), 3_600_000, 
+    // A refresh can resolve AFTER unload (slow network, test teardown):
+    // persisting a table into a closed store must be a swallowed no-op,
+    // never an unhandled rejection.
+    (table) => void store.setPricingTable(table).catch(() => undefined));
     void store.pricingTable().then((persisted) => {
         if (persisted)
             pricingCache.hydrate(persisted);
@@ -512,6 +576,15 @@ export function apply(ctx, config) {
     }
     // ── Fuse: the primary gate, before any token is spent ──────────────────
     ctx.on("agent/pre-step", async (payload, next) => {
+        // One-time revocation announcement: a device-token 401 during sync
+        // disconnected the SaaS; tell the user on the next step they run.
+        if (revocationNoticePending) {
+            revocationNoticePending = false;
+            appendSessionNotice(payload.agent, {
+                summary: "fuse: conexão com o painel revogada",
+                detail: "O token do dispositivo foi revogado no painel — este profile voltou a local-only (nada sincroniza, o fuse continua ativo). Reconecte com `dsh plugin --profile <perfil> exec dsh-fuse-connect` quando quiser. As linhas não sincronizadas ficaram retidas.",
+            });
+        }
         const agentId = payload.agent.id;
         const header = headers.get(agentId);
         const model = header?.model ||
@@ -532,6 +605,11 @@ export function apply(ctx, config) {
                 resetAt: remoteBlock.resetAt,
                 project,
             });
+            notifyCut(payload.agent, {
+                rule: remoteBlock.rule,
+                summary: "fuse: chamadas bloqueadas (orçamento do painel)",
+                detail: `O painel central cortou as chamadas deste escopo (regra: ${remoteBlock.rule}). O bloqueio vale até ${remoteBlock.resetAt} — o fuse local segue ativo e nenhum token é gasto enquanto isso.`,
+            });
             return { kind: "reject" };
         }
         const estimatedCostUsd = estimateStepCostUsd(payload.agent, payload.messages, model, provider);
@@ -565,6 +643,11 @@ export function apply(ctx, config) {
                 rule: decision.rule,
                 project,
             });
+            notifyCut(payload.agent, {
+                rule: decision.rule ?? "unknown",
+                summary: "fuse: chamada cortada — orçamento atingido",
+                detail: `O fuse bloqueou a chamada antes de gastar tokens (regra: ${decision.rule ?? "unknown"}). Ajuste o budget em cordis.patch.yml ou use a ferramenta dsh_budget_status para ver o status; o limite reseta no fim da janela.`,
+            });
             return { kind: "reject" };
         }
         return next();
@@ -643,13 +726,30 @@ export function apply(ctx, config) {
         return current;
     });
     // ── SaaS sync + policy pull, released by ctx.effect on unload ──────────
+    // Target resolution (ADR-0020): the device token from `dsh plugin connect`
+    // (credentials file) wins — it is the human-attached identity; the
+    // configured orgKey/baseUrl pair stays the headless/CI path. Local-only
+    // mode (neither) still owns the store.
+    const resolvedTarget = (() => {
+        const connected = loadCredentials();
+        if (connected) {
+            return {
+                baseUrl: connected.baseUrl,
+                auth: { kind: "bearer", token: connected.token },
+            };
+        }
+        if (config.baseUrl && config.orgKey) {
+            return {
+                baseUrl: config.baseUrl,
+                auth: { kind: "key", orgKey: config.orgKey },
+            };
+        }
+        return null;
+    })();
     ctx.effect(() => {
-        if (!config.baseUrl || !config.orgKey)
+        if (!resolvedTarget)
             return () => undefined;
-        const target = {
-            baseUrl: config.baseUrl,
-            orgKey: config.orgKey,
-        };
+        const target = resolvedTarget;
         let syncing = false;
         let refreshing = false;
         let lastPolicyAt = 0;
@@ -709,6 +809,19 @@ export function apply(ctx, config) {
                 }
                 if (!result.delivered) {
                     // Keep the rows: a failed batch is not a delivered batch.
+                    // A 401 on the BEARER path means the device token was
+                    // revoked at the SaaS — drop the credentials and stop
+                    // advertising a connected machine (the fuse keeps running
+                    // local-only; rows are retained for a future reconnect).
+                    if (result.status === 401 && target.auth.kind === "bearer") {
+                        logger.warn("[dsh] device token revoked — disconnecting local sync (rows retained)", { status: result.status });
+                        clearCredentials();
+                        // The sync timer has no agent to address; surface the
+                        // revocation on the NEXT step the user runs, once (the
+                        // visible counterpart to the fuse cut notice).
+                        revocationNoticePending = true;
+                        return;
+                    }
                     logger.warn("[dsh] sync failed — rows retained for retry", {
                         status: result.status,
                         error: result.error,
@@ -764,7 +877,7 @@ export function apply(ctx, config) {
         };
     });
     // Local-only mode still owns the store; release it on unload.
-    if (!config.baseUrl || !config.orgKey) {
+    if (!resolvedTarget) {
         ctx.effect(() => async () => {
             await flushMeter();
             store.close();

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { type CallProjection, hashSessionId, type MessageProvenance, projectCall
 export { createPricingCache, DEFAULT_REGISTRY_URL, estimateCostUsd, fetchPricingTable, normalizeModelId, type PricingAliases, type PricingEntry, type PricingResolution, type PricingTable, type PricingVia, parseGatewayModelEntry, parseGatewayModels, parsePricingRegistry, pricingCandidates, resolvePricingEntry, type TokenCounts, } from "./pricing.js";
 export { type RouteDecision, type RouteReason, type RouterPolicies, routeDecision, } from "./router.js";
 export { createLocalStore, type LocalStore, type RemotePolicy, type StoredUsage, type UsageRecord, } from "./store.js";
-export { fetchPolicy, type OrgKeyTarget, parseRemotePolicy, type SyncResult, syncBatch, } from "./sync.js";
+export { fetchPolicy, parseRemotePolicy, type SyncResult, type SyncTarget, syncBatch, } from "./sync.js";
 export type { BatchEvent, CutEvent, UsageEvent } from "./wire.js";
 /**
  * The Cordis entry.

package/dist/sync.d.ts

@@ -36,13 +36,21 @@ export interface SyncResult {
     /** Transport/HTTP failure detail for the log line, when any. */
     error?: string;
 }
-/** Shared request shape for the two key-authed endpoints. */
-export interface OrgKeyTarget {
-    baseUrl: string;
+/** Who the machine claims to be on the wire (ADR-0020). */
+export type MachineAuth = {
+    kind: "key";
     orgKey: string;
+} | {
+    kind: "bearer";
+    token: string;
+};
+/** Shared request shape for the two machine-authed endpoints. */
+export interface SyncTarget {
+    baseUrl: string;
+    auth: MachineAuth;
     fetchImpl?: typeof fetch;
 }
-export declare function syncBatch(input: OrgKeyTarget & {
+export declare function syncBatch(input: SyncTarget & {
     events: BatchEvent[];
 }): Promise<SyncResult>;
 /**
@@ -56,7 +64,7 @@ export declare function syncBatch(input: OrgKeyTarget & {
  * failed — the caller keeps the last cached policy either way (offline-first:
  * enforcement never depends on the network being up at boot).
  */
-export declare function fetchPolicy(input: OrgKeyTarget): Promise<{
+export declare function fetchPolicy(input: SyncTarget): Promise<{
     policy: RemotePolicy | null;
     error?: string;
 }>;

package/dist/sync.js

@@ -11,8 +11,10 @@
  * states explicitly whether the events reached the SaaS, and the caller only
  * advances the watermark when it did.
  */
-function keyHeaders(orgKey) {
-    return { "x-org-key": orgKey };
+function authHeaders(auth) {
+    if (auth.kind === "key")
+        return { "x-org-key": auth.orgKey };
+    return { authorization: `Bearer ${auth.token}` };
 }
 export async function syncBatch(input) {
     const fetchImpl = input.fetchImpl ?? fetch;
@@ -22,7 +24,7 @@ export async function syncBatch(input) {
             method: "POST",
             headers: {
                 "content-type": "application/json",
-                ...keyHeaders(input.orgKey),
+                ...authHeaders(input.auth),
             },
             body: JSON.stringify({ events: input.events }),
         });
@@ -86,7 +88,7 @@ export async function fetchPolicy(input) {
     try {
         const res = await fetchImpl(`${input.baseUrl}/v1/policy`, {
             method: "GET",
-            headers: keyHeaders(input.orgKey),
+            headers: authHeaders(input.auth),
         });
         if (res.status === 401)
             return { policy: null, error: "unauthorized" };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@openplan/dsh-fuse",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Cost policy for the DeepSeek Harness: per-call metering plus a local fuse that enforces budget, model and reasoning-effort limits before any token is spent.",
 	"license": "MIT",
 	"type": "module",
@@ -60,5 +60,8 @@
 		"@types/node": "^22.0.0",
 		"typescript": "^5.9.0",
 		"vitest": "^3.1.0"
+	},
+	"bin": {
+		"dsh-fuse-connect": "./dist/connect.js"
 	}
 }