@nuvin/session 0.1.0-rc.10

package/dist/protocol/types.d.ts

@@ -0,0 +1,971 @@
+import type { AgentMetricsSnapshot } from "@nuvin/agent-core/agent";
+import type { AgentEvent, AgentInput, AskUserAnswers, AskUserQuestionRequest, JsonObject, JsonValue } from "@nuvin/agent-core/shared";
+import type { ApprovalQueueState } from "../state/approvals.ts";
+import type { MessageState, ToolMessageStatus } from "../state/messages.ts";
+import type { DataRpcError, DataRpcMethod } from "./data-rpc.ts";
+/** Delegated child-agent context, mirrored from the agent channel. */
+export type WireDelegationScope = {
+    agentId: string;
+    parentToolCallId: string;
+};
+/** A tool call wants a path outside allowedDirs; the user may grant a dir. */
+export type DirAccessRequest = {
+    /** Absolute resolved path the tool asked for. */
+    requestedPath: string;
+    /** Default grant offered to the user (parent dir for file paths). */
+    proposedDir: string;
+};
+/** Wire-safe pending approval: IDs and display data only — no resolve fn. */
+export type ApprovalDescriptor = {
+    agentId: string;
+    /** Present when this approval is a directory-access grant prompt. */
+    dirAccess?: DirAccessRequest;
+    input?: JsonObject;
+    nickname?: string;
+    parentToolCallId?: string;
+    summary: string;
+    toolCallId: string;
+    toolName: string;
+};
+/** Wire-safe pending question. */
+export type QuestionDescriptor = {
+    questionId: string;
+    request: AskUserQuestionRequest;
+};
+/** Display metadata replicated to clients alongside session state. */
+export type SessionMeta = {
+    approvalMode: string;
+    /**
+     * Total context-window token budget for the active model, when known. Absent
+     * when no provider/model is configured or the model's limit is unknown
+     * (spec §4.3). The TUI uses it to render the context gauge.
+     */
+    contextWindowLimit?: number;
+    cwd: string;
+    modelName: string;
+    /** Active main-agent persona id (spec §4.3); `"default"` for the built-in coordinator. */
+    persona: string;
+    /**
+     * Active config profile the daemon runtime resolves config/agents/workspaces
+     * under (the `profiles.yaml` active profile). Display-only — clients render it
+     * as a header indicator. Omitted for the built-in `"default"` profile so the
+     * common case carries nothing on the wire.
+     */
+    profile?: string;
+    /**
+     * Resolved workspace name for this session (spec §7 — fixed at session
+     * creation). The session's active provider/model are fully determined by this
+     * workspace. Absent on legacy/host-less seeds that did not resolve one.
+     */
+    workspace?: string;
+    /**
+     * Current human-readable session topic; absent until the first user message
+     * or an UpdateTopic call sets it.
+     */
+    topic?: string;
+    /**
+     * Active provider reasoning (thinking) level (LOW/MEDIUM/HIGH), display-only.
+     * Absent when thinking is OFF/unset so the common case carries nothing on the
+     * wire. Clients render it as a suffix to the model name.
+     */
+    thinking?: string;
+};
+/**
+ * Wire-safe descriptor for a server-executed slash command. The daemon sends
+ * these in the welcome frame (spec §4.1); in-process they ride the attach
+ * snapshot. The Composer merges these with client-local command names for
+ * autocomplete. No execution logic crosses the wire — only display metadata.
+ */
+export type SlashCommandDescriptor = {
+    name: string;
+    description: string;
+    argumentHint?: string;
+    /**
+     * True for custom (markdown-defined) commands. These are the ONLY server
+     * commands the `commandsEnabled.<name>` toggle affects — the runtime's
+     * rebuild filters custom commands only, builtins (model/mcp/reset/…) are
+     * never dropped — so config panels must render builtins read-only.
+     */
+    custom?: boolean;
+};
+/**
+ * Raw model-completion data for the `/model` autocomplete popup, returned by
+ * the `complete-models` command (spec §6). The daemon gathers it from its
+ * runtime (authenticated providers + each provider's live model list + recent
+ * selections); the client builds the grouped ComboBox items. JSON-safe by rule
+ * — the round-trip test guards it.
+ */
+export type ModelCompletion = {
+    /** Authenticated providers, in registration order. */
+    providers: string[];
+    /** Per-provider model lists, keyed by provider. */
+    perProvider: Record<string, {
+        id: string;
+        name?: string;
+    }[]>;
+    /** Recently selected models (most recent first), for the "Recent" group. */
+    recentModels: {
+        provider: string;
+        model: string;
+    }[];
+};
+/**
+ * The replicated session state. Everything here survives JSON round-trip.
+ * The server holds exactly this plus private side tables (resolvers, queue
+ * texts, abort controller) that never cross the wire.
+ */
+export type SessionViewState = {
+    approval: ApprovalQueueState<ApprovalDescriptor>;
+    /**
+     * Active MCP OAuth login flow (spec §10/§12), or null when no login is in
+     * flight. Set/cleared by `auth-flow` events; the client renders McpAuthModal
+     * from it. NOT part of the message transcript.
+     */
+    authFlow: McpAuthFlowState | null;
+    busy: boolean;
+    /** Authoritative MCP catalog and operation state for the attached session. */
+    mcp: McpViewState;
+    messages: MessageState;
+    meta: SessionMeta;
+    /**
+     * Latest replicated agent metrics (token/usage counters), or null before the
+     * first `metrics` event (spec §4.3). The TUI renders this in the status
+     * footer; it is NOT part of the message transcript.
+     */
+    metrics: AgentMetricsSnapshot | null;
+    queuedCount: number;
+    /**
+     * Messages waiting in the auto-send queue while a turn runs, in send order.
+     * Reduced from `turn-status.queued`; UI-only, never agent context. `[]` when
+     * nothing is queued.
+     */
+    queued: QueuedMessageView[];
+    /**
+     * Reduced live summaries of background workflow runs, keyed by runId (spec
+     * §8.2/§8.3). Folded from `workflow-progress` events; UI-only, NEVER part of
+     * the message transcript or agent context. `{}` until the first run emits.
+     */
+    workflows: Record<string, WorkflowViewState>;
+    question: {
+        active: QuestionDescriptor | null;
+    };
+};
+export type SessionSnapshot = {
+    seq: number;
+    state: SessionViewState;
+    /**
+     * Descriptors for server-executed slash commands, surfaced to the client for
+     * Composer autocomplete. In-process this is the stand-in for the daemon's
+     * `welcome.serverCommands` (spec §4.1). Empty when the host registers none.
+     */
+    serverCommands: SlashCommandDescriptor[];
+};
+/**
+ * Why an approval settled without (or with) a human decision.
+ * "client": a connected client decided via decide-approval.
+ * "abort": the turn ended (user abort, error, or session close) and pending
+ * approvals were flushed as rejected without a decision.
+ */
+export type ApprovalSettledBy = "abort" | "client";
+/**
+ * Wire-safe MCP OAuth login flow state (spec §10/§12). The daemon drives the
+ * flow and publishes each state change as an `auth-flow` event; the client
+ * renders the URL/status and opens the URL itself. The server-side cancel
+ * handle never crosses the wire — clients abort via the `cancel-auth-flow`
+ * command. `null` clears the modal (login completed, errored, or cancelled).
+ */
+export type McpAuthFlowState = {
+    serverName: string;
+    status: string;
+    /** Authorization URL the client opens / displays. Absent before the redirect. */
+    url?: string;
+} | null;
+/** Coarse per-step status surfaced in the titled tree (§8.3). */
+export type WorkflowNodeWireStatus = "running" | "done" | "failed" | "skipped" | "stopped";
+/** One node in the coarse titled tree (phase → titled steps). No transcript. */
+export type WorkflowStatusNode = {
+    title: string;
+    status?: WorkflowNodeWireStatus;
+    children?: WorkflowStatusNode[];
+};
+/**
+ * The reduced, UI-facing summary of one run (§8.3). The reducer folds each
+ * `WorkflowProgressDelta` into this copy-on-write. It is the SAME model
+ * `WorkflowStatus` reads — titles/phases/statuses/counts/tokens only, NEVER
+ * prompts, tool-calls, agent messages, or node outputs.
+ */
+export type WorkflowViewState = {
+    runId: string;
+    status: "running" | "completed" | "failed" | "stopped";
+    /** Phase of the most recently started node, for a one-line live header. */
+    currentPhase?: string;
+    /** Phase → titled steps → latest status (§7.3 tree). */
+    tree: WorkflowStatusNode[];
+    /** Per-node-kind started counts (e.g. {agent: 3, transform: 1}). */
+    counts: Record<string, number>;
+    /** Summed `tokens` across finished nodes. */
+    tokens: number;
+    /** Highest `seq` folded in; lets clients dedupe replay vs live. */
+    lastSeq: number;
+    /**
+     * nodeId → [phase, title] index, so an incremental `node-finished` delta can
+     * re-locate its tree position (the tree keys on title, not nodeId). JSON-safe;
+     * UI-only; carries no transcript.
+     */
+    nodeKeys: Record<string, [string, string]>;
+};
+/**
+ * The wire form of one journal event (spec §7.2). Discriminated on `type`;
+ * mirrors @nuvin/workflow's JournalEvent member-for-member but with
+ * payload-bearing fields typed JsonValue (JSON-safe by rule — the json-safety
+ * test guards every member). Large prompts/outputs are NOT inlined: they ride
+ * as `promptRef`/`outputRef` strings the client fetches on demand.
+ */
+export type WorkflowProgressDelta = {
+    type: "run-started";
+    seq: number;
+    at: number;
+    runId: string;
+    file: string;
+    args: JsonValue;
+    irDigest: string;
+} | {
+    type: "node-started";
+    seq: number;
+    at: number;
+    nodeId: string;
+    kind: string;
+    phase?: string;
+    title?: string;
+    instanceKey?: string;
+    roundKey?: string;
+    inputsDigest: string;
+} | {
+    type: "agent-prompt";
+    seq: number;
+    at: number;
+    nodeId: string;
+    promptRef: string;
+} | {
+    type: "agent-step";
+    seq: number;
+    at: number;
+    nodeId: string;
+    kind: "model_request" | "tool_call" | "tool_result" | "assistant_message";
+    detail?: JsonValue;
+} | {
+    type: "agent-output";
+    seq: number;
+    at: number;
+    nodeId: string;
+    outputRef: string;
+    model?: string;
+    tokens?: number;
+} | {
+    type: "fanout-expanded";
+    seq: number;
+    at: number;
+    nodeId: string;
+    n: number;
+    keys: string[];
+} | {
+    type: "gate-decided";
+    seq: number;
+    at: number;
+    nodeId: string;
+    branch: string;
+} | {
+    type: "loop-round";
+    seq: number;
+    at: number;
+    nodeId: string;
+    round: number;
+    until: boolean;
+} | {
+    type: "node-finished";
+    seq: number;
+    at: number;
+    nodeId: string;
+    status: "ran" | "replayed" | "skipped" | "retried" | "fallback" | "failed" | "aborted";
+    outputDigest: string;
+    instanceKey?: string;
+    roundKey?: string;
+    durationMs?: number;
+    tokens?: number;
+} | {
+    type: "run-finished";
+    seq: number;
+    at: number;
+    status: "completed" | "failed" | "stopped";
+    summary?: JsonValue;
+};
+/**
+ * A message submitted during an active turn and waiting in the controller's
+ * auto-send queue (spec: removable-queued-messages). `id` is a controller-local
+ * monotonic handle used to cancel a specific item via the `dequeue` command.
+ */
+export type QueuedMessageView = {
+    id: string;
+    displayText: string;
+    attachmentLabels?: string[];
+};
+export type ServerEventBody = {
+    type: "agent-event";
+    event: AgentEvent;
+    scope?: WireDelegationScope;
+    /**
+     * Set on `tool_call` events to carry the initial status decided by the
+     * controller. Auto-approved tools arrive as ONE event with
+     * `toolStatus: "approved"` and never produce approval-requested
+     * (anti-flash rule, spec §4.5).
+     */
+    toolStatus?: ToolMessageStatus;
+} | {
+    type: "user-message";
+    text: string;
+    attachmentLabels?: string[];
+} | {
+    type: "approval-requested";
+    approval: ApprovalDescriptor;
+} | {
+    type: "approval-settled";
+    by: ApprovalSettledBy;
+    status: "approved" | "rejected";
+    toolCallId: string;
+} | {
+    type: "question-asked";
+    question: QuestionDescriptor;
+} | {
+    type: "question-settled";
+    questionId: string;
+} | {
+    type: "turn-status";
+    busy: boolean;
+    queuedCount: number;
+    queued?: QueuedMessageView[];
+} | {
+    type: "info";
+    message: string;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "session-meta";
+    meta: SessionMeta;
+} | {
+    /**
+     * Live agent metrics (token/usage counters), throttled to ~1/s during a
+     * turn and flushed once when the turn ends (spec §4.3). The snapshot is
+     * the JSON-safe AgentMetricsSnapshot from @nuvin/agent-core; AgentEvent's
+     * wire-frozen rule applies here too — changes require a PROTOCOL_VERSION
+     * bump enforced by the json-safety test.
+     */
+    type: "metrics";
+    snapshot: AgentMetricsSnapshot;
+} | {
+    /**
+     * MCP OAuth login flow update (spec §10/§12). Carries the wire-safe
+     * `McpAuthFlowState`; the client renders `McpAuthModal` from it and opens
+     * the URL client-side. The host emits these from its `McpAuthController`
+     * subscription. JSON-safe by rule (json-safety test covers it).
+     */
+    type: "auth-flow";
+    flow: McpAuthFlowState;
+} | {
+    type: "mcp-state";
+    state: McpViewState;
+} | {
+    /**
+     * UI progress for a background workflow run (spec §8.2). emit-only — the
+     * reducer folds `delta` into `state.workflows[runId]`; it NEVER calls
+     * submit and never touches agent messages. JSON-safe by rule (json-safety
+     * test covers it). `delta` is one journal event minus offloaded payloads.
+     */
+    type: "workflow-progress";
+    runId: string;
+    delta: WorkflowProgressDelta;
+} | {
+    type: "state-reset";
+    state: SessionViewState;
+};
+export type ServerEvent = ServerEventBody & {
+    /** Epoch ms assigned by the controller; reducers use this as "now". */
+    at: number;
+    /** Monotonic per-session sequence number. */
+    seq: number;
+};
+/**
+ * One config write in a `set-config` batch. `key` is a dotted config path
+ * (e.g. `skillsEnabled.my-skill`); `scope` selects the target file
+ * (`global` ⇒ `~/.nuvin-code/config.yaml`, `local` ⇒ `cwd/.nuvin-code/config.yaml`).
+ * The host enforces a key allowlist before writing — a generic write RPC is a
+ * privilege-escalation surface, so `hooks.*`/`providers.*` are rejected.
+ */
+export type ConfigPatch = {
+    key: string;
+    value: JsonValue;
+    scope: "global" | "local";
+};
+/** One rejected/failed patch in a `set-config` batch (allowlist, validation, or write). */
+export type SetConfigFailure = {
+    key: string;
+    message: string;
+};
+/** Result of `set-config`: the patches that did NOT apply. Empty ⇒ all applied. */
+export type SetConfigResult = {
+    failures: SetConfigFailure[];
+};
+/** One entry in the Skills-tab catalog (incl. disabled skills). */
+export type SkillCatalogEntry = {
+    id: string;
+    name: string;
+    description: string;
+    scope: string;
+    path: string;
+    enabled: boolean;
+};
+/** Lazy-loaded detail for a single skill — the raw SKILL.md body. */
+export type SkillDetail = {
+    id: string;
+    instructions: string;
+};
+/**
+ * Lazy-loaded detail for a single slash command — the markdown body of a custom
+ * (markdown-defined) command. `content` is empty for builtins/client commands,
+ * which carry no markdown body (the Commands tab only fetches this for custom
+ * commands). Mirrors {@link SkillDetail}.
+ */
+export type CommandDetail = {
+    name: string;
+    content: string;
+};
+/** One entry in the Agents-tab catalog (incl. disabled agents). */
+export type AgentCatalogEntry = {
+    id: string;
+    name: string;
+    description: string;
+    model?: string;
+    source: string;
+    enabled: boolean;
+    tools: string[];
+};
+/** Lazy-loaded detail for a single agent — its system prompt + tools. */
+export type AgentDetail = {
+    id: string;
+    systemPrompt: string;
+    tools: string[];
+    model?: string;
+};
+/** One MCP tool row in the MCP-tab server detail. */
+export type McpToolInfo = {
+    name: string;
+    description?: string;
+    inputSchema?: JsonValue;
+    enabled: boolean;
+};
+export type McpAction = "enable" | "disable" | "reload" | "login";
+export type McpActionResult = {
+    outcome: "completed" | "cancelled";
+};
+export type McpPendingOperation = {
+    action: McpAction;
+    serverName: string;
+};
+export type McpOperationError = {
+    serverName: string;
+    message: string;
+};
+export type McpViewState = {
+    revision: number;
+    servers: McpServerInfo[];
+    pending: McpPendingOperation | null;
+    error: McpOperationError | null;
+};
+/** One MCP server row in the MCP-tab catalog, with live status + its tools. */
+export type McpServerInfo = {
+    name: string;
+    enabled: boolean;
+    /** Server definition default before an explicit Control Center override. */
+    defaultEnabled: boolean;
+    /** Explicit persisted override, when one exists. */
+    overrideEnabled?: boolean;
+    /** Non-secret credential mode used only to gate available UI actions. */
+    authMode: "oauth" | "static" | "none";
+    status: "connected" | "disabled" | "authRequired" | "error";
+    message?: string;
+    tools: McpToolInfo[];
+};
+export type ClientCommand = {
+    id: string;
+    type: "submit";
+    input: AgentInput;
+    displayText: string;
+    attachmentLabels?: string[];
+} | {
+    id: string;
+    type: "decide-approval";
+    toolCallId: string;
+    decision: "a" | "n" | "y";
+    comment?: string;
+    /** Dir-access approvals only: the user-edited grant directory. */
+    grantDir?: string;
+} | {
+    id: string;
+    type: "answer-question";
+    questionId: string;
+    answers: AskUserAnswers;
+} | {
+    id: string;
+    type: "abort";
+} | {
+    id: string;
+    type: "dequeue";
+    queuedId: string;
+} | {
+    id: string;
+    type: "slash-command";
+    raw: string;
+} | {
+    id: string;
+    type: "complete-path";
+    prefix: string;
+}
+/**
+ * Fetch the available models for the `/model` autocomplete popup (spec §6).
+ * The ack `result` is a {@link ModelCompletion}. Carries no payload — the
+ * daemon reads its own runtime config. Answered by the attached host; an
+ * empty completion is returned when no host is attached.
+ */
+ | {
+    id: string;
+    type: "complete-models";
+} | {
+    id: string;
+    type: "load-history";
+    historyId: string;
+}
+/**
+ * Abort the in-flight MCP OAuth login (spec §10). The daemon invokes the
+ * live cancel handle on its `McpAuthController`, which rejects the pending
+ * wait-for-callback and publishes a cleared `auth-flow` event. Carries no
+ * payload. Acked ok when a host is attached; unsupported otherwise.
+ */
+ | {
+    id: string;
+    type: "cancel-auth-flow";
+} | {
+    id: string;
+    type: "mcp-action";
+    action: McpAction;
+    serverName: string;
+}
+/**
+ * Fetch a paginated raw slice of a run's journal as wire deltas (spec §8.2,
+ * D7). Session-scoped — answered only after `attach`. `sinceSeq` is the first
+ * seq to include (default 0). The ack `result` is
+ * `{ events: WorkflowProgressDelta[]; nextSeq?: number }`; page size 500. The
+ * client renders the collapsible audit tree from these (rendering is
+ * client-side, mirroring the reducer).
+ */
+ | {
+    id: string;
+    type: "get-workflow-trace";
+    runId: string;
+    sinceSeq?: number;
+}
+/**
+ * Restricted config write (spec: Ctrl+P config panel §Writes). The host
+ * enforces a key allowlist, validates each value, writes per dotted key
+ * (granular conflict detection), and live-applies to the CALLING session
+ * only. The ack `result` is a {@link SetConfigResult} listing any failures.
+ * Session-scoped — answered only by an attached host; `unsupported` otherwise.
+ */
+ | {
+    id: string;
+    type: "set-config";
+    patches: ConfigPatch[];
+}
+/**
+ * List the full skill catalog (incl. disabled) for the Skills tab. The ack
+ * `result` is a {@link SkillCatalogEntry}[] from unfiltered discovery.
+ */
+ | {
+    id: string;
+    type: "list-skills";
+}
+/**
+ * Lazy-load one skill's SKILL.md body for the Skills-tab detail pane. The ack
+ * `result` is a {@link SkillDetail}.
+ */
+ | {
+    id: string;
+    type: "get-skill";
+    skillId: string;
+}
+/**
+ * List the full agent catalog (incl. disabled) for the Agents tab. The ack
+ * `result` is an {@link AgentCatalogEntry}[] from unfiltered discovery.
+ */
+ | {
+    id: string;
+    type: "list-agents";
+}
+/**
+ * Lazy-load one agent's system prompt + tools for the Agents-tab detail pane.
+ * The ack `result` is an {@link AgentDetail}.
+ */
+ | {
+    id: string;
+    type: "get-agent";
+    agentId: string;
+}
+/**
+ * Lazy-load one custom (markdown-defined) slash command's markdown body for
+ * the Commands-tab detail pane. The ack `result` is a {@link CommandDetail}.
+ * Builtins/client commands have no body — the panel only calls this for custom
+ * commands.
+ */
+ | {
+    id: string;
+    type: "get-command";
+    name: string;
+}
+/**
+ * List MCP servers with live status + per-server tools for the MCP tab. The
+ * ack `result` is a {@link McpServerInfo}[] (the only data that can't come
+ * from disk — tools require a live connection).
+ */
+ | {
+    id: string;
+    type: "list-mcp-servers";
+};
+export type CommandAck = {
+    type: "ack";
+    id: string;
+    ok: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+    /**
+     * Optional request/response payload (e.g. `complete-path` returns a string[]
+     * of completions). JSON-safe by rule; the round-trip test guards it.
+     */
+    result?: JsonValue;
+};
+/** Everything a server sends over a transport. */
+export type ServerFrame = ServerEvent | CommandAck | {
+    type: "snapshot";
+    snapshot: SessionSnapshot;
+};
+/** Session lifecycle state surfaced by list-sessions (spec §4.2). */
+export type SessionStatus = "awaiting-approval" | "busy" | "idle";
+/** Session metadata returned by list-sessions / create-session (spec §4.2). */
+export type SessionDescriptor = {
+    id: string;
+    name: string;
+    cwd: string;
+    /** Resolved workspace name for this session (spec §7). */
+    workspace?: string;
+    /** Resolved config profile for this session (spec §7). */
+    profile?: string;
+    model: string;
+    status: SessionStatus;
+    attachedClients: number;
+    /** Epoch ms. */
+    createdAt: number;
+    /** Epoch ms of the last ServerEvent this session emitted. */
+    lastActivityAt: number;
+    /** Current human-readable session topic; absent until set by the first user message or UpdateTopic. */
+    topic?: string;
+    /**
+     * First line of the most recent user message (trimmed, truncated), if any.
+     * Used as the dashboard title fallback when no topic is set yet (spec §4):
+     * topic → lastMessage → name. Absent when the session has no user turn.
+     */
+    lastMessage?: string;
+};
+/**
+ * The signed payload inside a relay grant (relay spec §7): a short-lived
+ * permission slip minted per client connection. Timestamps are epoch ms.
+ * The wire form is `base64url(JSON payload) + "." + base64url(signature)`;
+ * sign/verify live in the Node-only @nuvin/session/grant module — this type
+ * is here so browser-safe code can name the shape without touching crypto.
+ */
+export type GrantPayload = {
+    /** The grant is only valid for this daemon. */
+    daemonId: string;
+    /** Clerk user id of who is connecting (authz + audit). */
+    userId: string;
+    /** Unique per grant, for logging/audit. */
+    grantId: string;
+    /** Epoch ms. Must not be absurdly in the future (±5 min skew window). */
+    issuedAt: number;
+    /** Epoch ms. Gates ONLY the handshake — established sessions live on. */
+    expiresAt: number;
+};
+/**
+ * Server → daemon frames on the relay CONTROL WebSocket (relay spec §4/§8.2).
+ * This is the relay control plane, NOT the session protocol: these frames
+ * never ride a daemon session socket, are not part of DaemonClientMessage /
+ * DaemonServerMessage, and are NOT covered by the PROTOCOL_VERSION exact-match
+ * handshake (the control connection authenticates via device token instead).
+ * Shared here so @nuvin/server and @nuvin/daemon agree on the envelope shape
+ * (relay spec §5: the server depends on @nuvin/session for protocol types only).
+ */
+/** Methods the relay may RPC to a daemon over the control connection (spec §4.1).
+ *  Alias of the data-plane schema keys — params/results are typed once in
+ *  DataRpcSchema (data-rpc.ts) and shared by REST + relay RPC. */
+export type RelayRpcMethod = DataRpcMethod;
+export type RelayControlMessage = 
+/** Dial wss://{server}/tunnel/{channelId} now — a client is waiting (spec §9.1). */
+{
+    type: "open-channel";
+    channelId: string;
+}
+/** Registration revoked: close tunnels, drop control, clear local relay config (spec §8.2/§10). */
+ | {
+    type: "revoked";
+}
+/** Relay → daemon request/reply (spec §4.1). Correlated by `rpcId`. */
+ | {
+    type: "rpc";
+    rpcId: string;
+    method: RelayRpcMethod;
+    params: unknown;
+};
+/**
+ * Daemon → relay control frames (spec §4.1). The daemon pushes its live-session
+ * list (relay caches it for GET /api/daemons) and replies to relay RPCs.
+ */
+export type DaemonControlMessage = {
+    type: "sessions";
+    sessions: SessionDescriptor[];
+} | {
+    type: "rpc-result";
+    rpcId: string;
+    ok: true;
+    result: unknown;
+} | {
+    type: "rpc-result";
+    rpcId: string;
+    ok: false;
+    error: string | DataRpcError;
+};
+/**
+ * First frame on every daemon socket, client → daemon. The credential travels
+ * HERE and never in the URL (query strings leak into proxy logs — spec §4.1).
+ * Two credential variants (relay spec §8.3, ONE protocol bump):
+ * - `token`: the daemon's bearer token — UDS/TCP sockets only.
+ * - `grant`: an Ed25519-signed, short-lived permission slip minted by the
+ *   relay server — relay-sourced sockets only. Opaque to clients; verified on
+ *   the daemon (@nuvin/session/grant). The `?: never` markers make the two
+ *   variants mutually exclusive while keeping property access narrowable.
+ */
+export type HelloFrame = {
+    type: "hello";
+    protocolVersion: number;
+} & ({
+    token: string;
+    grant?: never;
+} | {
+    grant: string;
+    token?: never;
+});
+/**
+ * Successful handshake reply. Version policy is EXACT match on
+ * PROTOCOL_VERSION; serverCommands feed the Composer autocomplete (spec §4.1).
+ */
+export type WelcomeFrame = {
+    type: "welcome";
+    protocolVersion: number;
+    daemonVersion: string;
+    serverCommands: SlashCommandDescriptor[];
+};
+/** Handshake refusal; the daemon closes the socket after sending it. */
+export type RejectedFrame = {
+    type: "rejected";
+    reason: "auth" | "version";
+};
+/**
+ * A profile advertised by the daemon management DataRpc surface. Returned as
+ * a JSON-safe array by `list-profiles`.
+ * `active` ⇒ the daemon's currently-resolved active profile. Distinct from
+ * config's richer ProfileMetadata.
+ */
+export type ProfileSummary = {
+    name: string;
+    active: boolean;
+    description?: string;
+};
+export declare const PROVIDER_SURFACE_IDS: readonly ["anthropic-messages", "openai-chat-completions", "openai-responses", "openai-responses-ws"];
+export type ProviderSurfaceId = (typeof PROVIDER_SURFACE_IDS)[number];
+export type ProviderCredentialInput = {
+    type: "apiKey";
+    apiKey: string;
+    authScheme?: "bearer" | "x-api-key";
+    githubTokenKind?: "accessToken" | "copilotApiKey";
+} | {
+    type: "oauth";
+    access: string;
+    refresh: string;
+    expires?: number;
+    authScheme?: "bearer" | "x-api-key";
+};
+export type ProviderConfigSummary = {
+    id: string;
+    label: string;
+    surface: ProviderSurfaceId;
+    baseUrl?: string;
+    defaultModel?: string;
+    hasAuth: boolean;
+    isDefault: boolean;
+};
+/**
+ * A workspace as advertised to directory clients (spec §7). Carried as a
+ * JSON-safe array in the `list-workspaces` / `create-workspace` REST (DataRpc)
+ * results. Distinct from config's richer `WorkspaceMetadata`: this is the
+ * wire-facing projection.
+ */
+export type WorkspaceSummary = {
+    name: string;
+    root: string;
+    adhoc: boolean;
+    sessionCount: number;
+};
+export type WorkspaceConfigSummary = WorkspaceSummary & {
+    configuredProvider?: string;
+    effectiveProvider?: string;
+    toggles: Record<string, boolean>;
+};
+export type ConfigMutationResult<T> = {
+    ok: true;
+    value: T;
+    reloadWarnings?: Array<{
+        sessionId: string;
+        message: string;
+    }>;
+};
+/** Exceptional pre-attach operator commands (spec §4.2). */
+export type DaemonAdminCommand = 
+/** Start the daemon-hosted web UI on `port` (default 3000). */
+{
+    id: string;
+    type: "web-start";
+    port?: number;
+}
+/** Stop the daemon-hosted web UI. */
+ | {
+    id: string;
+    type: "web-stop";
+}
+/** Re-read daemon config and reload running sessions. */
+ | {
+    id: string;
+    type: "reload-config";
+};
+/** Pre-attach session management and operator commands (spec §4.2). */
+export type DaemonCommand = {
+    id: string;
+    type: "list-sessions";
+} | {
+    id: string;
+    type: "create-session";
+    name?: string;
+    cwd: string;
+    workspace?: string;
+    /**
+     * Client-driven config profile (e.g. the local CLI's `--profile`). The
+     * daemon stays profile-agnostic and CONSUMES this only at session
+     * creation: the per-session runtime resolves config/agents under it.
+     * Omitted ⇒ the daemon's `profiles.yaml` active profile.
+     */
+    profile?: string;
+}
+/**
+ * Switch-and-resume (spec §3/§7): rehydrate a COLD history id into a NEW live
+ * SessionController and reply with a `session-created` frame carrying the live
+ * descriptor. The cold transcript has no daemon-side cwd, so the caller
+ * supplies the `cwd` the rehydrated runtime runs in. IDEMPOTENT daemon-side:
+ * resuming an already-live id returns the existing live session (no duplicate).
+ */
+ | {
+    id: string;
+    type: "resume-session";
+    historyId: string;
+    cwd: string;
+    name?: string;
+    workspace?: string;
+    /** Client-driven config profile, consumed at session creation (see create-session). */
+    profile?: string;
+} | {
+    id: string;
+    type: "attach";
+    sessionId: string;
+    lastSeq?: number;
+} | {
+    id: string;
+    type: "kill-session";
+    sessionId: string;
+    delete?: boolean;
+} | DaemonAdminCommand;
+/**
+ * A cold/resumable session from the daemon's JSONL SessionStore (spec §8).
+ * Display-only metadata; resuming it sends a `load-history` command after
+ * attaching to a (new or existing) live session.
+ */
+export type HistorySummary = {
+    id: string;
+    title: string;
+    /** Epoch ms of the last write to the session dir. */
+    updatedAt: number;
+    parentSessionId?: string;
+    /** Owning workspace name — the group key for /history (spec §5.1). */
+    workspace: string;
+    /** Workspace root path, for clients with no local registry (web). */
+    workspaceRoot?: string;
+};
+/**
+ * A paginated slice of cold history (spec §4.3): the `list-history` RPC result,
+ * the `GET /api/daemons/:id/history` body, and the cloud `fetchHistory()` return.
+ * `nextCursor` is an OPAQUE token — present only when more pages remain (decision
+ * §10.2: cursor, not offset). `currentWorkspace` is echoed when the caller sent a
+ * cwd that resolved to a workspace.
+ */
+export type HistoryPage = {
+    sessions: HistorySummary[];
+    nextCursor?: string;
+    currentWorkspace?: string;
+};
+/** Reply to list-sessions; `id` echoes the command id. */
+export type SessionListFrame = {
+    type: "session-list";
+    id: string;
+    sessions: SessionDescriptor[];
+};
+/** Reply to create-session; `id` echoes the command id. */
+export type SessionCreatedFrame = {
+    type: "session-created";
+    id: string;
+    session: SessionDescriptor;
+};
+/**
+ * Reply to attach when lastSeq is still inside the ring buffer: every missed
+ * event in seq order (spec §4.6). The client reduces them exactly like live
+ * events; an empty list means nothing was missed. When the buffer no longer
+ * covers the gap the daemon answers with a snapshot frame instead.
+ */
+export type ReplayFrame = {
+    type: "replay";
+    events: ServerEvent[];
+};
+/** The daemon detached this client (e.g. the session was killed — spec §8). */
+export type DetachedFrame = {
+    type: "detached";
+    reason: string;
+};
+/** Everything a client may send over a daemon socket. */
+export type DaemonClientMessage = ClientCommand | DaemonCommand | HelloFrame;
+/** Everything a daemon may send over a socket. */
+export type DaemonServerMessage = DetachedFrame | RejectedFrame | ReplayFrame | ServerFrame | SessionCreatedFrame | SessionListFrame | WelcomeFrame;
+//# sourceMappingURL=types.d.ts.map