@north-light/api 0.0.0 → 0.3.414

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

@@ -0,0 +1,371 @@
+import type { Cursor, ExitIntentDTO, IsoTime, LifecycleDTO, ModeDTO, NodeIdDTO, NodeStatusDTO, TerminalReasonDTO } from './common.js';
+import type { ReportDTO } from './reports.js';
+import type { NodeOutcomeDTO, NodeOutcomeSummaryDTO, RegisterOutcomeDeliveryRequest } from './node-outcomes.js';
+import type { FaultLink, FaultKind, FaultRetry, FaultProviderError } from './recovery.js';
+/** `GET /v1/nodes/{id}/subject` — the node-config subject substrate gate
+ *  predicates evaluate against. Mirrors `NodeConfigSubject`; this narrow
+ *  endpoint exists so a CLI process (a `crtr canvas read` of a document) can
+ *  gate-check its delivery rules without reaching canvas state. */
+export interface NodeSubjectDTO {
+    kind: string;
+    mode: ModeDTO;
+    lifecycle: LifecycleDTO;
+    hasManager: boolean;
+    cwd: string;
+    scope: 'user' | 'project';
+    orchestration: {
+        depth: number;
+    };
+    profile: string | null;
+    /** Effective run scopes; a null row resolves to the full runtime vocabulary. */
+    scopes: readonly string[];
+    /** Handles of the repos enclosing `cwd`, nearest first. */
+    repo: readonly string[];
+}
+/** `POST /v1/nodes` body. Carries the full immediate spawn recipe. */
+export interface CreateNodeRequest {
+    /** Persona kind. Omit to resolve the selected profile's `default_kind`, then `general`. */
+    kind?: string;
+    prompt?: string;
+    profile?: string;
+    mode?: ModeDTO;
+    /** The directory the create came from. It is what the daemon selects a
+     *  profile from when the request neither names one nor inherits one from a
+     *  parent, and — for a node with no `pin_cwd` and no spawner to inherit from —
+     *  where the node lands. */
+    cwd?: string;
+    /** Pin the node to this exact directory, overriding both the spawner's
+     *  directory and the launch cwd. See `crtr node new --cwd`. */
+    pin_cwd?: string;
+    /** Display name (tmux window + resume picker). Defaults to the kind. */
+    name?: string;
+    /** Caller-supplied short description, preserved against automatic naming. */
+    description?: string;
+    parent?: NodeIdDTO | null;
+    /** Node that created this request; absent for an external process. */
+    creator?: NodeIdDTO;
+    /** Per-run allow-list. Absent inherits everything. Some scopes are recorded but not enforced in beta: llm, files:<dir>, net, provider groups, and peers. */
+    scopes?: string[];
+    /** Sticky isolation; a child cannot turn off an isolated run. */
+    isolated?: boolean;
+    root?: boolean;
+    /** Lifecycle of the new node. Roots default to `resident`; managed children
+     *  default to `terminal`. Use `resident` for a child that remains wakeable
+     *  without owing a final, or `terminal` for a bounded worker that must
+     *  finalize. */
+    root_lifecycle?: LifecycleDTO;
+    /** Worktree branch name, or true for an auto-named managed worktree. */
+    worktree?: string | boolean;
+    fork_from?: string;
+    model?: string;
+    situational_context?: string;
+    no_kickoff?: boolean;
+    output_schema?: string;
+    /** Wall-clock bound from spawn, e.g. "45m", "2h", "1h30m". Expiry cancels the node and synthesizes a failure outcome with reason 'deadline_exceeded'. */
+    deadline?: string;
+    /** Arm outcome delivery atomically with node birth. */
+    outcome_delivery?: RegisterOutcomeDeliveryRequest;
+    /** Spawn AT this exact node id instead of a runtime-minted one — format-
+     *  validated and duplicate-rejected server-side (`NodeIdConflictError` →
+     *  HTTP 409 `node_id_exists`). See `crtr node new --node-id`. */
+    node_id?: string;
+    /** Opaque key generated once per create attempt. A repeated key returns the
+     *  node created by its first served request. */
+    request_key?: string;
+    /** Serve this create from the warm pool when a pre-booted spare matches the
+     *  request's frozen launch tuple (kind, mode, resolved cwd, profile, model,
+     *  situational_context) — answering in milliseconds instead of waiting out a
+     *  full engine boot. Only a bare root with no kickoff qualifies; anything the
+     *  pool cannot honor (or an empty pool) falls back to an ordinary cold spawn,
+     *  so the flag never fails a create, it only ever makes it faster. */
+    prefer_warm?: boolean;
+}
+/** The list/queryable projection of a node — the indexed row columns. */
+export interface NodeSummaryDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    /** Generated first-task description, absent when the node is not yet named.
+     *  Paired with `name` it forms the full display label, so a roster consumer
+     *  builds it without a per-node metadata fetch. */
+    description?: string;
+    /** How many times the node has been (re)launched; absent on a pre-v38 row. */
+    cycles?: number;
+    kind: string;
+    mode: ModeDTO;
+    lifecycle: LifecycleDTO;
+    status: NodeStatusDTO;
+    cwd: string;
+    host_kind: 'tmux' | 'broker' | null;
+    profile_id: string | null;
+    /** Per-run allow-list; null inherits everything. */
+    scopes: string[] | null;
+    isolated: boolean;
+    /** App that owns this node's agent folder. */
+    grantee: string;
+    /** Whether the node's profile is currently paused. */
+    profile_paused: boolean;
+    parent: NodeIdDTO | null;
+    created: IsoTime;
+    intent: ExitIntentDTO;
+    waiting_for: NodeIdDTO | null;
+    frozen_at: IsoTime | null;
+    terminal_reason: TerminalReasonDTO | null;
+    pi_pid: number | null;
+    /** Launch-time process identity paired with `pi_pid`, or null when absent. */
+    pi_pid_identity: string | null;
+    /** Current tmux placement cache. Local tmux callers re-check the pane itself before acting. */
+    window: string | null;
+    tmux_session: string | null;
+    pane: string | null;
+    /** Basename of the canonical final report, or null when this node has not finalized. */
+    final_report: string | null;
+    finalized_at: IsoTime | null;
+    deadline_at: IsoTime | null;
+    /** Cumulative input tokens reported by the broker telemetry producer. */
+    telemetry_tokens_in?: number | null;
+    /** Latest context-window token gauge reported by the broker. */
+    telemetry_context_tokens?: number | null;
+    /** Latest tool summary reported by the broker. */
+    telemetry_last_activity?: string | null;
+    /** Timestamp of the latest broker telemetry update. */
+    telemetry_updated_at?: IsoTime | null;
+    outcome: NodeOutcomeSummaryDTO | null;
+    fault?: NodeFaultDTO | null;
+    streaming?: boolean;
+    /** Present only when requested with `include=activity`. */
+    activity?: NodeActivityDTO;
+}
+/** Optional per-node activity payload for a list response. Reports are the
+ * stored push entries, newest first; `final_report` follows the row's canonical
+ * final-report basename rather than merely selecting the newest final-tier file. */
+export interface NodeActivityDTO {
+    latest_report: ReportDTO | null;
+    final_report: ReportDTO | null;
+    pending_human_count: number;
+}
+/** The spine + subscription edges of a node (absorbs `managers`/`paths` reads). */
+export interface NodeEdgesDTO {
+    /** Spine parent (my manager); null for a root. */
+    parent: NodeIdDTO | null;
+    /** Provenance — who spawned me. */
+    spawned_by: NodeIdDTO | null;
+    /** Publishers I subscribe to. */
+    subscribes_to: NodeIdDTO[];
+    /** Subscribers to my output (my managers). */
+    subscribers: NodeIdDTO[];
+    /** Children I spawned. */
+    children: NodeIdDTO[];
+}
+/** Absolute filesystem paths for a node (absorbs the `paths` read). */
+export interface NodePathsDTO {
+    node_dir: string;
+    context_dir: string;
+    meta_path: string;
+    transcript_path: string;
+    view_socket: string;
+}
+/** A node's managed git worktree, if any. */
+export interface NodeWorktreeDTO {
+    state: 'open' | 'closed' | 'abandoned';
+    /** Pending cleanup must be run manually after the owner exits. */
+    cleanup?: 'pending' | 'complete';
+    path: string;
+    branch: string;
+    repo_root: string;
+    base_ref: string;
+    base_sha: string;
+    created: IsoTime;
+    closed?: IsoTime;
+    abandoned?: {
+        branch: string;
+        tip_sha: string;
+        at: IsoTime;
+        by: string;
+    };
+}
+/** Immutable companion provenance and fork coordinates. Present only on a
+ *  daemon-spawned companion node: a `review/companion` node for a human review
+ *  (`kind` absent or `review`), or — for a page ticket's feedback conversation
+ *  (`kind: 'page_feedback'`, review_id = ticket id, target_file = the page
+ *  source) — a fork of the sending node itself, spawned with its kind. */
+export interface NodeReviewBindingDTO {
+    kind?: 'review' | 'page_feedback';
+    review_id: string;
+    origin_node_id: string;
+    branch_file: string;
+    target_file: string;
+}
+/** The active fault projection shown by node inspection. */
+export interface NodeFaultDTO {
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    since: IsoTime;
+    operation_id: string;
+    anchorEntryId?: string;
+    providerError?: FaultProviderError;
+}
+/** The full node view — summary ∪ identity extras ∪ edges ∪ paths. Returned by
+ *  `GET /v1/nodes/{id}` and by the create/lifecycle actions that yield a node. */
+export interface NodeDetailDTO extends Omit<NodeSummaryDTO, 'outcome'> {
+    outcome: NodeOutcomeDTO | null;
+    /** Node that created this node, or null when an external process did. */
+    creator: NodeIdDTO | null;
+    /** The namer's prose form of `description` — sentence case, punctuation intact
+     *  (`NodeMeta.title`). What a surface showing this node to a person reads;
+     *  absent on a node named before titles existed. */
+    title?: string;
+    /** The Nerd Font glyph the namer chose for this node's work, when it has one
+     *  (`NodeMeta.icon`). Rendered ahead of the label by surfaces that want it. */
+    icon?: string;
+    /** Approximate context-window token load of the node's live/last session,
+     *  used by the orchestrator yield-nudge (`childFollowUp`). Null when unknown
+     *  (never launched, or no token accounting yet). */
+    context_tokens?: number | null;
+    pi_session_id?: string | null;
+    /** The node's durable model override (`NodeMeta.model_override`), or null when
+     *  it runs on the kind/profile default. Surfaced so `node config --model`
+     *  can report the resolved model after a patch. */
+    model_override?: string | null;
+    /** Absolute path to pi's session `.jsonl`, captured at session_start
+     *  (`NodeMeta.pi_session_file`). Distinct from `paths.transcript_path` (the
+     *  crtr-owned transcript mirror). Used to resume or fork the node's pi session
+     *  and shown by the Inspector. */
+    pi_session_file?: string | null;
+    /** Immutable review-companion provenance — present only on nodes of kind
+     *  `review/companion`. Four fields capture the invocation-time fork
+     *  coordinates without duplicating the full review record. */
+    review_binding?: NodeReviewBindingDTO | null;
+    edges: NodeEdgesDTO;
+    paths: NodePathsDTO;
+    worktree?: NodeWorktreeDTO | null;
+    /** Present only on a `POST /promote` response — the roadmap/goal facts the
+     *  promote primitive returns beyond the node meta (spec §6.2). A plain detail
+     *  read omits them. */
+    roadmap_written?: boolean;
+    /** The node's roadmap document ref (`<node>/roadmap`). */
+    roadmap_ref?: string;
+    goal_path?: string;
+}
+/** `GET /v1/nodes` optional payloads. */
+export type NodeListInclude = 'activity';
+/** `GET /v1/nodes` query filters. Filters compose; `parent` selects direct
+ * children while `under` selects a whole subtree. */
+export interface ListNodesQuery {
+    status?: NodeStatusDTO;
+    lifecycle?: LifecycleDTO;
+    kind?: string;
+    mode?: ModeDTO;
+    /** Exact profile id. */
+    profile_id?: string;
+    /** Profile-id prefix, for callers that own a namespaced profile family. */
+    profile_prefix?: string;
+    /** Restrict to direct children of this node. Mutually exclusive with `top_level`. */
+    parent?: NodeIdDTO;
+    /** Restrict to nodes without a parent. */
+    top_level?: boolean;
+    /** Restrict to the subtree under this node. */
+    under?: NodeIdDTO;
+    /** Only nodes with a dangling/hanging manager edge. */
+    hanging?: boolean;
+    /** Opt into richer per-node payloads that require filesystem reads. */
+    include?: NodeListInclude;
+}
+/** `GET /v1/nodes/{id}/snapshot` — the node's reconstructed broker snapshot
+ *  (`readNodeSnapshot`): the message log, aggregate stats, and current engine
+ *  state, plus the node's registered command set. */
+export interface NodeSnapshotDTO {
+    node_id: NodeIdDTO;
+    snapshot: {
+        messages: unknown[];
+        messageIds?: string[];
+        messageVisibility: Array<'visible' | 'internal'>;
+        turnVisibility: 'visible' | 'internal';
+        stats: unknown;
+        state: Record<string, unknown>;
+        display: {
+            statuses: Record<string, string>;
+            widgets: Record<string, {
+                lines: string[];
+                placement: 'aboveEditor' | 'belowEditor';
+            }>;
+            title?: string;
+        };
+        queued?: {
+            steering: string[];
+            followUp: string[];
+        };
+        toolGroupSummaries?: Record<string, unknown>;
+        workingActivity?: string;
+    };
+    commands: {
+        name: string;
+        description: string;
+        source: string;
+    }[];
+    captured_at: IsoTime;
+}
+/** `GET /v1/nodes/{id}/messages` query. `cursor` walks backward from the
+ * newest messages; each returned page remains chronological. */
+export interface NodeMessagesQuery {
+    cursor?: Cursor;
+    limit?: number;
+}
+/** `GET /v1/nodes/{id}/messages` — a backward-paged window over the node's
+ * cycle-flattened visible history. */
+export interface NodeMessagesPageDTO {
+    node_id: NodeIdDTO;
+    /** pi AgentMessage[] JSON, chronological ascending within this page. */
+    messages: unknown[];
+    /** Stable session-entry ids aligned 1:1 with `messages`. */
+    message_ids?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    message_visibility: Array<'visible' | 'internal'>;
+    /** Opaque cursor toward older messages; null at the start of the session. */
+    next_cursor: Cursor | null;
+    captured_at: IsoTime;
+}
+/** `GET /v1/nodes/{id}/session` — the node's conversation exactly as it ran:
+ *  the raw session `.jsonl` bytes plus the assembled system prompt. Unlike
+ *  `NodeSnapshotDTO` nothing is reconstructed or flattened, so every
+ *  session-tree entry, cycle, branch, and custom message role survives. This is
+ *  what an export/download wants; `/snapshot` is what a renderer wants. */
+export interface NodeSessionDTO {
+    node_id: NodeIdDTO;
+    /** Absolute path (inside the node's host) of the file the bytes came from. */
+    session_file: string;
+    /** Verbatim `.jsonl` contents. */
+    session_jsonl: string;
+    /** Assembled system prompt as last captured, or `null` if never written. */
+    system_prompt: string | null;
+    captured_at: IsoTime;
+}
+/** `GET /v1/nodes/{id}/transcript` query. */
+export interface TranscriptQuery {
+    limit?: number;
+    cursor?: Cursor;
+}
+/** `GET /v1/nodes/{id}/transcript` result. The reader (`transcriptMarkdown`)
+ *  renders the whole conversation as a single markdown document. */
+export interface TranscriptDTO {
+    node_id: NodeIdDTO;
+    markdown: string;
+}
+/** One context root visible to a node — its own dir plus each publisher it
+ *  subscribes to (the shared-document roster). */
+export interface ContextRootDTO {
+    node_id: NodeIdDTO;
+    label: string;
+    dir: string;
+    /** True for the node's own context root. */
+    self: boolean;
+    /** Count of context files plus report documents for the root. */
+    files: number;
+}
+/** `GET /v1/nodes/{id}/context` result (the listing; the nvim popup stays local). */
+export interface ContextListDTO {
+    node_id: NodeIdDTO;
+    roots: ContextRootDTO[];
+}

package/dist/api/dto/nodes.js

@@ -0,0 +1,3 @@
+// Node resource DTOs (spec §6.2): create request, summary/detail projections,
+// list query, and the node read-endpoint shapes.
+export {};

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

@@ -0,0 +1,172 @@
+export declare const PRIVACY_LEVELS_DTO: readonly ["public", "friends", "private"];
+export type PrivacyName = typeof PRIVACY_LEVELS_DTO[number];
+export type OwnerTypeName = 'person' | 'app' | 'repo' | 'profile' | 'node' | 'document' | 'job';
+export interface ObjectOwnerDTO {
+    id: string;
+    type: OwnerTypeName;
+    handle: string;
+}
+export interface ObjectDTO {
+    id: string;
+    /** The object's kind name: `document`, `node`, `job`, `person`, `app`, `repo`, `profile`, or a later kind. */
+    type: string;
+    kind: string | null;
+    owner: ObjectOwnerDTO | null;
+    privacy: PrivacyName;
+    name: string;
+    preview: string;
+    created_at: string;
+    deleted_at: string | null;
+}
+export interface DocHeadDTO {
+    rev_id: string;
+    number: number;
+    author_id: string | null;
+    created_at: string;
+}
+/** Optional document fields a `--fields` read returns. */
+export interface DocFieldsDTO {
+    why_it_exists?: string | null;
+    unlisted?: boolean;
+    lint_ignore?: string[];
+    extensions?: Record<string, Record<string, unknown>>;
+    rules?: import('./docs.js').DeliveryRuleDTO[];
+}
+/** `data` of a document read. */
+export interface DocumentReadData {
+    summary: string | null;
+    revision: number;
+    heads: DocHeadDTO[];
+    /** One body per head, in `heads` order. */
+    bodies: string[];
+    needs_merge: boolean;
+    /** Documents named under it, then the documents it links to not already in your context at preview, each once. */
+    listing?: ObjectDTO[];
+    /** One `<auto-loaded-context>` block: enclosing listings and documents the read's `document-read` rules delivered. */
+    attachments?: string;
+    fields?: DocFieldsDTO;
+}
+/** `data` of a node read. */
+export interface NodeReadData {
+    status: string;
+    mandate_first_line: string;
+    children: ObjectDTO[];
+    owned: ObjectDTO[];
+    jobs: ObjectDTO[];
+}
+/** `data` of a job read. */
+export interface JobReadData {
+    command: string;
+    status: string;
+    exit_code: number | null;
+    log_path: string;
+}
+/** `data` of a person, app, repo or profile read. */
+export interface OwnerReadData {
+    handle: string;
+    display_name: string;
+    identity: {
+        scheme: string;
+        external_id: string;
+    };
+}
+/** A live object: `text` is exactly what `crtr canvas read` prints; `data` holds the kind's
+ *  structured fields (for the built-in kinds, the `*ReadData` shapes above). */
+export interface ObjectLiveReadDTO {
+    state: 'object';
+    type: string;
+    object: ObjectDTO;
+    text: string;
+    data: Record<string, unknown>;
+}
+/** A pointer to a deleted object resolves to that object (§8); an answer, not an error. */
+export interface ObjectDeletedDTO {
+    state: 'deleted';
+    deleted: ObjectDTO;
+}
+/** The name's first segment is no handle on this runtime; the object may live on another runtime. */
+export interface ObjectRemoteDTO {
+    state: 'remote';
+    remote: string;
+}
+export type ObjectReadDTO = ObjectLiveReadDTO | ObjectDeletedDTO | ObjectRemoteDTO;
+export interface ObjectReadQuery {
+    fields?: boolean;
+}
+export interface ObjectListRequest {
+    /** A kind name. */
+    type?: string;
+    kind?: string;
+    /** An owner ref (name or id). */
+    owner?: string;
+    privacy?: PrivacyName;
+    /** Name prefix. */
+    name?: string;
+    deleted?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+export interface ObjectListItemDTO extends ObjectDTO {
+    summary?: string | null;
+    /** A document's rule count. */
+    rules?: number;
+}
+export interface ObjectListDTO {
+    items: ObjectListItemDTO[];
+    next_cursor: string | null;
+}
+export interface ObjectSearchRequest {
+    text: string;
+    body?: boolean;
+    grep?: string;
+    /** A kind name. */
+    type?: string;
+    kind?: string;
+    owner?: string;
+    limit?: number;
+}
+export interface ObjectSearchHitDTO {
+    object: ObjectListItemDTO;
+    matches?: Array<{
+        line: number;
+        text: string;
+    }>;
+}
+export interface ObjectSearchDTO {
+    items: ObjectSearchHitDTO[];
+}
+export type ListenDeliveryName = 'interrupt' | 'steer' | 'after-turn' | 'next-turn';
+/** `{"<level 1-10>": delivery}` */
+export type ListenConfigDTO = Record<string, ListenDeliveryName>;
+export interface WatchRequest {
+    patterns?: string[];
+    config?: ListenConfigDTO;
+    filter?: Record<string, unknown>;
+    watcher?: string;
+}
+export interface UnwatchQuery {
+    pattern?: string;
+    watcher?: string;
+}
+export interface WatchResultDTO {
+    object: ObjectDTO;
+    patterns: string[];
+}
+export interface UnwatchResultDTO {
+    object: ObjectDTO;
+    removed: number;
+}
+export type EdgeTypeName = 'acted-on' | 'links-to' | 'watches';
+export interface EdgesQuery {
+    type?: EdgeTypeName;
+    direction?: 'out' | 'in';
+}
+export interface EdgeDTO {
+    type: EdgeTypeName;
+    src: ObjectDTO;
+    dst: ObjectDTO;
+    written_as?: string;
+}
+export interface EdgesDTO {
+    items: EdgeDTO[];
+}

package/dist/api/dto/objects.js

@@ -0,0 +1,5 @@
+// Canvas object DTOs — the `/v1/objects` shared verbs (read, list, search,
+// watch, unwatch, edges) over documents, nodes, jobs and owners.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export const PRIVACY_LEVELS_DTO = ['public', 'friends', 'private'];

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

@@ -0,0 +1,117 @@
+/** The disclosure ladder, lowest to highest. Index order is the ordering. */
+export declare const PROFILE_PROJECT_MEMORY_VALUES: readonly ["none", "name", "preview", "content"];
+/** How much of an owner's documents automatic delivery may disclose. */
+export type ProfileProjectMemory = (typeof PROFILE_PROJECT_MEMORY_VALUES)[number];
+/** One project directory in a profile's purview. */
+export interface ProfileProject {
+    /** Absolute, real-path-resolved directory. */
+    path: string;
+}
+/** Per-owner cap on automatic `boot` and `workspace-open` delivery, keyed by
+ *  owner handle (repo, profile, app, `user`, plugin). An absent owner is
+ *  uncapped (`content`); a node's own documents are never capped. */
+export type DeliveryLimits = Record<string, ProfileProjectMemory>;
+/** `PUT /v1/profiles/{name}` body — idempotent ensure. Every field applies
+ *  only at create; an existing same-named profile is returned untouched. */
+export interface EnsureProfileRequest {
+    /** Project directories in the profile's purview. */
+    projects?: ProfileProject[];
+    /** Persona kind for node creates under the profile that omit kind. */
+    default_kind?: string;
+    /** Profile facts (identity, role); each entry reaches every broker
+     *  launched under the profile as `CRTR_PROFILE_META_<KEY>` env. */
+    metadata?: Record<string, string>;
+}
+/** `POST /v1/profiles` body — create a profile of the caller's app. A name the
+ *  caller's app already holds is refused. */
+export interface CreateProfileRequest extends EnsureProfileRequest {
+    name: string;
+}
+/** `PATCH /v1/profiles/{name}` body — each present field changes one fact of a
+ *  profile the caller's app holds. */
+export interface UpdateProfileRequest {
+    name?: string;
+    default_kind?: string;
+    /** Append a project; a path already listed is left in place. */
+    add_project?: ProfileProject;
+    /** Set the automatic delivery limit for one owner handle; `content` removes it. */
+    set_delivery_limit?: {
+        owner: string;
+        level: ProfileProjectMemory;
+    };
+    /** Remove the project at this path; the directory need not still exist. */
+    remove_project?: string;
+}
+/** `GET /v1/profiles/{name}/env` — stored env var names, never values. */
+export interface ProfileEnvNamesDTO {
+    profile_id: string;
+    names: string[];
+}
+/** `PUT /v1/profiles/{name}/env/{var}` body. */
+export interface SetProfileEnvRequest {
+    value: string;
+}
+/** `PUT` / `DELETE /v1/profiles/{name}/env/{var}` result. */
+export interface ProfileEnvChangeDTO {
+    profile_id: string;
+    /** PUT: the name was newly added. DELETE: a stored value was removed. */
+    changed: boolean;
+}
+/** `PATCH /v1/profiles/{name}/metadata` body. Merges `set` and removes `unset`. */
+export interface UpdateProfileMetadataRequest {
+    set?: Record<string, string>;
+    unset?: string[];
+}
+/** The daemon-owned result of pausing or resuming one profile. */
+export interface ProfilePauseResultDTO {
+    profile_id: string;
+    paused_at: string | null;
+}
+/** `DELETE /v1/profiles/{name}` body. Destructive deletion is never implicit. */
+export interface DeleteProfileRequest {
+    force: boolean;
+    /** Preserve nodes and human history while removing their profile identity. */
+    detach?: boolean;
+    /** The invoking broker, when the request came from a node-owned CLI process. */
+    caller_node_id?: string | null;
+}
+export type DeleteProfileMode = 'deleted' | 'detached';
+/** The completed deletion, or the accepted plan when the invoking node is part of it. */
+export interface DeleteProfileResultDTO {
+    profile_id: string;
+    name: string;
+    mode: DeleteProfileMode;
+    nodes: number;
+    crons: number;
+    tickets: number;
+    reviews: number;
+    default_pins: number;
+    /** True only when crtrd acknowledged the response before tearing down its caller. */
+    accepted?: true;
+    grace_ms?: number;
+}
+/** A profile projection. */
+export interface ProfileDTO {
+    /** Stable profile-directory id (`<slug>-<id>`). */
+    id: string;
+    /** Owning app, including for profiles shared with the caller. */
+    app: string;
+    name: string;
+    projects: ProfileProject[];
+    /** Per-owner delivery caps; empty when the profile sets none. */
+    delivery_limits: DeliveryLimits;
+    /** ISO timestamp when the profile was paused, or null while active. */
+    paused_at: string | null;
+    /** Default node kind when a create omits kind; `general` when absent on the manifest. */
+    default_kind: string;
+    /** Stored profile facts; empty when the manifest carries none. */
+    metadata: Record<string, string>;
+    /** The directory this profile is pinned as default for, if any. */
+    default_dir?: string | null;
+    /** ISO timestamp the profile was created. */
+    created_at: string;
+    /** ISO timestamp of the most recent selection, or null if never selected. */
+    last_used_at: string | null;
+    /** Absolute path of the profile's directory under its app's space (the legacy location of its pre-canvas markdown; the profile's documents live in the canvas). */
+    memory_path: string;
+}

package/dist/api/dto/profiles.js

@@ -0,0 +1,4 @@
+// Profile DTOs (spec §6.6). Profile deletion crosses profile, canvas, cron,
+// inbox, and review state, so every consumer routes it through crtrd.
+/** The disclosure ladder, lowest to highest. Index order is the ordering. */
+export const PROFILE_PROJECT_MEMORY_VALUES = ['none', 'name', 'preview', 'content'];