@north-light/api 0.0.0 → 0.3.415

package/dist/api/client.d.ts

@@ -0,0 +1,521 @@
+import { ApiError } from './errors.js';
+import type { AppLimitsChangeDTO, LimitsDTO, SetAppLimitsRequest } from './dto/limits.js';
+import type { DaemonAdmitDTO, DaemonRestartDTO, DueDTO, HealthDTO, MigrateStateDTO, MigrateStateRequest, StatusDTO } from './dto/health.js';
+import type { BashJobStatusDTO, BashJobStopResultDTO } from './dto/bash-jobs.js';
+import type { ContextListDTO, CreateNodeRequest, ListNodesQuery, NodeDetailDTO, NodeMessagesPageDTO, NodeMessagesQuery, NodeSessionDTO, NodeSnapshotDTO, NodeSubjectDTO, NodeSummaryDTO, TranscriptDTO, TranscriptQuery } from './dto/nodes.js';
+import type { NodeOutcomeResponseDTO, OutcomeDeliveryDTO, RegisterOutcomeDeliveryRequest } from './dto/node-outcomes.js';
+import type { AnalyticsDTO, AnalyticsQuery, MemoryReadsRequestDTO } from './dto/analytics.js';
+import type { NodeEventsQuery } from './dto/node-events.js';
+import type { BrokerSignalLineDTO } from './dto/broker-signals.js';
+import type { NodeLogAppendRequest, NodeLogAppendResultDTO, NodeTelemetryRecordRequest, NodeRecapRecordRequest, NodeMessageBodyDTO, NodePushedFinalRequest, NodePushedFinalResultDTO } from './dto/node-records.js';
+import type { InterruptResultDTO, MessageResultDTO, SendMessageRequest } from './dto/messages.js';
+import type { CreateStructuredRequest, CreateStructuredRequestResponse, StructuredRequestDTO } from './dto/structured-requests.js';
+import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery, SubmitResultDTO, SubmitResultRequest } from './dto/reports.js';
+import type { CloseRequest, CloseResultDTO, PromoteRequest, RelaunchRootResultDTO, ReviveRequest, ReviveResultDTO, WaitRequest, YieldRequest } from './dto/lifecycle.js';
+import type { SubscribeRequest, SubscriptionDTO } from './dto/subscriptions.js';
+import type { FocusDTO, RegisterFocusRequest, SetFocusPaneRequest } from './dto/focus.js';
+import { type ArmCronRequest, type CancelCronQuery, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery, type PokeCronsResult } from './dto/crons.js';
+import type { KindListDTO, NodeConfigPatch } from './dto/config.js';
+import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js';
+import type { CreateProfileRequest, DeleteProfileRequest, DeleteProfileResultDTO, EnsureProfileRequest, ProfileDTO, ProfileEnvChangeDTO, ProfileEnvNamesDTO, ProfilePauseResultDTO, UpdateProfileMetadataRequest, UpdateProfileRequest } from './dto/profiles.js';
+import type { FileEncoding, FileListDTO, FilePeekDTO, FileWriteDTO } from './dto/files.js';
+import type { BashRunDTO, BashRunParams } from './dto/bash.js';
+import type { EdgesDTO, EdgesQuery, ObjectListDTO, ObjectListRequest, ObjectReadDTO, ObjectReadQuery, ObjectSearchDTO, ObjectSearchRequest, UnwatchQuery, UnwatchResultDTO, WatchRequest, WatchResultDTO } from './dto/objects.js';
+import type { DocDeletedDTO, DocEditRequest, DocEditedDTO, DocHistoryDTO, DocHistoryQuery, DocLintDTO, DocLintRequest, DocMoveRequest, DocMovedDTO, DocWriteRequest, DocWrittenDTO, ReconcilePackagesDTO } from './dto/docs.js';
+import type { BackgroundedJobDTO, BackgroundedJobRequest, DeliveryDryRunRequest, DeliveryRequest, DeliveryResponse } from './dto/delivery.js';
+import type { ChatInventoryDTO, ProspectiveChatInventoryDTO, ProspectiveChatInventoryQuery } from './dto/chat-inventory.js';
+import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, CompleteModelAuthFlowRequest, ModelAuthFlowCompletedDTO, ModelAuthFlowDTO, ModelAuthFlowStartedDTO, ModelAuthListDTO, ModelAuthReadinessDTO, ModelAuthReadinessQuery, StartModelAuthFlowRequest } from './dto/modelauth.js';
+import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
+import type { CreateReviewCommentRequest, EditReviewCommentRequest, ListReviewCommentsQuery, ReadReviewCommentEventsQuery, ReviewCommentActionRequest, ReviewCommentDetailDTO, ReviewCommentEventsDTO, ReviewCommentForkDTO, ReviewCommentListDTO, ReviewCommentMutationDTO, ReviewCommentRangeBatchRequest, ReviewCommentRangeBatchResultDTO } from './dto/review-comments.js';
+import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, InboxPageDTO, InboxPageHistoryDTO, InboxPageResponseDTO, InboxTicketIdDTO, PageFeedbackResolutionDTO, PageResponsesDTO, PageTicketResultDTO, RespondInboxPageRequest } from './dto/inbox.js';
+import type { CreateHumanRequestDTO, CreateHumanRequestRequest, HumanRequestDTO, HumanRequestIdDTO, ReplaceHumanRequestRequest, RespondHumanRequestRequest, SettleHumanRequestRequest, PageComponentListDTO } from './dto/human-requests.js';
+import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryStatsQuery, HistoryStatsResultDTO, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, GraphDTO, PruneRequest, PruneResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
+import type { AbandonWorktreeRequest, AbandonWorktreeResultDTO, CloseWorktreeResultDTO, QuarantinedWorktreeDTO, SpaceListDTO } from './dto/worktree.js';
+import type { BrokerExtensionStateDTO, BrokerExecutionRequest, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerParkActivityResultDTO, BrokerParkCompleteRequest, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest, BrokerTelemetryRequest } from './dto/broker-ops.js';
+import type { AcknowledgeMailRequest, AcknowledgeMailResultDTO, ClaimMailRequest, ClaimMailResultDTO } from './dto/mail.js';
+import type { BrokerFaultInputDTO, BrokerFaultRequest, BrokerFaultResultDTO, BrokerProviderRetryRequest, BrokerProviderRetryResultDTO, BrokerTurnRequest, BrokerTurnResultDTO, NodeFaultClearResultDTO, RecoveryStateDTO } from './dto/recovery.js';
+export interface CrtrClientOptions {
+    /** `http(s)://host:port` for a TCP/remote transport. */
+    baseUrl: string;
+    /** Fetch implementation. The global Web fetch is used unless a caller supplies one. */
+    fetch?: typeof fetch;
+    /** Extra headers, e.g. `{ authorization: 'Bearer <token>' }` when the target
+     *  crtrd's TCP listener has `CRTRD_TOKEN` set (unix-socket transport is
+     *  never checked, and a TCP daemon with no token set ignores this too). */
+    headers?: Record<string, string>;
+    /** Retry a cold local connection through this hook once when enabled. */
+    autostart?: boolean;
+    /** Maximum retries for transient GET, HEAD, and DELETE requests. Defaults to 2. */
+    maxRetries?: number;
+    /** Per-request timeout in ms (default 30_000). */
+    timeoutMs?: number;
+    /** Injected daemon-start hook (spec §7.1). Called once on a cold socket when
+     *  autostart is on; after it resolves, the client polls `/healthz` and retries
+     *  the original request once. Absent → a cold socket throws `daemon_unavailable`. */
+    onColdSocket?: () => Promise<void>;
+    /** Injected cold-start diagnostic. Called ONLY when the bounded
+     *  `/healthz` poll times out after `onColdSocket`, so the caller can attach
+     *  operator-useful context (e.g. a bounded tail of `crtrd.log`) to the
+     *  `daemon_unavailable` error instead of it staying a bare message. Must
+     *  return synchronously and cheaply — it runs on the failure path, not the
+     *  happy path. A thrown/undefined result is treated as "no diagnostic". */
+    coldStartDiagnostic?: () => string | undefined;
+    /** Polled during the cold-start wait: a string means the daemon this client
+     *  started has terminally failed (it exited before becoming ready), so the
+     *  wait ends immediately with that text instead of polling out the window. */
+    coldStartFailure?: () => string | undefined;
+    /** Strict wall-clock window (ms) for local API availability after a cold
+     * socket or interrupted response. Each probe is capped to the remaining
+     * budget. Defaults to `HEALTHZ_POLL_WINDOW_MS`. */
+    coldStartPollWindowMs?: number;
+}
+/** One strict wall-clock availability window shared by local API clients and
+ * daemon management. Each probe gets only the budget remaining at its start. */
+export declare function waitForDaemonAvailability({ windowMs, probe, initialError, pollIntervalMs, retry, now, sleep, }: {
+    windowMs: number;
+    probe: (timeoutMs: number) => Promise<void>;
+    initialError?: unknown;
+    pollIntervalMs?: number;
+    retry?: (error: unknown) => boolean;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void> | void;
+}): Promise<void>;
+export interface CrtrRequestOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeout?: number;
+    maxRetries?: number;
+    /** Limits the full call — every attempt, response body, and cold-socket or
+     * interrupted-response recovery — to one wall-clock budget, without changing
+     * the client's default inactivity timeout. */
+    budgetMs?: number;
+    /** The same limit as an absolute instant (epoch milliseconds), for a caller that already holds one deadline
+     *  for a larger operation and passes it to every call inside it. With `budgetMs` too, the earlier wins. */
+    deadlineAt?: number;
+}
+/** Why a call stopped at its deadline: `elapsed` — the time ran out; `retry_after` — the server asked for a wait
+ *  longer than the time left, so the call stopped without sleeping. */
+export type DeadlineReason = 'elapsed' | 'retry_after';
+/** The one error a call raises when its deadline passes (or a wait would pass it): status 504, code `deadline_exceeded`,
+ *  `details: { deadline_at, reason, retry_after_s? }`. */
+/** The longest delay a timer accepts (2^31-1 ms, about 24.8 days); a longer deadline would fire at once. */
+export declare const MAX_TIMER_MS = 2147483647;
+export declare function deadlineExceeded(deadlineAt: number, reason?: DeadlineReason, retryAfterS?: number): ApiError;
+export declare class CrtrClient {
+    private readonly baseUrl;
+    private readonly fetch;
+    private readonly headers;
+    private readonly autostart;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly localSocketTransport;
+    private readonly onColdSocket?;
+    private readonly coldStartDiagnostic?;
+    private readonly coldStartFailure?;
+    private readonly coldStartPollWindowMs;
+    /** Set when the last availability wait ended on a daemon startup failure, whose message already says why. */
+    private startupFailureReported;
+    /** Guards against invoking the daemon-start hook more than once per client. */
+    private coldStartAttempted;
+    constructor(opts: CrtrClientOptions);
+    healthz(): Promise<HealthDTO>;
+    /** One `/healthz` observation without cold-socket recovery. Availability
+     * waiters own retry policy and pass their remaining wall-clock budget here. */
+    probeHealthz(timeoutMs: number): Promise<HealthDTO>;
+    status(): Promise<StatusDTO>;
+    /** Busy and next-due state, the truth behind sandbox sleep and wake. */
+    due(): Promise<DueDTO>;
+    /** Ask the daemon to replace itself with a successor running the currently
+     *  selected runtime generation. Answers before the handover starts, so a
+     *  caller living inside a node the handover will tear down still gets a
+     *  settled result. */
+    restartDaemon(): Promise<DaemonRestartDTO>;
+    admitDaemon(): Promise<DaemonAdmitDTO>;
+    migrateState(req: MigrateStateRequest): Promise<MigrateStateDTO>;
+    appendNodeLog(id: string, req: NodeLogAppendRequest): Promise<NodeLogAppendResultDTO>;
+    putNodeTelemetry(id: string, req: NodeTelemetryRecordRequest): Promise<void>;
+    putNodeRecap(id: string, req: NodeRecapRecordRequest): Promise<void>;
+    readNodeInboxReport(id: string, ref: string, executionId: string): Promise<NodeMessageBodyDTO>;
+    readNodePassiveMessage(id: string, ref: string): Promise<NodeMessageBodyDTO>;
+    nodePushedFinal(id: string, req: NodePushedFinalRequest): Promise<NodePushedFinalResultDTO>;
+    createNode(req: CreateNodeRequest): Promise<NodeDetailDTO>;
+    /** List canvas nodes with composable row filters. `include: 'activity'` adds
+     * latest/canonical reports and pending-human counts in the same response. */
+    listNodes(q?: ListNodesQuery): Promise<NodeSummaryDTO[]>;
+    getNode(id: string): Promise<NodeDetailDTO>;
+    /** Read a node outcome, optionally awaiting it for at most 25 seconds. This
+     * is a GET so the client can safely replay it across daemon handover. */
+    getNodeOutcome(id: string, { waitSeconds }?: {
+        waitSeconds?: number;
+    }): Promise<NodeOutcomeResponseDTO>;
+    /** Open the raw server-sent event response for a node. The caller owns SSE
+     * parsing and must consume or cancel the response body. Streams deliberately
+     * have no client wall-clock timeout. */
+    getNodeEvents(id: string, query?: NodeEventsQuery, options?: Omit<CrtrRequestOptions, 'timeout'>): Promise<Response>;
+    /** Parsed NDJSON hints, consumed eagerly and line by line. The caller must
+     * cancel with `signal` when done; no wall-clock timeout applies to the stream. */
+    getBrokerSignals(id: string, executionId: string, options?: Omit<CrtrRequestOptions, 'timeout'>): AsyncIterable<BrokerSignalLineDTO>;
+    createStructuredRequest(req: CreateStructuredRequest, options?: CrtrRequestOptions): Promise<CreateStructuredRequestResponse>;
+    getStructuredRequest(requestId: string, { wait, budgetMs }?: {
+        wait?: number;
+        budgetMs?: number;
+    }): Promise<StructuredRequestDTO>;
+    cancelStructuredRequest(requestId: string, options?: CrtrRequestOptions): Promise<StructuredRequestDTO>;
+    /** Register or replace an armed target for terminal-outcome delivery. */
+    registerOutcomeDelivery(id: string, req: RegisterOutcomeDeliveryRequest): Promise<OutcomeDeliveryDTO>;
+    getOutcomeDelivery(id: string): Promise<OutcomeDeliveryDTO>;
+    /** Disarm an unsettled outcome-delivery registration. */
+    disarmOutcomeDelivery(id: string): Promise<void>;
+    listBashJobs(id: string): Promise<BashJobStatusDTO[]>;
+    stopBashJob(id: string, jobId: string): Promise<BashJobStopResultDTO>;
+    sendMessage(id: string, req: SendMessageRequest): Promise<MessageResultDTO>;
+    /** First-class interrupt (the human Esc): cancels pending undelivered
+     *  human-send inbox entries, then aborts a live in-flight turn. NEVER
+     *  revives a dormant target. */
+    interruptNode(id: string): Promise<InterruptResultDTO>;
+    pushReport(id: string, req: PushReportRequest): Promise<PushReportResultDTO>;
+    submitResult(id: string, req: SubmitResultRequest): Promise<SubmitResultDTO>;
+    forkNode(id: string): Promise<NodeDetailDTO>;
+    reviveNode(id: string, req?: ReviveRequest): Promise<ReviveResultDTO>;
+    relaunchRoot(id: string): Promise<RelaunchRootResultDTO>;
+    bindBrokerSession(id: string, req: BrokerSessionBoundRequest): Promise<BrokerSessionBoundResultDTO>;
+    settleBroker(id: string, req: BrokerSettleRequest): Promise<BrokerSettleDirective>;
+    completeBrokerPark(id: string, req: BrokerParkCompleteRequest): Promise<BrokerSettleDirective>;
+    recordBrokerParkActivity(id: string, req: BrokerExecutionRequest): Promise<BrokerParkActivityResultDTO>;
+    recordBrokerTelemetry(id: string, req: BrokerTelemetryRequest): Promise<void>;
+    claimNodeMail(id: string, req: ClaimMailRequest): Promise<ClaimMailResultDTO>;
+    acknowledgeNodeMail(id: string, req: AcknowledgeMailRequest): Promise<AcknowledgeMailResultDTO>;
+    recordBrokerTurn(id: string, req: BrokerTurnRequest): Promise<BrokerTurnResultDTO>;
+    mutateBrokerProviderRetry(id: string, req: BrokerProviderRetryRequest): Promise<BrokerProviderRetryResultDTO>;
+    mutateBrokerFault(id: string, req: BrokerFaultRequest): Promise<BrokerFaultResultDTO>;
+    getBrokerRecovery(id: string, expectedExecutionId: string): Promise<RecoveryStateDTO>;
+    recordNodeFault(id: string, req: BrokerFaultInputDTO): Promise<BrokerFaultResultDTO>;
+    clearNodeFault(id: string, opts?: {
+        link?: BrokerFaultInputDTO['link'];
+        preserve_episode?: boolean;
+    }): Promise<NodeFaultClearResultDTO>;
+    commitBrokerModel(id: string, req: BrokerModelCommitRequest): Promise<BrokerModelCommitResultDTO>;
+    brokerExtensionState(id: string): Promise<BrokerExtensionStateDTO>;
+    commitBrokerGeneratedName(id: string, req: BrokerGeneratedNameRequest): Promise<BrokerGeneratedNameResultDTO>;
+    commitBrokerPersonaAck(id: string, req: BrokerPersonaAckRequest): Promise<BrokerPersonaAckResultDTO>;
+    closeNode(id: string, req?: CloseRequest): Promise<CloseResultDTO>;
+    recycleNode(id: string): Promise<NodeDetailDTO>;
+    demoteNode(id: string): Promise<NodeDetailDTO>;
+    promoteNode(id: string, req: PromoteRequest): Promise<NodeDetailDTO>;
+    yieldNode(id: string, req: YieldRequest): Promise<NodeDetailDTO>;
+    waitNode(id: string, req: WaitRequest): Promise<NodeDetailDTO>;
+    listKinds(): Promise<KindListDTO>;
+    /** A model change may first wait up to 30 s for a starting broker's view
+     *  socket and then 15 s for its ack, so it gets that budget on top. */
+    patchConfig(id: string, patch: NodeConfigPatch): Promise<NodeDetailDTO>;
+    /** Land + close the node's managed git worktree (spec §6.2). Server-side
+     *  because it interleaves a canvas WRITE with a git land transaction and
+     *  crtrd is the repo host (same principle as spawnChild's creation git). */
+    closeWorktree(id: string): Promise<CloseWorktreeResultDTO>;
+    abandonWorktree(id: string, req: AbandonWorktreeRequest): Promise<AbandonWorktreeResultDTO>;
+    /** Re-queue a permanently failed push delivery or daemon action with a fresh attempt budget. */
+    retryDelivery(deliveryId: string): Promise<{
+        delivery_id: string;
+        state: 'pending';
+    }>;
+    listQuarantinedWorktrees(): Promise<QuarantinedWorktreeDTO[]>;
+    /** Effective per-app memory and disk caps and whether this host enforces them. */
+    showLimits(): Promise<LimitsDTO>;
+    setAppLimits(app: string, req: SetAppLimitsRequest): Promise<AppLimitsChangeDTO>;
+    removeAppLimits(app: string, fields: Array<'memory' | 'disk'>): Promise<AppLimitsChangeDTO>;
+    /** Every space on the runtime with its size. */
+    listSpaces(): Promise<SpaceListDTO>;
+    subscribe(id: string, req: SubscribeRequest): Promise<SubscriptionDTO>;
+    listFocuses(): Promise<FocusDTO[]>;
+    focusOf(nodeId: string): Promise<FocusDTO | null>;
+    focusByPane(pane: string): Promise<FocusDTO | null>;
+    registerFocus(req: RegisterFocusRequest): Promise<FocusDTO | null>;
+    setFocusPane(focusId: string, req: SetFocusPaneRequest): Promise<void>;
+    closeFocus(focusId: string): Promise<void>;
+    unsubscribe(id: string, target: string): Promise<void>;
+    /** Arm one cron (`POST /v1/crons`) — the server mints the cron_id. */
+    armCron(req: ArmCronRequest): Promise<CronDTO>;
+    /** Crons visible to the caller (`GET /v1/crons`). With `q.profile` that is
+     *  that profile's crons plus every global one; omit it only for a
+     *  canvas-home-wide provenance read ("which crons did node X arm"). */
+    listCrons(q?: ListCronsQuery): Promise<CronDTO[]>;
+    /** One cron with its run-log ring (`GET /v1/crons/:cronId`). */
+    showCron(cronId: string, q?: CronScopeQuery): Promise<CronShowDTO>;
+    /** Pause one cron (`POST /v1/crons/:cronId/pause`) — stops firing, keeps config+history. */
+    pauseCron(cronId: string, q?: CronScopeQuery): Promise<CronDTO>;
+    /** Resume one paused cron (`POST /v1/crons/:cronId/resume`). */
+    resumeCron(cronId: string, q?: CronScopeQuery): Promise<CronDTO>;
+    /** Run one cron NOW, out of band (`POST /v1/crons/:cronId/run`) — synchronous:
+     *  resolves with the settled run record after the subprocess closes. Does not
+     *  advance the schedule or consume a one-shot; never escalates. */
+    runCron(cronId: string, q?: CronScopeQuery): Promise<CronRunDTO>;
+    /** Cancel one cron (`DELETE /v1/crons/:cronId`, idempotent). */
+    cancelCron(cronId: string, q?: CancelCronQuery): Promise<void>;
+    /** Bare eligibility poke (`POST /v1/crons/poke`): re-dues every held active
+     *  cron now — "something changed; re-check now". Canvas-wide, label-free,
+     *  idempotent, and free when nothing is held. */
+    pokeCrons(): Promise<PokeCronsResult>;
+    ensureAttach(id: string, req?: AttachEnsureRequest): Promise<AttachEnsureResultDTO>;
+    getReports(id: string, q?: ReportsQuery): Promise<ReportDTO[]>;
+    getTranscript(id: string, q?: TranscriptQuery): Promise<TranscriptDTO>;
+    getSnapshot(id: string): Promise<NodeSnapshotDTO>;
+    /** The node-config subject substrate gates evaluate against. */
+    nodeSubject(id: string): Promise<NodeSubjectDTO>;
+    getNodeMessages(id: string, q?: NodeMessagesQuery): Promise<NodeMessagesPageDTO>;
+    /** The node's conversation exactly as it ran — raw `.jsonl` bytes plus the
+     *  assembled system prompt. For exports; `getSnapshot` is for renderers. */
+    getSession(id: string): Promise<NodeSessionDTO>;
+    /** What a non-terminal chat surface may offer for this node: the chat-capable
+     *  slash commands its live engine registered, and the memory documents an
+     *  inline `/name` token resolves to. Never revives — a node whose broker is
+     *  not live answers `broker_live: false` with empty arrays. */
+    getChatInventory(id: string): Promise<ChatInventoryDTO>;
+    getProspectiveChatInventory(q?: ProspectiveChatInventoryQuery): Promise<ProspectiveChatInventoryDTO>;
+    getContext(id: string): Promise<ContextListDTO>;
+    /** Read an absolute host path (capped, `truncated` when clipped). */
+    peekFile(path: string, encoding?: FileEncoding, options?: CrtrRequestOptions): Promise<FilePeekDTO>;
+    writeFile(path: string, content: string, encoding?: FileEncoding, options?: CrtrRequestOptions): Promise<FileWriteDTO>;
+    listFiles(path: string, limit?: number, options?: CrtrRequestOptions): Promise<FileListDTO>;
+    runBash(params: BashRunParams, options?: CrtrRequestOptions): Promise<BashRunDTO>;
+    /** `crtr canvas` shared verbs. A ref is a name (with or without `[[ ]]`) or a raw object id. */
+    readonly objects: {
+        read: (ref: string, query?: ObjectReadQuery) => Promise<ObjectReadDTO>;
+        list: (query?: ObjectListRequest) => Promise<ObjectListDTO>;
+        search: (request: ObjectSearchRequest) => Promise<ObjectSearchDTO>;
+        watch: (ref: string, request?: WatchRequest) => Promise<WatchResultDTO>;
+        unwatch: (ref: string, query?: UnwatchQuery) => Promise<UnwatchResultDTO>;
+        edges: (ref: string, query?: EdgesQuery) => Promise<EdgesDTO>;
+    };
+    /** `crtr doc` write verbs. */
+    readonly docs: {
+        write: (request: DocWriteRequest) => Promise<DocWrittenDTO>;
+        edit: (ref: string, request: DocEditRequest) => Promise<DocEditedDTO>;
+        move: (ref: string, request: DocMoveRequest) => Promise<DocMovedDTO>;
+        delete: (ref: string) => Promise<DocDeletedDTO>;
+        history: (ref: string, query?: DocHistoryQuery) => Promise<DocHistoryDTO>;
+        lint: (request?: DocLintRequest) => Promise<DocLintDTO>;
+    };
+    /** Package (builtin and plugin) documents. */
+    readonly documents: {
+        reconcilePackages: () => Promise<ReconcilePackagesDTO>;
+    };
+    /** The broker's delivery of one node activity. */
+    nodeDelivery(id: string, request: DeliveryRequest): Promise<DeliveryResponse>;
+    /** A person's dry run of one delivery activity, for a live or hypothetical node. Writes nothing. */
+    deliveryDryRun(request: DeliveryDryRunRequest): Promise<DeliveryResponse>;
+    /** Record a backgrounded bash command as a job object. */
+    recordBackgroundedJob(id: string, jobId: string, request: BackgroundedJobRequest): Promise<BackgroundedJobDTO>;
+    /** Create-or-return by name. Supplied `projects` are shape-checked even when
+     *  the profile already exists; their directories are only required to exist
+     *  when this call creates the profile. */
+    ensureProfile(name: string, req?: EnsureProfileRequest): Promise<ProfileDTO>;
+    /** Create a profile of the caller's app; a name it already holds is refused. */
+    createProfile(req: CreateProfileRequest): Promise<ProfileDTO>;
+    listProfiles(): Promise<ProfileDTO[]>;
+    /** Rename, set the default kind, or add or remove one project. */
+    updateProfile(name: string, req: UpdateProfileRequest): Promise<ProfileDTO>;
+    listAppEnv(): Promise<{
+        names: string[];
+    }>;
+    setAppEnv(variable: string, value: string): Promise<{
+        changed: boolean;
+    }>;
+    removeAppEnv(variable: string): Promise<{
+        changed: boolean;
+    }>;
+    listProfileEnv(name: string): Promise<ProfileEnvNamesDTO>;
+    setProfileEnv(name: string, variable: string, value: string): Promise<ProfileEnvChangeDTO>;
+    removeProfileEnv(name: string, variable: string): Promise<ProfileEnvChangeDTO>;
+    getProfile(name: string): Promise<ProfileDTO>;
+    pauseProfile(name: string): Promise<ProfilePauseResultDTO>;
+    resumeProfile(name: string): Promise<ProfilePauseResultDTO>;
+    /** Merge and remove entries in a profile's metadata map. */
+    updateProfileMetadata(name: string, req: UpdateProfileMetadataRequest): Promise<ProfileDTO>;
+    /** Force-delete or detach one profile by exact id or unique name. */
+    deleteProfile(name: string, req: DeleteProfileRequest): Promise<DeleteProfileResultDTO>;
+    listModelAuth(): Promise<ModelAuthListDTO>;
+    getModelAuthReadiness(query?: ModelAuthReadinessQuery): Promise<ModelAuthReadinessDTO>;
+    installCredential(provider: string, req: InstallCredentialRequest): Promise<CredentialResultDTO>;
+    removeCredential(provider: string): Promise<CredentialRemovalResultDTO>;
+    /** `model_auth.start` — the daemon runs the vendor OAuth; the caller only shows `url`. */
+    startModelAuth(req: StartModelAuthFlowRequest): Promise<ModelAuthFlowStartedDTO>;
+    /** `model_auth.complete` — hand the daemon the code the vendor showed. */
+    completeModelAuth(flowId: string, req: CompleteModelAuthFlowRequest): Promise<ModelAuthFlowCompletedDTO>;
+    /** `model_auth.cancel` — end an in-flight flow the person gave up on; it writes nothing. */
+    cancelModelAuth(flowId: string): Promise<ModelAuthFlowDTO>;
+    /** A flow's state; `waitSeconds` (1-25) long-polls until it leaves `pending`. */
+    getModelAuthFlow(flowId: string, waitSeconds?: number): Promise<ModelAuthFlowDTO>;
+    createReview(req: CreateReviewRequest): Promise<ReviewDTO>;
+    listReviews(query?: ListReviewsQuery): Promise<ReviewListDTO>;
+    getReview(reviewId: string): Promise<ReviewDTO>;
+    submitReview(reviewId: string): Promise<ReviewSubmitResultDTO>;
+    cancelReview(reviewId: string, req?: CancelReviewRequest): Promise<ReviewCancelResultDTO>;
+    getReviewDocumentBase(reviewId: string): Promise<ReviewDocumentBaseDTO>;
+    createReviewComment(reviewId: string | undefined, req: CreateReviewCommentRequest): Promise<ReviewCommentMutationDTO>;
+    listReviewComments(reviewId?: string, query?: ListReviewCommentsQuery): Promise<ReviewCommentListDTO>;
+    readReviewCommentEvents(reviewId: string, query?: ReadReviewCommentEventsQuery): Promise<ReviewCommentEventsDTO>;
+    updateReviewCommentRanges(reviewId: string, req: ReviewCommentRangeBatchRequest): Promise<ReviewCommentRangeBatchResultDTO>;
+    getReviewComment(commentId: string): Promise<ReviewCommentDetailDTO>;
+    editReviewComment(commentId: string, req: EditReviewCommentRequest): Promise<ReviewCommentMutationDTO>;
+    resolveReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
+    reopenReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
+    deleteReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
+    forkReviewComment(commentId: string): Promise<ReviewCommentForkDTO>;
+    /** Pending page/review tickets across every available crouter-owned
+     *  humanloop root. */
+    listHumanInbox(): Promise<InboxListDTO>;
+    /** Read one page ticket by its opaque ticket id (pending, resolved, or canceled). */
+    getHumanInboxPage(ticketId: InboxTicketIdDTO): Promise<InboxPageDTO>;
+    /** All page tickets, oldest first (pending, resolved, or canceled) —
+     *  home-wide, or narrowed to one raising node when `nodeId` is given. */
+    getInboxHistory(nodeId?: string): Promise<InboxPageHistoryDTO>;
+    /** Submit responses for a page ticket. Single-assignment server-side: a competing
+     *  resolution races to `ticket_already_resolved`. */
+    respondHumanInboxPage(ticketId: InboxTicketIdDTO, request: RespondInboxPageRequest): Promise<PageTicketResultDTO>;
+    /** Autosave partial page work. Omitted slots are permitted in progress updates. */
+    postInboxProgress(ticketId: InboxTicketIdDTO, responses: PageResponsesDTO): Promise<void>;
+    /** Get the published response for a resolved page ticket. 404 if pending or canceled. */
+    getInboxResponse(ticketId: InboxTicketIdDTO): Promise<InboxPageResponseDTO>;
+    /** Cancel a ticket (terminal response, never deletion). */
+    cancelHumanInboxTicket(ticketId: InboxTicketIdDTO, request?: CancelInboxTicketRequest): Promise<CanceledTicketResultDTO>;
+    /** Create one durable human request. The minted `request_id` identifies the
+     *  request; inbox presentation has its own ticket id. An unresolvable
+     *  `action.name` is rejected before the page is published, leaving no inbox
+     *  row behind. */
+    createHumanRequest(request: CreateHumanRequestRequest): Promise<CreateHumanRequestDTO>;
+    /** Product page components registered on the runtime (config + enabled plugins). */
+    listPageComponents(): Promise<PageComponentListDTO>;
+    /** Read one request: its current state, its answer when answered, and the
+     *  delivery state of its completion action when it bound one. */
+    getHumanRequest(requestId: HumanRequestIdDTO): Promise<HumanRequestDTO>;
+    /** Revise a pending request's page in place. Identity, provenance, and the
+     *  frozen action binding are preserved; a settled request refuses. */
+    replaceHumanRequest(requestId: HumanRequestIdDTO, request: ReplaceHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** Settle a request `answered` programmatically. Races a human answer to the
+     *  same first-writer-wins result. */
+    respondHumanRequest(requestId: HumanRequestIdDTO, request: RespondHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** The recipient surface closing a request without answering. */
+    dismissHumanRequest(requestId: HumanRequestIdDTO, request?: SettleHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** The requester withdrawing its own request. */
+    cancelHumanRequest(requestId: HumanRequestIdDTO, request?: SettleHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** Resolve one page feedback comment — the bound companion's report that it
+     *  has been dealt with. `nodeId` names the caller; the daemon refuses any
+     *  node but the ticket's companion. Terminal for the comment; appends no
+     *  chat turn. */
+    resolvePageFeedbackComment(ticketId: InboxTicketIdDTO, commentId: string, nodeId: string): Promise<PageFeedbackResolutionDTO>;
+    /** Composed client-side from `GET /v1/nodes` + `GET /v1/status` (spec §6.3 —
+     *  the dashboard is absorbed into those two reads; there is no single route).
+     *  `generated_at` is the client-side capture instant of the composition. */
+    dashboard(q?: DashboardQuery): Promise<DashboardDTO>;
+    attention(): Promise<AttentionDTO>;
+    /** Per-node pending-ticket counts for a bounded viewer slice. */
+    attentionCounts(node_ids: string[]): Promise<AttentionCountsDTO>;
+    /** Ranked/filtered content search over the per-cwd episodic corpus
+     *  (`crtr canvas history search`). Optional query: ranked when present,
+     *  recency browse when omitted. POST-bodied — the query carries arrays and
+     *  free text; the whole search executes server-side (spec §6.3). */
+    historySearch(q: HistorySearchQuery): Promise<HistorySearchResultDTO>;
+    /** Required-pattern line-hit search over the per-cwd episodic corpus
+     *  (`crtr canvas history grep`). Distinct stable schema from `historySearch`
+     *  — POST-bodied for the same reasons. */
+    historyGrep(q: HistoryGrepQuery): Promise<HistoryGrepResultDTO>;
+    /** Resolve one `<node-id>:<relpath>` history ref to its full body
+     *  (`crtr canvas history read`). */
+    historyRead(q: HistoryReadQuery): Promise<HistoryReadResultDTO>;
+    /** Grouped-count projection over the per-cwd episodic corpus
+     *  (`crtr canvas history stats`). Same filters as search/grep, aggregate
+     *  result instead of a hit page — POST-bodied for the same reasons. */
+    historyStats(q: HistoryStatsQuery): Promise<HistoryStatsResultDTO>;
+    /** The machine-readable browser canvas roster (`crtr canvas snapshot`) —
+     *  distinct from the per-node `getSnapshot`. */
+    canvasSnapshot(): Promise<SnapshotDTO>;
+    /** The Analytics page model (`GET /v1/canvas/analytics`). The
+     *  daemon scans transcripts for the window: a cold 7d scan of ~2 GB of
+     *  transcripts measured 10 s, and with scan workers capped at 4 a queued
+     *  request waits about one scan more. 60 s is 3x that worst case; past it the
+     *  page shows the error instead of computing forever. */
+    analytics(q: AnalyticsQuery): Promise<AnalyticsDTO>;
+    /** Record memory reads/loads for one node (`POST /v1/nodes/:id/memory-reads`). */
+    recordMemoryReads(nodeId: string, body: MemoryReadsRequestDTO): Promise<void>;
+    /** The lean, set-based topology roster (`GET /v1/canvas/roster`) — exactly
+     *  two indexed queries server-side, no per-row enrichment. The recurring
+     *  poll target for attach/browser topology; use `canvasSnapshot` for the
+     *  enriched on-demand view. */
+    canvasRoster(): Promise<RosterDTO>;
+    /** Explicitly compressed browse snapshot; the Node-only canvas source
+     * decompresses it because socketFetch does not interpret content-encoding. */
+    canvasBrowseCompressed(): Promise<Uint8Array>;
+    /** The lean attach-graph projection: display rows, topology, and focus state
+     * in one daemon-owned read rather than the full node-summary list. */
+    canvasGraph(): Promise<GraphDTO>;
+    prune(req: PruneRequest): Promise<PruneResultDTO>;
+    /** Raw request for routes not yet method-wrapped. Applies the same
+     *  autostart + retry + error-mapping semantics. */
+    request<T>(method: string, path: string, body?: unknown, opts?: CrtrRequestOptions): Promise<T>;
+    /** Open a live response with the normal cold-socket and retry policy, without consuming its body. */
+    rawResponse(method: string, path: string, opts?: CrtrRequestOptions): Promise<Response>;
+    /** The unparsed request: cold-socket and interrupted-response recovery, plus
+     *  the §7 retry policy (connection errors and 429/5xx on GET/HEAD/DELETE
+     *  only — POST/PATCH are never replayed once a request has actually been
+     *  sent). No JSON parse; every wrapper goes through here. */
+    private send;
+    private resolveBudget;
+    private awaitWithinBudget;
+    /** One transport attempt, deliberately without retry, cold-socket, or interrupted-response recovery. */
+    private sendOnce;
+    private nodePath;
+    /** Validate a background job id before route construction. Job ids arrive
+     *  from the daemon's file-backed roster and must remain one path segment. */
+    private jobPath;
+    /** Validate a cron id before route construction — `routes.ts` interpolates
+     *  it raw, so a value carrying `/`, whitespace or `?` would corrupt the
+     *  request line rather than 404 cleanly. Mirrors `nodePath`. */
+    private cronPath;
+    /** Validate a request id before route construction. Requests use the daemon's
+     * node-id-shaped identifiers, while inbox presentation uses a separate ticket
+     * id. A malformed request id is a server-rejectable request. */
+    private requestPath;
+    /** Validate an opaque inbox ticket id before route construction. A local
+     *  shape violation is a caller bug, not a server-rejectable request — throws
+     *  `TypeError` (matching the existing safe-segment discipline of a local
+     *  precondition, distinct from `nodePath`'s `ApiError` because that one IS a
+     *  request the server could plausibly receive and reject itself). */
+    private ticketId;
+    /** Validate a review id before route construction (D-A6). Reviews are minted
+     *  and addressed like node ids, but arrive from agent argv, so a malformed
+     *  one is a plausible request the server would also reject — `ApiError`,
+     *  not `TypeError`, matching `nodePath`. */
+    private reviewPath;
+    /** Validate a comment id before route construction (D-A6). Comment ids are
+     *  daemon-minted 32-char lowercase hex, but — like `reviewPath` — arrive from
+     *  agent argv, so a bad one is a plausible request the server would also
+     *  reject, not a caller-bug `TypeError` like `ticketId`. */
+    private commentPath;
+    /** The one fetch path (§1). Resolves as soon as headers arrive — the body
+     *  stays an unread `ReadableStream` on the returned `Response`, so a caller
+     *  that wants to stream (SSE, later) never waits on a buffered body. */
+    private transport;
+    private retainRequestLifetime;
+    private isColdSocketError;
+    /** A connection torn down MID-request (Node's "socket hang up" / a broken
+     * pipe). It establishes only that the response was interrupted, not why. */
+    private isInterruptedSocketError;
+    /** Wait for the local API after an interrupted response. GET/HEAD can retry
+     * because they are idempotent. A mutation may already have been applied, so
+     * it never replays. */
+    private rideOutInterruptedRequest;
+    private awaitAvailability;
+    /** Optionally start the daemon, then observe availability before retrying the
+     * request. Waiting is independent from permission to spawn: externally
+     * managed daemons still get the same bounded readiness window. */
+    private handleColdSocket;
+}
+/** One retry wait inside a call's deadline. A server-requested wait (`retryAfterS`) is honored only against a deadline:
+ *  when it would not finish before the deadline the call fails now with `deadline_exceeded` (`reason: 'retry_after'`)
+ *  instead of sleeping past it; a call without a deadline keeps the plain backoff. The sleep ends early, with the same
+ *  error, if the caller aborts. */
+export declare function sleepWithin(backoffMs: number, opts: {
+    deadlineAt?: number;
+    signal?: AbortSignal;
+}, retryAfterS?: number, cause?: unknown): Promise<void>;
+export declare function safeColdStartDiagnostic(hook: (() => string | undefined) | undefined): string | undefined;