@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/scaler/vm-job-bindings.d.ts

@@ -1,17 +1,13 @@
 /**
- * Durable job-to-agent bindings, read from the coordinator's dispatch queue.
- *
- * A worker has no database, so this is the coordinator's half of the
- * live-VM tracking: a VM whose agent holds a non-terminal job is tracked, even
- * when the node that runs the VM has lost every in-memory trace of it.
+ * Durable job-to-agent bindings from the coordinator's dispatch queue: the coordinator's half
+ * of live-VM tracking (a worker has no database). A VM whose agent holds a non-terminal job is
+ * tracked even when its node has lost every in-memory trace of it.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 /**
- * The non-terminal job each of `agentIds` holds, keyed by agent id. An agent
- * holds a job it was dispatched (`agent_id`) and a job waiting for it to
- * reconnect (`recovery_agent_id`). The value is the job id the queue
- * dispatches by, `dispatch_queue.id`.
+ * The non-terminal job (`dispatch_queue.id`) each of `agentIds` holds: one it was dispatched
+ * (`agent_id`) or one waiting for it to reconnect (`recovery_agent_id`).
  */
 export declare function findActiveJobBindings(db: Kysely<Database>, agentIds: readonly string[]): Promise<Map<string, string>>;
 //# sourceMappingURL=vm-job-bindings.d.ts.map

package/dist/scaler/warm-pool.d.ts

@@ -1,69 +1,51 @@
 /**
  * Warm pool manager for pre-provisioned idle agents.
  *
- * Each configured label set has a target `size`. On every tick the manager asks
- * the agent registry how many agents could already serve a job with those
- * labels, subtracts the spawns it has issued but not yet seen register, and
- * starts the difference. It holds no list of its own: the agent registry is the
- * single source of truth for what is ready, which is also what the dispatcher
- * reads, so the two can never disagree.
+ * Each configured label set has a target `size`. Every tick the manager starts
+ * `size - ready - inFlight` agents, where `ready` comes from the agent registry.
+ * It holds no list of its own: the registry is the single source of truth for
+ * what is ready, and the dispatcher reads it too, so the two never disagree.
  *
- * Uses a callback pattern to avoid circular dependencies with ScalerManager.
+ * Callbacks avoid a circular dependency with ScalerManager.
  */
 export interface WarmPoolCallbacks {
-    /** Request the ScalerManager to spawn a new agent for the given label set */
     onSpawnRequest: (labelSet: string[], backendName: string) => Promise<void>;
-    /** Request the ScalerManager to destroy an idle agent */
     onDestroyRequest: (managedId: string, backendName: string) => Promise<void>;
     /**
-     * How many registered agents could serve a job with this label set right
-     * now. Backed by `AgentRegistry.findAvailable`, which is the same query the
-     * dispatcher uses — so the warm pool and the dispatcher can never disagree
-     * about what "ready" means.
-     *
-     * A static agent that matches the labels counts: it removes the need for a
-     * warm one just as well as a spawned agent does.
+     * Registered agents that could serve a job with this label set now, via
+     * `AgentRegistry.findAvailable` — the dispatcher's own query. A matching
+     * static agent counts: it removes the need for a warm one just as well.
      */
     countAvailable: (labels: string[]) => number;
     /**
      * Agents this backend spawned that match the label set and have never run a
-     * job, with the timestamp they registered at. `registeredAt` doubles as
-     * "idle since": scaler agents are single-use, so an agent still registered
-     * with no active job has been idle since it came up.
+     * job. `registeredAt` doubles as "idle since": scaler agents are single-use.
      *
-     * Scoped to the backend because the result feeds the reaper, and the reaper
-     * destroys what it is given. A static agent that happens to match the labels
-     * is ready capacity, not this pool's to tear down.
+     * Scoped to the backend because the reaper destroys what it is given; a
+     * matching static agent is ready capacity, not this pool's to tear down.
      */
     listIdle: (labels: string[], backendName: string) => Array<{
         agentId: string;
         registeredAt: number;
     }>;
     /**
-     * How many more agents this backend may still start before it reaches the
-     * scaler's `maxAgents` or the orchestrator's `globalMaxAgents`, whichever
-     * binds first. The deficit is clamped to it, so a pool that cannot reach its
-     * target stops asking instead of issuing a spawn the caps refuse every tick.
+     * Headroom before the scaler's `maxAgents` or the orchestrator's
+     * `globalMaxAgents`, whichever binds first. The deficit is clamped to it, so
+     * a pool that cannot reach its target stops issuing spawns the caps refuse.
      */
     capacityRemaining: (backendName: string) => number;
     /**
-     * Called at the end of each tick, once the reap and the deficit pass have
-     * run. The ScalerManager publishes the warm-pool gauges from it, so they
-     * follow the pool rather than the scrape.
+     * Runs after each tick's reap and deficit pass; the ScalerManager publishes
+     * the warm-pool gauges from it, so they follow the pool rather than the scrape.
      */
     onTick?: () => void;
 }
-/** One label set's fill state, as the warm-pool metrics report it. */
 export interface WarmPoolStats {
     /**
-     * The pool's identity: its normalized DECLARED label set, which is the
-     * `configs` map key.
-     *
-     * This — not `labels` — is what a per-pool metric dimension keys on. Two
-     * pools on one scaler can widen to the SAME query set (one label set
-     * declaring the plain platform label the other only gets from the taint), so
-     * a dimension built from `labels` collapses them into one series and silently
-     * drops a pool's fill state.
+     * The normalized DECLARED label set (the `configs` key). Per-pool metric
+     * dimensions key on this, not `labels`: two pools on one scaler can widen to
+     * the SAME query set (one declares the platform label the other gets from the
+     * taint), and keying on `labels` would silently drop a pool's fill state.
      */
     key: string;
     /** The widened query set the `ready` count was measured with. */
@@ -75,22 +57,16 @@ export interface WarmPoolStats {
 }
 export declare class WarmPoolManager {
     private readonly callbacks;
-    /** Configuration per normalized label set */
     private readonly configs;
     /**
      * Warm spawns issued but not yet registered, per normalized label set.
-     *
-     * Load-bearing: without it, two passes landing before the first spawn
-     * registers would each see the full deficit and issue `size` spawns apiece.
+     * Without it, two passes before the first spawn registers would each issue
+     * `size` spawns.
      */
     private readonly inFlight;
-    /** Periodic deficit + idle check interval */
     private idleCheckInterval;
     constructor(callbacks: WarmPoolCallbacks);
     /**
-     * Configure the warm pool for a label set.
-     * Called during ScalerManager initialization based on YAML config.
-     *
      * `normalizedLabels` keys the pool by its DECLARED label set, which is what
      * every in-flight release path normalizes back to.
      */
@@ -101,52 +77,36 @@ export declare class WarmPoolManager {
         spawnLabels: string[];
     }): void;
     /**
-     * One deficit pass. For each configured label set, top the pool up to its
-     * target: `size - ready - inFlight`, clamped by the backend's remaining cap
-     * headroom.
-     *
-     * The per-backend budget is tracked across the whole pass: two label sets on
-     * one scaler draw from the same `maxAgents`, so clamping each against the
-     * same starting headroom would let them jointly overshoot it.
+     * One deficit pass. The per-backend budget spans the whole pass: two label
+     * sets on one scaler draw from the same `maxAgents`, so clamping each against
+     * the same starting headroom would let them jointly overshoot it.
      */
     evaluate(): void;
-    /** A warm spawn registered: release its in-flight slot. */
     onWarmAgentRegistered(labels: string[]): void;
     /**
      * A warm spawn failed, timed out, or was pruned as never-registered: release
-     * its in-flight slot so the next pass retries it. Without this the slot is
-     * held forever and the pool sits permanently below target.
+     * its in-flight slot so the next pass retries it.
      */
     onWarmSpawnFailed(labels: string[]): void;
     private releaseInFlight;
-    /** Per-label-set fill state, for the warm-pool metrics. */
     getStats(): WarmPoolStats[];
     /**
-     * Start the periodic tick: reap surplus agents past their idle timeout, then
-     * top the pools back up.
+     * Start the periodic tick: reap surplus idle agents, then top the pools up.
      *
-     * The first pass runs immediately rather than a tick later. The one caller
-     * is `ScalerManager.startWarmPools()`, which each host reaches only after
-     * `ensureHostsReady()` and — on the coordinator — after the event emitter
-     * is assigned, so spawning here is safe. Waiting a tick instead would leave
-     * the pool empty for 30 seconds after every restart, which is precisely the
-     * cold start it exists to remove.
+     * The first pass runs immediately: waiting a tick would leave the pool empty
+     * for 30 seconds after every restart, the cold start it exists to remove. It
+     * is safe because the one caller, `ScalerManager.startWarmPools()`, runs only
+     * after `ensureHostsReady()` and, on the coordinator, after the event emitter
+     * is assigned.
      */
     start(): void;
-    /**
-     * Stop the periodic tick.
-     */
     stop(): void;
-    /**
-     * Total ready agents across every configured pool. Surfaced by
-     * `getStatus().warmPoolCount`.
-     */
+    /** Ready agents across every pool; surfaced by `getStatus().warmPoolCount`. */
     getTotalPoolSize(): number;
     /**
-     * Update configs. Destroy surplus agents in pools that shrunk, and drop
-     * pools whose config disappeared (the scaler was removed from the config,
-     * or its `warmPool.enabled` flipped to false) — a warm agent must not
-     * outlive the config that asked for it.
+     * Destroy surplus agents in pools that shrunk, and drop pools whose config
+     * disappeared (scaler removed, or `warmPool.enabled` set to false) — a warm
+     * agent must not outlive the config that asked for it.
      */
     reload(newConfigs: Map<string, {
         backendName: string;
@@ -156,28 +116,21 @@ export declare class WarmPoolManager {
         spawnLabels: string[];
     }>): void;
     /**
-     * Destroy this pool's idle agents beyond `keep`, oldest first.
-     *
-     * Oldest-first because the survivors are the ones with the most time left
-     * before the idle reaper takes them, which is the set an arriving job is
-     * most likely to find still ready.
+     * Destroy this pool's idle agents beyond `keep`, oldest first: the survivors
+     * have the most time left before the idle reaper, so an arriving job is most
+     * likely to find them still ready.
      */
     private destroyIdle;
     /**
      * Destroy agents that are BOTH surplus to the pool's target AND idle past
-     * its timeout. `registeredAt` is the idle-since stamp: scaler agents are
-     * single-use, so an agent still registered with no active job has never run
-     * one.
-     *
-     * The target check is what stops the pool churning against itself. Reaping
-     * on age alone means a quiet pool destroys its own agent every
-     * `idleTimeoutSeconds` and immediately re-spawns it: the provisioning
-     * workflow runs forever on zero traffic, and — because an event-backend
-     * replacement takes minutes to boot — the pool is below target for much of
-     * every cycle. A warm pool that is cold most of the time is worse than none.
-     * So the timeout trims surplus only: a pool sitting at `size` never reaps.
+     * its timeout (`registeredAt` is the idle-since stamp).
      *
-     * `size: 0` still drains, because then every ready agent is surplus.
+     * The target check stops the pool churning against itself. Reaping on age
+     * alone makes a quiet pool destroy and re-spawn its agent every
+     * `idleTimeoutSeconds`: the provisioning workflow runs forever on zero
+     * traffic, and since an event-backend replacement takes minutes to boot, the
+     * pool is below target for much of every cycle. So a pool at `size` never
+     * reaps; `size: 0` still drains, since every ready agent is then surplus.
      *
      * Exposed for testing.
      */

package/dist/secrets/audit-logger.d.ts

@@ -35,14 +35,11 @@ export declare class AuditLogger {
      * `deleteSecret`, the scope writes, `rotateKey`, `secret-outputs.reveal`) bypass the
      * sampler — they are transactional with the mutation and must always
      * land.
-     *
-     * @param entry - The audit entry to record.
      */
     log(entry: AuditEntry): Promise<void>;
     /**
      * Query audit log entries with optional filters.
      *
-     * @param opts - Query filters and pagination.
      * @returns Matching audit log rows ordered by timestamp descending.
      */
     query(opts: {

package/dist/secrets/backend-health.d.ts

@@ -27,13 +27,7 @@ export declare class BackendHealthChecker {
      * Check health of all enabled backends in parallel.
      */
     checkAllBackends(): Promise<Map<string, BackendHealthStatus>>;
-    /**
-     * Start periodic health checks at the given interval.
-     */
     startPeriodicCheck(intervalMs?: number): void;
-    /**
-     * Stop periodic health checks.
-     */
     stopPeriodicCheck(): void;
     /**
      * Test connectivity to a backend without persisting it.
@@ -44,9 +38,6 @@ export declare class BackendHealthChecker {
         error?: string;
         latencyMs: number;
     }>;
-    /**
-     * Probe a backend by type and return its health status.
-     */
     private probeBackend;
     /**
      * Probe a PG backend by running SELECT 1.

package/dist/secrets/backend-registry.d.ts

@@ -71,17 +71,8 @@ export declare class BackendRegistry {
      * Returns a map of backend name to SecretStore.
      */
     loadAllStores(auditLogger: AuditLogger): Promise<Map<string, SecretStore>>;
-    /**
-     * Create a SecretStore for a given backend type and config.
-     */
     createStoreForBackend(backendType: BackendType, config: Record<string, unknown>, auditLogger: AuditLogger): SecretStore | null;
-    /**
-     * Update health status for a backend.
-     */
     updateHealthStatus(name: string, status: BackendHealthStatus, error?: string): Promise<void>;
-    /**
-     * Update sync status for a backend.
-     */
     updateSyncStatus(name: string, scopeCount: number, error?: string): Promise<void>;
     /**
      * Re-encrypt every non-sentinel backend config under the current master key

package/dist/secrets/cleanup.d.ts

@@ -12,7 +12,6 @@ export interface SecretCleanupDeps {
     db: Kysely<Database>;
     /** Max age in hours before rows are considered orphaned. Default: 24 */
     maxAgeHours?: number;
-    /** Optional logger for cleanup messages */
     logger?: {
         info(msg: string, meta?: Record<string, unknown>): void;
         warn(msg: string, meta?: Record<string, unknown>): void;

package/dist/secrets/config.d.ts

@@ -1,6 +1,3 @@
-/**
- * Secret store configuration.
- */
 export interface SecretStoreConfig {
     /** 32-byte AES-256 encryption key. */
     masterKey: Buffer;

package/dist/secrets/ephemeral-keys.d.ts

@@ -1,4 +1,3 @@
-/** AAD string used when encrypting/decrypting private keys with secret key. */
 /** AAD binding a wrapped run private key to its purpose (AES-GCM authenticated data). */
 export declare const PRIVATE_KEY_AAD = "ephemeral-private-key";
 /**
@@ -46,7 +45,6 @@ export declare function decryptPrivateKey(encryptedData: string, secretKey: stri
  *
  * @param envelope - { agentPublicKey: base64, encrypted: base64 (IV||AuthTag||Ciphertext) }
  * @param runPrivateKeyDer - DER-encoded run private key Buffer
- * @returns Decrypted plaintext string
  */
 export declare function decryptSecretOutput(envelope: {
     agentPublicKey: string;
@@ -62,7 +60,6 @@ export declare function decryptSecretOutput(envelope: {
  *
  * @param envelope - `{ ephemeralPublicKey: base64 DER-SPKI, encrypted: base64 IV||tag||ct }`
  * @param encryptionPrivateKeyDer - DER-encoded orchestrator X25519 private key
- * @returns Decrypted plaintext string
  */
 export declare function decryptDashboardSealedWrite(envelope: {
     ephemeralPublicKey: string;

package/dist/secrets/pg-secret-store.d.ts

@@ -85,9 +85,6 @@ export declare class PgSecretStore implements SecretStore {
      * keeps a key stored before this rule readable and deletable.
      */
     setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
-    /**
-     * Delete a secret from a scope.
-     */
     deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
     /**
      * List all secret key names in a scope (no values returned).

package/dist/secrets/rbac.d.ts

@@ -23,10 +23,11 @@ export type Permission = 'context.create' | 'context.read' | 'context.update' |
 /** Stop live Firecracker VMs the node's orchestrator does not track. */
  | 'scaler.manage'
 /** Drop a departed peer from the coordinators' live peer registries. */
- | 'peer.manage';
-/**
- * Error thrown when a role lacks the required permission.
- */
+ | 'peer.manage'
+/** Start or cancel a `kici run remote` test run through the direct test-run routes. */
+ | 'test_run.trigger'
+/** Follow a test run's status and logs through the direct test-run routes. */
+ | 'test_run.read';
 export declare class PermissionDeniedError extends Error {
     readonly role: Role;
     readonly permission: Permission;
@@ -39,9 +40,6 @@ export declare class PermissionDeniedError extends Error {
  * No database or external state -- purely in-memory evaluation.
  */
 export declare class RbacEnforcer {
-    /**
-     * Check whether a role has a specific permission.
-     */
     hasPermission(role: Role, permission: Permission): boolean;
     /**
      * Require a permission, throwing PermissionDeniedError if not authorized.

package/dist/secrets/routing-key-scope.d.ts

@@ -25,6 +25,7 @@
  * they use `requireUnscopedToken` instead.
  */
 import type { Context } from 'hono';
+export declare const UNSCOPED_REQUIRED_MESSAGE = "Access denied: this route requires an unscoped admin token (the calling token is restricted to a single routing key)";
 /**
  * Reject the request with 403 when the calling token has a routing-key
  * scope and the request targets a different routing key.

package/dist/secrets/secret-output-store.d.ts

@@ -1,11 +1,5 @@
 /**
  * Secret output store for cross-job secret output CRUD.
- *
- * Provides typed operations against the run_secret_outputs table:
- * - Upsert encrypted secret outputs (per run/job/key)
- * - Retrieve outputs for a specific job or multiple upstream jobs
- * - Delete all outputs for a run (cleanup)
- * - Delete orphaned outputs older than a threshold (maintenance)
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';

package/dist/secrets/secret-resolver.d.ts

@@ -55,9 +55,6 @@ export interface SecretStoreLike {
     decrypt(secret: ScopedSecret): string;
     getSecrets(orgId: string, scope: string): Promise<Record<string, string>>;
 }
-/**
- * Dependencies for the SecretResolver.
- */
 export interface SecretResolverDeps {
     bindingStore: BindingStoreLike;
     /** Map of backend name to store. Replaces single secretStore. */
@@ -114,7 +111,6 @@ export declare class SecretResolver implements SecretResolverApi {
     /**
      * Resolve secrets for a job dispatch.
      *
-     * @param orgId - Organization ID
      * @param context - The matched context row and the name the job declared
      * @param hostCtx - Optional fan-out child identity for per-host resolution.
      *   When supplied, each binding is gated by its `host_pattern` and its
@@ -160,14 +156,14 @@ export declare class SecretResolver implements SecretResolverApi {
     /** How many scope bindings the context row `contextId` has. */
     countContextBindings(contextId: string): Promise<number>;
     /**
-     * Resolve secrets with metadata (per, for secrets.getMeta).
+     * Resolve secrets with metadata (for secrets.getMeta).
      *
      * Returns the secret value along with which backend and scope provided it.
      */
     resolveForContextWithMeta(orgId: string, context: MatchedContextRef, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
     /**
      * Collect all secrets from all backend stores, prefixing scopes.
-     * Per /: unreachable backends are tracked but not fatal here.
+     * Unreachable backends are tracked but not fatal here.
      * Callers apply scoped failure policy based on job bindings.
      */
     private collectAllSecrets;

package/dist/secrets/token-manager.d.ts

@@ -32,7 +32,6 @@ export declare class TokenManager {
      *
      * On success, fires a non-blocking update to last_used_at.
      *
-     * @param token - The plaintext token to validate.
      * @returns Token info if valid, null if invalid/expired/revoked.
      */
     validate(token: string): Promise<{
@@ -40,10 +39,8 @@ export declare class TokenManager {
         role: Role;
         routingKey: string | null;
         label: string;
+        subject: string | null;
     } | null>;
-    /**
-     * Revoke a token by ID.
-     */
     revokeToken(tokenId: string): Promise<void>;
     /**
      * List all tokens (excluding hash for security).

package/dist/secrets/vault-secret-store.d.ts

@@ -1,12 +1,8 @@
 import type { SecretStore } from '@kici-dev/engine';
 import type { Logger } from '@kici-dev/shared';
-/**
- * Configuration for the Vault secret store backend.
- */
 export interface VaultConfig {
     /** Vault server URL (e.g., 'http://vault:8200'). */
     vaultUrl: string;
-    /** Authentication method. */
     authMethod: 'approle' | 'token';
     /** AppRole role ID (required for 'approle' auth). */
     roleId?: string;
@@ -45,9 +41,6 @@ export declare class VaultSecretStore implements SecretStore {
     private authenticate;
     private getToken;
     private withRetry;
-    /**
-     * Build the full Vault path for a scoped secret.
-     */
     private secretPath;
     /**
      * Get all secrets for a scope as key-value pairs.
@@ -57,13 +50,7 @@ export declare class VaultSecretStore implements SecretStore {
      * Set (create or update) a secret in a scope.
      */
     setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
-    /**
-     * Delete a secret key from a scope.
-     */
     deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
-    /**
-     * List all secret key names in a scope.
-     */
     listKeys(orgId: string, scope: string): Promise<string[]>;
     /**
      * List all distinct scopes for an org.

package/dist/security/comment-handler.d.ts

@@ -16,7 +16,6 @@ interface CommentCommand {
     /** Optional: specific run to approve/reject. */
     runId?: string;
 }
-/** Parameters for the approval comment handler. */
 export interface HandleApprovalCommentParams {
     commentBody: string;
     commenterUsername: string;
@@ -76,7 +75,6 @@ export interface HandleApprovalCommentParams {
      */
     onWorkflowReject?: (hold: HeldRun, reason: string) => Promise<boolean>;
 }
-/** Result of handling a comment. */
 interface HandleApprovalResult {
     handled: boolean;
     reason?: string;

package/dist/security/workflow-diff.d.ts

@@ -16,7 +16,7 @@ export interface WorkflowModification {
  * Compares workflow names and configurations:
  * - Added: in head but not base
  * - Removed: in base but not head
- * - Modified: in both but triggers, jobs, or steps differ
+ * - Modified: in both but triggers, jobs (steps included), or rules differ
  *
  * @param baseLockFile - Lock file from the base branch (null for new repos)
  * @param headLockFile - Lock file from the head commit (null means nothing to detect)