@crouter/api 0.3.377

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

@@ -0,0 +1,273 @@
+import type { IsoTime } from './common.js';
+/** Opaque, stable, URL-safe ticket id: lowercase SHA-256 hex. */
+export type InboxTicketIdDTO = string;
+export interface TicketSourceDTO {
+    sessionName?: string;
+    askedBy?: string;
+    blockedSince?: IsoTime;
+    emittedAt?: IsoTime;
+    profileName?: string;
+    nodeId?: string;
+}
+export interface ReviewTicketSummaryDTO {
+    /** Request identity for direct request/review routes. */
+    request_id: string;
+    /** Daemon-owned projection directory. */
+    request_dir: string;
+    ticket_id: InboxTicketIdDTO;
+    kind: 'review';
+    title: string;
+    subtitle: string;
+    blocked_since: IsoTime;
+    source: TicketSourceDTO;
+}
+/** One question's recommended option, flat on the wire like every other summary field. */
+export interface RecommendedOptionDTO {
+    slot_id: string;
+    option_id: string;
+    label: string;
+}
+/**
+ * What one keypress on an inbox row publishes. `responses` is a complete final response
+ * map this daemon already accepts for the ticket, so a client publishes it untouched
+ * rather than assembling one from the summary.
+ */
+export interface PageFastActionDTO {
+    kind: 'answer' | 'acknowledge';
+    responses: PageResponsesDTO;
+}
+export interface PageTicketSummaryDTO {
+    /** Request identity for direct request routes. */
+    request_id: string;
+    /** Daemon-owned projection directory. */
+    request_dir: string;
+    ticket_id: InboxTicketIdDTO;
+    kind: 'page';
+    title: string;
+    subtitle?: string;
+    placement: 'inline' | 'panel';
+    dialect: 'jsx' | 'html';
+    inbox: boolean;
+    steps: number;
+    emitted_at: IsoTime;
+    source: TicketSourceDTO;
+    slot_kinds: string[];
+    /** The ticket is waiting on the person: it asks something, or an agent bridge is parked on its reply. Not a writability gate — any pending, non-passive ticket accepts a response. */
+    awaits_response: boolean;
+    /** Omitted when no question recommends an option. */
+    recommended_options?: RecommendedOptionDTO[];
+    /** Present only on a pending ticket that a row can settle without opening it. */
+    fast_action?: PageFastActionDTO;
+    state: 'pending' | 'resolved' | 'canceled' | 'passive';
+    /** Present only on resolved history entries; the stored one-line answer digest. */
+    answer_digest?: string;
+}
+export type InboxTicketSummaryDTO = PageTicketSummaryDTO | ReviewTicketSummaryDTO;
+export interface InboxListDTO {
+    tickets: InboxTicketSummaryDTO[];
+}
+export interface PageSlotDTO {
+    id?: string;
+    kind: string;
+    step: number;
+    config: Record<string, unknown>;
+    unvalidated?: true;
+    display?: true;
+}
+/** The nested protocol object is deliberately camelCase on the wire. */
+export interface PageManifestDTO {
+    schema: 'crtr.page/v2';
+    dialect: 'jsx' | 'html';
+    title: string;
+    subtitle?: string;
+    delivery: {
+        placement: 'inline' | 'panel';
+        inbox: boolean;
+        reply: boolean;
+    };
+    document: 'page.tsx' | 'page.html';
+    steps: number;
+    slots: PageSlotDTO[];
+    source?: TicketSourceDTO;
+}
+/** Answer-annotation anchors: option on UserQuestion, row on UserTable.
+ * Feedback on other page content — including the question text — is a
+ * ticket-level feedback comment, never a response anchor. */
+export interface PageCommentAnchorDTO {
+    kind: 'option' | 'row';
+    optionId?: string;
+    rowId?: string;
+}
+export interface PageCommentDTO {
+    id: string;
+    anchor: PageCommentAnchorDTO;
+    text: string;
+}
+export interface PageOptionsResponseDTO {
+    selectedOptionIds: string[];
+    comments: PageCommentDTO[];
+    freetext?: string;
+}
+export interface PageTextResponseDTO {
+    text: string;
+    edited: boolean;
+}
+export interface PageTableResponseDTO {
+    selectedRowIds: string[];
+    selectedColumnIds: string[];
+    comments: PageCommentDTO[];
+}
+export interface PageCardsResponseDTO {
+    selectedCardIds: string[];
+}
+export type SlotResponseDTO = PageOptionsResponseDTO | PageTextResponseDTO | PageTableResponseDTO | PageCardsResponseDTO | Record<string, unknown>;
+export type PageResponsesDTO = Record<string, SlotResponseDTO>;
+export interface InboxPageDTO {
+    ticket_id: InboxTicketIdDTO;
+    kind: 'page';
+    state: 'pending' | 'resolved' | 'canceled' | 'passive';
+    /** Opaque SQL-selected immutable presentation revision. */
+    revision: string;
+    page: PageManifestDTO;
+    /** JSX is compiled for the host; HTML is the authored document verbatim. */
+    document: string;
+    /** Authored JSX or HTML, distinct from the compiled JSX host document. */
+    source_document: string;
+    document_media_type: 'text/jsx' | 'text/html';
+    progress: {
+        responses: PageResponsesDTO;
+    } | null;
+    /** Canonical stored terminal result, or null while the ticket remains open. */
+    result: PageTicketResultDTO | CanceledTicketResultDTO | null;
+    /** Ticket-attached feedback comments and the companion conversation they
+     * deliver to. Comments are immutable once sent — open until the companion
+     * resolves them. */
+    feedback: PageFeedbackDTO;
+}
+export interface PageFeedbackCommentDTO {
+    id: string;
+    /** The highlighted text the note is about; for a chart, its title. */
+    quote: string;
+    /** Surrounding text that locates the quote on the page. */
+    context?: string;
+    note: string;
+    /** Open until the companion has dealt with it; resolution is terminal. */
+    status: 'open' | 'resolved';
+    created_at: IsoTime;
+    resolved_at?: IsoTime;
+}
+export interface PageFeedbackDTO {
+    /** The ticket-bound companion conversation comments deliver to; null until
+     * the first comment realizes it. */
+    companion_node_id: string | null;
+    /** How many comments remain open. Zero once feedback exists is the ticket's
+     * authoritative signal that the companion has dealt with all of it. */
+    open_count: number;
+    comments: PageFeedbackCommentDTO[];
+}
+/** `POST /v1/human/inbox/:ticket_id/feedback-comments` body. */
+export interface CreatePageFeedbackCommentRequest {
+    quote: string;
+    context?: string;
+    note: string;
+}
+export interface PageFeedbackDeliveryDTO {
+    target_node_id: string;
+    status: 'delivered' | 'failed';
+    via?: 'engine' | 'inbox';
+    woke: boolean;
+    reason?: 'capacity_frozen';
+    error?: string;
+}
+/** Create result: the new comment, the ticket's full feedback state after it,
+ * and the delivery outcome in the companion conversation. */
+export interface PageFeedbackMutationDTO {
+    comment: PageFeedbackCommentDTO;
+    feedback: PageFeedbackDTO;
+    delivery: PageFeedbackDeliveryDTO;
+}
+/** `POST .../feedback-comments/:comment_id/resolve` request. Resolution is
+ * companion-only: `node_id` names the calling node and must equal the
+ * ticket's bound companion. */
+export interface ResolvePageFeedbackCommentRequest {
+    node_id: string;
+}
+/** `POST .../feedback-comments/:comment_id/resolve` result. Resolution appends
+ * no chat turn; the companion's own conversational report covers it. */
+export interface PageFeedbackResolutionDTO {
+    comment: PageFeedbackCommentDTO;
+    feedback: PageFeedbackDTO;
+}
+export interface InboxPageHistoryDTO {
+    tickets: PageTicketSummaryDTO[];
+}
+export interface RespondInboxPageRequest {
+    responses: PageResponsesDTO;
+}
+export interface InboxPageProgressDTO {
+    responses: PageResponsesDTO;
+}
+export interface PageTicketResultDTO {
+    schema: 'crtr.page-response/v1';
+    kind: 'page';
+    responses: PageResponsesDTO;
+    summary: string;
+    completedAt: IsoTime;
+}
+export interface PageAnswerGroupDTO {
+    group: 'option' | 'card' | 'row' | 'column';
+    mode: 'single' | 'multi';
+    total: number;
+    picked: {
+        id: string;
+        label: string;
+    }[];
+}
+export interface PageAnswerCommentDTO {
+    /** Legacy stored responses may still carry the retired `whole` anchor. */
+    anchor: PageCommentAnchorDTO | {
+        kind: 'whole';
+    };
+    anchorLabel: string;
+    text: string;
+}
+export interface PageAnswerSlotDTO {
+    id: string;
+    kind: string;
+    label?: string;
+    state: 'answered' | 'unanswered';
+    blank: boolean;
+    groups: PageAnswerGroupDTO[];
+    freetext?: string;
+    text?: {
+        value: string;
+        edited: boolean;
+        singleLine?: boolean;
+    };
+    comments: PageAnswerCommentDTO[];
+    raw?: Record<string, unknown>;
+}
+/** The camelCase protocol object shipped only by GET .../response. */
+export interface PageAnswerDTO {
+    title: string;
+    subtitle?: string;
+    completedAt: IsoTime;
+    kind: 'answer' | 'acknowledgement';
+    digest: string;
+    slots: PageAnswerSlotDTO[];
+}
+export interface InboxPageResponseDTO extends PageTicketResultDTO {
+    answer: PageAnswerDTO;
+}
+/** `POST /v1/human/inbox/:ticket_id/cancel` body. */
+export interface CancelInboxTicketRequest {
+    reason?: string;
+}
+/** `POST /v1/human/inbox/:ticket_id/cancel` result. */
+export interface CanceledTicketResultDTO {
+    schema: 'humanloop.cancel/v1';
+    kind: 'canceled';
+    canceledAt: IsoTime;
+    reason?: string;
+    actor?: string;
+}

package/dist/api/dto/inbox.js

@@ -0,0 +1,4 @@
+// Humanloop inbox DTOs — crtrd `/v1/human/inbox` (crouter cloud crouter-inbox v1,
+// inbox-contract.md §A). API envelope fields use snake_case; nested page
+// protocol objects retain their canonical camelCase field names.
+export {};

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

@@ -0,0 +1,88 @@
+import type { NodeIdDTO, NodeStatusDTO } from './common.js';
+/** `POST /v1/nodes/{id}/revive` body. */
+export interface ReviveRequest {
+    /** Resume the saved conversation (true) vs a fresh launch (false). */
+    resume?: boolean;
+    /** Clear the finalization latch before reviving (the `--reopen` gate). The
+     *  revive doorway accepts it only for a finalized node (`not_finalized`
+     *  otherwise); without it, a finalized node is rejected (`node_finalized`).
+     *  Message delivery has its own wider reopen behavior. */
+    reopen?: boolean;
+    /** Wake provenance: the cron whose run drove this revive (`CRTR_CRON_ID`,
+     *  set by the daemon in every cron run's environment and forwarded by the
+     *  CLI). With `resume:false` and a still-live cron row, crtrd injects the
+     *  `<crtr-wake>` block so the revived node learns a CLOCK woke it, not a
+     *  message. Prose only — an unknown id is ignored, never an error. */
+    cron_id?: string;
+}
+/** Result of a revive. `revived` is false on the idempotent double-revive no-op. */
+export interface ReviveResultDTO {
+    node_id: NodeIdDTO;
+    revived: boolean;
+    resumed: boolean;
+    status: NodeStatusDTO;
+    /** What the call did: `launched` started a broker, `already-live` found one
+     *  already running, `frozen` found no free broker slot and left the row
+     *  waiting for one. */
+    outcome: 'launched' | 'already-live' | 'frozen';
+}
+/** `POST /v1/nodes/{id}/relaunch-root` result. A null id means the target
+ * was not a relaunchable live root, or its replacement failed to launch. */
+export interface RelaunchRootResultDTO {
+    newNodeId: NodeIdDTO | null;
+}
+/** `POST /v1/nodes/revive-all` result. Node ids relaunched, any that failed to
+ *  revive with the reason, and any the broker cap turned away (the reader
+ *  reports all three). */
+export interface ReviveAllResultDTO {
+    revived: NodeIdDTO[];
+    failed: {
+        node_id: NodeIdDTO;
+        error: string;
+    }[];
+    /** Frozen for capacity, not failed: the daemon relaunches these as slots free. */
+    frozen: NodeIdDTO[];
+}
+/** `POST /v1/nodes/{id}/close` body. The cascade set is computed server-side
+ *  from edges; the flag only opts out of cascading descendants. */
+export interface CloseRequest {
+    cascade?: boolean;
+    /** PID of the shell that invoked this close. The daemon excludes this process
+     *  and its descendants from broker teardown so a node can close itself. */
+    caller_pid?: number;
+    /** Root close disposition: `true` finalizes the root to `done` (the browse `x`
+     *  "finish" semantics); default/`false` cancels it. The cascade set (computed
+     *  server-side) is torn down either way. */
+    finish?: boolean;
+}
+/** Result of a close. */
+export interface CloseResultDTO {
+    /** The closed node — the cascade root. */
+    root: NodeIdDTO;
+    /** Every node torn down (root + cascaded descendants), leaves-first. */
+    closed: NodeIdDTO[];
+    /** Descendants left alive because an out-of-subtree manager still subscribes. */
+    spared: NodeIdDTO[];
+}
+/** `POST /v1/nodes/{id}/promote` body. */
+export interface PromoteRequest {
+    /** Specialize as this kind of orchestrator; defaults to the node's current kind. */
+    kind?: string;
+    /** Also flip lifecycle→resident (interactable). */
+    resident?: boolean;
+    /** Durably change the model tier (ultra|strong). */
+    model?: string;
+}
+/** `POST /v1/nodes/{id}/yield` body. */
+export interface YieldRequest {
+    note?: string;
+    promote?: boolean;
+    /** Respecialize the kind as the node refreshes. */
+    kind?: string;
+    /** Durably raise the model tier (ultra|strong) for the fresh revive. */
+    model?: string;
+}
+/** `POST /v1/nodes/{id}/wait` body. */
+export interface WaitRequest {
+    controller: NodeIdDTO;
+}

package/dist/api/dto/lifecycle.js

@@ -0,0 +1,3 @@
+// Lifecycle action DTOs (spec §6.2). Recycle/demote take no body and return a
+// `NodeDetailDTO` (nodes.ts); revive/close/promote/yield/wait are here.
+export {};

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

@@ -0,0 +1,44 @@
+export interface MailEntryDTO {
+    entry_id: string;
+    seq?: number;
+    operation_id: string;
+    ts: string;
+    from: string | null;
+    from_name?: string;
+    tier: 'critical' | 'urgent' | 'normal' | 'deferred';
+    kind: 'update' | 'urgent' | 'final' | 'message' | 'completed';
+    ref?: string;
+    label: string;
+    data?: Record<string, unknown>;
+    disposition?: 'human-answer' | 'human-canceled';
+}
+export interface ClaimedMailDTO {
+    delivery_id: string;
+    attempts: number;
+    handoff: 'fresh' | 'inherited';
+    entry: MailEntryDTO;
+}
+export interface ClaimMailRequest {
+    execution_id: string;
+    channel: 'wake' | 'passive' | 'deferred_run';
+}
+export interface ClaimMailResultDTO {
+    action: 'claimed' | 'hold';
+    deliveries: ClaimedMailDTO[];
+}
+export interface MailReceiptDTO {
+    delivery_id: string;
+    attempts: number;
+    disposition: 'acknowledged' | 'released';
+}
+export interface AcknowledgeMailRequest {
+    execution_id: string;
+    deliveries: MailReceiptDTO[];
+}
+export interface AcknowledgeMailResultDTO {
+    action: 'acknowledged' | 'hold';
+    results: Array<{
+        delivery_id: string;
+        outcome: 'acknowledged' | 'released' | 'stale';
+    }>;
+}

package/dist/api/dto/mail.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,88 @@
+import type { InboxTierDTO, IsoTime, NodeIdDTO } from './common.js';
+/** One runtime card supplied by a caller: the runtime renders and escapes it
+ *  exactly once, so a caller cannot emit a malformed card or smuggle markup
+ *  into one. `kind` must be namespaced (contain `:`) — bare kinds are
+ *  crouter's own closed vocabulary. */
+export interface RuntimeCardRequest {
+    kind: string;
+    facts?: Record<string, string | number>;
+    /** Data, not markup. */
+    body?: string;
+}
+/** `POST /v1/nodes/{id}/messages` body. */
+export interface SendMessageRequest {
+    body: string;
+    tier?: InboxTierDTO;
+    /** Sender node id for feed attribution (the CLI resolves `CRTR_NODE_ID`;
+     *  the daemon has no ambient caller identity). Absent → an external/human
+     *  caller (`from: null`). */
+    from?: NodeIdDTO | null;
+    /** Revive with no inbox entry (`--fresh` → `reviveNode({ resume: false })`). */
+    fresh?: boolean;
+    /** Before delivery, make the target resident and clear its finalization latch
+     *  when present (`--reopen`). Accepted for both durable and interactive
+     *  delivery; `--fresh` retains its separate finalized-only gate. */
+    reopen?: boolean;
+    /** Hidden ambient context upserted onto the target's sidecar as a
+     *  `situational` card, never visible chat (`--situational-context`).
+     *  Immediate only; valid alone (no body). Prose only — its body is NOT
+     *  escaped; a caller with untrusted text uses `situational_card`. */
+    situational_context?: string;
+    /** A runtime card that REPLACES the target's situational sidecar, delivered
+     *  ahead of the body in the same turn and re-stated by the session-start
+     *  bearings after a context refresh. Mutually exclusive with
+     *  `situational_context`; valid alone (no body) on the durable path. */
+    situational_card?: RuntimeCardRequest;
+    /** One-shot runtime cards for this turn only — never persisted. Delivered in
+     *  array order, after `situational_card` and ahead of the body. */
+    context_cards?: RuntimeCardRequest[];
+    /** Raw JSON-schema string installing a one-off output schema before delivery
+     *  (`--output-schema`); the target answers with `crtr push result`. Immediate only. */
+    output_schema?: string;
+    /** `'interactive'`: deliver via the target's LIVE broker engine (prompt/steer
+     *  on its one serialized frame loop — the same ordering a tmux viewer gets)
+     *  instead of the durable inbox; a dormant or mid-revive target falls back to
+     *  the durable inbox + revive (watcher delivers post-boot). Plain immediate
+     *  body only — rejected with fresh/situational_context/output_schema or tier
+     *  'deferred'. Runtime cards and reopen ARE accepted: a
+     *  card-bearing send is an ordinary human send that happens to carry context,
+     *  and the live deliver frame places the cards ahead of the body in one turn.
+     *  Absent → durable inbox (unchanged). */
+    delivery?: 'interactive';
+}
+/** Result of an immediate message send. */
+export interface MessageResultDTO {
+    node_id: NodeIdDTO;
+    /** Whether an inbox entry was appended now. */
+    delivered: boolean;
+    /** Whether this request synchronously launched the target. Ordinary durable
+     *  delivery to an active or idle dormant target always reports false: the
+     *  lifecycle reconciler launches it from the durable inbox entry later. */
+    revived: boolean;
+    /** Present only when this request attempted a synchronous wake and no broker
+     *  slot was free. The target's row is frozen and the daemon relaunches it
+     *  when one frees; the entry was durably appended either way. */
+    not_revived_reason?: 'capacity_frozen';
+    /** Present only when the entry was appended ABOVE the requested tier: a
+     *  terminal target never takes the later cycle `normal`/`deferred` wait for,
+     *  so its mail is raised to the steering tier. */
+    delivered_tier?: InboxTierDTO;
+    delivered_at?: IsoTime;
+    /** Which channel a `delivery:'interactive'` send actually used: `'engine'`
+     *  (live broker frame loop, no inbox entry) or `'inbox'` (durable fallback).
+     *  Absent for non-interactive sends. */
+    delivered_via?: 'engine' | 'inbox';
+}
+/** `POST /v1/nodes/{id}/interrupt` result — the human Esc, first-class. Cancels
+ *  pending undelivered human-send inbox entries FIRST, then aborts a live
+ *  in-flight turn; a dormant target is NEVER revived. */
+export interface InterruptResultDTO {
+    node_id: NodeIdDTO;
+    /** Primary outcome: `aborted_turn` wins over `canceled_pending` over `idle`
+     *  (abort + cancel can co-occur; the flags below carry the full picture). */
+    outcome: 'aborted_turn' | 'canceled_pending' | 'idle';
+    /** True when a live in-flight turn (or `!` bash run) was actually aborted. */
+    aborted_turn: boolean;
+    /** How many pending undelivered human-send inbox entries were canceled. */
+    canceled_pending: number;
+}

package/dist/api/dto/messages.js

@@ -0,0 +1,2 @@
+// Message DTOs (spec §6.2).
+export {};

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

@@ -0,0 +1,25 @@
+export type ModelStrengthDTO = 'ultra' | 'strong' | 'medium' | 'light';
+export interface ModelRouteConfigDTO {
+    family: string;
+    credentialSource: string;
+    providerId: string;
+    models: Record<ModelStrengthDTO, string>;
+}
+export interface ModelRoutingDTO {
+    credentialSourceOrder?: string[];
+    familyOrder?: string[];
+    strengthFallback?: ModelStrengthDTO[];
+}
+export interface PutModelConfigRequest {
+    config_version: string;
+    modelRoutes: Record<string, ModelRouteConfigDTO>;
+    modelRouting: ModelRoutingDTO;
+    kinds: Record<string, {
+        model: string;
+        orchestratorModel?: string;
+    }>;
+}
+export interface PutModelConfigResponse {
+    config_version: string;
+    delivered: true;
+}

package/dist/api/dto/model-config.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,132 @@
+/** `PUT /v1/model-auth/{provider}` body — a discriminated union over credential
+ *  kind. Idempotent upsert/rotate keyed by provider (and `account_id` for a
+ *  managed account). */
+export type InstallCredentialRequest = {
+    kind: 'api_key';
+    api_key: string;
+} | {
+    kind: 'oauth';
+    access_token: string;
+    /** Required — pi's `OAuthCredentials` always carries both; the handler is
+     *  fail-loud (400) when either is absent, so the type matches (no lenient
+     *  fallback). */
+    refresh_token: string;
+    expires_at: string;
+    account_id?: string;
+    /** Provider-specific credential keys beyond the canonical tokens (e.g.
+     *  github-copilot's `enterpriseUrl`), retained for enterprise routing and
+     *  token refresh. */
+    extra?: Record<string, unknown>;
+} | {
+    kind: 'managed_account';
+    /** Optional requested label. A bare provider login automatically labels a newly seen
+     *  account from its identity profile. */
+    label?: string;
+    auto_label?: boolean;
+    account_id?: string;
+    access_token: string;
+    /** Required — the managed login always returns both; the handler is
+     *  fail-loud (400) when either is absent. */
+    refresh_token: string;
+    expires_at: string;
+    /** Causal-cooldown floor snapshotted before the interactive login flow. Epoch ms. */
+    last_rate_limited_at?: number;
+};
+/** Result of a credential install/rotate. */
+export interface CredentialResultDTO {
+    provider: string;
+    installed: true;
+    managed: boolean;
+    account_id?: string;
+}
+/** One managed-pool account, projected without credential material. Timestamps are
+ * ISO strings so remote consumers do not need to understand pi's epoch-ms storage. */
+export interface ManagedAccountStatusDTO {
+    label: string;
+    expires_at: string;
+    /** Account-wide cooldown: every model on the account is cooling until this instant. */
+    rate_limited_until: string;
+    /** Per-model-family cooldowns still in force (e.g. `opus` from an Opus weekly window); other families on the account stay usable. */
+    model_cooldowns?: Array<{
+        family: string;
+        rate_limited_until: string;
+    }>;
+    auth_failure?: 'invalid_grant';
+    account_id?: string;
+}
+/** A provider's sanitized credential state. Managed providers are always listed
+ * (even with no accounts); non-managed providers appear only when auth.json has
+ * an API-key or OAuth credential for them. */
+export type ModelAuthProviderStatusDTO = {
+    provider: string;
+    managed: true;
+    configured: boolean;
+    accounts: ManagedAccountStatusDTO[];
+} | {
+    provider: string;
+    managed: false;
+    configured: true;
+    kind: 'api_key' | 'oauth';
+};
+/** `GET /v1/model-auth` — credential-presence projection for every known provider. */
+export interface ModelAuthListDTO {
+    providers: ModelAuthProviderStatusDTO[];
+}
+/** Inputs that select the exact provider a new root node would use. */
+export interface ModelAuthReadinessQuery {
+    profile?: string;
+    cwd?: string;
+    kind?: string;
+    model?: string;
+}
+/** `GET /v1/model-auth/readiness` — credential state for the provider selected by a prospective root launch. */
+export interface ModelAuthReadinessDTO {
+    provider: string;
+    model: string;
+    credential: 'ready' | 'missing' | 'unusable';
+    reason?: 'invalid_grant';
+    rate_limited_until?: string | null;
+}
+/** `DELETE /v1/model-auth/{provider}` — all user credentials removed for one provider. */
+export interface CredentialRemovalResultDTO {
+    provider: string;
+    removed_accounts: number;
+}
+/** `POST /v1/model-auth/flows` (`model_auth.start`) — begin a daemon-run vendor
+ *  sign-in. `openai` is accepted as `openai-codex`; `openai-chatgpt` starts Sign in
+ *  with ChatGPT for the runtime provider `openai`. `redirect: "loopback"` makes
+ *  the daemon listen on the vendor's registered localhost port (self-host only). */
+export interface StartModelAuthFlowRequest {
+    provider: 'anthropic' | 'openai-codex' | 'openai' | 'openai-chatgpt';
+    redirect?: 'loopback';
+    /** Name for the signed-in account; omitted, a newly seen account is auto-labeled. */
+    label?: string;
+}
+/** The started flow: open `url`; for Anthropic's code page paste the code back
+ *  through `complete`; for OpenAI's device flow enter `user_code` at `url`; for
+ *  ChatGPT paste the final redirect URL through `complete`. `provider` is the
+ *  runtime provider id (`openai` for ChatGPT). */
+export interface ModelAuthFlowStartedDTO {
+    flow_id: string;
+    provider: 'anthropic' | 'openai-codex' | 'openai';
+    url: string;
+    instructions: string;
+    user_code?: string;
+    expires_at: string;
+}
+/** `POST /v1/model-auth/flows/{flow_id}/complete` (`model_auth.complete`). */
+export interface CompleteModelAuthFlowRequest {
+    input: string;
+}
+export interface ModelAuthFlowCompletedDTO {
+    flow_id: string;
+    provider: 'anthropic' | 'openai-codex' | 'openai';
+    status: 'connected';
+}
+/** `GET /v1/model-auth/flows/{flow_id}` — a flow's state. */
+export interface ModelAuthFlowDTO {
+    flow_id: string;
+    provider: 'anthropic' | 'openai-codex' | 'openai';
+    status: 'pending' | 'connected' | 'failed' | 'expired';
+    message?: string;
+}

package/dist/api/dto/modelauth.js

@@ -0,0 +1,4 @@
+// Model-auth DTOs (spec §7.6). `PUT /v1/model-auth/{provider}` installs/rotates
+// already-obtained credential material; `GET /v1/model-auth` exposes only sanitized
+// connection state; interactive collection stays client-side.
+export {};