@north-light/cli 0.0.0-stage → 0.3.413

package/dist/api/client.d.ts

@@ -0,0 +1,501 @@
+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;
+}
+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;
+}
+export declare function safeColdStartDiagnostic(hook: (() => string | undefined) | undefined): string | undefined;

package/dist/api/client.js

@@ -0,0 +1,3 @@
+var k=Object.defineProperty;var u=(n,e)=>k(n,"name",{value:e,configurable:!0});import{ApiError as m,isErrorBody as C}from"./errors.js";import{routes as r}from"./routes.js";import{isSafeNodeId as p}from"./dto/common.js";import{isSafeBashJobId as G}from"./dto/bash-jobs.js";import{isSafeCronId as A}from"./dto/crons.js";const M=3e4,N=Symbol.for("@north-light/api/local-socket-fetch"),_=1e4,D=200;async function x({windowMs:n,probe:e,initialError:t,pollIntervalMs:s=D,retry:i=u(()=>!0,"retry"),now:o=Date.now,sleep:h=y}){const d=o()+n;let c=t;for(;;){const f=d-o();if(f<=0)throw c??new Error("crtrd availability window expired without a probe failure");try{await e(f);return}catch(P){if(c=P,!i(P))throw P}const l=d-o();if(l<=0)throw c;await h(Math.min(s,l))}}u(x,"waitForDaemonAvailability");const E=u(()=>Object.assign(new Error("request budget exhausted"),{code:"ETIMEDOUT"}),"budgetExhausted");class W{static{u(this,"CrtrClient")}baseUrl;fetch;headers;autostart;timeoutMs;maxRetries;localSocketTransport;onColdSocket;coldStartDiagnostic;coldStartFailure;coldStartPollWindowMs;startupFailureReported=!1;coldStartAttempted=!1;constructor(e){if(e.baseUrl==="")throw new TypeError("CrtrClient requires baseUrl");this.baseUrl=new URL(e.baseUrl),this.fetch=e.fetch??globalThis.fetch,this.headers={...e.headers},this.autostart=e.autostart??!1,this.timeoutMs=e.timeoutMs??M,this.maxRetries=e.maxRetries??2,this.localSocketTransport=this.fetch[N]===!0,e.onColdSocket!==void 0&&(this.onColdSocket=e.onColdSocket),e.coldStartDiagnostic!==void 0&&(this.coldStartDiagnostic=e.coldStartDiagnostic),e.coldStartFailure!==void 0&&(this.coldStartFailure=e.coldStartFailure),this.coldStartPollWindowMs=e.coldStartPollWindowMs??_}healthz(){return this.request("GET",r.healthz())}async probeHealthz(e){const t=await this.transport("GET",r.healthz(),void 0,{timeout:e});if(t.status===503)try{const s=await t.clone().json();if(typeof s.startup_blocked=="string")return s}catch{}return w(t)}status(){return this.request("GET",r.status())}due(){return this.request("GET",r.due())}restartDaemon(){return this.request("POST",r.daemonRestart())}admitDaemon(){return this.request("POST",r.daemonAdmit())}migrateState(e){return this.request("POST",r.daemonMigrate(),e)}appendNodeLog(e,t){return this.request("POST",r.nodeLog(this.nodePath(e)),t)}async putNodeTelemetry(e,t){await this.request("PUT",r.nodeTelemetry(this.nodePath(e)),t)}async putNodeRecap(e,t){await this.request("PUT",r.nodeRecap(this.nodePath(e)),t)}readNodeInboxReport(e,t,s){return this.request("GET",a(r.nodeInboxReport(this.nodePath(e)),{ref:t,execution_id:s}))}readNodePassiveMessage(e,t){return this.request("GET",a(r.nodePassiveMessage(this.nodePath(e)),{ref:t}))}nodePushedFinal(e,t){return this.request("POST",r.nodePushedFinal(this.nodePath(e)),t)}createNode(e){return this.request("POST",r.nodes(),e)}listNodes(e){return this.request("GET",a(r.nodes(),e))}getNode(e){return this.request("GET",r.node(this.nodePath(e)))}getNodeOutcome(e,{waitSeconds:t}={}){if(t!==void 0&&(!Number.isInteger(t)||t<0||t>25))throw new RangeError("waitSeconds must be an integer between 0 and 25");return this.request("GET",a(r.nodeOutcome(this.nodePath(e)),{wait:t}),void 0,{timeout:(t??0)*1e3+this.timeoutMs})}getNodeEvents(e,t={},s={}){if(t.after!==void 0&&(!Number.isSafeInteger(t.after)||t.after<0))throw new RangeError("after must be a non-negative safe integer");return this.transport("GET",a(r.nodeEvents(this.nodePath(e)),t),void 0,{...s,headers:{accept:"text/event-stream",...s.headers??{}},timeout:0})}async*getBrokerSignals(e,t,s={}){const i=await this.send("GET",a(r.nodeBrokerSignals(this.nodePath(e)),{execution_id:t}),void 0,{...s,headers:{accept:"application/x-ndjson",...s.headers??{}},timeout:0});if(!i.ok){await w(i);return}if(i.body===null)throw new m(i.status,"invalid_response","broker signal stream has no body");const o=i.body.getReader(),h=new TextDecoder;let d="";try{for(;;){const{done:c,value:f}=await o.read();if(c)break;d+=h.decode(f,{stream:!0});let l;for(;(l=d.indexOf(`
+`))!==-1;){const P=d.slice(0,l);d=d.slice(l+1),P!==""&&(yield JSON.parse(P))}}if(d+=h.decode(),d.trim()!=="")throw new m(502,"invalid_response","broker signal stream ended mid-line")}finally{await o.cancel().catch(()=>{})}}createStructuredRequest(e,t){return e.mode==="sync"?this.sendOnce("POST","/v1/structured-requests",e,t):this.request("POST","/v1/structured-requests",e,t)}getStructuredRequest(e,{wait:t=0,budgetMs:s}={}){if(!Number.isInteger(t)||t<0||t>25)throw new RangeError("wait must be an integer between 0 and 25");return this.request("GET",a(`/v1/structured-requests/${this.requestPath(e)}`,{wait:t}),void 0,{budgetMs:s})}cancelStructuredRequest(e,t){return this.request("POST",`/v1/structured-requests/${this.requestPath(e)}/cancel`,{},t)}registerOutcomeDelivery(e,t){return this.request("PUT",r.nodeOutcomeDelivery(this.nodePath(e)),t)}getOutcomeDelivery(e){return this.request("GET",r.nodeOutcomeDelivery(this.nodePath(e)))}async disarmOutcomeDelivery(e){await this.request("DELETE",r.nodeOutcomeDelivery(this.nodePath(e)))}listBashJobs(e){return this.request("GET",r.nodeJobs(this.nodePath(e)))}stopBashJob(e,t){return this.request("DELETE",r.nodeJob(this.nodePath(e),this.jobPath(t)))}sendMessage(e,t){return this.request("POST",r.nodeMessages(this.nodePath(e)),t)}interruptNode(e){return this.request("POST",r.nodeInterrupt(this.nodePath(e)),{})}pushReport(e,t){return this.request("POST",r.nodeReports(this.nodePath(e)),t)}submitResult(e,t){return this.request("POST",r.nodeResult(this.nodePath(e)),t)}forkNode(e){return this.request("POST",r.nodeFork(this.nodePath(e)),{})}reviveNode(e,t){return this.request("POST",r.nodeRevive(this.nodePath(e)),t??{})}relaunchRoot(e){return this.request("POST",r.nodeRelaunchRoot(this.nodePath(e)),{})}bindBrokerSession(e,t){return this.request("POST",r.nodeBrokerSessionBound(this.nodePath(e)),t)}settleBroker(e,t){return this.request("POST",r.nodeBrokerSettle(this.nodePath(e)),t)}completeBrokerPark(e,t){return this.request("POST",r.nodeBrokerParkComplete(this.nodePath(e)),t)}recordBrokerParkActivity(e,t){return this.request("POST",r.nodeBrokerParkActivity(this.nodePath(e)),t)}async recordBrokerTelemetry(e,t){await this.request("POST",r.nodeBrokerTelemetry(this.nodePath(e)),t)}claimNodeMail(e,t){return this.request("POST",r.nodeMailClaim(this.nodePath(e)),t)}acknowledgeNodeMail(e,t){return this.request("POST",r.nodeMailAcknowledge(this.nodePath(e)),t)}recordBrokerTurn(e,t){return this.request("POST",r.brokerTurn(this.nodePath(e)),t)}mutateBrokerProviderRetry(e,t){return this.request("POST",r.brokerProviderRetry(this.nodePath(e)),t)}mutateBrokerFault(e,t){return this.request("POST",r.brokerFault(this.nodePath(e)),t)}getBrokerRecovery(e,t){return this.request("GET",`${r.brokerRecovery(this.nodePath(e))}?expected_execution_id=${encodeURIComponent(t)}`)}recordNodeFault(e,t){return this.request("POST",r.nodeFault(this.nodePath(e)),t)}clearNodeFault(e,t={}){const s=new URLSearchParams;t.link!==void 0&&s.set("link",t.link),t.preserve_episode!==void 0&&s.set("preserve_episode",String(t.preserve_episode));const i=s.size===0?"":`?${s.toString()}`;return this.request("DELETE",`${r.nodeFault(this.nodePath(e))}${i}`)}commitBrokerModel(e,t){return this.request("POST",r.nodeBrokerModel(this.nodePath(e)),t)}brokerExtensionState(e){return this.request("GET",r.nodeBrokerExtensionState(this.nodePath(e)))}commitBrokerGeneratedName(e,t){return this.request("POST",r.nodeBrokerGeneratedName(this.nodePath(e)),t)}commitBrokerPersonaAck(e,t){return this.request("POST",r.nodeBrokerPersonaAck(this.nodePath(e)),t)}closeNode(e,t){return this.request("POST",r.nodeClose(this.nodePath(e)),t??{})}recycleNode(e){return this.request("POST",r.nodeRecycle(this.nodePath(e)),{})}demoteNode(e){return this.request("POST",r.nodeDemote(this.nodePath(e)),{})}promoteNode(e,t){return this.request("POST",r.nodePromote(this.nodePath(e)),t)}yieldNode(e,t){return this.request("POST",r.nodeYield(this.nodePath(e)),t)}waitNode(e,t){return this.request("POST",r.nodeWait(this.nodePath(e)),t)}listKinds(){return this.request("GET",r.kinds())}patchConfig(e,t){return this.request("PATCH",r.nodeConfig(this.nodePath(e)),t,t.model!==void 0?{timeout:45e3+this.timeoutMs}:void 0)}closeWorktree(e){return this.request("POST",r.nodeWorktreeClose(this.nodePath(e)),{})}abandonWorktree(e,t){return this.request("POST",r.nodeWorktreeAbandon(this.nodePath(e)),t)}retryDelivery(e){return this.request("POST",r.deliveryRetry(e),{})}listQuarantinedWorktrees(){return this.request("GET",r.quarantinedWorktrees())}showLimits(){return this.request("GET",r.limits())}setAppLimits(e,t){return this.request("PUT",r.limitsApp(e),t)}removeAppLimits(e,t){return this.request("DELETE",a(r.limitsApp(e),{fields:t.join(",")}))}listSpaces(){return this.request("GET",r.spaces())}subscribe(e,t){return this.request("POST",r.nodeSubscriptions(this.nodePath(e)),t)}listFocuses(){return this.request("GET",r.focuses())}focusOf(e){return this.request("GET",a(r.focusByNode(),{node_id:e}))}focusByPane(e){return this.request("GET",a(r.focusByPane(),{pane:e}))}registerFocus(e){return this.request("POST",r.focuses(),e)}async setFocusPane(e,t){await this.request("PATCH",r.focus(e),t)}async closeFocus(e){await this.request("DELETE",r.focus(e))}async unsubscribe(e,t){await this.request("DELETE",r.nodeSubscription(this.nodePath(e),this.nodePath(t)))}armCron(e){return this.request("POST",r.crons(),e)}listCrons(e){return this.request("GET",a(r.crons(),e))}showCron(e,t){return this.request("GET",a(r.cron(this.cronPath(e)),t))}pauseCron(e,t){return this.request("POST",a(r.cronPause(this.cronPath(e)),t),{})}resumeCron(e,t){return this.request("POST",a(r.cronResume(this.cronPath(e)),t),{})}runCron(e,t){return this.request("POST",a(r.cronRun(this.cronPath(e)),t),{})}async cancelCron(e,t){await this.request("DELETE",a(r.cron(this.cronPath(e)),t))}pokeCrons(){return this.request("POST",r.cronsPoke(),{})}ensureAttach(e,t){return this.request("POST",r.nodeAttach(this.nodePath(e)),t??{})}getReports(e,t){return this.request("GET",a(r.nodeReports(this.nodePath(e)),t))}getTranscript(e,t){return this.request("GET",a(r.nodeTranscript(this.nodePath(e)),t))}getSnapshot(e){return this.request("GET",r.nodeSnapshot(this.nodePath(e)))}nodeSubject(e){return this.request("GET",r.nodeSubject(this.nodePath(e)))}getNodeMessages(e,t){return this.request("GET",a(r.nodeMessages(this.nodePath(e)),t))}getSession(e){return this.request("GET",r.nodeSession(this.nodePath(e)))}getChatInventory(e){return this.request("GET",r.nodeChatInventory(this.nodePath(e)))}getProspectiveChatInventory(e){return this.request("GET",a(r.prospectiveChatInventory(),e))}getContext(e){return this.request("GET",r.nodeContext(this.nodePath(e)))}peekFile(e,t,s){return this.request("GET",a(r.filePeek(),{path:e,encoding:t}),void 0,s)}writeFile(e,t,s,i){return this.request("POST",r.fileWrite(),{path:e,content:t,encoding:s},i)}listFiles(e,t,s){return this.request("GET",a(r.fileList(),{path:e,limit:t}),void 0,s)}runBash(e,t){return this.request("POST",r.bash(),e,t)}objects={read:u((e,t)=>this.request("GET",a(r.object(e),t)),"read"),list:u(e=>this.request("GET",a(r.objects(),e)),"list"),search:u(e=>this.request("POST",r.objectsSearch(),e),"search"),watch:u((e,t={})=>this.request("POST",r.objectWatch(e),t),"watch"),unwatch:u((e,t)=>this.request("DELETE",a(r.objectWatch(e),t)),"unwatch"),edges:u((e,t)=>this.request("GET",a(r.objectEdges(e),t)),"edges")};docs={write:u(e=>this.request("POST",r.docs(),e),"write"),edit:u((e,t)=>this.request("PATCH",r.doc(e),t),"edit"),move:u((e,t)=>this.request("POST",r.docMove(e),t),"move"),delete:u(e=>this.request("DELETE",r.doc(e)),"delete"),history:u((e,t)=>this.request("GET",a(r.docHistory(e),t)),"history"),lint:u((e={})=>this.request("POST",r.docsLint(),e),"lint")};documents={reconcilePackages:u(()=>this.request("POST",r.documentsReconcilePackages()),"reconcilePackages")};nodeDelivery(e,t){return this.request("POST",r.nodeDelivery(this.nodePath(e)),t)}deliveryDryRun(e){return this.request("POST",r.deliveryDryRun(),e)}recordBackgroundedJob(e,t,s){return this.request("POST",r.nodeJobBackground(this.nodePath(e),this.jobPath(t)),s)}ensureProfile(e,t){return this.request("PUT",r.profile(e),t??{})}createProfile(e){return this.request("POST",r.profiles(),e)}listProfiles(){return this.request("GET",r.profiles())}updateProfile(e,t){return this.request("PATCH",r.profile(e),t)}listAppEnv(){return this.request("GET",r.appEnv())}setAppEnv(e,t){return this.request("PUT",r.appEnvVar(e),{value:t})}removeAppEnv(e){return this.request("DELETE",r.appEnvVar(e))}listProfileEnv(e){return this.request("GET",r.profileEnv(e))}setProfileEnv(e,t,s){return this.request("PUT",r.profileEnvVar(e,t),{value:s})}removeProfileEnv(e,t){return this.request("DELETE",r.profileEnvVar(e,t))}getProfile(e){return this.request("GET",r.profile(e))}pauseProfile(e){return this.request("POST",r.profilePause(e),{})}resumeProfile(e){return this.request("POST",r.profileResume(e),{})}updateProfileMetadata(e,t){return this.request("PATCH",r.profileMetadata(e),t)}deleteProfile(e,t){return this.request("DELETE",r.profile(e),t)}listModelAuth(){return this.request("GET",r.modelAuths())}getModelAuthReadiness(e){return this.request("GET",a(r.modelAuthReadiness(),e))}installCredential(e,t){return this.request("PUT",r.modelAuth(e),t)}removeCredential(e){return this.request("DELETE",r.modelAuth(e))}startModelAuth(e){return this.request("POST",r.modelAuthFlows(),e,{timeout:3e4+this.timeoutMs})}completeModelAuth(e,t){return this.request("POST",r.modelAuthFlowComplete(e),t,{timeout:35e3+this.timeoutMs})}cancelModelAuth(e){return this.request("POST",r.modelAuthFlowCancel(e),{})}getModelAuthFlow(e,t){return this.request("GET",a(r.modelAuthFlow(e),{wait:t}),void 0,{timeout:(t??0)*1e3+this.timeoutMs})}createReview(e){return this.request("POST",r.humanReviews(),e)}listReviews(e){return this.request("GET",a(r.humanReviews(),e))}getReview(e){return this.request("GET",r.humanReview(this.reviewPath(e)))}submitReview(e){return this.request("POST",r.humanReviewSubmit(this.reviewPath(e)),{})}cancelReview(e,t={}){return this.request("POST",r.humanReviewCancel(this.reviewPath(e)),t)}getReviewDocumentBase(e){return this.request("GET",r.humanReviewDocument(this.reviewPath(e)))}createReviewComment(e,t){const s=e===void 0?"self":this.reviewPath(e);return this.request("POST",r.humanReviewComments(s),t)}listReviewComments(e,t){const s=e===void 0?"self":this.reviewPath(e);return this.request("GET",a(r.humanReviewComments(s),t))}readReviewCommentEvents(e,t){return this.request("GET",a(r.humanReviewCommentEvents(this.reviewPath(e)),t))}updateReviewCommentRanges(e,t){return this.request("POST",r.humanReviewCommentRanges(this.reviewPath(e)),t)}getReviewComment(e){return this.request("GET",r.humanComment(this.commentPath(e)))}editReviewComment(e,t){return this.request("POST",r.humanCommentEdit(this.commentPath(e)),t)}resolveReviewComment(e,t={}){return this.request("POST",r.humanCommentResolve(this.commentPath(e)),t)}reopenReviewComment(e,t={}){return this.request("POST",r.humanCommentReopen(this.commentPath(e)),t)}deleteReviewComment(e,t={}){return this.request("POST",r.humanCommentDelete(this.commentPath(e)),t)}forkReviewComment(e){return this.request("POST",r.humanCommentFork(this.commentPath(e)),{})}listHumanInbox(){return this.request("GET",r.humanInbox())}getHumanInboxPage(e){return this.request("GET",r.humanInboxTicket(this.ticketId(e)))}getInboxHistory(e){if(e===void 0)return this.request("GET",r.humanInbox()+"/history");if(typeof e!="string"||e==="")throw new TypeError(`invalid node id: ${JSON.stringify(e)}`);return this.request("GET",a(r.humanInbox()+"/history",{node_id:e}))}respondHumanInboxPage(e,t){return this.request("POST",r.humanInboxRespond(this.ticketId(e)),t)}postInboxProgress(e,t){return this.request("POST",r.humanInboxProgress(this.ticketId(e)),{responses:t})}getInboxResponse(e){return this.request("GET",r.humanInboxResponse(this.ticketId(e)))}cancelHumanInboxTicket(e,t){return this.request("POST",r.humanInboxCancel(this.ticketId(e)),t??{})}createHumanRequest(e){return this.request("POST",r.humanRequests(),e)}listPageComponents(){return this.request("GET",r.humanComponents())}getHumanRequest(e){return this.request("GET",r.humanRequest(this.requestPath(e)))}replaceHumanRequest(e,t){return this.request("POST",r.humanRequestReplace(this.requestPath(e)),t)}respondHumanRequest(e,t){return this.request("POST",r.humanRequestRespond(this.requestPath(e)),t)}dismissHumanRequest(e,t={}){return this.request("POST",r.humanRequestDismiss(this.requestPath(e)),t)}cancelHumanRequest(e,t={}){return this.request("POST",r.humanRequestCancel(this.requestPath(e)),t)}resolvePageFeedbackComment(e,t,s){if(!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(t))throw new TypeError(`invalid feedback comment id: ${JSON.stringify(t)}`);return this.request("POST",r.humanInboxFeedbackResolve(this.ticketId(e),t),{node_id:s})}async dashboard(e){const t=e?.under!==void 0?{under:e.under}:void 0,[s,i]=await Promise.all([this.listNodes(t),this.status()]);return{nodes:s,counts:i.node_counts,generated_at:new Date().toISOString()}}attention(){return this.request("GET",r.canvasAttention())}attentionCounts(e){const t={node_ids:e};return this.request("POST",r.canvasAttentionCounts(),t)}historySearch(e){return this.request("POST",r.canvasHistorySearch(),e)}historyGrep(e){return this.request("POST",r.canvasHistoryGrep(),e)}historyRead(e){return this.request("GET",a(r.canvasHistoryRead(),e))}historyStats(e){return this.request("POST",r.canvasHistoryStats(),e)}canvasSnapshot(){return this.request("GET",r.canvasSnapshot())}analytics(e){return this.request("GET",a(r.canvasAnalytics(),e),void 0,{timeout:6e4})}async recordMemoryReads(e,t){await this.request("POST",r.nodeMemoryReads(this.nodePath(e)),t)}canvasRoster(){return this.request("GET",r.canvasRoster())}async canvasBrowseCompressed(){const e=await this.send("GET",r.canvasBrowse());return e.ok||await w(e),new Uint8Array(await e.arrayBuffer())}canvasGraph(){return this.request("GET",r.canvasGraph())}prune(e){return this.request("POST",r.canvasPrune(),e)}async request(e,t,s,i){try{return await w(await this.send(e,t,s,i))}catch(o){throw T(o,i?.signal)}}async rawResponse(e,t,s){try{return await this.send(e,t,void 0,s)}catch(i){throw T(i,s?.signal)}}async send(e,t,s,i={}){const o=this.resolveBudget(i),h=e==="GET"||e==="HEAD"||e==="DELETE",d=o.maxRetries??this.maxRetries;for(let c=0;;c++){let f;try{f=await this.transport(e,t,s,o)}catch(l){if(this.isColdSocketError(l))try{await this.handleColdSocket(l,o.deadlineAt),f=await this.transport(e,t,s,o)}catch(P){throw T(P,o.signal)}else{if(this.isInterruptedSocketError(l)&&this.localSocketTransport&&(!h||c<d))return await this.rideOutInterruptedRequest(e,t,s,o);if(h&&c<d&&!I(l,o.signal)&&(!this.localSocketTransport||!this.isInterruptedSocketError(l))){await y(R(c+1));continue}else throw T(l,o.signal)}}if(h&&c<d&&B(f.status)){await b(f),await y(R(c+1));continue}return f}}resolveBudget(e){const{budgetMs:t,...s}=e;if(t===void 0)return s;if(!Number.isFinite(t)||t<=0)throw new RangeError("budgetMs must be a positive finite number");return{...s,deadlineAt:Date.now()+t}}async awaitWithinBudget(e,t){if(t===void 0)return e;const s=t-Date.now();if(s<=0)throw E();let i;try{return await Promise.race([e,new Promise((o,h)=>{i=setTimeout(()=>h(E()),s)})])}finally{i!==void 0&&clearTimeout(i)}}async sendOnce(e,t,s,i={}){const o=this.resolveBudget(i);try{return await w(await this.transport(e,t,s,o))}catch(h){throw T(h,o.signal)}}nodePath(e){if(!p(e))throw new m(400,"invalid_node_id",`invalid node id: ${JSON.stringify(e)}`);return e}jobPath(e){if(!G(e))throw new m(400,"invalid_job_id",`invalid background job id: ${JSON.stringify(e)}`);return e}cronPath(e){if(!A(e))throw new m(400,"invalid_cron_id",`invalid cron id: ${JSON.stringify(e)}`);return e}requestPath(e){if(!p(e))throw new m(400,"invalid_request_id",`invalid request id: ${JSON.stringify(e)}`);return e}ticketId(e){if(!/^[a-f0-9]{64}$/.test(e))throw new TypeError(`invalid inbox ticket id: ${JSON.stringify(e)}`);return e}reviewPath(e){if(!p(e))throw new m(400,"invalid_review_id",`invalid review id: ${JSON.stringify(e)}`);return e}commentPath(e){if(!/^[a-f0-9]{32}$/.test(e))throw new m(400,"invalid_comment_id",`invalid comment id: ${JSON.stringify(e)}`);return e}transport(e,t,s,i={}){const o=i.deadlineAt===void 0?void 0:i.deadlineAt-Date.now();if(o!==void 0&&o<=0)return Promise.reject(E());const h=s===void 0?void 0:JSON.stringify(s),d={accept:"application/json",...this.headers,...i.headers};h!==void 0&&(d["content-type"]="application/json");const c=i.timeout??this.timeoutMs,f=o===void 0?c:c>0?Math.min(c,o):o,l=new AbortController,P=f>0?setTimeout(()=>l.abort(new DOMException("request timed out","TimeoutError")),f):void 0,q=i.signal,g=u(()=>l.abort(q?.reason),"onExternalAbort");q!==void 0&&(q.aborted?l.abort(q.reason):q.addEventListener("abort",g,{once:!0}));const O=u(()=>{P!==void 0&&clearTimeout(P),q?.removeEventListener("abort",g)},"finish");return this.fetch(new URL(t,this.baseUrl),{method:e,headers:d,body:h,signal:l.signal}).then(S=>this.retainRequestLifetime(S,O,()=>l.signal.aborted?l.signal.reason:void 0),S=>{throw O(),S})}retainRequestLifetime(e,t,s){if(e.body===null)return t(),e;const i=e.body.getReader();let o=!1;const h=u(()=>{o||(o=!0,t())},"close"),d=new ReadableStream({async pull(c){try{const{done:f,value:l}=await i.read();f?(h(),c.close()):c.enqueue(l)}catch(f){h(),c.error(s()??f)}},async cancel(c){h(),await i.cancel(c)}});return new Response(d,{status:e.status,statusText:e.statusText,headers:e.headers})}isColdSocketError(e){const t=v(e);return t==="ECONNREFUSED"||t==="ENOENT"||t==="ENOTSOCK"}isInterruptedSocketError(e){const t=v(e);return t==="ECONNRESET"||t==="EPIPE"}async rideOutInterruptedRequest(e,t,s,i={}){try{await this.awaitAvailability(void 0,i.deadlineAt)}catch(o){throw T(o,i.signal)}if(e!=="GET"&&e!=="HEAD")throw new m(503,"daemon_request_interrupted",`crtrd connection ended before this ${e} response; the request may or may not have been applied.`);try{return await this.transport(e,t,s,i)}catch(o){throw T(o,i.signal)}}async awaitAvailability(e,t){const s=t===void 0?void 0:t-Date.now();if(s!==void 0&&s<=0)throw E();let i;try{await x({windowMs:Math.min(this.coldStartPollWindowMs,s??this.coldStartPollWindowMs),initialError:e,retry:u(o=>o!==i,"retry"),probe:u(async o=>{const h=this.coldStartFailure?.();if(h!==void 0)throw i=new m(503,"daemon_unavailable",`crtrd failed to start: ${h}`),i;const d=await this.transport("GET",r.healthz(),void 0,{timeout:o});if(d.status>=200&&d.status<300){await b(d);return}const c=await d.text();try{if(typeof JSON.parse(c).startup_blocked=="string")return}catch{}throw new m(d.status,"daemon_health_unavailable",`crtrd health check returned HTTP ${d.status}: ${c.slice(0,500)}`)},"probe")})}catch(o){throw o===i&&(this.startupFailureReported=!0),o}}async handleColdSocket(e,t){const s=this.autostart&&this.onColdSocket!==void 0&&!this.coldStartAttempted;s&&(this.coldStartAttempted=!0,await this.awaitWithinBudget(this.onColdSocket(),t));try{await this.awaitAvailability(e,t)}catch(i){if(s&&!this.startupFailureReported){const o=F(this.coldStartDiagnostic);if(o!==void 0){const h=T(i);throw new m(h.status,h.code,`${h.message}
+${o}`)}}throw i}}}function a(n,e){if(e===void 0)return n;const t=new URLSearchParams;for(const[i,o]of Object.entries(e))o!=null&&t.set(i,String(o));const s=t.toString();return s===""?n:`${n}?${s}`}u(a,"withQuery");async function w(n){const e=n.status>=200&&n.status<300,t=(await n.text()).trim();let s;if(t!=="")try{s=JSON.parse(t)}catch{if(e)return;throw new m(n.status,"invalid_response",t.slice(0,500),void 0,n.headers)}if(e)return s;throw C(s)?new m(n.status,s.error.code,s.error.message,s.error.details,n.headers,s.error):new m(n.status,"internal",`request failed with status ${n.status}`,void 0,n.headers)}u(w,"parse");function B(n){return n===429||n>=500}u(B,"isRetryableStatus");async function b(n){try{await n.body?.cancel()}catch{}}u(b,"drainResponseBody");function R(n){return Math.min(2e3,250*2**(n-1))}u(R,"retryDelayMs");function v(n){if(typeof n!="object"||n===null)return;const e=n.code;if(typeof e=="string")return e;const t=n.cause;if(typeof t=="object"&&t!==null){const s=t.code;if(typeof s=="string")return s}}u(v,"transportErrorCode");function I(n,e){return e?.aborted?!0:n instanceof DOMException&&(n.name==="AbortError"||n.name==="TimeoutError")}u(I,"isAbortError");function T(n,e){if(e?.aborted)return new m(0,"request_aborted","request aborted by caller signal");if(n instanceof m)return n;if(n instanceof DOMException&&n.name==="TimeoutError")return new m(504,"request_timeout",`crtrd request timed out: ${n.message}`);if(n instanceof DOMException&&n.name==="AbortError")return new m(0,"request_aborted","request aborted by caller signal");const t=v(n),s=n instanceof Error?n.message:String(n);return t==="ECONNREFUSED"||t==="ENOENT"||t==="ENOTSOCK"?new m(503,"daemon_unavailable",`crtrd is not reachable: ${s}`):t==="ETIMEDOUT"?new m(504,"request_timeout",`crtrd request timed out: ${s}`):new m(503,"transport_error",s)}u(T,"toTransportApiError");function y(n){return new Promise(e=>setTimeout(e,n))}u(y,"sleepMs");function F(n){if(n!==void 0)try{return n()}catch{return}}u(F,"safeColdStartDiagnostic");export{W as CrtrClient,F as safeColdStartDiagnostic,x as waitForDaemonAvailability};

package/dist/api/command-manifest/index.d.ts

@@ -0,0 +1,3 @@
+export * from './schema.js';
+export * from './manifest.js';
+export * from './result.js';

package/dist/api/command-manifest/index.js

@@ -0,0 +1 @@
+export*from"./schema.js";export*from"./manifest.js";export*from"./result.js";

package/dist/api/command-manifest/manifest.d.ts

@@ -0,0 +1,51 @@
+import type { DeclLeaf, DeclNode, TransportKind, ManifestTimeouts, CommandManifestIssue } from './schema.js';
+export interface ValidatedCoreMount {
+    /** The explicitly extensible core branch receiving this plugin node. */
+    parent: string[];
+    node: DeclNode<DeclLeaf>;
+}
+export interface ValidatedCommandManifest {
+    schemaVersion: 1;
+    /** The plugin's declared integer major (HTTP transport only); absent means
+     *  undeclared, which a locally installed plugin treats as 1. */
+    version?: number;
+    baseUrl?: string;
+    timeouts?: ManifestTimeouts;
+    /** Top-level plugin branches or repository-fragment nodes, ready to mount. */
+    roots: DeclNode<DeclLeaf>[];
+    /** Plugin nodes mounted below an explicitly extensible core branch. */
+    coreMounts: ValidatedCoreMount[];
+    /** Core command path (space-joined, e.g. "cron add") → attributed addendum
+     *  text appended beneath that core command's help. Append-only product
+     *  guidance — a plugin can never alter core contract text. */
+    helpAddenda?: Readonly<Record<string, string>>;
+}
+export interface CommandManifestValidation {
+    /** The validated, materialized manifest (present only if all issues are fixed). */
+    manifest?: ValidatedCommandManifest;
+    /** All typed validation issues. Any issue means zero contributions. */
+    issues: CommandManifestIssue[];
+}
+/**
+ * Validates a HTTP-transport plugin manifest exactly per §4, performing strict atomic
+ * validation and order-independent forest materialization. Returns either a
+ * valid manifest with roots ready to mount, or a complete issues list with
+ * zero contributions.
+ */
+export declare function validateCommandManifest(raw: unknown, options: {
+    transport: TransportKind;
+    reservedCoreNames: ReadonlySet<string>;
+    /** Every core command path (space-joined). Supplied at the strict gates
+     *  (install, bundle parse, doctor/inspect reports) so a helpAddenda key
+     *  naming no core command fails there — and by the help-render lookup
+     *  (`collectHelpAddenda`), which reproduces the gate's verdict so render
+     *  and ingress report can never disagree. Omitted on the tolerant compose
+     *  path, where mounting ignores addenda entirely, and on that lookup's
+     *  claimant pass, which only needs to know whether any addendum targets the
+     *  rendered path at all. */
+    coreCommandPaths?: ReadonlySet<string>;
+    /** A repository fragment attaches roots below an existing extensible branch. */
+    extensionFragment?: boolean;
+    /** Core branch names that accept plugin children. */
+    extensibleCoreBranches?: ReadonlySet<string>;
+}): CommandManifestValidation;