@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/worker/static-agent-token-store.d.ts

@@ -1,15 +1,12 @@
 /**
- * In-memory agent token store for worker nodes.
- *
- * Workers have no database access. This implementation stores token
- * hashes in memory and supports both static (long-lived) and ephemeral
- * (TTL-based) tokens with the same kat_ prefix format as the DB-backed
+ * In-memory agent token store for worker nodes, which have no database access.
+ * Supports static and ephemeral (TTL) tokens in the same format as the DB-backed
  * AgentTokenStore.
  *
  * Token format: kat_ + 64 hex chars (32 random bytes = 256 bits).
  * Only the SHA-256 hash is stored; plaintext is returned once at creation.
  */
-/** Safe token info returned from validate (matches SafeAgentTokenRow shape). */
+/** Matches the SafeAgentTokenRow shape. */
 interface SafeTokenInfo {
     id: string;
     token_prefix: string;
@@ -21,9 +18,6 @@ interface SafeTokenInfo {
 }
 export declare class StaticAgentTokenStore {
     private readonly tokens;
-    /**
-     * Create a static (long-lived) agent token.
-     */
     createStatic(opts: {
         labels?: string[];
         createdBy?: string;
@@ -31,27 +25,12 @@ export declare class StaticAgentTokenStore {
         token: string;
         id: string;
     }>;
-    /**
-     * Create an ephemeral (short-lived) agent token.
-     */
     createEphemeral(agentId: string, labels: string[], ttlMs: number): Promise<string>;
-    /**
-     * Validate a plaintext token.
-     *
-     * Returns token info if valid, null if unknown/revoked/expired.
-     */
+    /** Returns null for an unknown, revoked or expired token. */
     validate(token: string): Promise<SafeTokenInfo | null>;
-    /**
-     * Revoke a token by ID.
-     *
-     * @returns true if newly revoked, false if not found or already revoked.
-     */
+    /** @returns true if newly revoked, false if not found or already revoked. */
     revoke(id: string): Promise<boolean>;
-    /**
-     * Clean up expired ephemeral tokens.
-     *
-     * @returns Number of removed tokens.
-     */
+    /** Remove expired ephemeral tokens; returns how many were removed. */
     cleanupExpired(): Promise<number>;
 }
 export {};

package/dist/worker/worker-outbox-relay.d.ts

@@ -1,7 +1,7 @@
 /**
  * Relay glue between the worker's in-memory execution tracker and the durable
- * peer outbox. Extracted so the mapping/replay logic is unit-testable and so
- * the worker bootstrap stays under the function-length cap.
+ * peer outbox, kept separate so it is unit-testable and the worker bootstrap
+ * stays under the function-length cap.
  */
 import { type JobProgress } from '@kici-dev/engine';
 import type { StatusUpdate } from './in-memory-execution-tracker.js';

package/dist/worker/worker-status.d.ts

@@ -1,11 +1,4 @@
-/**
- * Worker /status and /drain HTTP endpoint handlers.
- *
- * - GET /status -- returns worker instance info, connection state, agents, active/recent jobs
- * - POST /drain -- sets draining flag, returns active job count
- *
- * These are mounted on the worker's HTTP server in worker-core.ts.
- */
+/** Worker GET /status and POST /drain handlers, mounted in worker-core.ts. */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { InMemoryExecutionTracker } from './in-memory-execution-tracker.js';
 import type { AgentRegistry } from '../agent/registry.js';
@@ -19,18 +12,8 @@ export interface WorkerStatusDeps {
     getDraining: () => boolean;
     setDraining: (v: boolean) => void;
 }
-/**
- * Create a handler for GET /status.
- *
- * Returns worker instance info including role, coordinator connection state,
- * draining flag, uptime, agent counts, active jobs, and recent job history.
- */
+/** GET /status; recentJobs is capped at 20. */
 export declare function createWorkerStatusHandler(deps: WorkerStatusDeps): (_req: IncomingMessage, res: ServerResponse) => void;
-/**
- * Create a handler for POST /drain.
- *
- * Sets the draining flag to true and returns the current active job count.
- * Idempotent -- calling multiple times has no additional effect.
- */
+/** POST /drain: sets draining and returns the active job count. Idempotent. */
 export declare function createWorkerDrainHandler(deps: WorkerStatusDeps): (_req: IncomingMessage, res: ServerResponse) => void;
 //# sourceMappingURL=worker-status.d.ts.map

package/dist/ws/agent-api-registry.d.ts

@@ -1,8 +1,6 @@
 /**
- * Agent private API registry.
- *
- * Provides a typed, extensible request-response API over the existing agent WS
- * connection. Each method is registered with a role (read/write) for authorization.
+ * Agent private API: request-response over the existing agent WS connection. Each
+ * method is registered with a role (read/write) for authorization.
  *
  * Adding a new API method:
  * 1. Add the typed method + return type in @kici-dev/sdk (api-types.ts)
@@ -11,9 +9,7 @@
  * The agent sends { type: 'agent.api.request', method, params } and receives
  * { type: 'agent.api.response', result?, error? } back.
  */
-/** Authorization roles for API methods. */
 export type ApiRole = 'read' | 'write';
-/** Handler function for an API method. */
 export type ApiHandler = (agentId: string, params: Record<string, unknown>) => Promise<unknown>;
 /**
  * The caller named a method the registry does not know.
@@ -36,34 +32,19 @@ export declare class ApiRoleDeniedError extends Error {
     constructor(method: string, requiredRole: ApiRole, allowedRoles: ApiRole[]);
 }
 /**
- * Registry for agent private API methods.
- *
- * Methods are dot-namespaced (e.g., 'infrastructure.list') and each has an
- * associated role. The orchestrator checks the caller's allowed roles before
- * invoking the handler.
+ * Methods are dot-namespaced (e.g., 'infrastructure.list'). The orchestrator checks the
+ * caller's allowed roles before invoking the handler.
  */
 export declare class AgentApiRegistry {
     private readonly methods;
-    /**
-     * Register an API method.
-     *
-     * @param method - Dot-namespaced method name (e.g., 'infrastructure.list')
-     * @param role - Required role to call this method
-     * @param handler - Async handler that receives agentId and params, returns result
-     */
+    /** Throws when `method` is already registered. */
     register(method: string, role: ApiRole, handler: ApiHandler): void;
     /**
-     * Handle an API request.
-     *
-     * @param agentId - The calling agent's ID
-     * @param method - Requested method name
-     * @param params - Method parameters
-     * @param allowedRoles - Roles the caller is authorized for
-     * @returns The method's result
-     * @throws Error if method not found or role not authorized
+     * @throws UnknownApiMethodError / ApiRoleDeniedError if the method is not found or
+     *   the caller lacks its role
      */
     handle(agentId: string, method: string, params: Record<string, unknown>, allowedRoles: ApiRole[]): Promise<unknown>;
-    /** Get all registered method names (for diagnostics). */
+    /** For diagnostics. */
     getMethods(): string[];
 }
 //# sourceMappingURL=agent-api-registry.d.ts.map

package/dist/ws/agent-handler.d.ts

@@ -1,23 +1,16 @@
 /**
- * WebSocket handler for agent connections.
- *
- * Agents connect to the orchestrator via WebSocket to:
- * - Authenticate with a kat_ token (when agentAuthMode === 'token')
- * - Register their capabilities (labels, concurrency)
- * - Receive job dispatches
- * - Report job execution status
- * - Send periodic heartbeats
+ * WebSocket handler for agent connections: kat_ token auth, registration,
+ * job dispatch, status reports and heartbeats.
  *
  * Two-phase auth flow (when agentAuthMode === 'token'):
  * 1. pendingAuth (5s): Agent must send auth.request with a valid kat_ token.
  * 2. pendingRegistration (10s): After auth.success, agent must send agent.register.
  * 3. registered: Agent is fully connected and can exchange messages.
  *
- * When agentAuthMode === 'none', the auth phase is skipped and the connection
- * starts in pendingRegistration. An agent that happens to carry a token still
- * opens with auth.request — nothing on the wire tells it the mode — so that
- * frame is accepted there and answered with auth.success without reading the
- * token, and the agent then registers as normal.
+ * When agentAuthMode === 'none', the connection starts in pendingRegistration.
+ * An agent carrying a token still opens with auth.request (nothing on the wire
+ * tells it the mode), so that frame is answered with auth.success without
+ * reading the token.
  */
 import type { WSContext, WSEvents, WSMessageReceive } from 'hono/ws';
 import { LogStream, ScaleDownReason } from '@kici-dev/engine';
@@ -41,38 +34,11 @@ import type { CacheStorage } from '../storage/types.js';
 import type { AgentMetricsAggregator } from '../metrics/agent-metrics-aggregator.js';
 import { type AgentApiRegistry } from './agent-api-registry.js';
 import type { FleetAgentCollector } from './fleet-agent-collector.js';
-/**
- * Run the three token-bound authorization gates against a wire-supplied
- * `agent.register` payload. The gates are identical at first register
- * (Phase 2 / `pendingRegistration`) and on every subsequent re-register
- * arriving on the same registered WS — every code path that mutates the
- * registry's `agentId → entry` mapping for an authenticated WS MUST run
- * them, otherwise the token-scope and identity-binding invariants only
- * hold for the very first register and a re-register can silently
- * overwrite the authority.
- *
- * Gates:
- *  1. Token-scope subset — wire labels MUST be a subset of
- *     `agent_tokens.labels` when that set is non-null. Closes the WS with
- *     `WS_CLOSE_AGENT_AUTH_FAILED` listing the elevated labels.
- *  2. Ephemeral identity-binding — for `agent_type === 'ephemeral'`,
- *     wire `agentId` MUST equal `tokenCreatedBy` (the scaler-spawned
- *     agentId the token was issued for). Closes the WS with
- *     `WS_CLOSE_AGENT_AUTH_FAILED`.
- *  3. Static-token agentId-collision — a different `tokenId` must not
- *     already claim the wire `agentId`. Closes the WS with
- *     `WS_CLOSE_INVALID_MESSAGE`.
- *
- * Returns `true` when every gate passed and the caller may proceed;
- * returns `false` after closing the WS on the first violation, in which
- * case the caller MUST stop processing.
- */
 /**
  * WebSocket close reasons are capped at 123 UTF-8 bytes (RFC 6455, section 5.5.1).
- * A reason longer than that makes `ws.close()` throw a RangeError, which —
- * thrown from an async message handler — surfaces as an unhandled rejection
- * and skips the close entirely. Truncate on a byte boundary and drop any
- * trailing partial multi-byte char.
+ * A longer reason makes `ws.close()` throw a RangeError, which in an async
+ * handler becomes an unhandled rejection and skips the close. Truncates on a
+ * byte boundary, dropping any trailing partial multi-byte char.
  */
 export declare function truncateCloseReason(reason: string): string;
 /** What a failed frame is about, for the failure log. */
@@ -83,9 +49,8 @@ export interface FrameIdentity {
     jobId?: string;
 }
 /**
- * Read the type and ids from a raw agent frame, for logging a failure. Only
- * string fields are copied, each capped at 128 characters; anything that is
- * not a JSON object yields nothing. Runs on the failure path only.
+ * Reads the type and ids from a raw agent frame for a failure log. Copies only
+ * string fields, each capped at 128 characters; a non-object yields nothing.
  */
 export declare function frameIdentity(data: unknown): FrameIdentity;
 /**
@@ -118,11 +83,10 @@ export interface AgentWsHandlerDeps {
      */
     onLogChunk?: (agentId: string, msg: AgentLogChunkInput) => void | Promise<void>;
     /**
-     * Register a log chunk's handling with its run's log drain, before anything
-     * is awaited (`LogWriter.trackPending`). The ownership check can fall back
-     * to the database, and a run that completes during that lookup would
-     * otherwise be drained without the chunk, whose segment is then never
-     * sealed.
+     * Registers a log chunk's handling with its run's log drain before anything
+     * is awaited (`LogWriter.trackPending`): a run completing during the
+     * ownership DB fallback would otherwise drain without the chunk, leaving its
+     * segment never sealed.
      */
     trackLogChunk?: (runId: string, pending: Promise<unknown>) => void;
     /** Optional callback when agent sends step status updates. */
@@ -146,19 +110,15 @@ export interface AgentWsHandlerDeps {
      * Optional callback when a scaler-managed agent registers.
      *
      * Returns:
-     * - `boundJobId` (optional): set when the scaler bound a specific queued
-     *   job to this agent at spawn time. The orchestrator eagerly dispatches
-     *   that job before the agent's idle timer fires.
+     * - `boundJobId` (optional): a queued job the scaler bound to this agent at
+     *   spawn time, dispatched eagerly before the agent's idle timer fires.
      * - `mandatoryLabels` (always populated for scaler-managed agents): the
-     *   spawning scaler's Kubernetes-taint-style gate. Threaded into the
-     *   AgentRegistry so subsequent label matches (queue drain + eager
-     *   dispatch) apply the same gate the scaler-side selector applied.
-     *
-     * Resolves to `null` for static agents not managed by any scaler.
+     *   spawning scaler's taint-style gate, threaded into the AgentRegistry so
+     *   queue drain and eager dispatch apply the same gate as the scaler.
      *
-     * Asynchronous because the agent may reach an instance that did not spawn
-     * it: that instance adopts the agent from the shared spawn record, which is
-     * a database round trip.
+     * Resolves to `null` for static agents. Asynchronous because an instance
+     * that did not spawn the agent adopts it from the shared spawn record (a
+     * database round trip).
      */
     onScalerAgentRegistered?: (agentId: string, labels: string[]) => Promise<{
         boundJobId?: string;
@@ -187,13 +147,11 @@ export interface AgentWsHandlerDeps {
     /**
      * Optional callback when agent emits a custom event via ctx.emit().
      *
-     * A returned `error` is relayed to the agent verbatim, and the agent runs
-     * untrusted workflow code that persists it into the author's step logs — so
-     * an implementation may only return author-facing wording (an unknown job
-     * context). Raw exception text belongs in the implementation's own
-     * `logger.*`, with {@link AgentWsInternalFailure.eventEmitFailed} returned in
-     * its place; a thrown exception is already replaced with the same string
-     * here.
+     * A returned `error` is relayed verbatim to the agent, which runs untrusted
+     * workflow code that persists it into the author's step logs, so it may only carry author-facing wording (an unknown job context). Raw
+     * exception text goes to the implementation's own `logger.*`, returning
+     * {@link AgentWsInternalFailure.eventEmitFailed} instead; a thrown exception
+     * is already replaced with that string here.
      */
     onEventEmit?: (agentId: string, msg: {
         jobId: string;
@@ -246,12 +204,10 @@ export interface AgentWsHandlerDeps {
     /** User-facing cache for serving restore/save requests from the sandbox. */
     userCache?: UserCache;
     /**
-     * Server-side jobId -> user-cache-namespace store. The orchestrator records
-     * `{orgId, repoId, cacheRefScope, runId}` per job at dispatch time; the
-     * `cache.user.*` handlers resolve the ref from HERE (keyed by the wire jobId),
-     * NEVER from the wire message body — a `cache.user.*` message carries only a
-     * `jobId` + `key`, so an agent can name a job it owns but can never influence
-     * which org/repo/scope that job resolves to.
+     * Server-side jobId -> `{orgId, repoId, cacheRefScope, runId}` store, recorded
+     * at dispatch. `cache.user.*` handlers resolve the ref from HERE, NEVER from
+     * the wire body (which carries only `jobId` + `key`): an agent can name a job
+     * it owns but never influence which org/repo/scope it resolves to.
      */
     dispatchCacheRefs?: DispatchCacheRefTracker;
     /**
@@ -264,9 +220,9 @@ export interface AgentWsHandlerDeps {
     cacheStorage?: CacheStorage;
     /**
      * In-flight build-cache publishes and the per-org bound a build's success
-     * waits for them. Built once per orchestrator, not per connection, so a
-     * success replayed on a reconnected socket still sees a publish started on
-     * the old one. Absent: no registration and no wait.
+     * waits for them. Per orchestrator, not per connection, so a success replayed
+     * on a reconnected socket sees a publish started on the old one. Absent: no
+     * registration and no wait.
      */
     cacheUploadSettle?: CacheUploadSettle;
     /**
@@ -340,11 +296,11 @@ export interface AgentWsHandlerDeps {
     /**
      * Optional callback when agent reports a job belongs to a concurrency group.
      *
-     * A returned `reason` is relayed to the agent verbatim as the
-     * `job.concurrency.ack` reason, and the agent runs untrusted workflow code
-     * that persists it into the author's step logs — so an implementation may
-     * only return author-facing wording (the group the job queued behind). Raw
-     * exception text belongs in the implementation's own `logger.*`.
+     * A returned `reason` is relayed verbatim as the `job.concurrency.ack`
+     * reason to the agent, which runs untrusted workflow code that persists it into
+     * the author's step logs, so it may only carry author-facing
+     * wording (the group the job queued behind). Raw exception text goes to the
+     * implementation's own `logger.*`.
      */
     onConcurrencyReport?: (agentId: string, msg: {
         runId: string;
@@ -357,19 +313,16 @@ export interface AgentWsHandlerDeps {
     }>;
     /**
      * Optional callback when an agent blocks an `approval` step. The server
-     * creates a step-scoped hold from the carried clauses (and the drift
-     * `payload` for a `when: 'drift'` gate) and returns a promise that resolves
-     * when the hold is approved, rejected, or expired. The handler relays the
-     * resolution back to the originating agent as a `step.approval-resolved`
-     * message. The `agentId` lets the server drop the pending resolver when the
-     * agent disconnects.
+     * creates a step-scoped hold from the clauses (and the drift `payload` for a
+     * `when: 'drift'` gate), resolving when it is approved, rejected, or
+     * expired; the handler relays that as `step.approval-resolved`. `agentId`
+     * lets the server drop the pending resolver on disconnect.
      *
-     * The resolved `reason` is relayed to the agent verbatim, and the agent runs
-     * untrusted workflow code that persists it into the author's step logs — so
-     * an implementation may only resolve with author-facing wording (an
-     * approver's decline note, an invalid per-gate timeout). Raw exception text
-     * belongs in the implementation's own `logger.*`; a rejected promise is
-     * already replaced with {@link AgentWsInternalFailure.approvalFailed} here.
+     * The resolved `reason` is relayed verbatim to the agent, which runs untrusted
+     * workflow code that persists it into the author's step logs, so it may only carry author-facing wording (a decline note, an invalid
+     * per-gate timeout). Raw exception text goes to the implementation's own
+     * `logger.*`; a rejected promise is already replaced with
+     * {@link AgentWsInternalFailure.approvalFailed} here.
      */
     onStepApproval?: (agentId: string, msg: {
         runId: string;
@@ -392,19 +345,17 @@ export interface AgentWsHandlerDeps {
         reason?: string;
     }>;
     /**
-     * Optional callback fired when an agent's WS connection closes, after the
-     * dispatcher's own cleanup has run. Used by the long-poll concurrency
-     * pipeline to drop the agent's queued waiters and `cancelQueued` the
-     * matching DB rows so the run is marked failed instead of dangling.
+     * Optional callback on WS close, after the dispatcher's cleanup. The
+     * concurrency pipeline drops the agent's queued waiters and `cancelQueued`s
+     * their DB rows so the run fails instead of dangling.
      */
     onConcurrencyAgentDisconnect?: (agentId: string) => void | Promise<void>;
     /** Agent private API registry for handling agent.api.request messages. */
     agentApiRegistry?: AgentApiRegistry;
     /**
-     * Orchestrator-scoped collector that correlates fleet.logs.request with the
-     * agent's chunked fleet.bundle.chunk / fleet.bundle.error response. Routed to
-     * from the incoming-message switch; pending requests for a given agent are
-     * rejected when that agent's WS closes.
+     * Orchestrator-scoped collector correlating fleet.logs.request with the
+     * agent's chunked fleet.bundle.chunk / fleet.bundle.error response. An
+     * agent's pending requests are rejected when its WS closes.
      */
     fleetAgentCollector?: FleetAgentCollector;
 }
@@ -438,19 +389,21 @@ export interface AgentLogChunkInput {
     stream: LogStream;
 }
 /**
- * Release the in-memory waiters of jobs a disconnect triage failed: pending
- * builds, inits, dynamic evaluations and global eval rounds, and the user-cache
- * refs of the dispatch. The dispatcher runs it inside `onAgentDisconnect`, so
- * every path that drops an agent reaches it, whether or not it waits for the
- * socket to close.
+ * Releases the in-memory waiters of jobs a disconnect triage failed (pending
+ * builds, inits, dynamic evaluations, global eval rounds, user-cache refs) so
+ * none hangs. Runs inside `onAgentDisconnect`, so every path that drops an
+ * agent reaches it, whether or not it waits for the socket to close.
  */
 export declare function releaseFailedJobWaiters(deps: Pick<AgentWsHandlerDeps, 'pendingBuilds' | 'pendingInits' | 'pendingDynamics' | 'pendingGlobalEvals' | 'dispatchCacheRefs'>, failedJobIds: string[]): void;
 /**
  * Create a Hono WS event handler for agent connections.
  *
  * Flow:
- * 1. onOpen: start 10-second register timer
- * 2. First onMessage: must be agent.register with labels and capacity
+ * 1. onOpen: start the auth timer (token mode) or the register timer (see the
+ *    file header for the phases and their timeouts)
+ * 2. Pre-register onMessage: auth.request (token mode), then agent.register
+ *    with labels and capacity; a scaler.claim-credentials self-bootstrap is
+ *    answered in either phase
  * 3. Subsequent onMessage: validated against protocol schemas, routed by type
  * 4. onClose: cleanup from pending registration or dispatcher
  *

package/dist/ws/agent-heartbeat.d.ts

@@ -1,12 +1,9 @@
 /**
- * Heartbeat monitor for agent WebSocket connections.
- *
- * Periodically inspects all registered agents and:
- * - Logs warnings for agents past the unhealthy threshold (90s).
+ * Heartbeat monitor for agent WebSocket connections:
+ * - Logs (info level) agents past the unhealthy threshold (90s).
  * - Forcibly disconnects agents past the disconnect threshold (180s).
  *
- * Follows the same pattern as the Platform's heartbeat monitor, for
- * consistency across the three-tier architecture.
+ * Mirrors the Platform's heartbeat monitor.
  */
 import type { AgentRegistry } from '../agent/registry.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
@@ -21,10 +18,8 @@ interface AgentHeartbeatMonitorDeps {
     checkIntervalMs?: number;
 }
 /**
- * Periodically inspects all registered agent connections and:
- * - Marks agents as unhealthy after 90s of silence (log only).
- * - Triggers dispatcher.onAgentDisconnect for an agent silent for 180s, then
- *   unregisters it and closes its socket.
+ * An agent silent for 90s is unhealthy (log only). One silent for 180s gets
+ * dispatcher.onAgentDisconnect, then is unregistered and its socket closed.
  */
 export declare class AgentHeartbeatMonitor {
     private readonly registry;
@@ -34,9 +29,7 @@ export declare class AgentHeartbeatMonitor {
     private readonly checkIntervalMs;
     private interval;
     constructor(deps: AgentHeartbeatMonitorDeps);
-    /** Start the periodic heartbeat check. */
     start(): void;
-    /** Stop the periodic heartbeat check. */
     stop(): void;
     private check;
 }

package/dist/ws/bringup-api.d.ts

@@ -11,7 +11,6 @@ export declare const BOOTSTRAP_TOKEN_TTL_MS: number;
 export declare const PRE_BOOT_DEFAULT_PORT = 2222;
 /** Default forced command at a dropbear unlock endpoint (ignored by `-c` forces). */
 export declare const PRE_BOOT_DEFAULT_COMMAND = "cryptroot-unlock";
-/** Shared deps for the bring-up handlers. */
 export interface BringupApiDeps {
     registry: AgentRegistry;
     rosterStore: HostRosterStore;
@@ -26,18 +25,17 @@ export interface BringupApiDeps {
     /** Resolve the orchestrator's own version — the payload version to stage on bring-up. */
     resolveVersion: () => string;
     /**
-     * The cache-bucket agent-package store, present only when S3 cache storage is
-     * configured. Backs the `s3-direct` delivery mode: the handler mints a
-     * box-routable presigned download URL for a probed platform. Absent ⇒ every
-     * bring-up falls back to `ssh-push` and the presign RPC is refused.
+     * Cache-bucket agent-package store, present only when S3 cache storage is
+     * configured. Backs `s3-direct` delivery (a box-routable presigned download URL
+     * per probed platform). Absent ⇒ every bring-up uses `ssh-push` and the presign
+     * RPC is refused.
      */
     agentPackages?: AgentPackageDownloadStorage;
 }
 /**
- * Reach the calling agent connects to + the resolved private key. Returned to
- * the agent so it can run the SSH transport. The key value transits to the ops
- * agent by design (it custodies the bring-up key), exactly as resolved secrets
- * reach an agent at job dispatch.
+ * Host reach returned to the calling agent for the SSH transport. The private
+ * key returned beside it transits to the ops agent by design (it custodies the
+ * bring-up key), exactly as resolved secrets reach an agent at job dispatch.
  */
 export interface BringupReach {
     agentId: string;
@@ -58,10 +56,10 @@ export interface EnsureInitRunnerResult {
     /** The orchestrator's own version — the self-contained payload version to stage. */
     version?: string;
     /**
-     * Per-host delivery mode the agent uses to stage the payload: `s3-direct` when
-     * the host is declared object-storage-reachable AND a cache store is
-     * configured, else `ssh-push`. The agent probes the platform then requests the
-     * presigned URL via `kici.presignAgentPackage` for the `s3-direct` case.
+     * Payload delivery mode: `s3-direct` when the host is declared
+     * object-storage-reachable AND a cache store is configured, else `ssh-push`.
+     * The agent probes the platform, then requests the presigned URL via
+     * `kici.presignAgentPackage`.
      */
     deliveryMode?: AgentDeliveryMode;
 }
@@ -93,14 +91,13 @@ export interface PresignAgentPackageResult {
     sha256: string | null;
 }
 /**
- * Build the `kici.presignAgentPackage` handler — the follow-up RPC the ops agent
- * calls AFTER it probes the target platform (so the presign is keyed by the real
- * platform). Same capability gate + access-log as the bring-up. Mints a
- * box-routable presigned GET URL for the version-keyed payload from the
- * orchestrator's own cache bucket; no standing S3 credential leaves the
- * orchestrator. A missing payload object throws loudly (never a silent stale
- * stage). Used by BOTH delivery paths: for `s3-direct` the URL goes to the box;
- * for `ssh-push` the ops agent fetches it and streams the bytes onward.
+ * Build the `kici.presignAgentPackage` handler, which the ops agent calls AFTER
+ * it probes the target platform, so the presign is keyed by the real platform.
+ * Same capability gate + access-log as the bring-up. Mints a box-routable
+ * presigned GET URL for the version-keyed payload in the orchestrator's cache
+ * bucket; no standing S3 credential leaves the orchestrator. A missing payload
+ * throws loudly (never a silent stale stage). For `s3-direct` the URL goes to
+ * the box; for `ssh-push` the ops agent fetches it and streams the bytes onward.
  */
 export declare function createPresignAgentPackageHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<PresignAgentPackageResult>;
 /** How the ops agent drains + restarts a re-staged host + where its install lives. */
@@ -134,16 +131,14 @@ export interface AgentVersionStatusResult {
     available: boolean;
 }
 /**
- * Build the `kici.agentVersionStatus` read handler — the availability-gate probe
- * the convergence check-step calls. Returns the target version, the host's
- * recorded staged version, and whether the target's payloads are available for
- * the host's platform (the whole bootstrap set when the platform is unknown). No
- * SSH, no token — a pure read, but same capability gate + audit as the bring-up.
+ * Build the `kici.agentVersionStatus` read handler: the availability-gate probe
+ * the convergence check-step calls. Availability covers the host's platform, or
+ * the whole bootstrap set when the platform is unknown. No SSH, no token — a
+ * pure read, with the same capability gate + audit as the bring-up.
  */
 export declare function createAgentVersionStatusHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<AgentVersionStatusResult>;
 /** Material the ops agent receives for a `kici.restageAgent` call. */
 export interface RestageAgentResult {
-    /** How to SSH to the target host. */
     reach: BringupReach;
     /** The resolved bring-up private key (custodied by the ops agent). */
     privateKey: string;
@@ -155,21 +150,19 @@ export interface RestageAgentResult {
     restart: AgentRestartSpec;
 }
 /**
- * Build the `kici.restageAgent` handler — the availability-gated, external-actor
- * re-stage authorization. Gates on the caller's `ssh-transport` capability,
+ * Build the `kici.restageAgent` handler: the availability-gated, external-actor
+ * re-stage authorization. Gates on the caller's `ssh-transport` capability and
  * REFUSES loudly when the target version's payloads are unavailable for the
- * host's platform (belt-and-suspenders over the check-step gate — never a
- * skew), resolves the host reach + SSH key + restart spec, records the staged
- * version, audits, and returns the material the ops agent needs to swap + restart
- * the target's agent over SSH. Mints NO token: the re-staged permanent agent
- * reconnects on its own persistent credential (no self-update-handoff).
+ * host's platform (a second gate over the check-step's — never a skew). Returns
+ * what the ops agent needs to swap + restart the target's agent over SSH. Mints
+ * NO token: the re-staged permanent agent reconnects on its own persistent
+ * credential (no self-update-handoff).
  */
 export declare function createRestageAgentHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<RestageAgentResult>;
 /**
- * Build the `kici.preBootSend` handler. Gates on the caller's capability,
- * resolves the pre-boot input secret (e.g. a LUKS passphrase), audits, and
- * returns the input + reach so the agent can pipe it to the target's pre-boot
- * SSH endpoint.
+ * Build the `kici.preBootSend` handler. Gates on the caller's capability and
+ * returns the resolved pre-boot input (e.g. a LUKS passphrase) + reach so the
+ * agent can pipe it to the target's pre-boot SSH endpoint.
  */
 export declare function createPreBootSendHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<PreBootSendResult>;
 //# sourceMappingURL=bringup-api.d.ts.map