mindwire 0.1.0 → 0.1.1

package/dist/client.d.ts

@@ -0,0 +1,476 @@
+import { Http, type FetchLike } from "./http.js";
+import { Run } from "./run.js";
+import { type Target } from "./target/index.js";
+import type { EnsureEvent } from "./target/host.js";
+import type { AgentInfo, AuthMethod, AuthState, AuthStatus, Catalog, ChatSummary, CustomProvider, DeleteResult, DoctorReport, Health, MCPServer, MemoryDoc, MemoryScope, Message, ModelInfo, Notification, NotifyChannel, NotifyChannelInput, NotifyChannelTestResult, NotifyConfigInput, NotifyConfigStatus, NotifyRule, NotifyRuleInput, ProcessFrame, PromptTemplate, ResolveOptions, SetupStatus, Stats, Subagent, TurnOptions } from "./types.js";
+export interface MindwireOptions {
+    /**
+     * Default agent type for agent-scoped calls (e.g. `"claude-code"`). When omitted, the daemon
+     * uses its own default. Override per call with the `agent` option, or scope a whole client
+     * with {@link Mindwire.withAgent}.
+     */
+    agent?: string;
+    /**
+     * **Where the daemon runs and how the SDK reaches it.** A {@link Target} factory: {@link local}
+     * (the default — an embedded loopback daemon, auto-spawned on a server runtime), {@link remote}
+     * (a daemon you already run, required in the browser), or {@link import("./target/ssh.js").ssh} /
+     * {@link import("./target/docker.js").docker} / {@link import("./target/oblien.js").oblien} — or any
+     * object implementing `Target`. One `new Mindwire` = one target = one daemon = one environment; to
+     * isolate agents, create another `Mindwire` with its own target. Omit for the zero-config default.
+     */
+    target?: Target;
+    /**
+     * Receives a step {@link EnsureEvent} while a target provisions (connect → probe → upload → launch →
+     * ready, or skip). Handy to surface the seconds-long "upload the daemon + launch + health-poll" of a
+     * fresh SSH/Docker/Oblien box. A throwing callback can't abort provisioning.
+     */
+    logger?: (e: EnsureEvent) => void;
+    /** Custom fetch. Defaults to the global `fetch` (Node 18+, Bun, Deno, browsers). */
+    fetch?: FetchLike;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /**
+     * Deadline in milliseconds for a single unary request (health, config, `turn` creation, memory,
+     * …). Guards against a hung daemon or a dead tunnel blocking a call forever — on expiry the call
+     * rejects with {@link import("./errors.js").TimeoutError}. Does **not** apply to the event stream,
+     * which is long-lived. Defaults to 120000; pass `0` to disable.
+     */
+    requestTimeoutMs?: number;
+}
+/** Options accepted by any agent-scoped method to override the client's default agent. */
+export interface AgentScoped {
+    agent?: string;
+}
+/**
+ * The mindwire client — one typed surface over the daemon, regardless of which coding-agent
+ * harness runs behind `?agent=<type>`.
+ *
+ * **Where** it runs is one option — `target`. By default it's an **embedded** daemon
+ * ({@link local}): on a server runtime it auto-spawns the bundled `mindwired` on loopback, so there's
+ * nothing to deploy. Point elsewhere with {@link remote} (a daemon you run; also required in the
+ * browser), {@link import("./target/ssh.js").ssh}, {@link import("./target/docker.js").docker}, or
+ * {@link import("./target/oblien.js").oblien}. One client = one target = one daemon = one environment.
+ *
+ * ```ts
+ * // Local embedded (default) — Node/Bun/Deno:
+ * const mw = new Mindwire({ agent: "claude-code" });
+ *
+ * // Remote — or in the browser:
+ * const mw = new Mindwire({ target: remote("https://mindwire.yourco.com", { token }) });
+ *
+ * // A fresh box over SSH, watching it provision:
+ * const mw = new Mindwire({ target: ssh({ host, username: "root" }), logger: (e) => console.log(e.phase, e.message) });
+ * await mw.ensure();
+ *
+ * const run = await mw.turn({ chatId: "c1", message: "add a health check" });
+ * for await (const ev of run) console.log(ev.type, ev.text ?? "");
+ * ```
+ */
+export declare class Mindwire {
+    readonly http: Http;
+    /** The default agent type applied to agent-scoped calls, if set. */
+    readonly defaultAgent: string | undefined;
+    /** Step-flow auth, scoped to this client's default agent (override per call). */
+    readonly auth: AuthApi;
+    /** Persistent memory files + saved prompt templates, scoped to this client's default agent. */
+    readonly prompts: PromptsApi;
+    /** Persistent MCP-server config (the config an agent loads every run), scoped to this client's default agent. */
+    readonly mcp: McpApi;
+    /** Custom LLM-provider registration (opencode/Codex native config), scoped to this client's default agent. */
+    readonly providers: ProvidersApi;
+    /** Daemon-driven notification channels + routing rules (webhook/slack/discord/telegram; per-agent/session/global). */
+    readonly notify: NotifyApi;
+    constructor(opts?: MindwireOptions);
+    /**
+     * Provision the destination and await readiness **now**, rather than lazily on the first request —
+     * useful to front-load a fresh SSH/Docker/Oblien box (and to stream its {@link EnsureEvent}s to the
+     * `logger`) before the first `turn()`. Idempotent and memoized: repeated `ensure()` calls, and the
+     * first real request, all await the same provisioning, so the target connects exactly once.
+     */
+    ensure(): Promise<void>;
+    /** Return a new client bound to a different default agent (shares the same transport config). */
+    withAgent(agent: string): Mindwire;
+    /** The `?agent=` value to send for a scoped call: explicit override → client default → none. */
+    agentParam(scoped?: AgentScoped): {
+        agent: string;
+    } | undefined;
+    /**
+     * Release target-owned resources by calling the {@link TargetHandle}'s `stop()` — once, even across
+     * {@link withAgent} clones that share the transport. For an `ssh`/`docker`/`oblien` target this reaps
+     * the box (tear down the tunnel, stop or delete the container/workspace, per `stopOnExit`); a no-op
+     * for `local`/`remote` (embedded self-cleans on process exit; remote is not ours to stop). Safe to
+     * call before the target has connected (nothing to reap yet).
+     */
+    close(): Promise<void>;
+    /** `GET /healthz` — public liveness check. Resolves with the daemon's health payload when it is up. */
+    health(): Promise<Health>;
+    /**
+     * `GET /stats` — the daemon **process's** resource snapshot (heap in use, memory reserved from the
+     * OS, goroutines, GC cycles, cores, platform, uptime). Cheap enough to call on demand — the daemon
+     * reads its own Go runtime, not the machine — so a UI can fetch it when a user opens a daemon's page
+     * without any background polling. See {@link Stats} for what each field means and doesn't.
+     */
+    stats(): Promise<Stats>;
+    /** `GET /catalog` — every agent this daemon binary supports. */
+    catalog(): Promise<Catalog>;
+    /** `GET /agent` — capabilities + settings schema + auth methods/status for the selected agent. */
+    agent(scoped?: AgentScoped): Promise<AgentInfo>;
+    /**
+     * `GET /models` — the models the selected agent can run for the configured account. An empty array
+     * is valid (no credentials yet / offline). Throws a 400 {@link ApiError} for an agent whose model is
+     * free text (check `capabilities.models` first).
+     */
+    models(scoped?: AgentScoped): Promise<ModelInfo[]>;
+    /** `GET /doctor` — daemon-level health plus the selected agent's own checks. */
+    doctor(scoped?: AgentScoped): Promise<DoctorReport>;
+    /** `POST /setup` — start the agent's install toolchain (background; poll {@link setupStatus}). */
+    setup(scoped?: AgentScoped): Promise<SetupStatus>;
+    /** `POST /update` — re-run the toolchain, forcing reinstall of installable steps. */
+    update(scoped?: AgentScoped): Promise<SetupStatus>;
+    /** `GET /setup` — current toolchain install progress. */
+    setupStatus(scoped?: AgentScoped): Promise<SetupStatus>;
+    /** `GET /config` — the declared, non-secret settings for the agent. */
+    getConfig(scoped?: AgentScoped): Promise<Record<string, string>>;
+    /** `PUT /config` — merge recognized (non-secret) setting keys. Unknown keys are ignored server-side. */
+    setConfig(values: Record<string, string>, scoped?: AgentScoped): Promise<void>;
+    /** `GET /chats` — recorded chats (newest first), shared across agents. */
+    chats(): Promise<ChatSummary[]>;
+    /**
+     * `PUT /chats/{id}` — rename a chat. The user title wins over the agent's native auto-title in
+     * every listing; an empty title clears the rename (reverting to the native/derived title).
+     * Returns the updated summary.
+     */
+    renameChat(chatId: string, title: string): Promise<ChatSummary>;
+    /**
+     * `DELETE /chats/{id}` — a true, irreversible delete: purges ALL of the chat's mindwire
+     * bookkeeping and, for every session the chat mapped to, removes that agent's native transcript
+     * (the source of truth). Rejects with a 409 error if a turn is live. Native deletion is
+     * best-effort per agent; the result reports what was purged vs. failed.
+     */
+    deleteChat(chatId: string): Promise<DeleteResult>;
+    /**
+     * `POST /chats/{id}/fork` — clone a chat into a new id (generated when `newChatId` is omitted).
+     * The fork shares the source's native session until its first turn, which branches it (natively
+     * on Claude via `--fork-session`; a fresh session on agents without native fork). Rejects with a
+     * 409 if the source has a live turn, 404 if the source is unknown, 400 if the target id is in
+     * use. Returns the new chat's summary.
+     */
+    forkChat(chatId: string, opts?: {
+        newChatId?: string;
+    }): Promise<ChatSummary>;
+    /**
+     * `GET /chats/{id}/messages` — a chat's transcript (native when the agent supports it, else
+     * the recorded fallback). `limit` caps to the newest N; `before` pages older history.
+     */
+    messages(chatId: string, opts?: AgentScoped & {
+        limit?: number;
+        before?: string;
+    }): Promise<Message[]>;
+    /** `GET /chats/{id}/run` — the latest run for a chat (reattach anchor), or `null` if none yet. */
+    latestRun(chatId: string): Promise<Run | null>;
+    /**
+     * `POST /turns` — start a turn. Returns a {@link Run} handle you can stream, cancel, or await.
+     * Rejects with an {@link ApiError} (409) if a turn is already running for the chat.
+     *
+     * `mode` defaults to `"turn"` — one agent turn that ends when the CLI settles. Pass
+     * `mode: "resolve"` (with optional {@link ResolveOptions} `resolve` caps) for a global-resolve run
+     * that auto-continues the agent's multi-step work until it's done; {@link Mindwire.resolve} is the
+     * clearer entry point for that. The returned {@link Run} is then the parent of the run tree.
+     */
+    turn(input: {
+        chatId: string;
+        message: string;
+        cwd?: string;
+        options?: TurnOptions;
+        mode?: "turn" | "resolve";
+        resolve?: ResolveOptions;
+    } & AgentScoped): Promise<Run>;
+    /**
+     * `POST /turns {mode:"resolve"}` — start a **global-resolve** run: instead of returning after one
+     * turn, the daemon holds the task open and auto-continues the agent (resuming on continuable stops
+     * and probing for completion) until the work is globally resolved, then aggregates one final result.
+     *
+     * The returned {@link Run} is the **parent** of a run tree: each auto-continued iteration is a child
+     * turn ({@link Run.children}) whose events stream onto the parent's topic, delimited by `continuation`
+     * boundary events. `run.wait()` resolves once with the aggregated result; `run.stopReason` /
+     * `run.iterations` report how the loop ended. Resolve turns run unattended (no mid-turn approvals)
+     * and are bounded by {@link ResolveOptions} caps — see the resolve guide. Rejects with an
+     * {@link ApiError} (409) if a turn is already running for the chat.
+     */
+    resolve(input: {
+        chatId: string;
+        message: string;
+        cwd?: string;
+        options?: TurnOptions;
+        resolve?: ResolveOptions;
+    } & AgentScoped): Promise<Run>;
+    /** `GET /runs/{id}` — fetch an existing run as a {@link Run} handle. */
+    run(id: string): Promise<Run>;
+    /**
+     * `POST /chats/{id}/compact` — run an on-demand conversation compaction as a first-class {@link Run}
+     * you can stream or await. The agent folds prior context into a summary it carries forward, emitting
+     * a `compaction` event on the stream and recording the boundary in history exactly like an
+     * auto-compaction. Optional `instructions` focus the continuation summary (Claude's
+     * `/compact <instructions>`; agents that don't honor focus still compact). Rejects with an
+     * {@link ApiError}: 400 if the agent doesn't support compaction (`capabilities.compactNow`) or the
+     * chat has no conversation yet, 409 if a turn is already running for the chat.
+     */
+    compact(chatId: string, opts?: {
+        instructions?: string;
+    } & AgentScoped): Promise<Run>;
+    /** `GET /notify/config` — whether a notification channel is wired (token never returned). */
+    getNotifyConfig(): Promise<NotifyConfigStatus>;
+    /** `PUT /notify/config` — store the provisioned notification channel (daemon-wide). */
+    setNotifyConfig(input: NotifyConfigInput): Promise<void>;
+    /** `GET /notify/stream` — SSE feed of the daemon's notifications (replay, then live). */
+    notifications(opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<Notification>;
+    /**
+     * `GET /processes/stream` — SSE feed of live per-turn CPU/memory, one {@link ProcessFrame} per tick.
+     * Sampling is **on demand**: the daemon starts measuring only while a client is connected and stops
+     * the instant the last one disconnects, so aborting the `signal` (or ending the loop) tells the
+     * daemon to stop — no background work, no leak. Pass `agent` to filter each frame's samples to one
+     * agent type. Frames are live snapshots (no replay); an empty `samples` array is a valid keep-alive.
+     */
+    processes(opts?: {
+        agent?: string;
+        signal?: AbortSignal;
+    }): AsyncGenerator<ProcessFrame>;
+}
+/** Step-flow auth (`methods → begin → step → status`) for a scoped agent. */
+export declare class AuthApi {
+    private readonly mw;
+    constructor(mw: Mindwire);
+    /** `GET /auth/methods` — the options list to present. */
+    methods(scoped?: AgentScoped): Promise<AuthMethod[]>;
+    /** `POST /auth/begin` — start one method (may return `{ url, code, fields, pending }`). */
+    begin(method: string, scoped?: AgentScoped): Promise<AuthState>;
+    /** `POST /auth/step` — submit fields, or poll an interactive login to completion. */
+    step(input: Record<string, string>, scoped?: AgentScoped): Promise<AuthState>;
+    /** `GET /auth/status` — is the agent authenticated, and via which method. */
+    status(scoped?: AgentScoped): Promise<AuthStatus>;
+}
+/**
+ * The persistent prompt/memory surface for a scoped agent — the three layers beneath a turn's
+ * per-turn `systemPrompt`: the agent's **memory file** (`CLAUDE.md` / `AGENTS.md`) and its saved
+ * **prompt templates** (slash-commands / saved prompts). One shape regardless of which agent runs;
+ * a call 400s if the selected agent doesn't support the layer.
+ *
+ * `dir` selects the project-scope working directory (defaults to the daemon cwd); `scope` picks
+ * `project` vs `user` (the agent's home config dir). Only agents whose `Capabilities.memory` /
+ * `Capabilities.promptTemplates` is set expose these — read that first to decide what to render.
+ */
+export declare class PromptsApi {
+    private readonly mw;
+    constructor(mw: Mindwire);
+    private query;
+    /**
+     * `GET /memory` — the agent's memory file at every supported scope (project + user for both
+     * Claude and Codex). Each entry carries the resolved `path` and `exists`; `content` is `""` for
+     * an absent file.
+     */
+    memory(opts?: AgentScoped & {
+        dir?: string;
+    }): Promise<MemoryDoc[]>;
+    /** `PUT /memory` — write the memory file at `scope`. Returns the resulting {@link MemoryDoc}. */
+    setMemory(input: {
+        scope: MemoryScope;
+        content: string;
+    }, opts?: AgentScoped & {
+        dir?: string;
+    }): Promise<MemoryDoc>;
+    /**
+     * `DELETE /memory` — remove the memory file at `scope` (defaults to `user`). Returns the resulting
+     * {@link MemoryDoc} (`exists: false` at the resolved path). Idempotent: deleting an absent file still
+     * succeeds.
+     */
+    deleteMemory(opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<MemoryDoc>;
+    /**
+     * `GET /prompts` — saved prompt templates across every supported scope (Claude: project + user;
+     * Codex: user only). `content` is omitted here; fetch it with {@link get}. A missing project
+     * directory yields an empty list for that scope rather than an error.
+     */
+    list(opts?: AgentScoped & {
+        dir?: string;
+    }): Promise<PromptTemplate[]>;
+    /** `GET /prompts/{name}` — one template's full body. Rejects with a 404 `ApiError` if absent. */
+    get(name: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<PromptTemplate>;
+    /** `PUT /prompts/{name}` — create or overwrite a template. Returns the resulting {@link PromptTemplate}. */
+    set(name: string, content: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<PromptTemplate>;
+    /**
+     * `DELETE /prompts/{name}` — remove one template at `scope` (defaults to `user`). Idempotent:
+     * deleting an absent template still succeeds. A traversal name rejects with a 400 `ApiError`.
+     */
+    delete(name: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<void>;
+    /**
+     * `GET /subagents` — persistent subagent definitions (Claude `.claude/agents/*.md`) across every
+     * supported scope. `content` is omitted here (fetch it with {@link subagent}); `meta` is the parsed
+     * frontmatter view. Rejects with a 400 `ApiError` on an agent without the subagent-definition module.
+     * Distinct from a turn's per-turn `subagents` passthrough — this is the on-disk definition store.
+     */
+    subagents(opts?: AgentScoped & {
+        dir?: string;
+    }): Promise<Subagent[]>;
+    /** `GET /subagents/{name}` — one definition's raw body + parsed meta. 404 `ApiError` if absent. */
+    subagent(name: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<Subagent>;
+    /** `PUT /subagents/{name}` — create or overwrite a definition (raw content is canonical). Returns it. */
+    setSubagent(name: string, content: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<Subagent>;
+    /**
+     * `DELETE /subagents/{name}` — remove one definition at `scope` (defaults to `user`). Idempotent:
+     * deleting an absent definition still succeeds. A traversal name rejects with a 400 `ApiError`.
+     */
+    deleteSubagent(name: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<void>;
+}
+/**
+ * The persistent MCP-server surface for a scoped agent — the servers an agent loads on **every run**
+ * from its own on-disk config (Claude's project `.mcp.json` + user `.claude.json`, Codex's
+ * `config.toml`), as opposed to a turn's per-turn {@link TurnOptions.mcpServers} overlay. One shape
+ * regardless of which agent runs; a call 400s if the selected agent doesn't expose the config
+ * (check `capabilities.mcpConfig` first).
+ *
+ * `scope` picks `project` vs `user` (defaults to `user` — the scope every supporting agent has;
+ * Codex is user-only); `dir` selects the project-scope working directory (defaults to the daemon cwd).
+ * No secret ever crosses this surface — HTTP auth travels as `bearerTokenEnvVar` (an env-var name).
+ */
+export declare class McpApi {
+    private readonly mw;
+    constructor(mw: Mindwire);
+    private query;
+    /**
+     * `GET /mcp` — every persistent MCP server across the agent's supported scopes, keyed
+     * `scope → name → server` (Claude: project + user; Codex: user only). A missing config file yields
+     * an empty object for that scope rather than an error.
+     */
+    list(opts?: AgentScoped & {
+        dir?: string;
+    }): Promise<Partial<Record<MemoryScope, Record<string, MCPServer>>>>;
+    /** `GET /mcp/{name}` — one server's definition. Rejects with a 404 `ApiError` if it isn't configured. */
+    get(name: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<MCPServer>;
+    /** `PUT /mcp/{name}` — create or overwrite one server. Returns the stored definition. */
+    set(name: string, server: MCPServer, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<MCPServer>;
+    /** `DELETE /mcp/{name}` — remove one server. Idempotent: deleting an absent server still succeeds. */
+    delete(name: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<void>;
+}
+/**
+ * The custom LLM-provider surface for a scoped agent — the OpenAI-compatible endpoints an agent loads on
+ * **every run** from its own native config (opencode's `opencode.json` `provider.<id>`, Codex's
+ * `config.toml` `[model_providers.<id>]`). One shape regardless of agent; a call 400s if the selected
+ * agent can't materialize one (check `capabilities.customProviders` — Claude uses its gateway auth lane
+ * instead). Registered models then appear in {@link Mindwire.models} with `custom:true`.
+ *
+ * `scope` picks `project` vs `user` (defaults to `user`; opencode/Codex are user-only); `dir` selects the
+ * project-scope working directory (defaults to the daemon cwd).
+ *
+ * SECURITY: secrets are passed write-only via {@link set}'s `apiKey` / `secrets` options and reported only
+ * as `hasKey` (plus the stored `envVars` NAMES). They never cross this surface on the way back and are never
+ * written literally into any config file — the harness references them through env-var placeholders and the
+ * daemon exports them at run time.
+ */
+export declare class ProvidersApi {
+    private readonly mw;
+    constructor(mw: Mindwire);
+    private query;
+    /**
+     * `GET /providers` — every registered custom provider across the agent's supported scopes, keyed
+     * `scope → id → provider` (opencode/Codex: user only). A missing config file yields an empty object for
+     * that scope rather than an error. `hasKey` reports whether a secret is stored; the key is never returned.
+     */
+    list(opts?: AgentScoped & {
+        dir?: string;
+    }): Promise<Partial<Record<MemoryScope, Record<string, CustomProvider>>>>;
+    /** `GET /providers/{id}` — one provider's definition. Rejects with a 404 `ApiError` if it isn't configured. */
+    get(id: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<CustomProvider>;
+    /**
+     * `PUT /providers/{id}` — create or overwrite one provider, returning the stored definition (with
+     * `hasKey` and the stored `envVars`). Two write-only secret channels, both optional: `opts.apiKey` is a
+     * single key (custom endpoints, single-key catalog brands); `opts.secrets` is a NAME→VALUE map for a
+     * catalog provider whose entry declares MULTIPLE env vars (e.g. AWS Bedrock). Omitting both leaves any
+     * previously stored secret intact. The path `id` wins over any `id` on the provider value.
+     */
+    set(id: string, provider: Omit<CustomProvider, "id" | "hasKey"> & Partial<Pick<CustomProvider, "hasKey">>, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+        apiKey?: string;
+        secrets?: Record<string, string>;
+    }): Promise<CustomProvider>;
+    /** `DELETE /providers/{id}` — remove one provider and clear its stored key. Idempotent. */
+    delete(id: string, opts?: AgentScoped & {
+        scope?: MemoryScope;
+        dir?: string;
+    }): Promise<void>;
+}
+/**
+ * Daemon-driven notification fan-out: named **channels** (a webhook URL shaped for
+ * webhook/Slack/Discord/Telegram, with optional headers, a bearer token, and — for the raw webhook
+ * type — an HMAC signing secret) and the **rules** that route matching notifications to them
+ * (`global` / per-`agent` / per-`session`, with optional event selection). This is daemon-wide
+ * config (NOT agent-scoped): the daemon evaluates every rule against each notification it emits and
+ * POSTs to the union of the matched channels — additive over the single {@link Mindwire.setNotifyConfig}
+ * webhook.
+ *
+ * Secrets are **write-only**: a channel read back via {@link channels} never carries the URL, token,
+ * secret, or header values — only their presence (and the URL host). On {@link setChannel}, omitting
+ * `url`/`token`/`secret` preserves the stored value; send a new value to rotate it.
+ */
+export declare class NotifyApi {
+    private readonly mw;
+    constructor(mw: Mindwire);
+    /** `GET /notify/channels` — every channel, masked (no secrets). */
+    channels(): Promise<NotifyChannel[]>;
+    /** `POST /notify/channels` — create a channel (server-assigns the id). Returns it masked. */
+    createChannel(input: NotifyChannelInput): Promise<NotifyChannel>;
+    /**
+     * `PUT /notify/channels/{id}` — update a channel, merge-preserving any omitted secret
+     * (`url`/`token`/`secret`). Returns the updated masked channel. 404 `ApiError` if unknown.
+     */
+    setChannel(id: string, input: NotifyChannelInput): Promise<NotifyChannel>;
+    /** `DELETE /notify/channels/{id}` — remove a channel. Idempotent. */
+    deleteChannel(id: string): Promise<void>;
+    /**
+     * `POST /notify/channels/{id}/test` — deliver a synthetic notification to a channel. A failed
+     * delivery is DATA (`{ ok: false, error }`), not a thrown error; only an unknown id rejects (404).
+     */
+    testChannel(id: string): Promise<NotifyChannelTestResult>;
+    /** `GET /notify/rules` — every routing rule. */
+    rules(): Promise<NotifyRule[]>;
+    /** `POST /notify/rules` — create a rule (server-assigns the id). Returns it. */
+    createRule(input: NotifyRuleInput): Promise<NotifyRule>;
+    /** `PUT /notify/rules/{id}` — replace a rule. Returns it. 404 `ApiError` if unknown. */
+    setRule(id: string, input: NotifyRuleInput): Promise<NotifyRule>;
+    /** `DELETE /notify/rules/{id}` — remove a rule. Idempotent. */
+    deleteRule(id: string): Promise<void>;
+}

package/dist/daemon-binary.d.ts

@@ -0,0 +1,13 @@
+export type DaemonPlatform = "darwin" | "linux" | "win32";
+export type DaemonArch = "x64" | "arm64";
+export interface EnsureDaemonBinaryOptions {
+    version?: string;
+    platform?: DaemonPlatform;
+    arch?: DaemonArch;
+    cacheDir?: string;
+    /** Override for tests or a private GitHub Releases mirror. */
+    releaseBaseUrl?: string;
+    fetch?: typeof fetch;
+}
+/** Ensure the SDK-matched daemon binary is present locally and return its executable path. */
+export declare function ensureDaemonBinary(opts?: EnsureDaemonBinaryOptions): Promise<string>;

package/dist/embedded.d.ts

@@ -0,0 +1,14 @@
+export interface EmbeddedOptions {
+    /** Working directory the daemon runs agents in. Defaults to the process cwd. */
+    cwd?: string;
+    /** Local state file for the embedded daemon. */
+    statePath?: string;
+    /** Explicit path to the `mindwired` binary (overrides discovery). */
+    bin?: string;
+}
+export interface EmbeddedDaemon {
+    baseUrl: string;
+    token?: string;
+    stop(): void;
+}
+export declare function startEmbedded(opts?: EmbeddedOptions): Promise<EmbeddedDaemon>;

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+/** Base class for every error thrown by the SDK. */
+export declare class MindwireError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A non-2xx HTTP response from the daemon. `body` is the parsed JSON error payload when the
+ * daemon returned one (it uses `{ "error": "..." }`), otherwise the raw text.
+ */
+export declare class ApiError extends MindwireError {
+    readonly status: number;
+    readonly url: string;
+    readonly method: string;
+    readonly body: unknown;
+    constructor(args: {
+        status: number;
+        url: string;
+        method: string;
+        body: unknown;
+    });
+    private static messageFor;
+}
+/**
+ * Thrown by {@link import("./run.js").Run.wait} when a run ends in a non-success terminal state
+ * (`error`/`cancelled`), or when the event stream ends before the run reaches any terminal state —
+ * a dropped/truncated stream. The `status` is whatever the run was in when `wait()` gave up, so a
+ * truncated stream surfaces as e.g. `run <id> running: event stream ended …` rather than silently
+ * returning a success-shaped result.
+ */
+export declare class RunFailedError extends MindwireError {
+    readonly status: string;
+    readonly runId: string;
+    constructor(runId: string, status: string, detail?: string);
+}
+/**
+ * Thrown when a unary request exceeds the client's `requestTimeoutMs` deadline. A hung daemon or a
+ * dead tunnel would otherwise block the caller forever; this bounds every non-streaming call. SSE
+ * streams are long-lived and are never subject to this timeout.
+ */
+export declare class TimeoutError extends MindwireError {
+    readonly method: string;
+    readonly path: string;
+    readonly timeoutMs: number;
+    constructor(method: string, path: string, timeoutMs: number);
+}

package/dist/http.d.ts

@@ -0,0 +1,97 @@
+/** A `fetch` implementation. Defaults to the global `fetch` (Node 18+, Bun, Deno, browsers). */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Fetches the current bearer token for a transport whose credential rotates (e.g. the Oblien
+ * gateway JWT). Called per request — implementations should cache and only mint on `{force:true}`
+ * or expiry. `request()`/`open()` call it with `{force:true}` once on a `401`, then retry.
+ */
+export type TokenGetter = (opts?: {
+    force?: boolean;
+}) => Promise<string | undefined>;
+/**
+ * Resolves the daemon's base URL, plus an optional static token, an optional dynamic `getToken`
+ * (for rotating credentials), and optional per-transport `headers` merged into every request
+ * (e.g. the Oblien proxy target). Called once, lazily, and memoized.
+ */
+export type BaseResolver = () => Promise<{
+    baseUrl: string;
+    token?: string;
+    getToken?: TokenGetter;
+    headers?: Record<string, string>;
+    /**
+     * A transport-specific `fetch` for this base — used for both unary requests and SSE streams. A
+     * sandbox adapter supplies it to route every call through its runtime (e.g. Oblien's `rt.proxy`);
+     * when omitted the client's default fetch is used, so embedded/remote transports are unchanged.
+     */
+    fetch?: FetchLike;
+}>;
+export interface HttpOptions {
+    /** Base URL of a running daemon, e.g. `http://127.0.0.1:8790`. */
+    baseUrl?: string;
+    /** Per-sandbox bearer token. */
+    token?: string;
+    /** Lazily resolve the base URL (used by the embedded transport to spawn on first call). */
+    resolveBase?: BaseResolver;
+    /** Custom fetch. Defaults to global `fetch`. */
+    fetch?: FetchLike;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /**
+     * Deadline in milliseconds for a single unary request. Does NOT apply to SSE streams (`open()`),
+     * which are long-lived by design. Defaults to {@link DEFAULT_TIMEOUT_MS}; pass `0` to disable.
+     */
+    timeoutMs?: number;
+}
+export interface RequestInitLike {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+/**
+ * The low-level transport: URL/auth/JSON/error plumbing shared by every high-level method.
+ * The base URL is resolved lazily and memoized — a fixed `baseUrl` resolves instantly; the
+ * embedded transport spawns the daemon on the first request.
+ */
+export declare class Http {
+    private readonly fetchImpl;
+    private readonly baseHeaders;
+    private readonly resolver;
+    private readonly timeoutMs;
+    private cached;
+    private pending;
+    constructor(opts: HttpOptions);
+    /**
+     * One fetch, with raw network failures wrapped as {@link MindwireError} so callers see a typed
+     * SDK error instead of a bare `TypeError: fetch failed`. An abort (the request's own signal, or
+     * our timeout controller) is re-thrown untouched — `fetchWithTimeout` classifies it.
+     */
+    private fetchOnce;
+    /**
+     * `fetchOnce` plus a timeout that composes with the caller's `signal`. A hand-rolled controller
+     * (not `AbortSignal.timeout`/`AbortSignal.any`, which need Node 20.3+/18.17+) fires after
+     * `timeoutMs`; whichever aborts first wins. Timeout → {@link TimeoutError}; the caller's own abort
+     * propagates as-is (its `reason`). `timeoutMs<=0` disables the deadline entirely.
+     */
+    private fetchWithTimeout;
+    /**
+     * The bearer token for the next request. Prefers the transport's dynamic `getToken` (which
+     * caches and mints on demand); falls back to the static token resolved at base time. `force`
+     * asks the getter to re-mint — used once on a 401 before retrying.
+     */
+    private authToken;
+    private base;
+    /**
+     * Resolve the base eagerly and memoize it — provisions the transport (spawns the embedded daemon,
+     * connects the sandbox/SSH/Docker target, …) now instead of on the first request. Idempotent: this
+     * awaits the *same* memoized promise the first `request()`/`open()` awaits, so the target's
+     * `connect()` fires exactly once. Backs {@link import("./client.js").Mindwire.ensure}.
+     */
+    ready(): Promise<void>;
+    private url;
+    private headers;
+    request<T>(method: string, path: string, init?: RequestInitLike): Promise<T>;
+    /** Open a streaming response (SSE). Caller owns the body. */
+    open(method: string, path: string, init?: RequestInitLike): Promise<Response>;
+    private toApiError;
+}