@heyditto/cli 2.0.1 → 2.2.0

package/README.md

@@ -42,6 +42,17 @@ You can also reorder your `PATH` so the npm global bin comes before `/usr/bin`,
 
 ## Auth
 
+Humans sign in through the browser:
+
+```bash
+heyditto login
+```
+
+This prints a short code, opens `https://heyditto.ai/device` (pre-filled with the
+code), and saves the resulting key to your CLI config directory once you approve
+it. Pass a key as an argument (`heyditto login ditto_mcp_…`), pipe it with
+`--stdin`, or use `--paste` for the older copy-a-key page.
+
 Agents can self-provision without a browser, email, or OTP:
 
 ```bash
@@ -74,7 +85,25 @@ requires backend support — see
 [ditto-assistant/backend#1199](https://github.com/ditto-assistant/backend/issues/1199)),
 so picking the right name at init avoids a stuck label.
 
-For a human-owned key, get one at **https://app.heyditto.ai/mcp/newkey**.
+### Humans: sign in through the browser
+
+```bash
+heyditto login
+```
+
+opens the Ditto web app with a one-time device code (sign in with Google, X, Apple
+or GitHub, or create an account), approves it, and hands the key back to the CLI —
+nothing to copy. `heyditto claude` / `heyditto codex` run the same flow
+automatically on first use, and the web page lets you pick or create the
+inference endpoint to launch through, so a fresh machine needs exactly one
+command:
+
+```bash
+npx @heyditto/cli@latest claude --yolo --worktree
+```
+
+You can still paste a key from **https://app.heyditto.ai/mcp/newkey**
+(`heyditto login <key>`, `--paste`, or `--stdin`), or set it in the environment:
 
 ```bash
 export DITTO_API_KEY=ditto_mcp_…
@@ -111,6 +140,17 @@ heyditto graphs subscribers
 heyditto graphs sharing (--enable|--disable) [--title <t>] [--description <d>]
 heyditto init [--name <name>] [--subscribe <@graph>]... [<@graph>...] [--json]
 heyditto login [<key>] [--paste] [--stdin]
+heyditto endpoints [--set-default <slug>] [--clear-default]
+heyditto claude [options] [-- <claude args>]
+heyditto codex  [options] [-- <codex args>]
+heyditto sessions [--json] [--all]
+heyditto sessions rm <id>
+heyditto session new [<name>...] [--id <id>]
+heyditto session list [--all]
+heyditto session use <id>
+heyditto session current
+heyditto session end
+heyditto agents [--output <format>]
 heyditto logout
 heyditto status [--output <format>]
 heyditto config
@@ -289,10 +329,136 @@ graph. Choose it up front — renaming after init isn't yet supported. See
 
 Print a Claude Desktop / Cursor / generic-MCP-client config snippet for the Ditto memory server.
 
+## Coding agents
+
+`heyditto claude` and `heyditto codex` launch Claude Code or Codex through one of
+your Ditto **inference endpoints** (managed at https://developer.heyditto.ai/endpoints;
+the Ditto app's Settings → Developer page still works too). Each launch:
+
+1. signs you in through the browser if this machine has no key yet, then uses
+   the endpoint you picked there, `--endpoint`, the saved default, or a picker,
+2. mints a temporary endpoint key (optionally capped with `--budget <tokens>`),
+3. starts the agent with that key and a fresh `X-Ditto-Session-Id`, so the
+   session becomes its own thread with full traces under the endpoint,
+4. **revokes the key when the agent exits** (Ctrl+C included). The thread and
+   traces are kept; `--keep-key` opts out, `--expires` sets a server-side
+   safety expiry (default `1d`).
+
+```bash
+npx -y @heyditto/cli login
+npx -y @heyditto/cli claude --endpoint my-endpoint
+
+heyditto endpoints --set-default my-endpoint   # skip the picker next time
+heyditto claude                                # interactive Claude Code
+heyditto codex --yellow                        # Codex, auto-accept edits
+heyditto claude --yolo --worktree fix-login    # bypass prompts in <repo>/.worktrees/fix-login
+heyditto codex -p "summarize this repo" --json # headless (codex exec)
+heyditto claude -p "list TODOs" --output-format json --max-turns 3
+heyditto claude --resume                       # reopen the last session in the same thread
+heyditto claude -- --verbose                   # anything after -- goes to the agent
+```
+
+Options shared by both commands:
+
+| Flag | Meaning |
+| --- | --- |
+| `-e, --endpoint <slug>` | endpoint to route through (default: saved default, else a picker) |
+| `--budget <tokens>` | spend cap for this session's key, in Ditto tokens |
+| `--expires <1h…never>` | server-side key expiry; the key is still revoked on exit unless `--keep-key` |
+| `--session <id>` | reuse a Ditto session id so traces land in an existing thread |
+| `--resume [id]` / `-c, --continue` | resume a local session (`heyditto sessions`) / the agent's most recent conversation |
+| `--yolo` / `--yellow` / `--plan` | bypass permissions / auto-accept edits / plan mode (Claude only) |
+| `-p, --prompt <text>` | headless run: `claude -p` or `codex exec` |
+| `-m, --model <id>` | model to request (Codex defaults to the endpoint slug; Claude's ids follow the endpoint's routes) |
+| `-w, --worktree [name]` | run inside `<repo>/.worktrees/<name>` on a branch of that name; `.worktrees/` is added to `.gitignore` |
+| `--name <label>` | key name shown in the app (default `cli:<agent>:<hostname>`) |
+| `--dry-run` | print the command, args and env with the key masked; mints nothing |
+
+Unknown flags and everything after `--` are forwarded to the agent, so Claude's
+and Codex's own options keep working.
+
+How the wiring works:
+
+- **Claude Code** gets `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` (a bearer
+  token, which skips Claude's "use this API key?" prompt) and
+  `ANTHROPIC_CUSTOM_HEADERS` with the session id. Any inherited
+  `ANTHROPIC_API_KEY` is removed from the child environment.
+- **Codex** speaks the Responses API only, so the endpoint is injected as a
+  `ditto` model provider via `-c` overrides (nothing is written to
+  `~/.codex/config.toml`) with the key in `DITTO_INFERENCE_API_KEY`.
+
+### `endpoints`
+
+Manage the inference endpoints the launchers route through — a CLI mirror of
+the developer console at https://developer.heyditto.ai/endpoints (`open` takes
+you to an endpoint's page there; set `DITTO_DEVELOPER_BASE` to point elsewhere):
+
+```
+heyditto endpoints [--set-default <slug>] [--clear-default]   list (* = default)
+heyditto endpoints create [--name <n>] [--slug <s>] [--model <id>] [--default]
+heyditto endpoints show <endpoint>
+heyditto endpoints use <endpoint>          make it the default
+heyditto endpoints pick                    choose the default interactively
+heyditto endpoints open [endpoint]         open the editor in the Ditto app
+heyditto endpoints set <endpoint> --model … --system-prompt … --spend-limit <tokens|none>
+                                   --spend-period … --record-trace on|off --recall on|off
+                                   --record on|off --memory-depth <n>
+heyditto endpoints delete <endpoint> [--yes]
+heyditto endpoints keys <endpoint>         list keys
+heyditto endpoints keys revoke <endpoint> <keyId> [--yes]
+```
+
+Endpoints spend your Ditto credits, so deleting one, revoking a key or raising a
+spend limit asks you to type the slug back; pass `--yes` in scripts. `--output
+json` is available everywhere and includes the gateway base URL.
+
+**Agent accounts.** An agent set up with `heyditto init` can create and manage
+endpoints too, but an endpoint created by an unclaimed agent starts **inactive**:
+it serves requests once the person the agent works for claims the agent and
+subscribes to Ditto Hero. The CLI prints the server's explanation together with
+an activation link (the agent's claim link plus the endpoint) — hand that link
+to the user.
+
+### `sessions`
+
+List the coding-agent sessions launched from this machine (stored under
+`~/.config/heyditto/cli/sessions/`). `heyditto sessions rm <id>` forgets a local
+record; the Ditto thread and traces are unaffected.
+
+### `session`
+
+Explicit MCP sessions. Without one, the server groups your saves and searches
+into a time-based *implicit* session (activity within a cooldown, auto-named
+when it goes quiet). `heyditto session new [name]` pins an explicit session:
+every MCP request from then on carries `X-Ditto-Session-Id`, and the name goes
+out once as `X-Ditto-Session-Name` so the thread gets that title. Saves and
+searches land in one thread inside the agent your key is attached to.
+
+```bash
+heyditto session new "refactor auth module"   # prints the id and makes it active
+heyditto save "Decided to keep JWT refresh in the gateway"
+heyditto session current                      # the active id (exit 1 when none)
+heyditto session list                         # local history, * marks the active one
+heyditto session end                          # back to implicit sessions
+heyditto session use 9e9a93c3                 # reactivate by id or unique prefix
+```
+
+`DITTO_SESSION_ID=<id>` pins a session for one shell or script (it overrides the
+saved one and never sends a name). Sessions are tracked locally in
+`~/.config/heyditto/cli/mcp-sessions.json`; the server keeps the threads.
+
+### `agents`
+
+List your Ditto agents (`GET /api/v5/chat-agents`): id, kind (`main`, `chat`,
+`inference_endpoint`, `mcp`, `connector`), name, thread count, last activity and
+the live connections (API keys, OAuth grants, endpoints) writing into each.
+
 ## Environment
 
 - `DITTO_API_KEY` (optional) — MCP API key override. Agents can instead run `heyditto init --json` for no-human setup.
 - `DITTO_API_BASE` (optional) — API base URL. Defaults to `https://api.heyditto.ai`. Useful for local dev (`http://localhost:3400`).
+- `DITTO_SESSION_ID` (optional) — pin an explicit MCP session id for this shell (see `session`).
+- `DITTO_CONFIG_DIR` (optional) — config directory for the saved key, default endpoint and session records. Defaults to `$XDG_CONFIG_HOME/heyditto/cli` or `~/.config/heyditto/cli`.
 
 ## Output
 

package/dist/agents/claude.d.ts

@@ -0,0 +1,11 @@
+import { type HarnessPlan, type PlanInput } from "./types.js";
+/**
+ * Builds the `claude` invocation.
+ *
+ * Auth goes through ANTHROPIC_AUTH_TOKEN (sent as `Authorization: Bearer`):
+ * unlike ANTHROPIC_API_KEY it never triggers the interactive "use this API
+ * key? No (recommended)" approval prompt, so the same plan works headless.
+ * Any inherited ANTHROPIC_API_KEY is removed so it cannot re-trigger that
+ * prompt or add a stray x-api-key header.
+ */
+export declare function planClaude(input: PlanInput): HarnessPlan;

package/dist/agents/claude.js

@@ -0,0 +1,48 @@
+import { SESSION_HEADER, apiRootOf } from "./types.js";
+/**
+ * Builds the `claude` invocation.
+ *
+ * Auth goes through ANTHROPIC_AUTH_TOKEN (sent as `Authorization: Bearer`):
+ * unlike ANTHROPIC_API_KEY it never triggers the interactive "use this API
+ * key? No (recommended)" approval prompt, so the same plan works headless.
+ * Any inherited ANTHROPIC_API_KEY is removed so it cannot re-trigger that
+ * prompt or add a stray x-api-key header.
+ */
+export function planClaude(input) {
+    const args = [];
+    if (input.yolo)
+        args.push("--dangerously-skip-permissions");
+    else if (input.yellow)
+        args.push("--permission-mode", "acceptEdits");
+    else if (input.plan)
+        args.push("--permission-mode", "plan");
+    if (input.resumeId)
+        args.push("--resume", input.resumeId);
+    else if (input.resumeLast)
+        args.push("--continue");
+    else
+        args.push("--session-id", input.sessionId);
+    if (input.model)
+        args.push("--model", input.model);
+    if (input.prompt !== undefined)
+        args.push("-p", input.prompt);
+    args.push(...input.passthrough);
+    const headers = [input.env.ANTHROPIC_CUSTOM_HEADERS?.trim(), `${SESSION_HEADER}: ${input.sessionId}`]
+        .filter((h) => Boolean(h))
+        .join("\n");
+    const envSet = {
+        ANTHROPIC_BASE_URL: apiRootOf(input.baseUrl),
+        ANTHROPIC_AUTH_TOKEN: input.apiKey,
+        ANTHROPIC_CUSTOM_HEADERS: headers,
+    };
+    if (input.model)
+        envSet.ANTHROPIC_MODEL = input.model;
+    return {
+        command: "claude",
+        args,
+        envSet,
+        envUnset: ["ANTHROPIC_API_KEY"],
+        installHint: "install Claude Code: npm i -g @anthropic-ai/claude-code (or see https://code.claude.com)",
+    };
+}
+//# sourceMappingURL=claude.js.map

package/dist/agents/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzF;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB;IACzC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,KAAK,CAAC,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;SACvD,IAAI,KAAK,CAAC,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC,CAAC;SAChE,IAAI,KAAK,CAAC,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IAE5D,IAAI,KAAK,CAAC,QAAQ;QAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;SACrD,IAAI,KAAK,CAAC,UAAU;QAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;;QAC9C,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAEhD,IAAI,KAAK,CAAC,KAAK;QAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IAEhC,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,EAAE,EAAE,GAAG,cAAc,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;SAClG,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;SACtC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,MAAM,GAA2B;QACrC,kBAAkB,EAAE,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC;QAC5C,oBAAoB,EAAE,KAAK,CAAC,MAAM;QAClC,wBAAwB,EAAE,OAAO;KAClC,CAAC;IACF,IAAI,KAAK,CAAC,KAAK;QAAE,MAAM,CAAC,eAAe,GAAG,KAAK,CAAC,KAAK,CAAC;IAEtD,OAAO;QACL,OAAO,EAAE,QAAQ;QACjB,IAAI;QACJ,MAAM;QACN,QAAQ,EAAE,CAAC,mBAAmB,CAAC;QAC/B,WAAW,EAAE,0FAA0F;KACxG,CAAC;AACJ,CAAC"}

package/dist/agents/codex.d.ts

@@ -0,0 +1,13 @@
+import { type HarnessPlan, type PlanInput } from "./types.js";
+/** Quotes a string as a TOML basic string for `codex -c key=value`. */
+export declare function tomlString(value: string): string;
+/**
+ * Builds the `codex` invocation.
+ *
+ * Codex ignores OPENAI_BASE_URL while a ChatGPT login exists and only speaks
+ * the Responses wire, so the endpoint is injected as a dedicated `ditto`
+ * model provider through `-c` overrides (nothing is written to
+ * ~/.codex/config.toml). The session header rides on the provider's
+ * http_headers so every request lands in the same Ditto thread.
+ */
+export declare function planCodex(input: PlanInput): HarnessPlan;

package/dist/agents/codex.js

@@ -0,0 +1,48 @@
+import { CODEX_KEY_ENV, SESSION_HEADER } from "./types.js";
+/** Quotes a string as a TOML basic string for `codex -c key=value`. */
+export function tomlString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Builds the `codex` invocation.
+ *
+ * Codex ignores OPENAI_BASE_URL while a ChatGPT login exists and only speaks
+ * the Responses wire, so the endpoint is injected as a dedicated `ditto`
+ * model provider through `-c` overrides (nothing is written to
+ * ~/.codex/config.toml). The session header rides on the provider's
+ * http_headers so every request lands in the same Ditto thread.
+ */
+export function planCodex(input) {
+    const args = [];
+    if (input.prompt !== undefined)
+        args.push("exec");
+    else if (input.resumeId || input.resumeLast)
+        args.push("resume");
+    args.push("-c", `model_provider=${tomlString("ditto")}`, "-c", `model_providers.ditto.name=${tomlString("Ditto")}`, "-c", `model_providers.ditto.base_url=${tomlString(input.baseUrl)}`, "-c", `model_providers.ditto.env_key=${tomlString(CODEX_KEY_ENV)}`, "-c", `model_providers.ditto.wire_api=${tomlString("responses")}`, "-c", `model_providers.ditto.http_headers={${tomlString(SESSION_HEADER)}=${tomlString(input.sessionId)}}`);
+    if (input.model)
+        args.push("-m", input.model);
+    if (input.yolo)
+        args.push("--dangerously-bypass-approvals-and-sandbox");
+    else if (input.yellow)
+        args.push("-a", "on-request", "-s", "workspace-write");
+    if (input.prompt !== undefined) {
+        args.push("--skip-git-repo-check", ...input.passthrough, input.prompt);
+    }
+    else if (input.resumeId) {
+        args.push(...input.passthrough, input.resumeId);
+    }
+    else if (input.resumeLast) {
+        args.push("--last", ...input.passthrough);
+    }
+    else {
+        args.push(...input.passthrough);
+    }
+    return {
+        command: "codex",
+        args,
+        envSet: { [CODEX_KEY_ENV]: input.apiKey },
+        envUnset: [],
+        installHint: "install Codex: npm i -g @openai/codex (or brew install codex)",
+    };
+}
+//# sourceMappingURL=codex.js.map

package/dist/agents/codex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/agents/codex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoC,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7F,uEAAuE;AACvE,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,KAAgB;IACxC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;SAC7C,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,UAAU;QAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEjE,IAAI,CAAC,IAAI,CACP,IAAI,EACJ,kBAAkB,UAAU,CAAC,OAAO,CAAC,EAAE,EACvC,IAAI,EACJ,8BAA8B,UAAU,CAAC,OAAO,CAAC,EAAE,EACnD,IAAI,EACJ,kCAAkC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAC7D,IAAI,EACJ,iCAAiC,UAAU,CAAC,aAAa,CAAC,EAAE,EAC5D,IAAI,EACJ,kCAAkC,UAAU,CAAC,WAAW,CAAC,EAAE,EAC3D,IAAI,EACJ,uCAAuC,UAAU,CAAC,cAAc,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CACpG,CAAC;IACF,IAAI,KAAK,CAAC,KAAK;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAE9C,IAAI,KAAK,CAAC,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;SACnE,IAAI,KAAK,CAAC,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC;IAE9E,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,GAAG,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzE,CAAC;SAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;SAAM,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,OAAO,EAAE,OAAO;QAChB,IAAI;QACJ,MAAM,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE;QACzC,QAAQ,EAAE,EAAE;QACZ,WAAW,EAAE,+DAA+D;KAC7E,CAAC;AACJ,CAAC"}

package/dist/agents/launch.d.ts

@@ -0,0 +1,25 @@
+import { type InferenceEndpoint } from "../api.js";
+import { type Harness } from "./types.js";
+export interface LaunchOptions {
+    endpoint?: string;
+    budget?: string;
+    expires?: string;
+    keepKey?: boolean;
+    session?: string;
+    resume?: string | boolean;
+    continue?: boolean;
+    yolo?: boolean;
+    yellow?: boolean;
+    plan?: boolean;
+    prompt?: string;
+    model?: string;
+    worktree?: string | boolean;
+    name?: string;
+    dryRun?: boolean;
+}
+/** Interactive numbered picker; also accepts a slug or id. Exported for `heyditto endpoints pick`. */
+export declare function pickEndpoint(endpoints: InferenceEndpoint[], defaultSlug?: string): Promise<InferenceEndpoint>;
+/** Refuses to launch against an endpoint the backend marked inactive (e.g. awaiting the user's plan). */
+export declare function assertEndpointActive(endpoint: InferenceEndpoint): Promise<void>;
+/** Launches a coding harness against a Ditto inference endpoint with a temporary key. */
+export declare function launchHarness(harness: Harness, rawArgs: string[], options: LaunchOptions): Promise<void>;