@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/routes/admin-scheduled-jobs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Admin route for triggering scheduled-job ticks out of band.
+ *
+ *   POST /api/v1/admin/scheduled-jobs/:name/trigger
+ *     Path: :name must be one of the registered OrchestratorScheduledJobName
+ *     Requires: scheduled_job.trigger role permission (owner + admin roles)
+ *     Returns: { triggered: true, ok: boolean, durationMs: number, error?: string }
+ *
+ * Phase A's E2E smoke uses this endpoint to force a cold-store-archive
+ * tick without waiting for the hourly cron. Future dashboard "Run now"
+ * buttons use it too.
+ *
+ * The access_log row is written directly (not via the typed
+ * AccessLogWriter) because `scheduled_job.trigger` is not in the
+ * protocol-level AccessLogAction enum — matching the pattern the
+ * scheduler wrapper itself uses for `scheduled_job.tick` failure rows.
+ */
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { TokenManager } from '../secrets/token-manager.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+export interface AdminScheduledJobsRoutesDeps {
+    db: Kysely<Database>;
+    tokenManager: TokenManager;
+    rbac: RbacEnforcer;
+}
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+    };
+};
+export declare function createAdminScheduledJobsRoutes(deps: AdminScheduledJobsRoutesDeps): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-scheduled-jobs.d.ts.map

package/dist/routes/admin-sources.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Admin API routes for webhook source management.
+ *
+ * Provides CRUD endpoints for managing webhook sources (GitHub Apps, etc.)
+ * through the admin API. Source secrets (private keys, webhook secrets) are
+ * stored via PgSecretStore and never exposed in list/get responses.
+ *
+ * All routes are mounted under /api/v1/admin/sources and protected by
+ * the admin auth middleware in admin.ts.
+ */
+import { Hono } from 'hono';
+import type { SourceStore } from '../sources/source-store.js';
+interface SourceRouteDeps {
+    sourceStore: SourceStore;
+}
+export declare function createSourceRoutes(deps: SourceRouteDeps): Hono;
+export {};
+//# sourceMappingURL=admin-sources.d.ts.map

package/dist/routes/admin.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Admin API routes for secrets management.
+ *
+ * Provides CRUD endpoints for contexts, secrets, tokens, audit log queries,
+ * and key rotation. All routes are protected by Bearer token authentication
+ * and RBAC permission checks.
+ *
+ * Secret values are write-only -- there is deliberately no "get secret value"
+ * endpoint. Values are only read during dispatch resolution.
+ */
+import { Hono } from 'hono';
+import type { TokenManager } from '../secrets/token-manager.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { PgSecretStore } from '../secrets/pg-secret-store.js';
+import type { AuditLogger } from '../secrets/audit-logger.js';
+import type { AgentTokenStore } from '../agent/token-store.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { SharedConfigStore } from '../config/shared-store.js';
+import type { SourceStore } from '../sources/source-store.js';
+import type { JoinTokenManager } from '../cluster/join-token.js';
+import type { BackendRegistry } from '../secrets/backend-registry.js';
+import type { BackendHealthChecker } from '../secrets/backend-health.js';
+import type { BackendSyncManager } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type pg from 'pg';
+/**
+ * Dependencies for admin API routes.
+ */
+export interface AdminRouteDeps {
+    tokenManager: TokenManager;
+    rbac: RbacEnforcer;
+    secretStore: PgSecretStore;
+    auditLogger: AuditLogger;
+    /** Optional -- for agent token CRUD endpoints. */
+    tokenStore?: AgentTokenStore;
+    /**
+     * Optional -- for kicking in-flight agent WS on token revoke.
+     *
+     * The DELETE /api/v1/agent-tokens/:id route calls
+     * `agentRegistry.disconnectByTokenId(id)` synchronously after
+     * `tokenStore.revoke(id)` so a revoked token loses data-plane
+     * authority immediately instead of staying live until the agent
+     * itself disconnects. Mirrors the fix on the orch->Platform
+     * leg (`disconnectByKeyId`).
+     *
+     * When unset, the DELETE route returns 503 — agent-token revoke is
+     * meaningless without the kick path because a revoked token would
+     * still grant in-flight authority for hours-to-days.
+     */
+    agentRegistry?: AgentRegistry;
+    /**
+     * Optional -- fan out the revoke to every peer in a clustered orchestrator.
+     *
+     * The DELETE /api/v1/agent-tokens/:id route calls this after the synchronous
+     * local kick, so every peer's `AgentRegistry.disconnectByTokenId(tokenId)`
+     * runs locally and closes its own in-flight WS for the same token. Mirrors
+     *'s Valkey fan-out pattern on the orch->Platform leg.
+     *
+     * Unset on standalone deployments (no peer fabric) -- the local kick alone
+     * is sufficient there.
+     */
+    broadcastAgentTokenRevoke?: (tokenId: string) => void;
+    /** Optional -- for source management endpoints. */
+    sourceStore?: SourceStore;
+    /** Optional -- for DB migration endpoints. */
+    db?: Kysely<any>;
+    /** Optional -- for DB migration endpoints. */
+    pool?: pg.Pool;
+    /** Optional -- for cluster join token creation. */
+    joinTokenManager?: JoinTokenManager;
+    /** Optional -- for secret backend management endpoints. */
+    backendRegistry?: BackendRegistry;
+    /** Optional -- for secret backend health checking. */
+    backendHealthChecker?: BackendHealthChecker;
+    /** Optional -- for secret backend scope sync. */
+    backendSyncManager?: BackendSyncManager;
+    /**
+     * Optional -- for `POST /api/v1/admin/rotate-key`.
+     *
+     * When set, `rotate-key` re-encrypts `config_versions` alongside
+     * `scoped_secrets` in two sequential transactions. When unset (e.g. a
+     * secret-store-only admin deployment), config rotation is skipped and the
+     * response reports `reEncryptedConfigs: 0`.
+     */
+    sharedStore?: SharedConfigStore;
+}
+/** Hono env type for admin routes with context variables. */
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+/**
+ * Create admin API routes with Bearer token authentication and RBAC.
+ *
+ * @param deps - Admin route dependencies (token manager, RBAC, secret store, audit logger, etc.)
+ * @returns Hono app with admin routes mounted at /api/v1/admin/*
+ */
+export declare function createAdminRoutes(deps: AdminRouteDeps): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin.d.ts.map

package/dist/routes/capabilities.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Orchestrator capability manifest exposed to REST clients (the CLI).
+ *
+ * The `/capabilities` endpoint returns a small versioned manifest the CLI can
+ * read on demand to format actionable errors when it detects a feature gap
+ * (e.g. `kici status --logs` against an orchestrator that lacks the logs
+ * endpoint). See `docs/architecture/coordinator-worker.md` for the minimum-
+ * version semantics this mirrors for the WS connections.
+ *
+ * Public (no auth) — same security posture as `/health`, which already exposes
+ * the orchestrator's version. Version info must be reachable without a token
+ * so the CLI can fetch it even when authenticated calls fail with 404/401.
+ */
+import { Hono } from 'hono';
+export interface CapabilitiesManifest {
+    /** Orchestrator package version (injected at build time). */
+    orchestratorVersion: string;
+    /** Protocol version the orchestrator speaks. */
+    protocolVersion: number;
+    /** Minimum protocol version the orchestrator accepts from peers/clients. */
+    minProtocolVersion: number;
+}
+export declare function createCapabilitiesRoutes(): Hono;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/routes/diagnostics.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Diagnostic health check HTTP endpoint.
+ *
+ * Provides GET /admin/diagnose for monitoring system integration.
+ * Returns structured JSON with per-check results and overall status.
+ */
+import { Hono } from 'hono';
+import type { DiagnosticDeps } from '../diagnostics/types.js';
+/**
+ * Create diagnostic routes.
+ *
+ * @param deps - Dependencies for diagnostic checks
+ * @returns Hono app with /admin/diagnose endpoint
+ */
+export declare function createDiagnosticsRoutes(deps: DiagnosticDeps): Hono;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/routes/health.d.ts

@@ -0,0 +1,20 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+export interface HealthRoutesDeps {
+    /** Optional DB instance for readiness checks */
+    db?: Kysely<Database>;
+}
+/**
+ * Create orchestrator health routes with database readiness check.
+ *
+ * Delegates to the shared health route helper, providing
+ * a database connectivity check as the readiness probe.
+ *
+ * - GET /health - Liveness probe (always 200)
+ * - GET /ready  - Readiness probe (checks DB if provided)
+ *
+ * @param deps - Dependencies (optional database for readiness)
+ * @returns Hono app with health routes
+ */
+export declare function createHealthRoutes(deps?: HealthRoutesDeps): import("hono").Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=health.d.ts.map

package/dist/routes/test-trigger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * REST endpoints for CLI-initiated test runs.
+ *
+ * POST /api/v1/test/trigger           - Trigger a test run with a fixture event
+ * GET  /api/v1/test/runs/:runId       - Get status of a test run
+ * GET  /api/v1/test/runs/:runId/logs  - Get logs for a test run
+ * POST /api/v1/test/cancel            - Cancel a running test run
+ *
+ * All endpoints require Bearer token authentication via the admin token system.
+ * The test trigger injects a synthetic event into the existing pipeline,
+ * reusing trigger matching and job dispatch.
+ */
+import { Hono } from 'hono';
+import { type TestPipelineDeps } from '../pipeline/test-pipeline.js';
+import type { AppConfig } from '../config.js';
+import type { TokenManager } from '../secrets/token-manager.js';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** Hono env type for test trigger routes with context variables. */
+type TestTriggerEnv = {
+    Variables: {
+        userId: string;
+        routingKey: string | null;
+    };
+};
+/**
+ * Dependencies for test trigger routes.
+ * Extends TestPipelineDeps with additional route-specific deps.
+ */
+export interface TestTriggerRouteDeps extends TestPipelineDeps {
+    config: AppConfig;
+    tokenManager?: TokenManager;
+    db: Kysely<Database>;
+    cacheStorage?: import('../storage/types.js').CacheStorage;
+}
+/**
+ * Create Hono routes for test trigger and cancel endpoints.
+ */
+export declare function createTestTriggerRoutes(deps: TestTriggerRouteDeps): Hono<TestTriggerEnv>;
+export {};
+//# sourceMappingURL=test-trigger.d.ts.map

package/dist/routes/uploads.d.ts

@@ -0,0 +1,38 @@
+/**
+ * REST endpoints for test run upload management.
+ *
+ * POST /api/v1/uploads/init           - Initialize an upload (returns signed URL + public key)
+ * GET  /api/v1/uploads/:uploadId/status - Check upload status
+ *
+ * Uploads support the repo state transfer mechanism: CLI uploads an encrypted
+ * tarball of changed files to S3 via a pre-signed URL, then references the
+ * upload ID in the test trigger request.
+ */
+import { Hono } from 'hono';
+import type { AppConfig } from '../config.js';
+import type { TokenManager } from '../secrets/token-manager.js';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { CacheStorage } from '../storage/types.js';
+/**
+ * Dependencies for upload routes.
+ */
+export interface UploadRouteDeps {
+    config: AppConfig;
+    db: Kysely<Database>;
+    tokenManager?: TokenManager;
+    cacheStorage?: CacheStorage;
+}
+/** Hono env type for upload routes with context variables. */
+type UploadEnv = {
+    Variables: {
+        userId: string;
+        routingKey: string | null;
+    };
+};
+/**
+ * Create Hono routes for upload management endpoints.
+ */
+export declare function createUploadRoutes(deps: UploadRouteDeps): Hono<UploadEnv>;
+export {};
+//# sourceMappingURL=uploads.d.ts.map

package/dist/routes/webhooks.d.ts

@@ -0,0 +1,36 @@
+import { Hono } from 'hono';
+import type { DedupCache } from '../webhook/dedup.js';
+import type { WebhookInfo } from '../webhook/handler.js';
+import type { GenericSourceManager } from '../webhook/generic-sources.js';
+/**
+ * Dependencies for generic webhook routes.
+ */
+export interface GenericWebhookRoutesDeps {
+    /** Generic source manager for source lookup and validation */
+    sourceManager: GenericSourceManager;
+    /** Delivery ID deduplication cache */
+    dedup: DedupCache;
+    /** Processing callback -- connects to the trigger matching pipeline */
+    onWebhook: (info: WebhookInfo) => Promise<void>;
+}
+/**
+ * Create generic webhook routes for non-GitHub webhook ingestion.
+ *
+ * Endpoint: POST /webhook/:orgId/generic/:sourceId
+ *
+ * Handler flow:
+ * 1. Read raw body
+ * 2. Look up source from GenericSourceManager
+ * 3. Check payload size
+ * 4. Rate limit check
+ * 5. Verify signature using per-source verification config
+ * 6. Extract idempotency key, check dedup
+ * 7. Extract event type, check allowed events
+ * 8. Normalize and process through pipeline
+ * 9. Return response
+ *
+ * @param deps - Dependencies (source manager, dedup cache, processing callback)
+ * @returns Hono app with generic webhook routes
+ */
+export declare function createGenericWebhookRoutes(deps: GenericWebhookRoutesDeps): Hono;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/scaler/bare-metal-backend.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Bare-metal scaler backend implementation.
+ *
+ * Manages ephemeral agent processes using child_process.spawn.
+ * Uses detached process groups for clean killing of entire process trees.
+ * All agents are single-use: destroyed after job completion.
+ */
+import { type ToolRequirement } from '@kici-dev/shared';
+import type { AgentTokenStore } from '../agent/token-store.js';
+import type { ScalerBackend, ScalerEntry, ManagedAgent, LabelSetConfig, LogCapture, ResourceRequest, ScalerEventCallback, ValidationResult, EffectiveLimits } from './types.js';
+export interface BareMetalScalerBackendOptions {
+    /** Human-readable name for this scaler */
+    name: string;
+    /** Label sets this backend can provision */
+    labelSets: LabelSetConfig[];
+    /** Maximum concurrent agents */
+    maxAgents: number;
+    /** Default resource limits applied when label set has none */
+    defaultResources?: ResourceRequest;
+    /** Token store for creating ephemeral agent auth tokens. Optional -- when undefined, no token is injected. */
+    tokenStore?: AgentTokenStore;
+    /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
+    tokenTtlMs?: number;
+    /** Agent roles for this scaler. undefined = all, [] = execution only. */
+    roles?: string[];
+    /**
+     * When true, wrap each spawned agent process in a transient systemd scope
+     * (`systemd-run --user --scope --slice=kici-scaler`) and translate the
+     * job's effective CPU / memory limits into `CPUQuota=` / `MemoryMax=`
+     * properties so the kernel cgroup actually enforces the limits. When
+     * false (the default), bare-metal stays its historical "advisory limits
+     * only" mode — limits drive the scaler's per-machine cap math but no
+     * cgroup is created.
+     *
+     * Linux-only. On macOS / Windows hosts the option is silently a no-op
+     * (`systemd-run` does not exist), with a one-time startup warning.
+     */
+    enforceCgroups?: boolean;
+}
+export declare class BareMetalScalerBackend implements ScalerBackend {
+    readonly type: "bare-metal";
+    readonly logsSource = "bare-metal";
+    readonly maxAgents: number;
+    private _labelSets;
+    private readonly name;
+    private readonly defaultResources?;
+    private readonly tokenStore?;
+    private readonly tokenTtlMs;
+    private readonly roles;
+    private readonly enforceCgroups;
+    /** Tracks all managed agent processes */
+    private readonly agents;
+    /** LogCapture instances for each managed agent (keyed by ManagedAgent.id) */
+    private readonly logCaptures;
+    constructor(options: BareMetalScalerBackendOptions);
+    private warnNetworkPolicy;
+    /**
+     * Declare required tools for a bare-metal scaler entry.
+     *
+     * - Every label set's `binaryPath` must be an executable file on disk.
+     * - If `KICI_SANDBOX=true` will be forwarded to spawned agents (either via
+     *   the orchestrator's `KICI_AGENT_ENV_KICI_SANDBOX=true` env var or via a
+     *   label set's `env.KICI_SANDBOX=true` in scalers.yaml), then `bwrap` must
+     *   be available on PATH so the agent can actually wrap workflow runners.
+     *
+     *   This check runs at orchestrator startup so misconfiguration fails
+     *   fast with a clear error instead of crashing every job at dispatch
+     *   time. On macOS and Windows (where bwrap does not exist) any attempt
+     *   to enable KICI_SANDBOX will be rejected here.
+     */
+    static getRequiredTools(entry: ScalerEntry): ToolRequirement[];
+    get labelSets(): LabelSetConfig[];
+    getActiveCount(): number;
+    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits): Promise<ManagedAgent>;
+    getScalerContext(agentId: string): Record<string, unknown> | undefined;
+    destroy(managedId: string): Promise<void>;
+    /**
+     * Get the LogCapture for a managed agent (used by ScalerManager for log forwarding).
+     */
+    getLogCapture(managedId: string): LogCapture | undefined;
+    shutdownAll(): Promise<void>;
+    reload(labelSets: LabelSetConfig[]): ValidationResult;
+    /**
+     * Build the (command, args) tuple used to spawn an agent process.
+     *
+     * Two modes:
+     *   - Direct: returns (binaryPath, []) — the historical bare-metal flow.
+     *     Used when enforceCgroups is false, the host is non-Linux, or the
+     *     resolved limits carry no positive cpus/memBytes.
+     *   - systemd-run scope: returns ('systemd-run', [...]) wrapping the
+     *     binary in a transient `--user --scope --slice=kici-scaler` cgroup
+     *     with `CPUQuota=` / `MemoryMax=` properties translated from the
+     *     effective limits. The scope name embeds `agentId` so each agent is
+     *     a separately-named transient unit (and `systemctl --user status
+     *     kici-agent-<agentId>.scope` works).
+     *
+     * `CPUQuota` is expressed as a percent (1.0 cpus = 100%). `MemoryMax`
+     * accepts a raw byte count.
+     */
+    private buildSpawnInvocation;
+    /**
+     * Wait for a process to exit within a timeout.
+     * Returns true if the process exited, false if timed out.
+     */
+    private waitForExit;
+}
+//# sourceMappingURL=bare-metal-backend.d.ts.map