@north-light/cli 0.0.0 → 0.3.413

package/dist/api/dto/broker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The crtrd broker `error` control frame — `{ code, message, id? }`. `id` is a
+ * correlation token echoed only from the request that failed (a read-op /
+ * `dequeue`); absent on uncorrelated errors. There is NO `retryable` field.
+ */
+export interface BrokerErrorFrame {
+    type: 'error';
+    code: string;
+    message: string;
+    /** Correlation token, echoed from the failed request; absent on uncorrelated errors. */
+    id?: string;
+}
+/**
+ * The `welcome` frame's history/state snapshot, narrowed to what a relay consumer
+ * replays: the message history, the streaming flag, and the unrun queue. `M` is
+ * the message shape (pi's `AgentMessage` in a pi consumer; `unknown` by default).
+ *
+ * `queued` carries the same two arrays a live `queue_update` frame carries — the
+ * steer/follow-up texts accepted by the engine but not started yet. A relay that
+ * renders queued rows needs it to survive (re)attach: a message enqueued mid-turn
+ * is in NEITHER `messages` (it never ran) nor any later frame the consumer has
+ * already seen. Optional: a broker on an older runtime generation omits it, which
+ * a consumer reads as an empty queue.
+ */
+export interface BrokerWelcomeSnapshot<M = unknown> {
+    messages: M[];
+    /** Stable session-entry ids aligned 1:1 with `messages`. */
+    messageIds?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    messageVisibility: Array<'visible' | 'internal'>;
+    /** Presentation visibility of the run currently owned by the engine. */
+    turnVisibility: 'visible' | 'internal';
+    state?: {
+        isStreaming?: boolean;
+    };
+    queued?: {
+        steering?: string[];
+        followUp?: string[];
+    };
+}
+/**
+ * The crtrd broker `welcome` control frame — the history/resume catch-up snapshot
+ * delivered on (re)attach.
+ */
+export interface BrokerWelcomeFrame<M = unknown> {
+    type: 'welcome';
+    snapshot?: BrokerWelcomeSnapshot<M>;
+}
+/**
+ * The crtrd broker `node_named` control frame — the node's generated name at the
+ * instant crtrd committed it.
+ *
+ * A node names itself off its first real message: the naming extension asks a
+ * headless model for a handle, commits it through crtrd's guarded compare-and-set,
+ * and pushes this frame down the attach stream in the same callback. It is sent
+ * ONLY when that guarded commit APPLIED, so a name a human already set is never
+ * announced as generated.
+ *
+ * It exists because the name lands SECONDS AFTER the turn that triggered it — a
+ * consumer that settles its own display state on turn-end reads an unnamed node and
+ * has nothing left to re-read on. This frame is the push: `description` is the
+ * 3-8 word kebab-case handle, `title` the prose sentence a conversation list
+ * shows, `icon` the Nerd Font glyph the namer chose (empty when it chose none),
+ * and `editorLabel` crtrd's own rendered label for the node.
+ */
+export interface BrokerNodeNamedFrame {
+    type: 'node_named';
+    description: string;
+    title: string;
+    icon: string;
+    editorLabel: string;
+}
+/**
+ * The broker-control frames a relay consumer reads: `welcome`, `error`, and
+ * `node_named`. The broker interleaves others (display_*, ack, …)
+ * under non-colliding `type` discriminants; a relay mapper drops those through its
+ * `default` arm untyped, so they are not enumerated here.
+ */
+export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerErrorFrame | BrokerNodeNamedFrame;
+/**
+ * What the crtrd broker attach delivers to a relay consumer: the live engine
+ * event stream (`E` — pi's `AgentSessionEvent`, relayed verbatim) unioned with the
+ * broker's own control frames. Discriminants never collide: an `AgentSessionEvent`
+ * owns no `welcome` / `error` `type`.
+ */
+export type BrokerAttachFrame<E, M = unknown> = E | BrokerControlFrame<M>;

package/dist/api/dto/canvas.d.ts

@@ -0,0 +1,359 @@
+import type { Cursor, IsoTime, NodeIdDTO, NodeStatusDTO } from './common.js';
+import type { NodeFaultDTO, NodeSummaryDTO } from './nodes.js';
+/** `GET /v1/nodes` + `GET /v1/status` composed for the dashboard view. */
+export interface DashboardQuery {
+    /** Restrict to the subtree under this node. */
+    under?: NodeIdDTO;
+}
+export interface DashboardDTO {
+    nodes: NodeSummaryDTO[];
+    /** Node counts keyed by status. */
+    counts: Partial<Record<NodeStatusDTO, number>>;
+    generated_at: IsoTime;
+}
+/** A node needing attention (tickets across the canvas). Projected from the
+ *  `TicketEntry` reader — one entry per node with open human tickets. */
+export interface AttentionItemDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    cwd: string;
+    /** Number of open tickets on this node. */
+    count: number;
+    /** Open ticket titles for this node, newest first — one per counted ticket. */
+    subjects: string[];
+}
+/** `GET /v1/canvas/attention` result. */
+export interface AttentionDTO {
+    items: AttentionItemDTO[];
+}
+/** `POST /v1/canvas/attention/counts` request. Restrict the synchronous inbox
+ * scan to the nodes a viewer is actually rendering instead of enriching the
+ * entire canvas roster. */
+export interface AttentionCountsRequest {
+    node_ids: NodeIdDTO[];
+}
+/** `POST /v1/canvas/attention/counts` result, keyed by requested node id. */
+export interface AttentionCountsDTO {
+    counts: Record<NodeIdDTO, number>;
+}
+/** `POST /v1/canvas/history/search` body — the ranked/filtered search over the
+ *  per-cwd conversation corpus (inboxes and transcripts), backing `crtr canvas history search` (optional
+ *  query: ranked when present, recency browse when omitted). The CLI parses +
+ *  validates flags (`--type` set, `--since`/`--until` → epoch ms) and sends
+ *  this normalized query; the server runs `buildCorpus` + ranking + pagination
+ *  (closures like `loadBody` cannot cross the boundary, so the whole search
+ *  executes server-side). Sent as POST — the query carries arrays and
+ *  free-text that do not serialize cleanly as GET params. */
+export interface HistorySearchQuery {
+    /** Whitespace-separated terms, ranked; omit to browse by recency. */
+    query?: string;
+    cwd?: string;
+    all_cwds?: boolean;
+    under?: string;
+    /** Restrict to specific node ids. */
+    nodes?: string[];
+    /** Corpus types: inbox | transcript. */
+    types?: string[];
+    kinds?: string[];
+    statuses?: string[];
+    /** Lower bound on artifact timestamp (epoch ms), parsed CLI-side. */
+    since_ms?: number;
+    /** Upper bound on artifact timestamp (epoch ms), parsed CLI-side. */
+    until_ms?: number;
+    /** Inbound-message narrowing (transcript + inbox): what drove arrival. */
+    origins?: string[];
+    /** Transcript-message roles: user | assistant | toolResult. */
+    roles?: string[];
+    /** Case-insensitive substring against sender attribution. */
+    from?: string;
+    /** Weigh full body text in ranking (`--body`). */
+    weigh_body?: boolean;
+    /** relevance | recency | oldest — already resolved to the effective sort. */
+    sort?: string;
+    snippet_lines?: number;
+    full?: boolean;
+    limit?: number;
+    cursor?: Cursor;
+}
+/** `POST /v1/canvas/history/search` result. `hits` is heterogeneous by mode
+ *  (with/without a relevance score, snippet vs full body), so it stays a
+ *  loose object list — the CLI's renderer already treats hits as
+ *  `Record<string, unknown>[]`. The static `follow_up` line is appended
+ *  CLI-side. */
+export interface HistorySearchResultDTO {
+    hits: Record<string, unknown>[];
+    next_cursor: Cursor | null;
+    total: number;
+}
+/** `POST /v1/canvas/history/grep` body — the required-pattern line-hit search
+ *  over the per-cwd conversation corpus (inboxes and transcripts), backing `crtr canvas history grep`.
+ *  Shares scope/corpus filters with `HistorySearchQuery` but is a distinct
+ *  wire contract: `pattern` is mandatory (an ECMAScript regex) and there is no
+ *  ranking/snippet/full-body shape. */
+export interface HistoryGrepQuery {
+    /** Required ECMAScript regex, matched per body line (case-insensitive). */
+    pattern: string;
+    cwd?: string;
+    all_cwds?: boolean;
+    under?: string;
+    /** Restrict to specific node ids. */
+    nodes?: string[];
+    /** Corpus types: inbox | transcript. */
+    types?: string[];
+    kinds?: string[];
+    statuses?: string[];
+    /** Lower bound on artifact timestamp (epoch ms), parsed CLI-side. */
+    since_ms?: number;
+    /** Upper bound on artifact timestamp (epoch ms), parsed CLI-side. */
+    until_ms?: number;
+    /** Inbound-message narrowing (transcript + inbox): what drove arrival. */
+    origins?: string[];
+    /** Transcript-message roles: user | assistant | toolResult. */
+    roles?: string[];
+    /** Case-insensitive substring against sender attribution. */
+    from?: string;
+    limit?: number;
+    cursor?: Cursor;
+}
+/** `POST /v1/canvas/history/stats` body — the grouped-count projection over
+ *  the same corpus search and grep scan, backing `crtr canvas history stats`.
+ *  Shares every scope/corpus/message filter; carries no query, pattern, or
+ *  pagination because the result is an aggregate, not a hit list. */
+export interface HistoryStatsQuery {
+    /** origin | node | kind | day | type | role. Defaults to type. */
+    group_by?: string;
+    cwd?: string;
+    all_cwds?: boolean;
+    under?: string;
+    nodes?: string[];
+    types?: string[];
+    kinds?: string[];
+    statuses?: string[];
+    since_ms?: number;
+    until_ms?: number;
+    origins?: string[];
+    roles?: string[];
+    from?: string;
+}
+/** `POST /v1/canvas/history/stats` result — counts by the grouped dimension,
+ *  descending. `total` counts the artifacts that carried the dimension, so it
+ *  can be lower than the corpus size when grouping by one not every artifact
+ *  has (origin, role). */
+export interface HistoryStatsResultDTO {
+    group_by: string;
+    groups: Array<{
+        key: string;
+        count: number;
+    }>;
+    total: number;
+    /** Artifacts scanned before the grouping dimension was applied. */
+    scanned: number;
+}
+/** One matching body line from `crtr canvas history grep`. */
+export interface HistoryGrepHitDTO {
+    ref: string;
+    /** "name (id)". */
+    node: string;
+    ts: IsoTime;
+    line: number;
+    text: string;
+}
+/** `POST /v1/canvas/history/grep` result — a stable line-hit schema, distinct
+ *  from `HistorySearchResultDTO`'s heterogeneous ranked/browse shape. */
+export interface HistoryGrepResultDTO {
+    hits: HistoryGrepHitDTO[];
+    next_cursor: Cursor | null;
+    total: number;
+}
+/** `GET /v1/canvas/history/read` query — resolve one `<node-id>:inbox/<n>`,
+ *  `<node-id>:session` or `<node-id>:session/<n>` ref. */
+export interface HistoryReadQuery {
+    ref: string;
+    /** `rendered` (default) or `raw` — the verbatim bytes behind the ref: the
+     *  session file for a bare `session` ref, the one jsonl line for a message. */
+    format?: string;
+}
+/** `GET /v1/canvas/history/read` result — one hit's full body. */
+export interface HistoryReadResultDTO {
+    ref: string;
+    /** "name (id)". */
+    node: string;
+    /** inbox | transcript. */
+    source: string;
+    ts: IsoTime;
+    content: string;
+}
+/** One node row in the browser canvas roster (`GET /v1/canvas/snapshot`). A
+ *  richer projection than `NodeSummaryDTO`: it carries the enriched viewer
+ *  fields (`dashboardRowsAll` + `enrichRows`) the browser canvas renders —
+ *  attention counts, ctx tokens, streaming/hanging/viewed state, last activity. */
+export interface SnapshotNodeDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    /** Caller-supplied node title, kept separate from the enriched full label. */
+    title: string;
+    /** Caller-supplied node brief, or null when absent. */
+    description: string | null;
+    kind: string;
+    mode: string;
+    lifecycle?: string;
+    status: NodeStatusDTO;
+    cwd: string;
+    /** The profile this node runs under; null for a historical no-profile row.
+     *  Carried here because it is the only field that says WHOSE work a node is —
+     *  a snapshot consumer grouping nodes by agent has nothing else to key on. */
+    profile_id: string | null;
+    parent: NodeIdDTO | null;
+    created: IsoTime;
+    host_kind: string;
+    /** True when the node hosts an enterable broker (`host_kind === 'broker'`). */
+    enterable: boolean;
+    attention_count: number;
+    cycles?: number;
+    last_activity?: IsoTime;
+    ctx_tokens?: number;
+    streaming: boolean;
+    /** Number of active background bash jobs, reported only for a live broker. */
+    jobs_active: number;
+    /** Controller node this node is durably waiting for, or null. */
+    waiting_for: string | null;
+    /** The node's active fault projection (structurally a `Fault`), or null. Kept
+     *  as a loose object to keep this DTO free of a `core` type import. */
+    hanging: Record<string, unknown> | null;
+    viewed: boolean;
+    /** Basename of the node's final report, or null when it never pushed one.
+     *  Presence — not `status === 'done'` — is what distinguishes finished work
+     *  from clean parking. */
+    final_report: string | null;
+    finalized_at: IsoTime | null;
+}
+/** `GET /v1/canvas/snapshot` result — the machine-readable browser canvas
+ *  roster (`crtr canvas snapshot`). Distinct from the per-node `NodeSnapshotDTO`
+ *  (nodes.ts). `subscriptions` is the authoritative `subscribes_to` adjacency
+ *  map: each node id → its publisher/child node ids in edge order. */
+export interface SnapshotDTO {
+    generated_at: IsoTime;
+    nodes: SnapshotNodeDTO[];
+    subscriptions: Record<string, NodeIdDTO[]>;
+}
+/** One node row in the lean roster (`GET /v1/canvas/roster`). Carries only
+ *  stored node fields, without a process-liveness probe. `attention_count`/`last_activity`/`ctx_tokens`/
+ *  `streaming`/`hanging`/`viewed` stay on `SnapshotNodeDTO`; a roster consumer
+ *  that needs attention counts fetches them separately via the existing
+ *  `POST /v1/canvas/attention/counts` (already scoped to exactly the ids it
+ *  renders, never the whole canvas). */
+export interface RosterNodeDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    kind: string;
+    mode: string;
+    lifecycle?: string;
+    status: NodeStatusDTO;
+    cwd: string;
+    host_kind: string;
+    /** True when the node hosts an enterable broker (`host_kind === 'broker'`). */
+    enterable: boolean;
+    parent: NodeIdDTO | null;
+    created: IsoTime;
+}
+/** One `subscribes_to` edge in the roster's topology half. Every edge is kept
+ *  (passive + multiple per node) — never collapsed to one edge per node. */
+export interface RosterEdgeDTO {
+    from_id: NodeIdDTO;
+    to_id: NodeIdDTO;
+    active: boolean;
+    created: IsoTime;
+}
+/** `GET /v1/canvas/roster` result — the lean, set-based topology read shared by
+ *  the attach viewer and the browser canvas: exactly two indexed queries
+ *  (`rosterNodes()` + `rosterEdges()`), no `enrichRows`, no per-row
+ *  `getNode`/`subscriptionsOf` loop, no synchronous liveness probe. The
+ *  recurring poll target that replaces the enriched `/v1/canvas/snapshot`
+ *  storm; that endpoint remains for genuinely on-demand rich views. */
+export interface RosterDTO {
+    generated_at: IsoTime;
+    nodes: RosterNodeDTO[];
+    edges: RosterEdgeDTO[];
+}
+/** Browse's initial frame needs the dashboard fields and topology, not the full
+ * node detail/list projection. Transported as gzip JSON (application/gzip) over
+ * the local socket; other /v1/nodes consumers keep their original response. */
+export interface BrowseNodeDTO {
+    node_id: string;
+    name: string;
+    description?: string;
+    kind: string;
+    mode: string;
+    lifecycle: string;
+    status: NodeStatusDTO;
+    cwd: string;
+    profile_id: string | null;
+    grantee: string;
+    parent: string | null;
+    created: IsoTime;
+    frozen_at: IsoTime | null;
+    terminal_reason: string | null;
+    final_report: string | null;
+    telemetry_tokens_in: number | null;
+    telemetry_updated_at: IsoTime | null;
+    fault: import('./nodes.js').NodeFaultDTO | null;
+    streaming: boolean;
+}
+export interface BrowseCanvasDTO {
+    nodes: BrowseNodeDTO[];
+    edges: RosterEdgeDTO[];
+}
+/** One row in `GET /v1/canvas/graph`: exactly the node fields the attach graph displays. */
+export interface GraphNodeDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    description: string | null;
+    cycles: number | null;
+    kind: string;
+    status: NodeStatusDTO;
+    frozen_at: IsoTime | null;
+    pi_pid: number | null;
+    telemetry_context_tokens: number | null;
+    telemetry_last_activity: string | null;
+    fault: NodeFaultDTO | null;
+    streaming: boolean;
+}
+/** `GET /v1/canvas/graph` — the attach graph's one-read projection: display rows, subscription topology, and the current local viewer-focus set. */
+export interface GraphDTO {
+    generated_at: IsoTime;
+    nodes: GraphNodeDTO[];
+    edges: RosterEdgeDTO[];
+    focused_node_ids: NodeIdDTO[];
+}
+/** `POST /v1/canvas/prune` body — the three exclusive prune modes of
+ *  `crtr canvas prune`, precedence COUNT (`limit`) > EMPTY (`empty`) > TTL sweep. */
+export interface PruneRequest {
+    /** COUNT mode: keep the N most-recently-active nodes, prune the oldest
+   *   remaining terminal nodes (protected nodes always survive). */
+    limit?: number;
+    /** TTL sweep retention window in days (default 14). */
+    ttl_days?: number;
+    /** TTL sweep: also prune stale active/idle nodes past the TTL whose process
+   *   is provably gone. */
+    include_stale?: boolean;
+    /** EMPTY mode: reap nodes whose engine never produced an assistant message. */
+    empty?: boolean;
+    /** Report what would be pruned without mutating. */
+    dry_run?: boolean;
+}
+/** One node in a prune result (pruned, or candidate under `dry_run`). */
+export interface PrunedNodeDTO {
+    node_id: NodeIdDTO;
+    /** Lifecycle status, or `empty` for EMPTY-mode reaps. */
+    status: string;
+    /** ISO created timestamp (empty string for EMPTY-mode reaps). */
+    created: string;
+}
+/** `POST /v1/canvas/prune` result. `pruned` is the pruned set (or, under
+ *  `dry_run`, the candidate set — nothing deleted). `ttl_days` echoes the
+ *  retention window used. */
+export interface PruneResultDTO {
+    pruned: PrunedNodeDTO[];
+    dry_run: boolean;
+    ttl_days: number;
+}

package/dist/api/dto/chat-inventory.d.ts

@@ -0,0 +1,56 @@
+/** One command a chat surface may advertise. Builtin and non-opted-in rows are
+ *  dropped before this DTO exists, so `source` never carries `'builtin'`. */
+export interface ChatInventoryCommandDTO {
+    /** No leading slash, exactly as the engine dispatches it. */
+    name: string;
+    description: string;
+    source: 'command' | 'template';
+    /** Argument shape to display beside the name, when the command supplies one. */
+    argument_hint?: string;
+    /** Deterministic expansion metadata for a memory-slash command — the same
+     *  material the terminal preview uses, so a chat preview cannot drift from
+     *  what submission sends. */
+    expansion?: {
+        kind: 'memory-slash';
+        commandName: string;
+        body: string;
+    };
+    /** Raw prompt-template content (frontmatter stripped), for `source: 'template'`. */
+    template?: string;
+}
+/** One resolvable inline memory reference. Metadata only — never the document
+ *  body or its source path. `shortForm` stays camelCase to mirror the broker's
+ *  own `RefMeta`, which is where these rows come from. */
+export interface ChatInventoryMemoryRefDTO {
+    /** Canonical `/`-joined name, e.g. `taste/writing`. */
+    name: string;
+    kind: 'knowledge' | 'preference';
+    scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+    shortForm: string;
+}
+/** `GET /v1/nodes/{id}/chat-inventory` result.
+ *
+ *  `broker_live` reports whether the node's engine was reachable at all. There
+ *  is no per-part error flag: a part that failed and a part that is genuinely
+ *  empty both arrive as an empty array, and a client's behavior is identical
+ *  for both. A dormant node answers 200 with `broker_live: false` — this read
+ *  never revives an engine. */
+export interface ChatInventoryDTO {
+    node_id: string;
+    broker_live: boolean;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+/** Session-less inventory for the launch target a create would resolve. */
+export interface ProspectiveChatInventoryDTO {
+    profile_id: string | null;
+    cwd: string;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+export interface ProspectiveChatInventoryQuery {
+    profile?: string;
+    cwd?: string;
+    /** Same optional kind operand as POST /v1/nodes. */
+    kind?: string;
+}

package/dist/api/dto/common.d.ts

@@ -0,0 +1,29 @@
+/** ISO-8601 timestamp string (matches the runtime's `nowIso()` output). */
+export type IsoTime = string;
+/** A node id — the existing `<slug>-<hash>` string. Typed as a nominal alias so
+ *  DTOs read as thin projections; validated at the boundary by `isSafeNodeId`. */
+export type NodeIdDTO = string;
+/** Opaque pagination cursor (server-defined; clients pass it back verbatim). */
+export type Cursor = string;
+/** Standard list-pagination inputs shared by paged queries. */
+export interface Pagination {
+    limit?: number;
+    cursor?: Cursor;
+}
+/** Runtime status of a node (mirrors the runtime `NodeStatus` union; declared
+ *  locally to keep `/api` free of any `core/*` import). */
+export type NodeStatusDTO = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+/** Lifecycle class of a node (mirrors the runtime `Lifecycle` union). */
+export type LifecycleDTO = 'terminal' | 'resident';
+/** Execution mode of a node (mirrors the runtime `Mode` union). */
+export type ModeDTO = 'base' | 'orchestrator';
+/** Why a node last stopped (mirrors the runtime `ExitIntent` union). */
+export type ExitIntentDTO = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
+/** Why a terminal node ended (mirrors the runtime `TerminalReason` union). */
+export type TerminalReasonDTO = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined' | 'out_of_memory';
+/** Inbox urgency tier for a delivered message (mirrors feed/inbox `InboxTier`). */
+export type InboxTierDTO = 'critical' | 'urgent' | 'normal' | 'deferred';
+/** Whether a node id is a safe single filesystem path segment. Re-declared here
+ *  (not imported from `core/canvas/paths.ts`) to keep the exported `/api`
+ *  contract dependency-light; kept byte-for-byte equivalent to the runtime's. */
+export declare function isSafeNodeId(id: string): boolean;

package/dist/api/dto/common.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var e=(t,f)=>n(t,"name",{value:f,configurable:!0});const o=128;function r(t){return typeof t=="string"&&t!==""&&t!=="."&&t!==".."&&!/[\\/\0]/u.test(t)&&Buffer.byteLength(t,"utf8")<=128}e(r,"isSafeNodeId");export{r as isSafeNodeId};

package/dist/api/dto/config.d.ts

@@ -0,0 +1,46 @@
+import type { LifecycleDTO, ModeDTO } from './common.js';
+/** `PATCH /v1/nodes/{id}/config` body. All fields optional; a set field is
+ *  applied, an absent field is untouched. */
+export interface NodeConfigPatch {
+    /** Model tier or exact selection override. */
+    model?: string;
+    /** Ambient situational-context text override. */
+    situational_context?: string;
+    /** Persona kind respecialization — rebuilds the launch spec server-side. */
+    kind?: string;
+    /** Persona mode; setting `orchestrator` seeds a roadmap scaffold if absent. */
+    mode?: ModeDTO;
+    /** Lifecycle flip (terminal↔resident), rebuilding the launch spec. */
+    lifecycle?: LifecycleDTO;
+    /** Rename the node (and, when it has a live viewer window, that window). */
+    name?: string;
+    /** Replacement launch directory; exclusive of every other field except `keep_session` and `restart`.
+     *  Without `keep_session` it is repair-only (dormant node, recorded cwd gone, Pi session cleared). */
+    cwd?: string;
+    /** With `cwd`: the new path is the SAME directory as the recorded one (a symlink alias, or an
+     *  alias that is already gone — the caller asserts it). Relocates without clearing the Pi session
+     *  and rewrites the transcript header's cwd; allowed for live nodes. */
+    keep_session?: boolean;
+    /** Reassign the node to this profile (id or exact name). Exclusive of every other field except `restart`. */
+    profile?: string;
+    /** With `profile` or `cwd`+`keep_session` on a live node: SIGTERM the broker after the change so the
+     *  daemon resumes it (same transcript) with the new profile/cwd. Ignored for a node with no live broker. */
+    restart?: boolean;
+    /** Per-run allow-list. A patch may only remove scopes; it applies to a live broker on its next revive. */
+    scopes?: string[];
+    /** The node's default listening configuration: event level ("1".."10") → delivery
+     *  (`interrupt`|`steer`|`after-turn`|`next-turn`) for watches with no config of their own.
+     *  `null` resets it to the global default. */
+    listen?: Record<string, 'interrupt' | 'steer' | 'after-turn' | 'next-turn'> | null;
+}
+/** One installed persona kind, as the daemon resolves kinds for node creation. */
+export interface KindDTO {
+    kind: string;
+    when_to_use: string | null;
+    /** Top-level kinds a sub-kind is offered to; null takes the default (its own ancestor). */
+    available_to: string[] | null;
+}
+/** `GET /v1/kinds` — every kind the daemon accepts on create, sorted by name. */
+export interface KindListDTO {
+    kinds: KindDTO[];
+}