@kici-dev/orchestrator 0.1.14 → 0.1.16

package/dist/cache/user-cache.d.ts

@@ -0,0 +1,116 @@
+import type { CacheRefScope } from '@kici-dev/engine';
+import type { CacheStorage } from '../storage/types.js';
+/**
+ * Cluster-wide default quota: 5 GiB. Serves as the fallback when an org has no
+ * per-org override in `org_settings.user_cache_quota_bytes`. The cluster-wide
+ * value is itself operator-configurable via KICI_USER_CACHE_QUOTA_BYTES.
+ */
+export declare const DEFAULT_USER_CACHE_QUOTA_BYTES: number;
+/**
+ * Cluster-wide default entry TTL: 7 days. Fallback when an org has no per-org
+ * override in `org_settings.user_cache_ttl_ms`. The cluster-wide value is
+ * operator-configurable via KICI_USER_CACHE_TTL_MS.
+ */
+export declare const DEFAULT_USER_CACHE_TTL_MS: number;
+/**
+ * Per-org override of the cache quota + TTL, read from `org_settings` at
+ * operation time. A field left `undefined` means "no per-org override" — the
+ * cluster-wide default applies. Injected into `UserCache` so the cache stays
+ * decoupled from the DB layer (and unit-testable with a stub reader).
+ */
+export interface UserCacheOrgLimits {
+    quotaBytes?: number;
+    ttlMs?: number;
+}
+/** Resolves the per-org cache limits for an org id (e.g. an `org_settings` read). */
+export type UserCacheOrgLimitsReader = (orgId: string) => Promise<UserCacheOrgLimits>;
+/** Identifies the org + repo + write scope a cache operation targets. */
+export interface UserCacheRef {
+    org: string;
+    repo: string;
+    scope: CacheRefScope;
+    /** Required when scope === 'isolated' — the per-run isolation namespace. */
+    runId?: string;
+}
+/** Outcome of a restore: whether an entry matched and how to fetch it. */
+export interface UserCacheRestoreResult {
+    hit: boolean;
+    matchedKey?: string;
+    downloadUrl?: string;
+    tarHash?: string;
+}
+/** Outcome of begin-save: a presigned PUT to a temp key, or skip when the key already exists. */
+export interface UserCacheBeginSaveResult {
+    skip: boolean;
+    uploadUrl?: string;
+    tempKey?: string;
+}
+export declare class UserCache {
+    private readonly storage;
+    /** Cluster-wide default quota (the `KICI_USER_CACHE_QUOTA_BYTES` value). */
+    private readonly defaultQuotaBytes;
+    /** Cluster-wide default TTL (the `KICI_USER_CACHE_TTL_MS` value). */
+    private readonly defaultTtlMs;
+    /** Optional per-org override reader; absent = always use the cluster defaults. */
+    private readonly orgLimitsReader?;
+    constructor(opts: {
+        storage: CacheStorage;
+        /** Cluster-wide default quota (env-var default). */
+        quotaBytes?: number;
+        /** Cluster-wide default TTL (env-var default). */
+        ttlMs?: number;
+        /** Per-org override reader (org_settings). When unset, defaults apply. */
+        orgLimitsReader?: UserCacheOrgLimitsReader;
+    });
+    /**
+     * Resolve the effective quota + TTL for an org: the per-org override from
+     * `org_settings` when present, otherwise the cluster-wide default. A reader
+     * failure falls back to the defaults (logged) — the cache must never fail a
+     * restore/save because the settings lookup hiccupped.
+     */
+    private resolveLimits;
+    /**
+     * Sanitize a path segment so a key can never escape its org/repo/scope
+     * namespace. Beyond stripping disallowed characters, a segment consisting
+     * only of dots (`.`, `..`, …) is replaced wholesale: such a segment is a
+     * dot-segment that HTTP/S3 path canonicalization collapses (`a/./b` → `a/b`,
+     * `a/../b` → `b`), which both corrupts the namespace and breaks the SigV4
+     * signature on a pre-signed PUT/GET. Repo identifiers like `.` (the internal
+     * provider's repo id) hit exactly this case, so the all-dots guard keeps the
+     * object key canonical and the namespace boundary intact.
+     */
+    private seg;
+    /** Org-level prefix: the per-tenant isolation boundary and quota scope. */
+    private orgPrefix;
+    /** Org + repo prefix shared by every scope of a repo. */
+    private repoPrefix;
+    /** Namespace prefix for the WRITE scope of a ref (shared OR per-run isolated). */
+    private writePrefix;
+    /** Namespace prefixes the ref may READ, in priority order. Isolated reads its own run scope, then shared. */
+    private readPrefixes;
+    private finalKey;
+    /** Restore: try the exact key across read prefixes, then restoreKeys prefix scan (newest wins). */
+    restore(ref: UserCacheRef & {
+        key: string;
+        restoreKeys?: string[];
+    }): Promise<UserCacheRestoreResult>;
+    /** Try the exact key in read-prefix priority order. */
+    private restoreExact;
+    /** restoreKeys prefix fallback (ordered); within a prefix, list() returns newest-first. */
+    private restoreByPrefix;
+    /** Begin a save: presigned PUT to a temp key, or skip=true when the immutable key exists. */
+    beginSave(ref: UserCacheRef & {
+        key: string;
+    }): Promise<UserCacheBeginSaveResult>;
+    /** Commit a save: copy temp -> final, init metadata, store companion hash/size, delete temp, enforce quota. */
+    commitSave(ref: UserCacheRef & {
+        key: string;
+        tarHash: string;
+        sizeBytes: number;
+        tempKey?: string;
+    }): Promise<void>;
+    private readHash;
+    /** Evict least-recently-used entries for the org until total tarball size <= the per-org quota. */
+    private enforceQuota;
+}
+//# sourceMappingURL=user-cache.d.ts.map

package/dist/cancel/cancel-run.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared run-cancellation path.
+ *
+ * `cancelRunWithReason` is the single canonical implementation of "cancel
+ * this whole run, recording a reason". It is invoked by:
+ *
+ *  - the operator-facing `POST /api/v1/admin/runs/:runId/cancel` route
+ *    (user-initiated `kici cancel`), and
+ *  - the WorkflowDeadlineDetector, which cancels runs that exceeded their
+ *    workflow-level wall-clock timeout (TimeoutReason.workflow_timeout).
+ *
+ * Keeping one implementation means the deadline enforcer and the user cancel
+ * follow identical mechanics: send `job.cancel` to the agents running the
+ * run's jobs, cancel queued dispatch rows, mark pending/queued jobs cancelled,
+ * stamp the failure reason, and drive the run terminal when no agent work is
+ * outstanding.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { JobQueue } from '../queue/job-queue.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+export interface CancelRunDeps {
+    db: Kysely<Database>;
+    jobQueue: JobQueue;
+    dispatcher: Dispatcher;
+    registry: AgentRegistry;
+    executionTracker: ExecutionTracker;
+}
+export interface CancelRunOptions {
+    /** Force immediate SIGKILL on the agent (skip graceful hooks). */
+    force?: boolean;
+    /** Attribution stamped into execution_runs.cancelled_by. */
+    cancelledBy?: string;
+}
+export interface CancelRunResult {
+    /** Number of `job.cancel` messages dispatched to agents (running jobs). */
+    agentsNotified: number;
+    /** Number of pending/queued execution_jobs rows marked cancelled. */
+    pendingCancelled: number;
+}
+/**
+ * Cancel a whole run, recording `reason` on its cancelled jobs and (if not
+ * already set) on the run's failure_reason. Sends `job.cancel` to every agent
+ * holding a dispatched job for the run; cancels queued dispatch rows; marks
+ * pending/queued jobs cancelled. When no agent had outstanding work, drives
+ * the run to its terminal status immediately so the run does not linger in
+ * `cancelling`.
+ *
+ * Idempotent against terminal runs: callers should pre-check terminal state
+ * (the cancel route returns 409); the underlying UPDATEs are status-guarded so
+ * a double-call is harmless.
+ */
+export declare function cancelRunWithReason(deps: CancelRunDeps, runId: string, reason: string, options?: CancelRunOptions): Promise<CancelRunResult>;
+//# sourceMappingURL=cancel-run.d.ts.map

package/dist/cli/api-client.d.ts

@@ -5,6 +5,19 @@
  * All methods are thin wrappers around fetch() that handle JSON serialization,
  * error formatting, and URL construction.
  */
+/** A node in the fleet topology returned by GET /admin/fleet-topology. */
+export interface FleetTopologyNodeResponse {
+    kind: 'orchestrator' | 'agent';
+    id: string;
+    role?: 'coordinator' | 'worker';
+    hostname?: string;
+    labels: Record<string, string>;
+    parentId: string | null;
+}
+/** Response shape for GET /admin/fleet-topology. */
+export interface FleetTopologyResponse {
+    nodes: FleetTopologyNodeResponse[];
+}
 /**
  * Universal-git configuration shape carried in `git_config` on
  * generic_webhook_sources. Matches `UniversalGitConfigSchema` in
@@ -71,6 +84,17 @@ export declare class AdminApiClient {
      * Public GET request returning raw response text.
      */
     getText(path: string): Promise<string>;
+    /** Enumerate the cluster topology for `debug-bundle --fleet --list` / `--pick`. */
+    getFleetTopology(): Promise<FleetTopologyResponse>;
+    /**
+     * Drive the fleet fan-out and write the assembled ZIP to `outPath`. The
+     * response is an octet-stream, so it is read as bytes rather than parsed JSON.
+     */
+    downloadFleetBundle(body: {
+        selectors: string[];
+        logWindowHours?: number;
+        timeoutSeconds?: number;
+    }, outPath: string): Promise<void>;
     listScopes(orgId: string): Promise<{
         scopes: string[];
     }>;

package/dist/cli/commands/environment.d.ts

@@ -6,6 +6,7 @@
  *   environment set-policy     — update policy fields (branch, reviewers, timers, trust)
  *   environment list           — list environments for an org
  *   environment show           — show a single environment with variables + bindings
+ *   environment delete         — delete an environment (cascades bindings, variables, overrides; held-run history survives; pending held runs block with a clear error, resolved holds do not)
  *   environment create-template — create/update an environment template + its seed variables
  *
  * Each command supports two modes (stage-4 pattern from `maintenance.ts`):

package/dist/cli/commands/firecracker/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `kici-admin firecracker` command group.
+ *
+ * Local host-networking ops for the orchestrator's Firecracker scaler:
+ * provision/verify/teardown the per-coordinator bridge + nft table, with
+ * --persist for reboot survival. These run directly on the host (privileged
+ * `ip`/`nft`/`systemctl`) and do NOT use the admin HTTP client.
+ */
+import type { Command } from 'commander';
+export declare function registerFirecrackerCommands(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/firecracker/provision.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+import { type FirecrackerBridgeConfig } from '../../../firecracker/host-network.js';
+export interface ProvisionOptions {
+    bridge: string;
+    cidr?: string;
+    table?: string;
+    hostIface?: string;
+    persist?: boolean;
+    sudo?: boolean;
+}
+export declare function optionsToConfig(opts: ProvisionOptions): FirecrackerBridgeConfig;
+export declare function registerProvision(group: Command): void;
+//# sourceMappingURL=provision.d.ts.map

package/dist/cli/commands/firecracker/teardown.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerTeardown(group: Command): void;
+//# sourceMappingURL=teardown.d.ts.map

package/dist/cli/commands/firecracker/verify.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerVerify(group: Command): void;
+//# sourceMappingURL=verify.d.ts.map

package/dist/cli/commands/scaler.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Standalone scaler maintenance commands for kici-admin.
+ *
+ *   scaler reap-orphans   Free leaked Firecracker/container resources WITHOUT a
+ *                         running orchestrator (recovery for a wedged node whose
+ *                         data disk is full).
+ *
+ * This command loads the orchestrator's LOCAL config (no HTTP admin API, no DB)
+ * and runs the liveness-driven reaper. It is the sanctioned operator path for
+ * the ENOSPC bootstrap deadlock: when the data disk is 100% full the
+ * orchestrator crash-loops before its in-process orphan sweep can run, so a
+ * tool that frees disk WITHOUT the orchestrator is required.
+ */
+import type { Command } from 'commander';
+/** Probe the local orchestrator /health endpoint. Healthy => it reaps itself. */
+export declare function isOrchestratorHealthy(port: number, basePath: string): Promise<boolean>;
+export declare function registerScalerCommands(program: Command): void;
+//# sourceMappingURL=scaler.d.ts.map

package/dist/cli/kici-admin.d.ts

@@ -9,5 +9,14 @@
  *   --url / -u    Orchestrator URL (env: KICI_ADMIN_URL, default: http://localhost:8080)
  *   --token / -t  Admin API token (env: KICI_ADMIN_TOKEN, required)
  */
-export {};
+import { Command } from 'commander';
+/**
+ * Build the kici-admin Commander program with every command group registered.
+ * Exported so the surface registry can walk the real command tree without
+ * parsing argv (no action runs during a tree walk, so `getClient` is
+ * constructed but never invoked).
+ */
+export declare function buildProgram(): Command;
+/** Build the program and parse argv — the bin-shim entry point. */
+export declare function runCli(argv?: string[]): void;
 //# sourceMappingURL=kici-admin.d.ts.map

package/dist/cli/service/image-digests.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolves the customer installer's image reference from the digest record
+ * shipped with this package (installer-image-digests.json at the package root).
+ *
+ * Emits a manifest-list-digest-pinned ref so a `docker`/`podman pull` verifies
+ * the image hash — a registry that serves substituted bits fails the pull. When
+ * the record is missing (a dev tree that never ran a release) or lacks the
+ * image, falls back to the moving `:latest` tag and warns.
+ *
+ * The record resolves relative to this module's directory and works for both
+ * layouts: the source tree (`src/cli/service/` → the JSON is three dirs up at
+ * the package root) and the single-file bundle (`dist/cli.js` → one dir up).
+ */
+/**
+ * Resolve `quay.io/kici-dev/<name>:<version>@sha256:<digest>` for an installer
+ * image. Falls back to `:latest` (with a warning) when no recorded digest exists.
+ */
+export declare function resolveImageRef(name: string, opts?: {
+    filePath?: string;
+}): string;
+//# sourceMappingURL=image-digests.d.ts.map