@gtc6244/immediacy-daemon 0.1.0

package/dist/src/protocol.d.ts

@@ -0,0 +1,1226 @@
+/**
+ * Wire protocol — the contract between the Mac daemon and the Flutter client.
+ *
+ * This file is the SOURCE OF TRUTH. The Dart mirror lives at
+ * app/lib/protocol.dart and must be kept in sync by hand (the shapes are small
+ * and stable enough that codegen is not worth the toolchain weight yet).
+ *
+ * Transport-agnostic by design: nothing here may assume Cloudflare, WSS, or any
+ * particular framing. A single multiplexed connection carries every message.
+ *
+ * The envelope fields (v, id, ts, ws, type) stay in clear for routing. Only
+ * `payload` is encrypted in the E2E layer (slice 5); until then it travels as
+ * plain JSON.
+ */
+export declare const PROTOCOL_VERSION: 1;
+/** Workspace lifecycle status, surfaced as a badge in the client. */
+export type WorkspaceStatus = "idle" | "running" | "awaiting_permission" | "done" | "error";
+/** Generic envelope. `T` is the message `type`; `P` its payload shape. */
+export interface Envelope<T extends MessageType = MessageType> {
+    v: typeof PROTOCOL_VERSION;
+    id: string;
+    ts: number;
+    ws: string | null;
+    type: T;
+    payload: PayloadFor<T>;
+}
+/** Client → daemon. */
+export type ClientMessageType = "project.list" | "project.create" | "project.delete" | "project.reorder" | "project.branches" | "project.pulls" | "project.issues" | "issue.create" | "workspace.list" | "workspace.create" | "workspace.delete" | "workspace.archive" | "workspace.action" | "delete.batch" | "prompt.send" | "agent.stop" | "permission.respond" | "question.respond" | "allowlist.list" | "allowlist.revoke" | "allowlist.clear" | "terminal.input" | "terminal.resize" | "terminal.snapshot" | "forward.list" | "forward.open" | "forward.data" | "forward.close" | "git.status" | "git.commit" | "git.push" | "git.resolve" | "git.merge" | "pr.create" | "pr.merge" | "workspace.open" | "diff.get" | "tree.get" | "file.get" | "file.set" | "chat.history" | "github.status" | "github.repos" | "models.list" | "job.list" | "job.create" | "job.update" | "job.delete" | "job.run" | "job.runs" | "settings.get" | "settings.set" | "config.set" | "log.tail" | "hello" | "pair.info" | "daemon.get" | "daemon.rename" | "ping" | "echo";
+/** Daemon → client. */
+export type DaemonMessageType = "project.list.result" | "project.branches.result" | "project.pulls.result" | "project.issues.result" | "workspace.list.result" | "workspace.created" | "workspace.renamed" | "delete.batch.result" | "event.assistant_message" | "event.tool_use" | "event.permission_request" | "event.permission_resolved" | "event.ask_question" | "event.session" | "event.agent_done" | "event.session_limit" | "terminal.data" | "terminal.snapshot.result" | "forward.available" | "git.status.result" | "git.result" | "diff.result" | "tree.result" | "file.result" | "file.saved" | "chat.history.result" | "github.status.result" | "github.repos.result" | "models.list.result" | "job.list.result" | "job.runs.result" | "event.job_run" | "settings.result" | "allowlist.result" | "log.tail.result" | "log.event" | "hello.ok" | "pair.info.result" | "daemon.info" | "pong" | "error" | "echo.result";
+export type MessageType = ClientMessageType | DaemonMessageType;
+export interface ProjectListPayload {
+}
+/**
+ * Register a project (one repo the user can spin worktrees off). Source is one
+ * of: `blank` — a brand-new empty repo the daemon `git init`s (no existing repo
+ * needed, local or remote); a GitHub repo (cloned into the daemon's managed
+ * root); or an existing local repo path. Where blank/GitHub projects live on
+ * disk is inherent — the client never chooses. `name` defaults to the repo
+ * name. GitHub/local are idempotent (by full name / resolved path); blank
+ * always creates.
+ */
+export interface ProjectCreatePayload {
+    /** Create a brand-new empty repo via `git init` — no existing repo required. */
+    blank?: boolean;
+    repo?: string;
+    github?: {
+        fullName: string;
+        defaultBranch?: string;
+    };
+    name?: string;
+}
+/** Remove a project registration. Rejected while it still has worktrees. */
+export interface ProjectDeletePayload {
+    id: string;
+}
+/**
+ * Reorder the project list. `ids` is the full set of project ids in the desired
+ * display order. Ids the daemon doesn't recognise are ignored; any known project
+ * missing from `ids` (e.g. a concurrent create the client hadn't seen yet) keeps
+ * its prior relative position at the end.
+ */
+export interface ProjectReorderPayload {
+    ids: string[];
+}
+export interface WorkspaceListPayload {
+}
+/**
+ * Create a workspace (git worktree) under a project. Preferred form passes
+ * `projectId` (from project.list); the repo/branch are taken from the project.
+ *
+ * The legacy form — a bare `repo` path or `github` source with no `projectId` —
+ * still works: the daemon find-or-creates the matching project first, then
+ * forks the worktree off it.
+ */
+export interface WorkspaceCreatePayload {
+    /**
+     * Create a repo-less free-form chat instead of a git worktree. When `"chat"`,
+     * every git/project field below is ignored and none is required.
+     */
+    kind?: "worktree" | "chat";
+    /** Project to fork the worktree from (from project.list.result). */
+    projectId?: string;
+    repo?: string;
+    github?: {
+        fullName: string;
+        defaultBranch?: string;
+    };
+    name?: string;
+    branchBase?: string;
+    /**
+     * Check out this *existing* branch instead of forking a fresh one — the
+     * "create worktree from an existing branch" flow. A local branch is checked
+     * out directly; otherwise a local tracking branch is created off
+     * `origin/<sourceBranch>`. The diff/PR base stays the project's default
+     * branch, so an existing feature branch still diffs against main.
+     */
+    sourceBranch?: string;
+    /**
+     * Check out an existing open PR's head branch instead of forking a fresh one —
+     * the "create worktree from an existing open PR" flow (the successor to
+     * `sourceBranch`). The daemon resolves the PR's head ref and fetches
+     * `refs/pull/<n>/head` so fork PRs work too. Mutually exclusive with
+     * `sourceBranch`; the diff/PR base stays the project's default branch.
+     */
+    sourcePr?: number;
+    /**
+     * Seed the new workspace's agent with this first prompt right after the
+     * worktree is created — powers "create worktree from an issue", where the
+     * (user-confirmed) issue becomes the task. Omitted → the workspace starts idle.
+     */
+    initialPrompt?: string;
+    /** Model id from the catalog (see models.list); omitted → daemon default. */
+    model?: string;
+}
+/** Request the branches a new worktree can be based on, for one project. */
+export interface ProjectBranchesPayload {
+    projectId: string;
+}
+/** Request the open pull requests a new worktree can be based on. */
+export interface ProjectPullsPayload {
+    projectId: string;
+}
+/** Request the open issues a new worktree's task can be seeded from. */
+export interface ProjectIssuesPayload {
+    projectId: string;
+}
+/**
+ * Open a GitHub issue from a worktree's output — the mirror of `pr.create`. The
+ * agent's produced plan/document is the issue `body`. Outcome rides the shared
+ * `git.result` channel with `op: "issue"`.
+ */
+export interface IssueCreatePayload {
+    ws: string;
+    title: string;
+    body?: string;
+}
+export interface ModelsListPayload {
+}
+export interface GithubStatusPayload {
+}
+export interface GithubReposPayload {
+    /** Optional cap on how many repos to return (most-recently-pushed first). */
+    limit?: number;
+}
+export interface WorkspaceDeletePayload {
+    ws: string;
+}
+export interface WorkspaceArchivePayload {
+    ws: string;
+}
+/**
+ * A prompt-backed agent action. Each kind maps to a built-in base instruction
+ * plus the matching `prompts.*` custom text (see AppConfig): `code_review` →
+ * `codeReview`, `create_pr` → `createPr`, `fix_errors` → `fixErrors`,
+ * `resolve_merge_conflicts` → `resolveMergeConflicts`, `rename_branch` →
+ * `renameBranch`.
+ */
+export type WorkspaceActionKind = "code_review" | "create_pr" | "fix_errors" | "resolve_merge_conflicts" | "rename_branch";
+export interface WorkspaceActionPayload {
+    ws: string;
+    kind: WorkspaceActionKind;
+}
+/**
+ * Mass-delete request. `workspaces` are worktree ids to remove; `projects` are
+ * project ids to remove *including* their remaining worktrees. The daemon
+ * removes worktrees first (a project can't be deleted while it still has any),
+ * skips ids it doesn't know, and continues past per-item failures — a dirty
+ * worktree that blocks removal is reported in the result, not fatal. Both
+ * arrays are optional; at least one should be non-empty.
+ */
+export interface DeleteBatchPayload {
+    workspaces?: string[];
+    projects?: string[];
+}
+/**
+ * A file attached to a prompt — an image or a document the user picked in the
+ * composer. Carried inline (base64) in the same `prompt.send` frame as the text,
+ * over the one multiplexed connection; the daemon turns each into a Claude
+ * content block (image / PDF document / inlined text) for the model to read.
+ *
+ * Keep these modest: the daemon caps per-file and per-message size (see
+ * server.ts) so a stray large file can't stall the encrypted channel.
+ */
+export interface PromptAttachment {
+    /** Original filename, e.g. "screenshot.png" — shown in the transcript. */
+    name: string;
+    /** MIME type, e.g. "image/png", "application/pdf", "text/plain". */
+    mediaType: string;
+    /** The file's bytes, base64-encoded (no data: URI prefix). */
+    data: string;
+}
+export interface PromptSendPayload {
+    ws: string;
+    text: string;
+    /** Files attached to this prompt (images / documents). Optional. */
+    attachments?: PromptAttachment[];
+}
+export interface PermissionRespondPayload {
+    ws: string;
+    requestId: string;
+    /**
+     * `allow`/`deny` answer this one call. `allow_all` also persists a category
+     * rule on the daemon (the host, folder, or tool this call belongs to) so every
+     * later matching call auto-approves without another prompt — see
+     * {@link AllowRulePayload} and the `allowlist.*` messages.
+     */
+    decision: "allow" | "deny" | "allow_all";
+}
+/**
+ * One clarifying question the model asked via the `AskUserQuestion` tool. Mirrors
+ * the Agent SDK's input schema: each question is multiple-choice with 2–4
+ * options, single- or multi-select. `header` is a ≤12-char chip label.
+ */
+export interface AgentQuestionOption {
+    label: string;
+    description?: string;
+    /** Optional rich preview (markdown/HTML) when the session enables it. */
+    preview?: string;
+}
+export interface AgentQuestion {
+    question: string;
+    header: string;
+    options: AgentQuestionOption[];
+    multiSelect: boolean;
+}
+/**
+ * The user's answers to an AskUserQuestion, keyed by each question's `question`
+ * text. A single-select answer is the chosen option's `label`; a multi-select
+ * answer is an array of labels (or free text the user typed for an "Other").
+ */
+export type QuestionAnswers = Record<string, string | string[]>;
+/**
+ * A client's reply to an `event.ask_question`. Either structured `answers` (the
+ * common case) or a freeform `response` the user typed instead of picking any
+ * option — when `response` is set the model is told "The user responded: …".
+ */
+export interface QuestionRespondPayload {
+    ws: string;
+    requestId: string;
+    answers: QuestionAnswers;
+    response?: string;
+}
+/**
+ * A persisted "Allow all" rule — a *category*, not a single call:
+ *   - host: any web request to `host` (any page on that site);
+ *   - dir:  any file/shell call whose target resolves inside `path`;
+ *   - tool: any call of `tool` (for calls we can't bound to a host or folder).
+ */
+export type AllowRulePayload = {
+    kind: "host";
+    host: string;
+} | {
+    kind: "dir";
+    path: string;
+} | {
+    kind: "tool";
+    tool: string;
+};
+/** One grant in the allowlist, with provenance for the admin list. */
+export interface AllowEntryPayload {
+    /** Stable identity; also the handle passed to `allowlist.revoke`. */
+    key: string;
+    rule: AllowRulePayload;
+    /** One-line human description, e.g. "all requests to example.com". */
+    description: string;
+    /** Epoch ms the grant was made. */
+    createdMs: number;
+    /** Workspace + tool the grant was created from (context, not scope). */
+    fromWorkspace?: string;
+    fromTool?: string;
+}
+export interface AllowlistListPayload {
+}
+export interface AllowlistRevokePayload {
+    /** The `key` of the entry to drop (from an AllowEntryPayload). */
+    key: string;
+}
+export interface AllowlistClearPayload {
+}
+/** The full current allowlist (reply to `allowlist.list`; also broadcast). */
+export interface AllowlistResultPayload {
+    entries: AllowEntryPayload[];
+}
+export interface TerminalInputPayload {
+    ws: string;
+    data: string;
+    /**
+     * Stable per-device id. Each device gets its OWN pty (its own size + its own
+     * scrollback) so a phone and a tablet with different screens don't clobber
+     * each other's geometry. Omitted by older clients → the daemon falls back to
+     * a per-connection id (isolated, but not restored across a reconnect).
+     */
+    deviceId?: string;
+}
+/** Stop the current agent turn (the session can be resumed by a new prompt). */
+export interface AgentStopPayload {
+    ws: string;
+}
+export interface TerminalResizePayload {
+    ws: string;
+    cols: number;
+    rows: number;
+    /** See TerminalInputPayload.deviceId — resizes only this device's pty. */
+    deviceId?: string;
+}
+/**
+ * Ask for the terminal's retained scrollback so a client that just connected
+ * (or just opened the pane) can render history it never streamed.
+ */
+export interface TerminalSnapshotPayload {
+    ws: string;
+    /** See TerminalInputPayload.deviceId — snapshots this device's own pty. */
+    deviceId?: string;
+}
+/** Branch/ahead-behind/dirty summary for the review-and-merge path. */
+export interface GitStatusPayload {
+    ws: string;
+    /**
+     * Set by a deliberate open/refresh of the worktree. Forces the daemon to
+     * fetch origin past its per-repo throttle before computing the numbers, so a
+     * just-pushed base is reflected on the click. Omitted/false on background
+     * polls, which stay throttled. Mirrored in protocol.dart / Protocol.swift.
+     */
+    sync?: boolean;
+}
+/** Stage everything in the worktree and commit. */
+export interface GitCommitPayload {
+    ws: string;
+    message: string;
+}
+/** Push the workspace branch to origin (sets upstream on first push). */
+export interface GitPushPayload {
+    ws: string;
+}
+/** Merge the base branch into the workspace branch to clear a divergence. */
+export interface GitResolvePayload {
+    ws: string;
+}
+/**
+ * Drive an in-progress merge's conflict resolution from the client:
+ *  - `ours`/`theirs` keep the workspace-branch / merged-in-base version of the
+ *    conflicting files (all of them, or just `paths` when given);
+ *  - `commit` finalizes the merge (refused while conflicts remain);
+ *  - `abort` rolls the merge back.
+ */
+export interface GitMergePayload {
+    ws: string;
+    action: "ours" | "theirs" | "commit" | "abort";
+    /** Subset of conflicting files for `ours`/`theirs`; omit to apply to all. */
+    paths?: string[];
+}
+/** Open a pull request for the workspace branch via the gh CLI. */
+export interface PrCreatePayload {
+    ws: string;
+    title: string;
+    body?: string;
+}
+/** Merge the workspace branch's open pull request via `gh pr merge`. */
+export interface PrMergePayload {
+    ws: string;
+}
+/**
+ * Reveal the worktree on the daemon's Mac. Local-only convenience: the client
+ * stays a pure front end and the daemon shells out to `open`.
+ */
+export interface WorkspaceOpenPayload {
+    ws: string;
+    target: "finder" | "terminal" | "editor";
+}
+export interface DiffGetPayload {
+    ws: string;
+}
+/** List every tracked + untracked (non-ignored) file in the worktree. */
+export interface TreeGetPayload {
+    ws: string;
+}
+/** Read one file's contents from the worktree (path is worktree-relative). */
+export interface FileGetPayload {
+    ws: string;
+    path: string;
+}
+/** Write new UTF-8 contents to one worktree-relative file (in-app editor save). */
+export interface FileSetPayload {
+    ws: string;
+    path: string;
+    content: string;
+}
+/**
+ * Fetch a workspace's persisted chat transcript ("transactions"). The daemon
+ * keeps a running log of every prompt/response so a client can rebuild the
+ * conversation after a reboot or a fresh connect. See ChatHistoryResultPayload.
+ */
+export interface ChatHistoryPayload {
+    ws: string;
+}
+export interface PingPayload {
+}
+export interface EchoPayload {
+    text: string;
+}
+/**
+ * A registered project: one repo, the group worktrees hang under in the
+ * sidebar. Persists even with zero worktrees so it stays a stable "+ new
+ * worktree here" target.
+ */
+export interface ProjectSummary {
+    id: string;
+    name: string;
+    /** Local repo path the worktrees fork from (a clone path for GitHub sources). */
+    repo: string;
+    /** Present when the project was added from GitHub (drives clone/fetch). */
+    github?: {
+        fullName: string;
+        defaultBranch?: string;
+    };
+    /**
+     * `git remote get-url origin` for this project's repo, when it has one. Lets a
+     * client that is connected to several daemons match a project on daemon A to
+     * the "same" project on daemon B (same origin) — the basis for moving a
+     * workspace between daemons. Omitted for a repo with no origin remote.
+     */
+    originUrl?: string;
+}
+export interface ProjectListResultPayload {
+    projects: ProjectSummary[];
+}
+/** Branches a new worktree can be based on for a project (local + remote). */
+export interface ProjectBranchesResultPayload {
+    /** Echoed back so clients can key the result to the project they asked about. */
+    projectId: string;
+    branches: string[];
+    /** The repo's default branch, when known (pickers surface it first). */
+    defaultBranch?: string;
+}
+/** One open pull request, as surfaced in the "create worktree from PR" picker. */
+export interface PullRequestSummary {
+    number: number;
+    title: string;
+    /** The PR's head branch — what gets checked out into the new worktree. */
+    headRefName: string;
+    /** Login of the PR author (for a subtitle in the picker). */
+    author: string;
+    url: string;
+    isDraft: boolean;
+}
+/** Open pull requests a new worktree can be based on for a project. */
+export interface ProjectPullsResultPayload {
+    /** Echoed back so clients can key the result to the project they asked about. */
+    projectId: string;
+    pulls: PullRequestSummary[];
+}
+/**
+ * One open issue. `body` is carried so the "from issue" flow can seed (and let
+ * the user confirm) the new worktree's task without a second round-trip.
+ */
+export interface IssueSummary {
+    number: number;
+    title: string;
+    body: string;
+    author: string;
+    url: string;
+}
+/** Open issues a new worktree's task can be seeded from, for a project. */
+export interface ProjectIssuesResultPayload {
+    /** Echoed back so clients can key the result to the project they asked about. */
+    projectId: string;
+    issues: IssueSummary[];
+}
+/** One item that could not be deleted in a `delete.batch`, with the reason. */
+export interface DeleteFailure {
+    id: string;
+    kind: "workspace" | "project";
+    message: string;
+}
+/**
+ * Outcome of a `delete.batch`: what was removed and what failed. Unlike the
+ * single-item `workspace.delete` — which throws and surfaces as an `error`
+ * frame — a batch never aborts on one bad item; it always resolves and reports
+ * per-item failures here instead.
+ */
+export interface DeleteBatchResultPayload {
+    deletedWorkspaces: string[];
+    deletedProjects: string[];
+    failures: DeleteFailure[];
+}
+export interface WorkspaceSummary {
+    ws: string;
+    name: string;
+    branch: string;
+    status: WorkspaceStatus;
+    /** Project this worktree belongs to (groups the sidebar). */
+    projectId: string;
+    /**
+     * Workspace flavor. Absent/`"worktree"` is the normal git-backed workspace;
+     * `"chat"` is a repo-less free-form chat (no branch, no diff) surfaced under
+     * the sidebar's Chat button rather than a project group.
+     */
+    kind?: "worktree" | "chat";
+    /** Model id backing this workspace's agent (see models.list). */
+    model?: string;
+    /** Lines added vs the base branch (uncommitted + committed); omitted if 0. */
+    added?: number;
+    /** Lines removed vs the base branch; omitted if 0. */
+    removed?: number;
+    /** Files differing from the base branch (count, not lines); omitted if 0. */
+    filesChanged?: number;
+    /**
+     * `git remote get-url origin` of the workspace's repo, when it has one. A
+     * client moving this workspace to another daemon uses it to find (or create) a
+     * matching project there before pulling the branch. Omitted if no origin.
+     */
+    repoUrl?: string;
+}
+/** Which agent backend runs a model. */
+export type ModelProvider = "claude" | "codex" | "openrouter";
+/** One selectable model, surfaced to the client via models.list.result. */
+export interface ModelInfo {
+    id: string;
+    label: string;
+    provider: ModelProvider;
+    default?: boolean;
+}
+export interface ModelsListResultPayload {
+    models: ModelInfo[];
+    /** The id used when a workspace is created without an explicit model. */
+    defaultModel: string;
+}
+/**
+ * A billing/auth provider the daemon can hold an API key for. Distinct from
+ * `ModelProvider` (which names the agent *backend*): `anthropic` keys back the
+ * Claude backend, `openai` keys back the Codex backend, `openrouter` keys back
+ * the OpenRouter backend.
+ */
+export type CredentialProvider = "anthropic" | "openai" | "openrouter";
+/**
+ * Which credential a provider's sessions will use:
+ *   - "apikey" — an API key is stored on (or seeded into) the daemon.
+ *   - "sso"    — no key, so sessions fall back to the CLI/SDK's own cached
+ *                subscription login (Claude Code login / Codex ChatGPT login).
+ *   - "none"   — no key and no login fallback (OpenRouter is API-key only).
+ */
+export type CredentialSource = "apikey" | "sso" | "none";
+/** Per-provider credential status — safe to broadcast (no raw key material). */
+export interface CredentialInfo {
+    provider: CredentialProvider;
+    source: CredentialSource;
+    /** An effective API key is present (stored on the daemon or seeded from env). */
+    hasKey: boolean;
+    /** Non-reversible hint (last 4 chars, e.g. "…a1b2"); null when no key. */
+    maskedKey: string | null;
+}
+/** Read the credential status for every provider (plus the app config). */
+export interface SettingsGetPayload {
+}
+/** Set (non-empty) or clear (empty/omitted) a provider's stored API key. */
+export interface SettingsSetPayload {
+    provider: CredentialProvider;
+    apiKey: string;
+}
+/**
+ * Broadcast whenever credentials or the app config change. Carries the full,
+ * current state of both so every client converges: credential status (no raw
+ * key material) and the daemon-owned {@link AppConfig}.
+ */
+export interface SettingsResultPayload {
+    credentials: CredentialInfo[];
+    config: AppConfig;
+}
+/**
+ * How a workspace's branch name is prefixed:
+ *   - "none"     — no prefix; the slug is the branch name.
+ *   - "username" — prefix with the local git user (e.g. `alice/`).
+ *   - "custom"   — prefix with the literal {@link GitConfig.branchPrefix}.
+ */
+export type BranchPrefixType = "none" | "username" | "custom";
+/**
+ * Custom prompt text the daemon injects into agent sessions / actions.
+ *
+ * `general` is appended to the system prompt of every agent session. The rest
+ * are per-action prompts; an action's prompt is used only once that action
+ * exists in the daemon (several actions are not built yet — the field is stored
+ * and editable so the wiring is ready when the action lands).
+ */
+export interface PromptsConfig {
+    /** Appended to the system prompt of every agent session in this daemon. */
+    general: string;
+    /** Custom prompt for the code-review action. */
+    codeReview: string;
+    /** Custom prompt for the create-PR action. */
+    createPr: string;
+    /** Custom prompt for the fix-errors action. */
+    fixErrors: string;
+    /** Custom prompt for the resolve-merge-conflicts action. */
+    resolveMergeConflicts: string;
+    /** Custom prompt for the branch-naming / rename-branch action. */
+    renameBranch: string;
+}
+/**
+ * Git lifecycle behavior for workspaces.
+ *
+ * NOTE: `deleteBranchOnArchive` and `archiveOnMerge` presuppose an archive/merge
+ * lifecycle the daemon does not have yet, and deleting a branch conflicts with
+ * the standing invariant that `workspace.delete` never touches the branch. They
+ * are persisted and editable, but inert until that lifecycle is designed.
+ */
+export interface GitConfig {
+    /** (Reserved) Delete the workspace branch when a workspace is archived. */
+    deleteBranchOnArchive: boolean;
+    /** (Reserved) Archive a workspace automatically when its PR merges. */
+    archiveOnMerge: boolean;
+    /** Configure the upstream remote on first push (`git push -u`). */
+    worktreePushAutoSetupRemote: boolean;
+    /** How branch-name prefixes are generated. */
+    branchPrefixType: BranchPrefixType;
+    /** Literal prefix used when `branchPrefixType` is "custom" (e.g. `feature/`). */
+    branchPrefix: string;
+}
+/** The full daemon-owned app configuration. */
+export interface AppConfig {
+    prompts: PromptsConfig;
+    git: GitConfig;
+}
+/**
+ * Replace the daemon's app config wholesale (last-write-wins). The daemon
+ * validates/clamps every field, persists, then broadcasts a fresh
+ * `settings.result` so all clients converge.
+ */
+export interface ConfigSetPayload {
+    config: AppConfig;
+}
+export interface WorkspaceListResultPayload {
+    workspaces: WorkspaceSummary[];
+}
+export interface WorkspaceCreatedPayload {
+    ws: string;
+    name: string;
+    branch: string;
+    /** Present as `"chat"` for a repo-less chat workspace; else worktree. */
+    kind?: "worktree" | "chat";
+}
+/** A workspace's sidebar label changed (e.g. chat auto-title). */
+export interface WorkspaceRenamedPayload {
+    ws: string;
+    name: string;
+}
+export interface EventAssistantMessagePayload {
+    ws: string;
+    text: string;
+}
+export interface EventToolUsePayload {
+    ws: string;
+    tool: string;
+    inputSummary: string;
+}
+export interface EventPermissionRequestPayload {
+    ws: string;
+    requestId: string;
+    tool: string;
+    inputSummary: string;
+}
+/**
+ * A previously-broadcast permission request was resolved without the client
+ * answering it — a new "allow all" rule retroactively covered it — so clients
+ * collapse its card. Emitted by the retroactive-release sweep (see
+ * ClaudeAgent.releaseCoveredPending).
+ */
+export interface EventPermissionResolvedPayload {
+    ws: string;
+    requestId: string;
+    decision: "allow" | "deny";
+}
+/**
+ * The model asked one or more clarifying questions via `AskUserQuestion`. The
+ * client renders an interactive card and replies with `question.respond`
+ * carrying the picked option label(s). Unlike a permission (allow/deny), the
+ * chosen answers are fed back to the model as the tool's result.
+ */
+export interface EventAskQuestionPayload {
+    ws: string;
+    requestId: string;
+    questions: AgentQuestion[];
+}
+export interface EventSessionPayload {
+    ws: string;
+    sessionId: string;
+    status: WorkspaceStatus;
+}
+export interface EventAgentDonePayload {
+    ws: string;
+    summary?: string;
+    /**
+     * Pre-formatted token/cost readout for the turn, e.g. "12.3k in · 1.1k out ·
+     * $0.04". The daemon formats it once (see usage.ts) so the live "✓ done" line
+     * and the replayed transcript entry stay identical across clients. Absent when
+     * the backend reported no usage.
+     */
+    usageText?: string;
+}
+/**
+ * A plan/session usage limit was hit in a workspace. Clients surface this as a
+ * card offering to schedule a one-shot restart job at `resetAt` (epoch ms, when
+ * the notice carried a reset time). Distinct from a transient 429 (which stays a
+ * plain `error`).
+ */
+export interface EventSessionLimitPayload {
+    ws: string;
+    message: string;
+    resetAt?: number;
+}
+export interface TerminalDataPayload {
+    ws: string;
+    data: string;
+}
+/** Retained scrollback (may be empty if no terminal has been started). */
+export interface TerminalSnapshotResultPayload {
+    ws: string;
+    data: string;
+}
+/**
+ * A TCP port a worktree's process tree is listening on — discovered by the
+ * daemon (via `lsof`, correlated to a worktree by the owning process's `cwd`).
+ * `addr` is the raw bind address lsof reported (`127.0.0.1`, `*`, `[::1]`, …);
+ * the daemon always dials `127.0.0.1:port` regardless, so an all-interfaces bind
+ * is still reachable.
+ */
+export interface ForwardPort {
+    ws: string;
+    port: number;
+    addr: string;
+}
+/** Ask for the current worktree-owned listening ports (reply: forward.available). */
+export interface ForwardListPayload {
+}
+/** The current set of worktree-owned listening ports. Broadcast on every change. */
+export interface ForwardAvailablePayload {
+    ports: ForwardPort[];
+}
+/**
+ * Open a forwarded TCP stream: the client just accepted a local connection on
+ * its loopback listener and wants it bridged to `127.0.0.1:port` on the daemon.
+ * `streamId` is a fresh client-minted id that keys every later frame for this
+ * connection. The daemon refuses (immediate `forward.close` with `error`) unless
+ * `port` is currently in the worktree-owned set — you cannot reach arbitrary
+ * loopback ports on the daemon box.
+ */
+export interface ForwardOpenPayload {
+    ws: string;
+    streamId: string;
+    port: number;
+}
+/**
+ * One chunk of forwarded bytes, base64-encoded. BIDIRECTIONAL: client→daemon
+ * carries browser→server bytes; daemon→client carries the server's reply. Keyed
+ * by `streamId`.
+ */
+export interface ForwardDataPayload {
+    streamId: string;
+    data: string;
+}
+/**
+ * Tear down a forwarded stream. BIDIRECTIONAL: either side closes its end.
+ * `error` is set when the daemon refuses or aborts the stream (an unowned port,
+ * a dial failure, or the target hung up unexpectedly).
+ */
+export interface ForwardClosePayload {
+    streamId: string;
+    error?: string;
+}
+export interface GitStatusResultPayload {
+    ws: string;
+    branch: string;
+    baseBranch: string;
+    /** Commits on the workspace branch that the base doesn't have. */
+    ahead: number;
+    /** Commits on the base that the workspace branch doesn't have. */
+    behind: number;
+    /** Whether the branch has an `origin/<branch>` remote-tracking ref yet. */
+    hasRemote: boolean;
+    /** Commits on HEAD not yet on the remote branch (all of them before first push). */
+    unpushed: number;
+    /** A merge is in progress (MERGE_HEAD present) — the conflict flow is active. */
+    merging: boolean;
+    /**
+     * An open pull request already exists for this branch (via `gh`). Clients hide
+     * "Create PR" when true and gate "Merge"/"Resolve" on it. Always false for a
+     * branch with no remote — a PR can't exist before the first push.
+     */
+    hasPr: boolean;
+    /**
+     * This branch's pull request has been merged on the remote (via `gh`). Backs
+     * the "Archive" affordance once the PR lands. Mutually exclusive with `hasPr`.
+     */
+    prMerged: boolean;
+    /**
+     * The branch's PR number, when one exists (open, merged, or closed). Clients
+     * render it as a `#<n>` link to `prUrl`. Absent for a branch with no PR.
+     */
+    prNumber?: number;
+    /** The branch's PR web URL, paired with `prNumber`. Absent when there's no PR. */
+    prUrl?: string;
+    /**
+     * Reconciling the base into this branch would conflict — a `git merge-tree`
+     * prediction that never touches the worktree. Backs the "Resolve" button;
+     * false whenever the branch is not behind the base.
+     */
+    conflictsWithBase: boolean;
+    /** Worktree-relative paths with merge conflicts (unmerged), sorted. */
+    conflicted: string[];
+    /** Worktree-relative paths with uncommitted changes (porcelain). */
+    changed: string[];
+    /** Total lines added vs the base branch (committed + uncommitted). */
+    added: number;
+    /** Total lines removed vs the base branch. */
+    removed: number;
+}
+/** Outcome of a git.commit / git.push / git.resolve / git.merge / pr.create / pr.merge / issue.create request. */
+export interface GitResultPayload {
+    ws: string;
+    op: "commit" | "push" | "pr" | "pr_merge" | "resolve" | "merge" | "issue";
+    ok: boolean;
+    /** Human-readable success detail or failure reason. */
+    message: string;
+    /** PR URL when op === "pr", or issue URL when op === "issue", and ok. */
+    url?: string;
+}
+/** Role of a persisted transcript entry — mirrors the client's ChatRole. */
+export type ChatEntryRole = "user" | "assistant" | "tool" | "permission" | "question" | "limit" | "system";
+/**
+ * One durable line in a workspace's transcript. The daemon appends these to a
+ * per-workspace running log as prompts and events flow, so the whole
+ * conversation can be replayed on demand (chat.history).
+ */
+export interface ChatEntry {
+    ts: number;
+    role: ChatEntryRole;
+    text: string;
+    requestId?: string;
+    tool?: string;
+    resolved?: "allow" | "deny";
+    questions?: AgentQuestion[];
+    answers?: QuestionAnswers;
+    response?: string;
+    resetAt?: number;
+    /**
+     * user-only: metadata for files attached to this prompt. Only `name` and
+     * `mediaType` are persisted — never the bytes — so the transcript can render
+     * an "📎 name" chip on replay without carrying the payload in the log.
+     */
+    attachments?: ChatAttachmentMeta[];
+}
+/** Lightweight attachment descriptor persisted in the transcript (no bytes). */
+export interface ChatAttachmentMeta {
+    name: string;
+    mediaType: string;
+}
+export interface ChatHistoryResultPayload {
+    ws: string;
+    entries: ChatEntry[];
+}
+export interface DiffHunk {
+    header: string;
+    lines: string[];
+}
+export interface DiffFile {
+    path: string;
+    hunks: DiffHunk[];
+}
+export interface DiffResultPayload {
+    ws: string;
+    files: DiffFile[];
+}
+/** Flat, sorted list of worktree-relative file paths (the full codebase). */
+export interface TreeResultPayload {
+    ws: string;
+    files: string[];
+}
+/** One file's contents for the in-app viewer. */
+export interface FileResultPayload {
+    ws: string;
+    path: string;
+    content: string;
+    truncated: boolean;
+    binary: boolean;
+}
+/** Acknowledges a successful in-app editor save (file.set). */
+export interface FileSavedPayload {
+    ws: string;
+    path: string;
+    bytes: number;
+}
+export interface GithubStatusResultPayload {
+    available: boolean;
+    authenticated: boolean;
+    user?: string;
+}
+export interface GithubRepo {
+    fullName: string;
+    name: string;
+    owner: string;
+    description: string;
+    isPrivate: boolean;
+    defaultBranch: string;
+    url: string;
+}
+export interface GithubReposResultPayload {
+    repos: GithubRepo[];
+}
+export interface PongPayload {
+}
+/** Client → daemon: announce this device's public key to establish E2E. */
+export interface HelloPayload {
+    /** base64 of the device's X25519 public key. */
+    pub: string;
+    /** Optional human label for the paired-devices record. */
+    label?: string;
+}
+/** Daemon → client: handshake ack carrying the daemon's public key. */
+export interface HelloOkPayload {
+    /** base64 of the daemon's public key (empty when E2E is off). */
+    pub: string;
+    /** Whether payloads on this socket are now sealed. */
+    sealed: boolean;
+}
+/** Client → daemon: ask for the daemon's public key (to build a pairing QR). */
+export interface PairInfoPayload {
+}
+/** Daemon → client: the daemon's public key, or empty when E2E is off. */
+export interface PairInfoResultPayload {
+    pub: string;
+}
+/** Client → daemon: ask for this daemon's identity (name, id, host, version). */
+export interface DaemonGetPayload {
+}
+/** Client → daemon: set this daemon's human name. Empty/blank is rejected. */
+export interface DaemonRenamePayload {
+    name: string;
+}
+/**
+ * Daemon → client: this daemon's identity. Pushed unsolicited right after a
+ * socket connects, returned for `daemon.get`, and broadcast after
+ * `daemon.rename`. A client connected to multiple daemons uses `daemonId` as the
+ * stable key and `name` as the label; older daemons never send this, so a client
+ * falls back to the connection's URL host as the name.
+ */
+export interface DaemonInfoPayload {
+    /** Stable per-daemon uuid, persisted in ~/.immediacy/daemon.json. */
+    daemonId: string;
+    /** Human name; defaults to the machine hostname on first run. */
+    name: string;
+    /** os.hostname() of the daemon's machine (shown as a subtitle / default name). */
+    hostname: string;
+    /** Daemon package version (VERSION file), for display / diagnostics. */
+    version: string;
+    /** The PROTOCOL_VERSION this daemon speaks, for future skew detection. */
+    protocolVersion: number;
+}
+export interface ErrorPayload {
+    code: string;
+    message: string;
+    ws?: string;
+}
+export interface EchoResultPayload {
+    text: string;
+}
+/**
+ * A time-based trigger. `cron` is a croner pattern (standard 5-field cron, plus
+ * seconds if 6 fields); e.g. "0 9 * * *" = 09:00 daily. If the daemon was down
+ * at fire time the run is simply missed (no catch-up) — next occurrence fires
+ * normally.
+ */
+export interface ScheduleTrigger {
+    kind: "schedule";
+    cron: string;
+    /** IANA timezone (e.g. "America/New_York"); daemon-local zone if omitted. */
+    timezone?: string;
+}
+/** Identifiable prior actions a reactive trigger can wait behind. */
+export type JobSystemEvent = "agent.done" | "pr.created" | "commit" | "push" | "workspace.created";
+/**
+ * A reactive trigger: run `delayMinutes` after `event` fires. Optionally scoped
+ * to a single workspace (`ws`); otherwise any workspace's event arms it.
+ */
+export interface AfterTrigger {
+    kind: "after";
+    event: JobSystemEvent;
+    delayMinutes: number;
+    ws?: string;
+}
+export type JobTrigger = ScheduleTrigger | AfterTrigger;
+/** Run the job's prompt inside an existing workspace. */
+export interface WorkspaceTarget {
+    kind: "workspace";
+    /** For an `after` trigger, omit to run in the workspace the event fired in. */
+    ws?: string;
+}
+/**
+ * Spin up a throwaway workspace from a repo source, run the prompt, then tear it
+ * down — kept for review if the worktree ends dirty. The natural fit for a pure
+ * time-based job with no standing workspace to run in.
+ */
+export interface EphemeralTarget {
+    kind: "ephemeral";
+    repo?: string;
+    github?: {
+        fullName: string;
+        defaultBranch?: string;
+    };
+    branchBase?: string;
+    model?: string;
+    /** Base name for the throwaway workspace (defaults to the job name). */
+    name?: string;
+}
+export type JobTarget = WorkspaceTarget | EphemeralTarget;
+export type JobRunStatus = "started" | "ok" | "error" | "skipped";
+/** A persisted job definition (the daemon owns id/timestamps/bookkeeping). */
+export interface JobRecord {
+    id: string;
+    name: string;
+    /** The prompt handed to the agent when the job fires (supports `{{ctx}}`). */
+    prompt: string;
+    trigger: JobTrigger;
+    target: JobTarget;
+    enabled: boolean;
+    createdAt: number;
+    updatedAt: number;
+    lastRunAt?: number;
+    lastStatus?: JobRunStatus;
+    /** Next fire time for a schedule trigger (informational; undefined for after). */
+    nextRunAt?: number;
+}
+/** Client-supplied fields for job.create / job.update (server fills the rest). */
+export interface JobInput {
+    name: string;
+    prompt: string;
+    trigger: JobTrigger;
+    target: JobTarget;
+    enabled?: boolean;
+}
+/** One entry in a job's run history (append-only, like ChatEntry). */
+export interface JobRun {
+    id: string;
+    jobId: string;
+    jobName: string;
+    ts: number;
+    status: JobRunStatus;
+    /** Workspace the run executed in (resolved, incl. an ephemeral one). */
+    ws?: string;
+    trigger: "schedule" | "after" | "manual";
+    /** Human-readable detail / error / skip reason. */
+    message: string;
+}
+export interface JobListPayload {
+}
+export interface JobCreatePayload {
+    job: JobInput;
+}
+export interface JobUpdatePayload {
+    id: string;
+    patch: Partial<JobInput>;
+}
+export interface JobDeletePayload {
+    id: string;
+}
+/** Manually fire a job now, ignoring its trigger. */
+export interface JobRunPayload {
+    id: string;
+}
+export interface JobRunsPayload {
+    /** Restrict to one job's runs; all jobs if omitted. */
+    jobId?: string;
+    /** Cap on how many (most-recent-first); daemon default if omitted. */
+    limit?: number;
+}
+export interface JobListResultPayload {
+    jobs: JobRecord[];
+}
+export interface JobRunsResultPayload {
+    runs: JobRun[];
+}
+/** Broadcast when a job starts, finishes, errors, or is skipped. */
+export interface EventJobRunPayload {
+    run: JobRun;
+}
+/** Severity. `debug` is dropped unless LOG_DEBUG=1; warn/error always kept. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/** Which subsystem an entry came from — drives the client-side filter. */
+export type LogCategory = "conn" | "model" | "agent" | "forward" | "error" | "system";
+/**
+ * One structured log line. `seq` is a daemon-monotonic counter (resets to 0 on
+ * restart) and is the ordering + dedup key: clients render ascending `seq` and
+ * drop any live entry with `seq <=` the highest already shown. Never carries a
+ * secret (NaCl key, Access token, device pub) — enforced at the call site and
+ * by a unit test.
+ */
+export interface LogEntry {
+    seq: number;
+    ts: number;
+    level: LogLevel;
+    cat: LogCategory;
+    msg: string;
+    ws?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Client → daemon: fetch a tail of the ring buffer and subscribe this socket to
+ * live `log.event` pushes. `limit` defaults to 200 (clamped to the 500 ring).
+ * With `sinceSeq`, return only entries with `seq > sinceSeq` (used to backfill a
+ * gap after a reconnect). Re-sending re-subscribes idempotently.
+ */
+export interface LogTailPayload {
+    limit?: number;
+    sinceSeq?: number;
+}
+/** Daemon → client: the snapshot, ascending by `seq`. */
+export interface LogTailResultPayload {
+    entries: LogEntry[];
+}
+/** Daemon → client: one live entry, pushed only to subscribed sockets. */
+export interface LogEventPayload {
+    entry: LogEntry;
+}
+export interface PayloadMap {
+    "project.list": ProjectListPayload;
+    "project.create": ProjectCreatePayload;
+    "project.delete": ProjectDeletePayload;
+    "project.branches": ProjectBranchesPayload;
+    "project.pulls": ProjectPullsPayload;
+    "project.issues": ProjectIssuesPayload;
+    "issue.create": IssueCreatePayload;
+    "workspace.list": WorkspaceListPayload;
+    "workspace.create": WorkspaceCreatePayload;
+    "workspace.delete": WorkspaceDeletePayload;
+    "workspace.archive": WorkspaceArchivePayload;
+    "workspace.action": WorkspaceActionPayload;
+    "delete.batch": DeleteBatchPayload;
+    "prompt.send": PromptSendPayload;
+    "agent.stop": AgentStopPayload;
+    "permission.respond": PermissionRespondPayload;
+    "question.respond": QuestionRespondPayload;
+    "allowlist.list": AllowlistListPayload;
+    "allowlist.revoke": AllowlistRevokePayload;
+    "allowlist.clear": AllowlistClearPayload;
+    "terminal.input": TerminalInputPayload;
+    "terminal.resize": TerminalResizePayload;
+    "terminal.snapshot": TerminalSnapshotPayload;
+    "forward.list": ForwardListPayload;
+    "forward.open": ForwardOpenPayload;
+    "forward.data": ForwardDataPayload;
+    "forward.close": ForwardClosePayload;
+    "git.status": GitStatusPayload;
+    "git.commit": GitCommitPayload;
+    "git.push": GitPushPayload;
+    "git.resolve": GitResolvePayload;
+    "git.merge": GitMergePayload;
+    "pr.create": PrCreatePayload;
+    "pr.merge": PrMergePayload;
+    "workspace.open": WorkspaceOpenPayload;
+    "diff.get": DiffGetPayload;
+    "tree.get": TreeGetPayload;
+    "file.get": FileGetPayload;
+    "file.set": FileSetPayload;
+    "chat.history": ChatHistoryPayload;
+    "github.status": GithubStatusPayload;
+    "github.repos": GithubReposPayload;
+    "models.list": ModelsListPayload;
+    "job.list": JobListPayload;
+    "job.create": JobCreatePayload;
+    "job.update": JobUpdatePayload;
+    "job.delete": JobDeletePayload;
+    "job.run": JobRunPayload;
+    "job.runs": JobRunsPayload;
+    "settings.get": SettingsGetPayload;
+    "settings.set": SettingsSetPayload;
+    "config.set": ConfigSetPayload;
+    "log.tail": LogTailPayload;
+    hello: HelloPayload;
+    "pair.info": PairInfoPayload;
+    "daemon.get": DaemonGetPayload;
+    "daemon.rename": DaemonRenamePayload;
+    ping: PingPayload;
+    echo: EchoPayload;
+    "project.list.result": ProjectListResultPayload;
+    "project.branches.result": ProjectBranchesResultPayload;
+    "project.pulls.result": ProjectPullsResultPayload;
+    "project.issues.result": ProjectIssuesResultPayload;
+    "workspace.list.result": WorkspaceListResultPayload;
+    "workspace.created": WorkspaceCreatedPayload;
+    "workspace.renamed": WorkspaceRenamedPayload;
+    "delete.batch.result": DeleteBatchResultPayload;
+    "event.assistant_message": EventAssistantMessagePayload;
+    "event.tool_use": EventToolUsePayload;
+    "event.permission_request": EventPermissionRequestPayload;
+    "event.permission_resolved": EventPermissionResolvedPayload;
+    "event.ask_question": EventAskQuestionPayload;
+    "event.session": EventSessionPayload;
+    "event.agent_done": EventAgentDonePayload;
+    "event.session_limit": EventSessionLimitPayload;
+    "terminal.data": TerminalDataPayload;
+    "terminal.snapshot.result": TerminalSnapshotResultPayload;
+    "forward.available": ForwardAvailablePayload;
+    "git.status.result": GitStatusResultPayload;
+    "git.result": GitResultPayload;
+    "diff.result": DiffResultPayload;
+    "tree.result": TreeResultPayload;
+    "file.result": FileResultPayload;
+    "file.saved": FileSavedPayload;
+    "chat.history.result": ChatHistoryResultPayload;
+    "github.status.result": GithubStatusResultPayload;
+    "github.repos.result": GithubReposResultPayload;
+    "models.list.result": ModelsListResultPayload;
+    "job.list.result": JobListResultPayload;
+    "job.runs.result": JobRunsResultPayload;
+    "event.job_run": EventJobRunPayload;
+    "settings.result": SettingsResultPayload;
+    "allowlist.result": AllowlistResultPayload;
+    "log.tail.result": LogTailResultPayload;
+    "log.event": LogEventPayload;
+    "hello.ok": HelloOkPayload;
+    "pair.info.result": PairInfoResultPayload;
+    "daemon.info": DaemonInfoPayload;
+    pong: PongPayload;
+    error: ErrorPayload;
+    "echo.result": EchoResultPayload;
+}
+export type PayloadFor<T extends MessageType> = T extends keyof PayloadMap ? PayloadMap[T] : never;