@oh-hai/cli 0.1.0-beta.0

package/dist/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/commands/flags.d.ts

@@ -0,0 +1,25 @@
+import { parseArgs } from "node:util";
+import type { ParseArgsConfig } from "node:util";
+type OptionsConfig = NonNullable<ParseArgsConfig["options"]>;
+/** The global flags available on every command (§4.2). */
+export declare const GLOBAL_OPTIONS: OptionsConfig;
+/**
+ * Coerce a `parseArgs` boolean-flag value to on/off. Under `strict: false`, `--json` yields
+ * `true` but `--json=true` yields the STRING `"true"`, so a bare `=== true` check would treat
+ * the common `--json=true` / `--version=1` forms as off. Bare presence and truthy `=`-values
+ * are on; `--json=false` / `0` / `no` are off. A repeated flag becomes an array — last wins.
+ */
+export declare function flagOn(value: unknown): boolean;
+/** Parse argv for a command with no subcommand operand (the auth commands). */
+export declare function parseCommandArgs(argv: string[], extra?: OptionsConfig): ReturnType<typeof parseArgs>;
+/** Parse argv for a command that takes a SUBCOMMAND operand (`ask`/`task` → submit | await).
+ *  Like `parseCommandArgs` (global + `extra` options, `strict:false` so the `--flag=value`
+ *  boolean form isn't rejected, then reject any unknown flag), but `positionals[0]` is the
+ *  command token and `positionals[1]` MUST be one of `subcommands`. With correct option types
+ *  no flag value leaks into the positionals, so exactly `[command, subcommand]` is expected;
+ *  a missing subcommand, an unknown one, or an extra operand is a usage error (exit 2). */
+export declare function parseSubcommandArgs(argv: string[], subcommands: readonly string[], extra?: OptionsConfig): {
+    values: ReturnType<typeof parseArgs>["values"];
+    subcommand: string;
+};
+export {};

package/dist/commands/flags.js

@@ -0,0 +1,100 @@
+// Shared flag parsing (docs/specs/cli.md §4.2). The global-flag schema lives here so both the
+// top-level entrypoint (cli.ts) and each per-command handler parse the SAME globals; a handler
+// adds only its own command-specific options on top. `strict: false` mirrors the entrypoint —
+// unknown tokens don't throw, they're tolerated (a handler ignores globals it doesn't consume).
+import { parseArgs } from "node:util";
+import { CliError } from "../envelope.js";
+/** The global flags available on every command (§4.2). */
+export const GLOBAL_OPTIONS = {
+    "base-url": { type: "string" },
+    account: { type: "string" },
+    agent: { type: "string" },
+    json: { type: "boolean" },
+    quiet: { type: "boolean", short: "q" },
+    verbose: { type: "boolean", short: "v" },
+    "no-color": { type: "boolean" },
+    timeout: { type: "string" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean" },
+};
+/**
+ * Coerce a `parseArgs` boolean-flag value to on/off. Under `strict: false`, `--json` yields
+ * `true` but `--json=true` yields the STRING `"true"`, so a bare `=== true` check would treat
+ * the common `--json=true` / `--version=1` forms as off. Bare presence and truthy `=`-values
+ * are on; `--json=false` / `0` / `no` are off. A repeated flag becomes an array — last wins.
+ */
+export function flagOn(value) {
+    if (value === true) {
+        return true;
+    }
+    if (typeof value === "string") {
+        const v = value.trim().toLowerCase();
+        return v === "" || v === "true" || v === "1" || v === "yes" || v === "on";
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0 && flagOn(value[value.length - 1]);
+    }
+    return false;
+}
+/** Parse argv against the global flags plus the command's own `extra` options with `strict: false`
+ *  (so the `--flag=value` boolean form the CLI supports isn't rejected), then reject any flag NOT
+ *  in the known set — so a typo like `oh-hai whoami --chek` is a usage error (exit 2), not silently
+ *  ignored. Shared by the no-subcommand and subcommand parsers below. */
+function parseKnownFlags(argv, extra) {
+    const options = { ...GLOBAL_OPTIONS, ...extra };
+    // Guard the parseArgs greedy-value footgun: under strict:false a string option either consumes the
+    // NEXT token even when it's another flag (`notify --title --dry-run` → title="--dry-run", --dry-run
+    // UNSET) or, when it's the last token, is left as boolean `true` (`notify --title Hi --base-url` →
+    // base-url silently falls back to default). Both let a malformed invocation perform a LIVE action
+    // instead of failing. If a bare `--<string-flag>` has no real value — the next token is another
+    // `--…` flag OR the args end — reject as usage (pass `--flag=<value>` for a value starting with `--`).
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok.startsWith("--") && tok !== "--" && !tok.includes("=") && options[tok.slice(2)]?.type === "string") {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                const got = next === undefined ? "reached the end of the arguments" : `got ${next}`;
+                throw new CliError("usage", `${tok} expects a value but ${got}; to pass a value that starts with '--', use ${tok}=<value>.`);
+            }
+        }
+    }
+    const parsed = parseArgs({ args: argv, allowPositionals: true, strict: false, options });
+    const allowed = new Set(Object.keys(options));
+    for (const key of Object.keys(parsed.values)) {
+        if (!allowed.has(key)) {
+            throw new CliError("usage", `unknown flag: --${key}. Run 'oh-hai <command> --help'.`);
+        }
+    }
+    return parsed;
+}
+/** Parse argv for a command with no subcommand operand (the auth commands). */
+export function parseCommandArgs(argv, extra = {}) {
+    const parsed = parseKnownFlags(argv, extra);
+    // positionals[0] is the command token; these auth commands take no positional operands, so a
+    // stray one (`oh-hai logout all`, `oh-hai whoami check`) is a typo, not a silently-ignored arg.
+    if (parsed.positionals.length > 1) {
+        throw new CliError("usage", `unexpected argument: ${parsed.positionals[1]}. Run 'oh-hai <command> --help'.`);
+    }
+    return parsed;
+}
+/** Parse argv for a command that takes a SUBCOMMAND operand (`ask`/`task` → submit | await).
+ *  Like `parseCommandArgs` (global + `extra` options, `strict:false` so the `--flag=value`
+ *  boolean form isn't rejected, then reject any unknown flag), but `positionals[0]` is the
+ *  command token and `positionals[1]` MUST be one of `subcommands`. With correct option types
+ *  no flag value leaks into the positionals, so exactly `[command, subcommand]` is expected;
+ *  a missing subcommand, an unknown one, or an extra operand is a usage error (exit 2). */
+export function parseSubcommandArgs(argv, subcommands, extra = {}) {
+    const parsed = parseKnownFlags(argv, extra);
+    const subcommand = parsed.positionals[1];
+    if (subcommand === undefined) {
+        throw new CliError("usage", `missing subcommand: expected one of ${subcommands.join(" | ")}.`);
+    }
+    if (!subcommands.includes(subcommand)) {
+        throw new CliError("usage", `unknown subcommand: ${subcommand} (expected ${subcommands.join(" | ")}).`);
+    }
+    if (parsed.positionals.length > 2) {
+        throw new CliError("usage", `unexpected argument: ${parsed.positionals[2]}.`);
+    }
+    return { values: parsed.values, subcommand };
+}
+//# sourceMappingURL=flags.js.map

package/dist/commands/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../../src/commands/flags.ts"],"names":[],"mappings":"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"}

package/dist/commands/handlers.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from "./context.js";
+export declare const COMMAND_HANDLERS: Record<string, CommandHandler>;

package/dist/commands/handlers.js

@@ -0,0 +1,26 @@
+// The command-handler registry (docs/specs/cli.md §4). #106 wired the three auth commands; #107
+// wires the messaging commands (notify / ask / task); #209 wires `agents` (account/identity
+// management); #108 wires `doctor` (health). Every registry command now has a handler; the
+// entrypoint (cli.ts) looks a command up here first, and a miss still falls through to
+// `notImplemented()` as a defensive fallback for any future entry added without a handler.
+import { agentsCommand } from "./agents.js";
+import { askCommand } from "./ask.js";
+import { doctorCommand } from "./doctor.js";
+import { inboxCommand } from "./inbox.js";
+import { loginCommand } from "./login.js";
+import { logoutCommand } from "./logout.js";
+import { notifyCommand } from "./notify.js";
+import { taskCommand } from "./task.js";
+import { whoamiCommand } from "./whoami.js";
+export const COMMAND_HANDLERS = {
+    login: loginCommand,
+    logout: logoutCommand,
+    whoami: whoamiCommand,
+    notify: notifyCommand,
+    ask: askCommand,
+    task: taskCommand,
+    agents: agentsCommand,
+    inbox: inboxCommand,
+    doctor: doctorCommand,
+};
+//# sourceMappingURL=handlers.js.map

package/dist/commands/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/commands/handlers.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,4FAA4F;AAC5F,2FAA2F;AAC3F,uFAAuF;AACvF,2FAA2F;AAE3F,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,CAAC,MAAM,gBAAgB,GAAmC;IAC9D,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,aAAa;CACtB,CAAC"}

package/dist/commands/http.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Map a transport-layer failure (the `fetch` itself rejecting, before any HTTP response) to the
+ * right §7 exit code: a per-request timeout is exit 7 (`timeout`, §7); any other connection failure
+ * (DNS, refused, unreachable) is exit 5 (`network`, §9). A non-`Error` throw is not a timeout, so it
+ * takes the network branch. Always throws — the `never` return lets a caller use it as the whole
+ * body of a `catch`.
+ */
+export declare function throwTransportError(error: unknown, baseUrl: string): never;

package/dist/commands/http.js

@@ -0,0 +1,19 @@
+// Shared HTTP helper for the network-touching commands (login, whoami). Kept tiny and
+// dependency-free: the one thing worth sharing is the transport-error → §7 exit-code mapping, so a
+// DNS/refused failure and a per-request timeout surface the SAME codes and messages from every
+// command (cli spec §7/§9) instead of each command carrying its own copy.
+import { CliError } from "../envelope.js";
+/**
+ * Map a transport-layer failure (the `fetch` itself rejecting, before any HTTP response) to the
+ * right §7 exit code: a per-request timeout is exit 7 (`timeout`, §7); any other connection failure
+ * (DNS, refused, unreachable) is exit 5 (`network`, §9). A non-`Error` throw is not a timeout, so it
+ * takes the network branch. Always throws — the `never` return lets a caller use it as the whole
+ * body of a `catch`.
+ */
+export function throwTransportError(error, baseUrl) {
+    if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+        throw new CliError("timeout", `Hub did not respond within the timeout (${baseUrl}).`);
+    }
+    throw new CliError("network", `Hub unreachable at ${baseUrl}.`);
+}
+//# sourceMappingURL=http.js.map

package/dist/commands/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/commands/http.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,mGAAmG;AACnG,+FAA+F;AAC/F,0EAA0E;AAE1E,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,OAAe;IACjE,IAAI,KAAK,YAAY,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;QAC7F,MAAM,IAAI,QAAQ,CAAC,SAAS,EAAE,2CAA2C,OAAO,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC,SAAS,EAAE,sBAAsB,OAAO,GAAG,CAAC,CAAC;AAClE,CAAC"}

package/dist/commands/inbox.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "./context.js";
+export declare function inboxCommand(ctx: CommandContext): Promise<void>;

package/dist/commands/inbox.js

@@ -0,0 +1,111 @@
+// `oh-hai inbox` (docs/specs/cli.md §4.7) — the CLI-owned poll loop for the MA2H v0.4 human→agent
+// leg (spec §13/§14/§15; issue #153). Subcommand `watch`: DRAIN the agent's mailbox, HAND each
+// directive to the agent runtime (a stdout stream), post the single batched consume-ACK, and — since
+// every authenticated drain touches `agent_seen` server-side — emit the PRESENCE heartbeat simply by
+// polling on an interval. Owning this plumbing is the point: "so the agent invents nothing and stays
+// spec-conformant" — a runtime can `oh-hai inbox watch --json | my-runtime` and get a clean directive stream.
+//
+// TRUST / SCOPE (deliberate): the CLI drains over the AUTHENTICATED PULL channel (bearer GET over
+// TLS, straight from the Hub) and trusts it exactly as `await.ts` trusts a pulled Response — it does
+// NOT verify the §9.7 inbound signature, keep a jti-replay cache, or run the §13.4 addressee check.
+// Those are PUSH/webhook-channel obligations (conformance vectors dp-007 cases 5–6), not this pull
+// loop's. The signed delivery `{ directive, signature }` is forwarded VERBATIM so a runtime that
+// wants defense-in-depth can verify it against the Hub key. In-session `id` dedup (§13.4) IS handled
+// here (see the loop). Sibling subcommands (`inbox list` / `inbox ack`) and long-poll are out of scope.
+import { buildOk, serializeEnvelope } from "../envelope.js";
+import { parseSubcommandArgs } from "./flags.js";
+import { ackInbox, drainInbox, redactToken } from "./messaging/http.js";
+import { requireToken } from "./messaging/identity.js";
+import { positiveInt, sanitizeForTerminal, strictBoolFlag, stringFlag } from "./messaging/shared.js";
+const SUBCOMMANDS = ["watch"];
+const INBOX_WATCH_OPTIONS = {
+    interval: { type: "string" },
+    max: { type: "string" },
+    once: { type: "boolean" },
+};
+/** Default poll cadence (ms). Well under the Hub's 90s presence-freshness window so the agent stays
+ *  `online` between polls, and responsive to arriving directives without hammering the Hub. */
+const DEFAULT_INTERVAL_MS = 5000;
+/** A sane upper bound for `--max` (a drain batch size, not a timer): generous enough to never reject a
+ *  realistic mailbox drain, small enough to reject an absurd `?max=` — the Hub clamps to its own cap
+ *  regardless. Distinct from the timer ceiling `--interval` uses. */
+const MAX_DRAIN_BATCH = 10_000;
+export async function inboxCommand(ctx) {
+    // `watch` is the only subcommand, so dispatch is unconditional — the parse still validates the
+    // operand (an unknown/absent subcommand is a usage error) before we get here.
+    const { values } = parseSubcommandArgs(ctx.argv, SUBCOMMANDS, INBOX_WATCH_OPTIONS);
+    await inboxWatch(ctx, values);
+}
+async function inboxWatch(ctx, flags) {
+    const intervalMs = flags.interval !== undefined ? positiveInt(stringFlag(flags.interval), "--interval") : DEFAULT_INTERVAL_MS;
+    const max = flags.max !== undefined ? positiveInt(stringFlag(flags.max), "--max", "a positive integer", MAX_DRAIN_BATCH) : undefined;
+    // Strict boolean: a mistyped `--once=treu` is a usage error, not a silent fall-through to the
+    // infinite watch loop (it would keep draining + acking every interval instead of a one-shot).
+    const once = strictBoolFlag(flags.once, "--once");
+    // The mailbox is selected by the bearer alone (the Hub derives the agent from the token), so this
+    // needs only a token — like `await`, and unlike a submit, it does not require a resolvable account.
+    const token = await requireToken(ctx);
+    // Cross-poll dedup (§13.4): once a directive id has been emitted AND its batch acked, a later
+    // redelivery of that same id (fresh t/jti, after a crash or the server's visibility timeout) is
+    // suppressed from re-emission — but still acked so the Hub consumes it. `seen` commits only AFTER a
+    // successful ack (below), so an unacked batch is never suppressed: on ack failure the loop throws
+    // and exits, and a fresh process re-emits the redelivery (at-least-once holds). The set is in-memory
+    // / per-session — cross-restart at-most-once needs an idempotent side effect or a persisted dedup
+    // set (dp-007), the runtime's concern, not this loop's. A long-lived watch grows `seen` with
+    // directive volume; acceptable for v1.
+    const seen = new Set();
+    for (;;) {
+        const { directives } = await drainInbox(ctx, token, max);
+        // The unique ids in THIS drain — both the ack list and the within-batch emit guard (a Hub could
+        // repeat an id inside one batch; emit it once and ack it once, not twice).
+        const batchIds = new Set();
+        for (const delivery of directives) {
+            const id = delivery.directive.id;
+            if (!seen.has(id) && !batchIds.has(id))
+                emitDirective(ctx, delivery, token);
+            batchIds.add(id);
+        }
+        if (batchIds.size > 0) {
+            // Flush stdout BEFORE acking so the emit-then-ack handoff is genuinely at-least-once: `io.log`
+            // only queues to stdout, so when `watch` is piped to a runtime under backpressure the bytes may
+            // still be buffered in this process. Acking first would let the Hub consume a directive that a
+            // crash/EPIPE could still lose before it reaches the consumer. `flushOutput` waits for the
+            // queued writes to complete (a write-callback barrier, not just the drain flag); THEN ack.
+            await ctx.runtime.flushOutput?.();
+            // The single batched consume-ack (§14) — one call per drained batch, deduped ids.
+            await ackInbox(ctx, token, [...batchIds]);
+            // Commit to the cross-poll dedup set only now that the batch is durably consumed.
+            for (const id of batchIds)
+                seen.add(id);
+        }
+        // --once: a single drain→emit→ack pass (cron / scripting / deterministic tests). Otherwise loop;
+        // the poll itself IS the presence heartbeat, so keep polling on the interval even on an empty drain.
+        if (once)
+            return;
+        await ctx.runtime.sleep(intervalMs);
+    }
+}
+/** Hand one directive to the agent runtime. stdout is the directive STREAM.
+ *
+ *  Under `--json` the delivery is emitted BYTE-VERBATIM — one NDJSON `inbox.watch` envelope carrying
+ *  the exact `{ directive, signature }`. This is deliberate and must not be redacted: the detached
+ *  `signature` is computed over the `directive` bytes, so mutating the directive (even to strip an
+ *  echoed token) would break the signature a defense-in-depth runtime verifies — and we'd then ack a
+ *  directive the runtime couldn't authenticate. A conformant Hub never puts the bearer in directive
+ *  content, and the machine stream feeds the agent's OWN runtime (which already holds the token), so
+ *  verbatim is the right posture; JSON.stringify escapes control chars.
+ *
+ *  The HUMAN summary carries no signature contract, so it stays hardened (§5.4): fields are
+ *  terminal-sanitized AND the bearer is redacted — a compromised/buggy Hub can't inject ANSI or echo
+ *  the token into a line a person might read or log. */
+function emitDirective(ctx, delivery, token) {
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk("inbox.watch", { directive: delivery.directive, signature: delivery.signature })));
+        return;
+    }
+    const d = delivery.directive;
+    const priority = d.priority !== undefined ? ` (${sanitizeForTerminal(d.priority)})` : "";
+    const summary = `📨 ${sanitizeForTerminal(d.id)} · ${sanitizeForTerminal(d.from)} · ${sanitizeForTerminal(d.title)}${priority}`;
+    ctx.io.log(redactToken(summary, token) ?? summary);
+}
+//# sourceMappingURL=inbox.js.map

package/dist/commands/inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.js","sourceRoot":"","sources":["../../src/commands/inbox.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,+FAA+F;AAC/F,qGAAqG;AACrG,qGAAqG;AACrG,qGAAqG;AACrG,8GAA8G;AAC9G,EAAE;AACF,kGAAkG;AAClG,qGAAqG;AACrG,oGAAoG;AACpG,mGAAmG;AACnG,iGAAiG;AACjG,qGAAqG;AACrG,wGAAwG;AAExG,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGrG,MAAM,WAAW,GAAG,CAAC,OAAO,CAAU,CAAC;AAEvC,MAAM,mBAAmB,GAAG;IAC1B,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC5B,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACvB,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;CACjB,CAAC;AAEX;+FAC+F;AAC/F,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACjC;;qEAEqE;AACrE,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAmB;IACpD,+FAA+F;IAC/F,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE,GAAG,mBAAmB,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,mBAAmB,CAAC,CAAC;IACnF,MAAM,UAAU,CAAC,GAAG,EAAE,MAAiC,CAAC,CAAC;AAC3D,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,GAAmB,EAAE,KAA8B;IAC3E,MAAM,UAAU,GAAG,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC;IAC9H,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,oBAAoB,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACrI,8FAA8F;IAC9F,8FAA8F;IAC9F,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAElD,kGAAkG;IAClG,oGAAoG;IACpG,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IAEtC,8FAA8F;IAC9F,gGAAgG;IAChG,oGAAoG;IACpG,kGAAkG;IAClG,qGAAqG;IACrG,kGAAkG;IAClG,6FAA6F;IAC7F,uCAAuC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,SAAS,CAAC;QACR,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACzD,gGAAgG;QAChG,2EAA2E;QAC3E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC5E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnB,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACtB,+FAA+F;YAC/F,gGAAgG;YAChG,+FAA+F;YAC/F,2FAA2F;YAC3F,2FAA2F;YAC3F,MAAM,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;YAClC,kFAAkF;YAClF,MAAM,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;YAC1C,kFAAkF;YAClF,KAAK,MAAM,EAAE,IAAI,QAAQ;gBAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,iGAAiG;QACjG,qGAAqG;QACrG,IAAI,IAAI;YAAE,OAAO;QACjB,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;wDAYwD;AACxD,SAAS,aAAa,CAAC,GAAmB,EAAE,QAAyB,EAAE,KAAa;IAClF,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;QACxH,OAAO;IACT,CAAC;IACD,MAAM,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC;IAC7B,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,mBAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,QAAQ,EAAE,CAAC;IAChI,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC;AACrD,CAAC"}

package/dist/commands/login.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "./context.js";
+export declare function loginCommand(ctx: CommandContext): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,272 @@
+// `oh-hai login` (docs/specs/cli.md §4.3). Two paths:
+//   - `--token-stdin`: read a token from stdin and store it in the OS keychain (or the 0600
+//     file fallback). The token is NEVER printed and NEVER accepted as a flag value (§5.4).
+//   - bare `login` (device-code): the PRIMARY flow — request a device code, print a short
+//     `user_code` + verification URL to STDERR, and poll the Hub's device-authorization grant
+//     (RFC 8628; server routes from #193) until the human approves in a browser. On success the
+//     Hub returns the agent bearer, stored under the Hub-scoped key `<origin>|<agent id>` (§5.1).
+//     The token is never shown, never typed, never through the LLM (§1/§5.4).
+import { CliError, buildOk, serializeEnvelope } from "../envelope.js";
+import { originOf } from "../auth/resolve-token.js";
+import { sanitizeForTerminal } from "../terminal.js";
+import { flagOn, parseCommandArgs } from "./flags.js";
+import { throwTransportError } from "./http.js";
+/** Per-request bound for each device-grant POST when no `--timeout`/`MA2H_TIMEOUT_MS` is set. It
+ *  bounds a SINGLE request, never the whole flow — the human's approval window (minutes) is bounded
+ *  separately by the poll budget below, so a snappy per-request timeout can't abort a slow human. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** RFC 8628 §3.5: on `slow_down` (and the Hub's HTTP 429 rate-limit), the client backs off +5s. */
+const SLOW_DOWN_INCREMENT_MS = 5_000;
+/** Cap on an honored `Retry-After` (seconds) so a hostile Hub can't stall the poll indefinitely. */
+const MAX_RETRY_AFTER_SECONDS = 300;
+// Poll interval / code-expiry bounds. The server advertises `interval` (5s) and `expires_in` (900s),
+// but they arrive over the wire from a not-yet-authenticated endpoint, so they're clamped into sane
+// ranges: a missing / zero / fractional-floors-to-zero / negative / absurd value must never yield a
+// zero or effectively unbounded poll budget (a `0` interval alone divides `maxPolls` to Infinity and
+// spins the loop with a no-op sleep). Maxima are generous so a legit human window is never cut short.
+const DEFAULT_INTERVAL_SECONDS = 5;
+const MIN_INTERVAL_SECONDS = 1;
+const MAX_INTERVAL_SECONDS = 60;
+const DEFAULT_EXPIRES_IN_SECONDS = 900;
+const MIN_EXPIRES_IN_SECONDS = 1;
+const MAX_EXPIRES_IN_SECONDS = 3600;
+export async function loginCommand(ctx) {
+    const { values } = parseCommandArgs(ctx.argv, { "token-stdin": { type: "boolean" } });
+    if (flagOn(values["token-stdin"])) {
+        await tokenStdinLogin(ctx);
+    }
+    else {
+        await deviceCodeLogin(ctx);
+    }
+}
+/** `--token-stdin` (§4.3): read a bearer from stdin (local bootstrap / paste) and store it the same
+ *  way the device-code path does. Behavior is frozen — #195 only adds the device-code flow. */
+async function tokenStdinLogin(ctx) {
+    const account = ctx.config.account;
+    if (account === undefined) {
+        throw new CliError("usage", "an agent id is required — pass --account/--agent or set MA2H_AGENT_ID.");
+    }
+    const raw = await ctx.runtime.readStdin();
+    const token = raw.trim();
+    if (token === "") {
+        throw new CliError("usage", "no token on stdin — pipe the token, e.g. `printf %s \"$TOKEN\" | oh-hai login --token-stdin`.");
+    }
+    await storeAndReport(ctx, account, token);
+}
+/**
+ * The bare `oh-hai login` device-code acquisition (§4.3/§1, RFC 8628). Requests a device code,
+ * prompts on STDERR (stdout stays reserved for the single `--json` envelope, §8), then polls until
+ * the human approves — storing the returned bearer under `<origin>|<agent id>`. The agent id comes
+ * FROM the token response (the human chose which agent to bind at approval time), so this path
+ * needs no `--account`, unlike `--token-stdin`.
+ */
+async function deviceCodeLogin(ctx) {
+    const code = await requestDeviceCode(ctx);
+    // Prompt on stderr. `openUrl` prefers the one-click `verification_uri_complete` (embeds the code);
+    // the code is shown separately so a human copying the plain URL still knows what to enter. Both are
+    // sanitized of control characters first — they're server-supplied and echoed straight to the terminal.
+    ctx.io.err(`oh-hai: to authorize this device, open ${sanitizeForTerminal(code.openUrl)}`);
+    ctx.io.err(`oh-hai: and enter the code: ${sanitizeForTerminal(code.userCode)}`);
+    ctx.io.err("oh-hai: waiting for approval…");
+    // Poll budget: the server expires the code and returns `expired_token` at the real deadline; this
+    // cap is a pure anti-infinite-loop guard against a server that never returns a terminal state.
+    const maxPolls = Math.ceil(code.expiresInSeconds / code.intervalSeconds) + 2;
+    // `intervalMs` is the advertised base interval; only `slow_down` raises it permanently (RFC 8628
+    // §3.5). `nextDelayMs` is the wait before the NEXT poll — it resets to the base each round, so a
+    // one-shot 429 back-off (below) never stretches every later poll and risks missing an approval
+    // before the code expires.
+    let intervalMs = code.intervalSeconds * 1000;
+    let nextDelayMs = intervalMs;
+    for (let poll = 0; poll < maxPolls; poll++) {
+        await ctx.runtime.sleep(nextDelayMs);
+        nextDelayMs = intervalMs; // resume the advertised interval unless this round overrides it below
+        const res = await hubPost(ctx, "/auth/device/token", { device_code: code.deviceCode });
+        if (res.status === 200) {
+            const token = await readAccessToken(res);
+            await storeAndReport(ctx, token.agentId, token.accessToken);
+            return;
+        }
+        // The Hub's per-IP limiter throttles the shared device surface with HTTP 429 `rate_limited`
+        // (+ Retry-After); a legit poller (e.g. behind a corporate NAT) can trip it mid-approval, so
+        // back off and keep polling rather than aborting. Honor Retry-After (the remaining window) as a
+        // ONE-SHOT delay so we don't hammer inside the window, then resume the advertised interval.
+        if (res.status === 429) {
+            const retryAfterMs = retryAfterMillis(res.headers?.get("retry-after"));
+            nextDelayMs = Math.max(intervalMs + SLOW_DOWN_INCREMENT_MS, retryAfterMs);
+            continue;
+        }
+        // Every other non-200 poll response is the grant's HTTP 400 carrying an RFC 8628 `error.code`.
+        // A non-400 here is an unexpected transport/server error (5xx, a proxy) — map it and stop, so a
+        // stray RFC-looking body on a 5xx isn't mistaken for a live grant state and silently retried.
+        const { code: errCode, message } = await readErrorEnvelope(res);
+        if (res.status !== 400) {
+            throw mapHubError(res.status, message);
+        }
+        switch (errCode) {
+            case "authorization_pending":
+                continue; // human hasn't approved yet — keep polling at the current interval
+            case "slow_down":
+                intervalMs += SLOW_DOWN_INCREMENT_MS; // RFC 8628 §3.5 — permanent interval increase
+                nextDelayMs = intervalMs;
+                continue;
+            case "access_denied":
+                throw new CliError("auth", "device authorization was denied.");
+            case "expired_token":
+                throw new CliError("timeout", "the device code expired before it was approved; run `oh-hai login` again.");
+            default:
+                // A 400 with an unexpected/absent error code — not one of the four RFC states.
+                throw mapHubError(res.status, message);
+        }
+    }
+    // The loop exhausted its budget without a terminal response — treat as a timeout (§7).
+    throw new CliError("timeout", "device authorization did not complete before the code expired; run `oh-hai login` again.");
+}
+/** Store the bearer Hub-scoped (§5.1) and report success. The token is NEVER in the output (§5.4);
+ *  an existing token for this identity is overwritten silently (§4.3). Shared by both login paths. */
+async function storeAndReport(ctx, agentId, token) {
+    const store = await ctx.runtime.openStore();
+    await store.set(originOf(ctx.config.baseUrl), agentId, token);
+    if (ctx.json) {
+        // No token field, ever (§5.4). `storage` reports which backend actually holds it. The agent id
+        // is emitted raw — JSON.stringify escapes any control character, so it can't reach the terminal.
+        ctx.io.log(serializeEnvelope(buildOk("login", { agent_id: agentId, base_url: ctx.config.baseUrl, storage: store.backendName })));
+    }
+    else {
+        // Sanitize the DISPLAYED agent id — on the device-code path it's server-supplied, so a hostile
+        // Hub could return control characters. The stored credential key above uses the RAW id so it
+        // still matches the Hub's identity for later resolution.
+        ctx.io.log(`Logged in as ${sanitizeForTerminal(agentId)} @ ${ctx.config.baseUrl}`);
+    }
+}
+/** POST /auth/device/code, validate the fields the prompt + poll need, and normalize the poll
+ *  interval / expiry to sane bounded values. */
+async function requestDeviceCode(ctx) {
+    const res = await hubPost(ctx, "/auth/device/code", {});
+    if (res.status !== 200) {
+        const { message } = await readErrorEnvelope(res);
+        throw mapHubError(res.status, message);
+    }
+    const body = await readJson(res);
+    const deviceCode = str(body.device_code);
+    const userCode = str(body.user_code);
+    const verificationUri = str(body.verification_uri);
+    if (deviceCode === undefined || userCode === undefined || verificationUri === undefined) {
+        throw new CliError("server", "the Hub returned a malformed device-code response.");
+    }
+    // Only ever invite the user to open an http(s) URL — a hostile Hub must not get a `file:` /
+    // `javascript:` verification URL echoed as "open this". Prefer the complete form when it's also http(s).
+    if (!isHttpUrl(verificationUri)) {
+        throw new CliError("server", "the Hub returned a non-http verification URL.");
+    }
+    const complete = str(body.verification_uri_complete);
+    return {
+        deviceCode,
+        userCode,
+        openUrl: complete !== undefined && isHttpUrl(complete) ? complete : verificationUri,
+        intervalSeconds: boundedInt(body.interval, DEFAULT_INTERVAL_SECONDS, MIN_INTERVAL_SECONDS, MAX_INTERVAL_SECONDS),
+        expiresInSeconds: boundedInt(body.expires_in, DEFAULT_EXPIRES_IN_SECONDS, MIN_EXPIRES_IN_SECONDS, MAX_EXPIRES_IN_SECONDS),
+    };
+}
+/** Read + validate the 200 token response (`{ access_token, agent_id }`). */
+async function readAccessToken(res) {
+    const body = await readJson(res);
+    const accessToken = str(body.access_token);
+    const agentId = str(body.agent_id);
+    if (accessToken === undefined || agentId === undefined) {
+        throw new CliError("server", "the Hub returned a malformed token response.");
+    }
+    return { accessToken, agentId };
+}
+/** POST a JSON body to `path` on the Hub, mapping transport failures to §7 exit codes. The
+ *  per-request timeout bounds THIS request only; the poll budget bounds the whole flow. */
+async function hubPost(ctx, path, body) {
+    const url = `${ctx.config.baseUrl}${path}`;
+    const init = {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(ctx.config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS),
+    };
+    try {
+        return await ctx.runtime.fetchImpl(url, init);
+    }
+    catch (error) {
+        throwTransportError(error, ctx.config.baseUrl);
+    }
+}
+/** Parse a response body as a JSON object, defensively — a fake without `json()`, a non-JSON body,
+ *  or a non-object (array / string / null) all collapse to `{}`, so callers read fields off a plain
+ *  record without unchecked casts. */
+async function readJson(res) {
+    if (typeof res.json !== "function")
+        return {};
+    try {
+        const parsed = await res.json();
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Read the A2H error envelope `{ error: { code, message } }` from a non-200 response. */
+async function readErrorEnvelope(res) {
+    const body = await readJson(res);
+    const error = body.error;
+    const record = error !== null && typeof error === "object" ? error : {};
+    return { code: str(record.code), message: str(record.message) };
+}
+/** Map an unexpected Hub error status to the right §7 exit code, preferring the server's message.
+ *  The server-supplied `message` is stripped of terminal control characters — the top-level catch
+ *  prints a CliError's message to the terminal, so a hostile Hub could otherwise inject escapes. */
+function mapHubError(status, message) {
+    const detail = message !== undefined ? sanitizeForTerminal(message) : `Hub returned ${status}.`;
+    if (status === 401 || status === 403)
+        return new CliError("auth", detail);
+    if (status === 404)
+        return new CliError("not_found", detail);
+    if (status === 413)
+        return new CliError("payload_too_large", detail);
+    if (status === 400 || status === 422)
+        return new CliError("bad_request", detail);
+    if (status >= 500)
+        return new CliError("server", detail);
+    return new CliError("error", detail);
+}
+/** Parse a `Retry-After` header of the numeric-seconds form the Hub sends into milliseconds, capped
+ *  so a hostile value can't stall the poll; 0 when the header is absent or unparseable. */
+function retryAfterMillis(headerValue) {
+    if (headerValue === null || headerValue === undefined)
+        return 0;
+    const seconds = Number.parseInt(headerValue.trim(), 10);
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return 0;
+    return Math.min(seconds, MAX_RETRY_AFTER_SECONDS) * 1000;
+}
+/** A trimmed non-empty string from an unknown field, else undefined (validates response fields). */
+function str(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** True when `value` parses as an http(s) URL — the only schemes we invite the user to open (§4.3). */
+function isHttpUrl(value) {
+    try {
+        const { protocol } = new URL(value);
+        return protocol === "http:" || protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** An integer from an unknown response field, clamped to `[min, max]`; `fallback` (already in range)
+ *  is used when the value is missing or non-finite. Clamping means a missing, zero, fractional
+ *  (floors to 0), negative, or absurdly large server-supplied `interval` / `expires_in` can never
+ *  produce a zero/negative or effectively unbounded poll budget — which would defeat the poll cap. */
+function boundedInt(value, fallback, min, max) {
+    const n = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : fallback;
+    return Math.min(Math.max(n, min), max);
+}
+//# sourceMappingURL=login.js.map