@kici-dev/orchestrator 0.0.0 → 0.1.1

package/dist/cache/pending-tracker.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Generic pending-job tracker for coordinating two-phase orchestrator pipelines
+ * (build-then-execute, init-then-execute, dynamic-eval-then-execute).
+ *
+ * The orchestrator dispatches a precursor job (build / init / dynamic eval) and
+ * needs to wait for the agent to report completion before continuing. This
+ * tracker exposes a deferred Promise per jobId that resolves with a typed
+ * payload (or rejects on failure / disconnect).
+ *
+ * Usage:
+ * - dispatcher calls track(jobId), awaits the returned promise
+ * - terminal-status handler calls resolve(jobId, value) or reject(jobId, err)
+ * - cleanup(jobId) is invoked on agent disconnect to reject with a fixed error
+ */
+export interface PendingTrackerOptions<T> {
+    /** Logger prefix, e.g. 'pending-builds'. */
+    logPrefix: string;
+    /** Noun used in log messages, e.g. 'build', 'init', 'dynamic eval'. */
+    itemLabel: string;
+    /** Error message used when cleanup() rejects a pending entry on disconnect. */
+    disconnectError: string;
+    /**
+     * Optional extractor that derives extra structured log fields from the
+     * resolved value (e.g. `jobCount` for dynamic-eval results). The returned
+     * keys are merged into the `resolve` log line for telemetry / debugging.
+     */
+    extractResolveMeta?: (value: T) => Record<string, unknown>;
+}
+export declare class PendingTracker<T> {
+    private readonly pending;
+    private readonly logger;
+    private readonly opts;
+    constructor(opts: PendingTrackerOptions<T>);
+    /**
+     * Register a pending job and return a promise that resolves when the agent
+     * reports completion (or rejects on failure / disconnect).
+     *
+     * Each call creates a new Promise. If track() is called for the same jobId
+     * twice, the previous Promise's callbacks are replaced -- the previous
+     * caller's Promise will never settle (orphaned). Callers (e.g. BuildCoordinator)
+     * are responsible for coalescing duplicate work upstream.
+     */
+    track(jobId: string): Promise<T>;
+    /**
+     * Resolve a pending entry (agent reported success).
+     */
+    resolve(jobId: string, value: T): void;
+    /**
+     * Reject a pending entry (agent reported failure).
+     */
+    reject(jobId: string, error: Error): void;
+    /**
+     * Clean up on agent disconnect. Rejects with the configured disconnect error.
+     */
+    cleanup(jobId: string): void;
+    /**
+     * Check if an entry is pending for a given jobId.
+     */
+    has(jobId: string): boolean;
+    /**
+     * Number of pending entries (for metrics / debugging).
+     */
+    get size(): number;
+}
+//# sourceMappingURL=pending-tracker.d.ts.map

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

@@ -0,0 +1,30 @@
+/**
+ * Source-tarball cache layer wrapping CacheStorage.
+ *
+ * Provides content-hash-keyed operations for customer-workflow source tarballs
+ * (the `.kici/` directory minus `node_modules/`, packed by the agent's build
+ * job via `source-packer.ts`). Tarballs are platform-independent: raw TypeScript
+ * source files are identical across architectures. Refreshes TTL on reads
+ * (touch-on-read) so actively used sources stay in cache longer.
+ *
+ * Cache key format: source/{contentHash}.tar.gz
+ *
+ * Replaces the former `BundleCache` / `bundles/{contentHash}.js` layout that
+ * stored Rolldown-bundled `.compiled.mjs` artifacts — the new execution path
+ * downloads the source tarball, extracts it, and imports the workflow entry
+ * via the shared oxc-transform ESM loader hook.
+ */
+import type { CacheStorage } from '../storage/types.js';
+export declare class SourceCache {
+    private readonly storage;
+    constructor(options: {
+        storage: CacheStorage;
+    });
+    has(contentHash: string): Promise<boolean>;
+    get(contentHash: string): Promise<Buffer | null>;
+    getUrl(contentHash: string): Promise<string | null>;
+    getUploadUrl(contentHash: string): Promise<string>;
+    store(contentHash: string, tarball: Buffer | string): Promise<void>;
+    remove(contentHash: string): Promise<boolean>;
+}
+//# sourceMappingURL=source-cache.d.ts.map

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

@@ -0,0 +1,411 @@
+/**
+ * HTTP client wrapper for the kici-admin CLI.
+ *
+ * Communicates with the orchestrator admin API via Bearer token authentication.
+ * All methods are thin wrappers around fetch() that handle JSON serialization,
+ * error formatting, and URL construction.
+ */
+/**
+ * Universal-git configuration shape carried in `git_config` on
+ * generic_webhook_sources. Matches `UniversalGitConfigSchema` in
+ * `providers/universal-git/config.ts`. Kept as a loose `Record` here to
+ * avoid a cross-package import in the CLI wire type.
+ */
+export type GenericSourceGitConfigPayload = Record<string, unknown>;
+/**
+ * Response shape for generic webhook sources from the admin API.
+ */
+export interface GenericSourceResponse {
+    id: string;
+    customer_id: string;
+    name: string;
+    routing_key: string;
+    verification_method: string;
+    verification_config: string;
+    event_type_header: string | null;
+    event_type_path: string | null;
+    idempotency_key_header: string | null;
+    idempotency_key_path: string | null;
+    dedup_window_seconds: number;
+    max_payload_bytes: number;
+    allowed_events: string | null;
+    strip_headers: string;
+    enabled: boolean;
+    rate_limit_rpm: number;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+    provider_type?: string;
+    /** Universal-git config; raw JSON string or parsed object (pg driver dependent). */
+    git_config?: string | GenericSourceGitConfigPayload | null;
+}
+export declare class AdminApiClient {
+    private readonly baseUrl;
+    private readonly token;
+    constructor(baseUrl: string, token: string);
+    /**
+     * Make an authenticated HTTP request to the admin API.
+     */
+    private request;
+    /**
+     * Public GET request returning parsed JSON.
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * Public POST request returning parsed JSON.
+     */
+    post<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * Public PATCH request returning parsed JSON.
+     */
+    patch<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * Public DELETE request returning parsed JSON.
+     */
+    delete<T>(path: string): Promise<T>;
+    /**
+     * Public GET request returning raw response text.
+     */
+    getText(path: string): Promise<string>;
+    listScopes(orgId: string): Promise<{
+        scopes: string[];
+    }>;
+    listKeys(orgId: string, scope: string): Promise<{
+        keys: string[];
+    }>;
+    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
+    deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
+    rotateKey(): Promise<{
+        reEncrypted: number;
+        reEncryptedConfigs: number;
+        skippedConfigs: number;
+    }>;
+    createGenericSource(data: {
+        orgId: string;
+        name: string;
+        verificationMethod?: string;
+        verificationConfig?: Record<string, unknown>;
+        eventTypeHeader?: string;
+        eventTypePath?: string;
+        idempotencyKeyHeader?: string;
+        idempotencyKeyPath?: string;
+        dedupWindowSeconds?: number;
+        maxPayloadBytes?: number;
+        allowedEvents?: string[];
+        stripHeaders?: string[];
+        rateLimitRpm?: number;
+        providerType?: string;
+        gitConfig?: GenericSourceGitConfigPayload;
+    }): Promise<{
+        source: GenericSourceResponse;
+    }>;
+    listGenericSources(orgId: string, includeDeleted?: boolean): Promise<{
+        sources: GenericSourceResponse[];
+    }>;
+    getGenericSource(id: string): Promise<{
+        source: GenericSourceResponse;
+    }>;
+    updateGenericSource(id: string, data: {
+        name?: string;
+        verificationMethod?: string;
+        verificationConfig?: Record<string, unknown>;
+        eventTypeHeader?: string;
+        eventTypePath?: string;
+        idempotencyKeyHeader?: string;
+        idempotencyKeyPath?: string;
+        dedupWindowSeconds?: number;
+        maxPayloadBytes?: number;
+        allowedEvents?: string[];
+        stripHeaders?: string[];
+        rateLimitRpm?: number;
+        providerType?: string;
+        /** `null` clears the config; omit to leave unchanged. */
+        gitConfig?: GenericSourceGitConfigPayload | null;
+    }): Promise<{
+        source: GenericSourceResponse;
+    }>;
+    deleteGenericSource(id: string, hard?: boolean): Promise<{
+        deleted: boolean;
+        hard: boolean;
+    }>;
+    enableGenericSource(id: string): Promise<{
+        enabled: boolean;
+    }>;
+    disableGenericSource(id: string): Promise<{
+        enabled: boolean;
+    }>;
+    queryAudit(opts?: {
+        contextName?: string;
+        routingKey?: string;
+        action?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+        /** Phase D opt-in for cold-store read-through. */
+        includeArchived?: boolean;
+    }): Promise<any[]>;
+    createToken(data: {
+        label: string;
+        role: string;
+        routingKey?: string;
+    }): Promise<{
+        token: string;
+        id: string;
+    }>;
+    listTokens(): Promise<any[]>;
+    revokeToken(id: string): Promise<void>;
+    createAgentToken(opts: {
+        labels?: string[];
+    }): Promise<{
+        id: string;
+        token: string;
+    }>;
+    listAgentTokens(opts?: {
+        type?: string;
+    }): Promise<{
+        tokens: any[];
+    }>;
+    /**
+     * Revoke an agent token.
+     *
+     * The orchestrator both flips `agent_tokens.revoked_at` AND
+     * synchronously closes every in-flight agent WS authenticated by
+     * this token. The returned `kicked` count is the number
+     * of WS connections that were closed on the wire — surface it to
+     * the operator so they know the revocation actually propagated.
+     */
+    revokeAgentToken(id: string): Promise<{
+        kicked: number;
+    }>;
+    configSeed(config: object, description?: string): Promise<{
+        version: number;
+    }>;
+    configGet(path?: string): Promise<{
+        config: unknown;
+        version: number;
+        source: string;
+    }>;
+    configSet(path: string, value: unknown, description?: string): Promise<{
+        version: number;
+    }>;
+    configDelete(path: string, description?: string): Promise<{
+        version: number;
+    }>;
+    configExport(): Promise<{
+        config: object;
+        version: number;
+    }>;
+    configValidate(config: object, type?: string): Promise<{
+        valid: boolean;
+        errors?: any[];
+    }>;
+    configDiff(): Promise<{
+        local: object;
+        shared: object;
+        differences: any[];
+    }>;
+    configHistory(limit?: number): Promise<{
+        versions: any[];
+    }>;
+    configRollback(version: number): Promise<{
+        newVersion: number;
+    }>;
+    configReload(opts?: {
+        drain?: boolean;
+        target?: string;
+    }): Promise<{
+        success: boolean;
+        version?: number;
+        errors?: string[];
+    }>;
+    createApiKey(opts: {
+        label?: string;
+        routingKeys?: string[];
+    }): Promise<{
+        id: string;
+        key: string;
+        routingKeys: string[];
+    }>;
+    addRoutingKeyPermission(keyId: string, pattern: string): Promise<{
+        id: string;
+        pattern: string;
+    }>;
+    addBackend(params: {
+        name: string;
+        backendType: string;
+        config: Record<string, unknown>;
+        scopeFilter?: string;
+        syncIntervalMs?: number;
+    }): Promise<Record<string, unknown>>;
+    removeBackend(name: string): Promise<{
+        removed: boolean;
+        scopeCount: number;
+    }>;
+    listBackends(): Promise<{
+        backends: Record<string, unknown>[];
+    }>;
+    getBackend(name: string): Promise<Record<string, unknown>>;
+    testBackend(params: {
+        name: string;
+        backendType: string;
+        config: Record<string, unknown>;
+        scopeFilter?: string;
+        syncIntervalMs?: number;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+        latencyMs: number;
+    }>;
+    testNamedBackend(name: string): Promise<{
+        ok: boolean;
+        error?: string;
+        latencyMs: number;
+    }>;
+    syncBackend(name: string): Promise<{
+        synced: boolean;
+        scopeCount: number;
+    }>;
+    syncAllBackends(): Promise<{
+        results: Array<{
+            name: string;
+            scopeCount: number;
+            error?: string;
+        }>;
+    }>;
+    /**
+     * List execution runs. `status` accepts either a single status or a
+     * comma-separated list (e.g. `success,failed`). `since` is an ISO-8601
+     * timestamp; only runs with `created_at` strictly later than this value
+     * are returned.
+     */
+    listRuns(opts?: {
+        status?: string;
+        workflowName?: string;
+        repo?: string;
+        since?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        runs: Array<Record<string, unknown>>;
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+    /**
+     * Count matching runs without returning the row list. Wraps the list
+     * endpoint with `?count=true`, which skips the row query server-side.
+     */
+    countRuns(opts?: {
+        status?: string;
+        workflowName?: string;
+        repo?: string;
+        since?: string;
+    }): Promise<{
+        total: number;
+        since: string | null;
+        status: string[] | null;
+        workflowName: string | null;
+        repo: string | null;
+    }>;
+    /**
+     * Fetch the run header (no jobs, no steps). Use `getRunJobs` for the
+     * jobs sub-resource.
+     */
+    getRun(runId: string): Promise<{
+        run: Record<string, unknown>;
+    }>;
+    /**
+     * Fetch the jobs list for a run. When `includeSteps: true`, each job
+     * entry embeds a `steps[]` array.
+     */
+    getRunJobs(runId: string, opts?: {
+        includeSteps?: boolean;
+    }): Promise<{
+        jobs: Array<Record<string, unknown>>;
+    }>;
+    /**
+     * Fetch the scrub status of the run's ephemeral key. Never returns the
+     * key material itself — only `{ exists, createdAt }`.
+     */
+    getRunEphemeralKey(runId: string): Promise<{
+        exists: boolean;
+        createdAt: string | null;
+    }>;
+    /**
+     * List secret outputs for a run. Values are masked unless `reveal: true`
+     * is passed AND the calling token has the `secret.reveal` permission.
+     * Every reveal call writes a `secret-outputs.reveal` row to the
+     * secret_audit_log table.
+     */
+    getRunSecretOutputs(runId: string, opts?: {
+        outputKey?: string;
+        reveal?: boolean;
+    }): Promise<{
+        outputs: Array<{
+            id: string;
+            jobId: string;
+            outputKey: string;
+            createdAt: string;
+            value: string | null;
+            masked: boolean;
+            revealError?: string;
+        }>;
+    }>;
+    listEventLog(opts?: {
+        orgId?: string;
+        routingKey?: string;
+        event?: string;
+        action?: string;
+        status?: string;
+        from?: string;
+        to?: string;
+        deliveryId?: string;
+        limit?: number;
+        offset?: number;
+        includeArchived?: boolean;
+    }): Promise<{
+        deliveries: Array<Record<string, unknown>>;
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+    getEventLog(deliveryId: string, opts: {
+        orgId: string;
+        includePayload?: boolean;
+        routingKey?: string;
+    }): Promise<Record<string, unknown>>;
+    listAccessLog(opts?: {
+        orgId?: string;
+        actorType?: string;
+        actorId?: string;
+        action?: string;
+        source?: string;
+        outcome?: string;
+        targetType?: string;
+        targetId?: string;
+        from?: string;
+        to?: string;
+        q?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: Array<Record<string, unknown>>;
+        nextCursor: string | null;
+    }>;
+    getAccessLogEntry(id: string, opts?: {
+        orgId?: string;
+    }): Promise<Record<string, unknown>>;
+    diagnose(): Promise<{
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        checks: Array<{
+            name: string;
+            status: 'pass' | 'warn' | 'fail';
+            message: string;
+            details?: Record<string, unknown>;
+            durationMs: number;
+        }>;
+        timestamp: string;
+    }>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/cli/commands/access-log.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Access log commands for kici-admin.
+ *
+ * Operator-facing read access to the orchestrator's access_log table
+ * (read + mutation attribution with ActorPrincipal). Dogfood replacement
+ * for raw psql when an operator asks "who read this run's payload last
+ * Tuesday" or "show me everything a platform_operator actor did".
+ *
+ *   access-log list   List access-log rows with filters (cursor-paginated)
+ *   access-log show   Show a single entry by id
+ *
+ * Filter flags for `list`:
+ *   --org-id          -> ?orgId=
+ *   --actor-type      -> ?actorType=
+ *   --actor-id        -> ?actorId=
+ *   --action          -> ?action=
+ *   --source          -> ?source=
+ *   --outcome         -> ?outcome=
+ *   --target-type     -> ?targetType=
+ *   --target-id       -> ?targetId=
+ *   --from / --to     -> ?from= / ?to= (ISO timestamps)
+ *   --q               -> ?q= (substring of error_message, trigram-indexed)
+ *   --limit           -> ?limit= (default 50, max 200)
+ *   --cursor          -> ?cursor=
+ *   --json            Emit raw JSON
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+export declare function registerAccessLogCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=access-log.d.ts.map

package/dist/cli/commands/agent-service/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Agent service command group registration.
+ *
+ * Adds install, uninstall, start, stop, restart, status, logs, and upgrade
+ * subcommands to the existing `agent` command group for managing the agent
+ * as a system service.
+ *
+ * These commands manage local services directly and do NOT use AdminApiClient.
+ * They coexist with the existing agent token management commands (register, list, revoke).
+ *
+ * Must be called AFTER registerAgentCommands() so the `agent` command already exists.
+ */
+import type { Command } from 'commander';
+export declare function registerAgentServiceCommands(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/agent-service/install.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `kici-admin agent install` command.
+ *
+ * Registers the agent as a native system service on the current platform.
+ * Accepts orchestrator URL and token for connecting to the orchestrator.
+ */
+import type { Command } from 'commander';
+export declare function registerAgentInstall(agent: Command): void;
+//# sourceMappingURL=install.d.ts.map

package/dist/cli/commands/agent-service/logs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `kici-admin agent-service logs` command.
+ *
+ * Tails and follows agent service logs with filtering.
+ * Delegates to the platform-specific service manager.
+ */
+import type { Command } from 'commander';
+export declare function registerAgentLogsCommand(parent: Command): void;
+//# sourceMappingURL=logs.d.ts.map

package/dist/cli/commands/agent-service/restart.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `kici-admin agent restart` command.
+ *
+ * Restarts the agent service.
+ */
+import type { Command } from 'commander';
+export declare function registerAgentRestart(agent: Command): void;
+//# sourceMappingURL=restart.d.ts.map

package/dist/cli/commands/agent-service/start.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `kici-admin agent start` command.
+ *
+ * Starts the agent service.
+ */
+import type { Command } from 'commander';
+export declare function registerAgentStart(agent: Command): void;
+//# sourceMappingURL=start.d.ts.map

package/dist/cli/commands/agent-service/status.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `kici-admin agent-service status` command.
+ *
+ * Shows OS-level service status (state, PID, uptime) and queries
+ * the running agent's health API for agent-specific info (labels,
+ * orchestrator connection, current job).
+ */
+import type { Command } from 'commander';
+export declare function registerAgentStatusCommand(parent: Command): void;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/commands/agent-service/stop.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `kici-admin agent stop` command.
+ *
+ * Stops the agent service.
+ */
+import type { Command } from 'commander';
+export declare function registerAgentStop(agent: Command): void;
+//# sourceMappingURL=stop.d.ts.map

package/dist/cli/commands/agent-service/uninstall.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `kici-admin agent uninstall` command.
+ *
+ * Removes the agent service registration.
+ * Preserves config files and logs per user decision.
+ */
+import type { Command } from 'commander';
+export declare function registerAgentUninstall(agent: Command): void;
+//# sourceMappingURL=uninstall.d.ts.map

package/dist/cli/commands/agent-service/upgrade.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `kici-admin agent-service upgrade` command.
+ *
+ * Upgrades the agent using the versioned directory layout:
+ * - Same pattern as orchestrator: versioned directories with symlink switching
+ * - Extracts to agent-{version}/, symlink at agent/
+ * - No database migrations (agents are stateless)
+ */
+import type { Command } from 'commander';
+export declare function registerAgentUpgradeCommand(parent: Command): void;
+//# sourceMappingURL=upgrade.d.ts.map

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

@@ -0,0 +1,10 @@
+/**
+ * Agent token management commands for kici-admin.
+ *
+ * Provides CRUD operations for agent authentication tokens:
+ *   agent register, list, revoke
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+export declare function registerAgentCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=agent.d.ts.map

package/dist/cli/commands/api-key.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Platform API key management commands for kici-admin.
+ *
+ * These commands target the Platform admin API for managing API keys
+ * and routing key permissions. Uses the same --url flag (point to Platform URL).
+ *
+ *   api-key create, add-routing-key
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+export declare function registerApiKeyCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=api-key.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * Audit log query command for kici-admin.
+ *
+ * Queries the secrets audit log with optional filters.
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+export declare function registerAuditCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=audit.d.ts.map