@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/webhook/relay-buffer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Per-messageId reassembly buffer for the chunked webhook.relay protocol.
+ *
+ * Platform splits the inbound webhook body into N WS frames so a 25 MiB body
+ * can interleave with other concurrent traffic. The orchestrator must:
+ * - Allocate a buffer on `webhook.relay.start` keyed by `messageId`.
+ * - Append each `webhook.relay.chunk` in strict ascending sequence order.
+ * - Enforce the 25 MiB hard ceiling (defensively; Platform also caps).
+ * - On the chunk where `final=true`, return the assembled body + metadata so
+ *   the WS handler can run verify+process and emit the ack.
+ * - Garbage-collect buffers Platform abandoned mid-stream (e.g. the originating
+ *   Platform process crashed between chunks) via a per-buffer TTL.
+ *
+ * Concurrency: a single orchestrator may be receiving many concurrent inbound
+ * webhooks; the registry is a Map keyed by messageId so streams don't collide.
+ *
+ * Errors are NEVER thrown — every malformed input produces a typed `ChunkError`
+ * with a non-secret-bearing diagnostic the WS handler maps to a
+ * `rejected_misconfigured` ack. This keeps the WS handler inside its 5 s budget
+ * and prevents a malicious sender from killing the orch process via a bad frame.
+ */
+/** Metadata captured on the start frame and kept for the lifetime of the stream. */
+export interface RelayStartMeta {
+    routingKey: string;
+    deliveryId: string;
+    event: string;
+    action: string | null | undefined;
+    signatureHeaderName: string | null | undefined;
+    signatureHeader: string | null | undefined;
+    clientIp: string | null | undefined;
+    headers: Record<string, string>;
+    totalSize: number;
+    chunkCount: number;
+    requestId?: string;
+}
+/** Outcome of a chunk apply: either still waiting, or completed with a ready body. */
+export type ChunkApplyResult = {
+    status: 'pending';
+} | {
+    status: 'completed';
+    meta: RelayStartMeta;
+    body: Buffer;
+} | {
+    status: 'error';
+    reason: string;
+};
+/** Outcome of a start: success or rejection (e.g., duplicate messageId). */
+export type StartResult = {
+    status: 'started';
+} | {
+    status: 'error';
+    reason: string;
+};
+/**
+ * Per-messageId reassembly registry.
+ *
+ * Single instance per orchestrator process. Concurrent inbound webhooks share
+ * the same registry but operate on separate Map entries keyed by messageId.
+ */
+export declare class RelayBufferRegistry {
+    private readonly buffers;
+    private readonly bufferTtlMs;
+    constructor(options?: {
+        bufferTtlMs?: number;
+    });
+    /** Number of in-flight reassembly buffers. Useful for metrics + tests. */
+    get size(): number;
+    /**
+     * Begin a new reassembly stream. Allocates an entry keyed by `meta.messageId`
+     * (passed through the meta object's caller — actually keyed externally below).
+     *
+     * Returns an error if `messageId` is already in flight (Platform sent two
+     * `start` frames with the same id, indicates a sender bug or abuse).
+     */
+    start(messageId: string, meta: RelayStartMeta): StartResult;
+    /**
+     * Apply one chunk. Returns `pending` if more chunks expected, `completed`
+     * with the assembled body when the final chunk closes the stream, or `error`
+     * for any malformed-stream condition.
+     *
+     * Stream errors drop the buffer — the caller MUST ack `rejected_misconfigured`
+     * and stop expecting further chunks for that messageId.
+     */
+    chunk(messageId: string, sequence: number, dataBase64: string, final: boolean): ChunkApplyResult;
+    /**
+     * Drop an in-flight buffer (TTL fired, stream errored, or assembly completed).
+     * Idempotent: dropping a missing messageId is a no-op.
+     */
+    drop(messageId: string): void;
+    /**
+     * Drop every in-flight buffer. Used during graceful shutdown so abandoned
+     * streams don't keep timers alive past process exit.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=relay-buffer.d.ts.map

package/dist/webhook/verify-inbound.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Inbound webhook verification dispatcher.
+ *
+ * Single entry point used by the orchestrator's chunked webhook.relay handler
+ * to decide whether an inbound webhook is trusted before it enters the normal
+ * processing pipeline. Dispatches by routing-key prefix to the appropriate
+ * provider verification path:
+ *
+ * - `github:*`  -> reads the webhook secret from PgSecretStore at scope
+ *                  `__source__/<sourceId>` and runs engine `verifySignature`
+ *                  against the inbound `x-hub-signature-256` header (or the
+ *                  signature header forwarded from Platform).
+ * - `generic:*` -> looks up the source via GenericSourceManager, parses
+ *                  `verification_method` + `verification_config`, and runs
+ *                  the corresponding HMAC / bearer / IP-allowlist check via
+ *                  `verifyGenericWebhook`.
+ *
+ * All four `WebhookRelayResult` outcomes are produced here:
+ * - `accepted` when the source exists and the inbound signature/method passes.
+ * - `rejected_signature` when the source exists but the signature does not match
+ *   any rotation secret (or method-specific check fails).
+ * - `rejected_unknown_source` when no row exists for the routing key (deleted,
+ *   never created, or the prefix is for a provider that is not yet implemented).
+ * - `rejected_misconfigured` when the source exists but its server-side state
+ *   prevents verification (no secret stored, malformed verification_config JSON,
+ *   etc). Operators should see this in metrics and fix the source config.
+ *
+ * The `reason` string returned alongside each rejection is non-secret-bearing
+ * (no HMAC keys, bearer tokens, computed signatures); it is safe to surface in
+ * `webhook.ack` reason field and in dashboards.
+ */
+import type { Kysely } from 'kysely';
+import type { WebhookRelayResult } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+import type { PgSecretStore } from '../secrets/pg-secret-store.js';
+import type { GenericSourceManager } from './generic-sources.js';
+/** Verification result + non-secret-bearing diagnostic for the orchestrator ACK. */
+export interface VerifyOutcome {
+    result: WebhookRelayResult;
+    reason?: string;
+}
+/** Inputs the orchestrator-side handler hands to the dispatcher. */
+export interface VerifyInboundInput {
+    /** Routing key including provider prefix (`github:<appId>`, `generic:<orgId>:<sourceId>`, ...). */
+    routingKey: string;
+    /** Reassembled raw body bytes from the chunked relay stream. */
+    body: Buffer;
+    /** Lowercased headers Platform forwarded for this inbound webhook. */
+    headers: Record<string, string>;
+    /**
+     * Inbound HTTP signature header NAME (lowercased), e.g. `x-hub-signature-256`.
+     * Null when the inbound HTTP request had no signature header at all (some
+     * generic verification methods do not need it; HMAC paths reject in that case).
+     */
+    signatureHeaderName: string | null;
+    /** Inbound HTTP signature header VALUE (the claimed signature). */
+    signatureHeader: string | null;
+    /** Inbound HTTP request client IP, for IP-allowlist verification. */
+    clientIp: string | null;
+}
+/** Dependencies the dispatcher reads from. */
+export interface VerifyInboundDeps {
+    /** Kysely DB handle for `sources` table lookups (github sources). */
+    db: Kysely<Database>;
+    /** Encrypted secret store for reading webhook secrets at `__source__/<sourceId>`. */
+    secretStore: PgSecretStore;
+    /** Manager for `generic_webhook_sources` rows. */
+    genericSourceManager: GenericSourceManager;
+}
+/**
+ * Run inbound verification for one webhook.
+ *
+ * Pure-ish: reads from the DB + secret store, but never throws — every error
+ * path collapses into a `WebhookRelayResult`. The orchestrator handler is
+ * waiting on a 5 s ACK budget and must not block on an exception.
+ */
+export declare function verifyInboundWebhook(deps: VerifyInboundDeps, input: VerifyInboundInput): Promise<VerifyOutcome>;
+//# sourceMappingURL=verify-inbound.d.ts.map

package/dist/worker/in-memory-execution-tracker.d.ts

@@ -0,0 +1,94 @@
+/**
+ * In-memory execution tracker for worker nodes.
+ *
+ * Workers have no database access. This lightweight implementation
+ * satisfies the same interface subset that the dispatcher and processor
+ * call (onExecutionStarted, onJobStatus, onStepStatus, getRunStatus),
+ * allowing those subsystems to work unchanged on workers.
+ *
+ * Optionally forwards status updates via a callback for coordinator relay,
+ * and maintains a ring buffer of recently completed jobs for /status.
+ */
+import type { ObserverRegistry } from '../ws/observer-registry.js';
+/** A status update forwarded to the coordinator. */
+export interface StatusUpdate {
+    type: 'job' | 'step';
+    runId: string;
+    jobId: string;
+    status: string;
+    stepIndex?: number;
+    stepName?: string;
+    timestamp: number;
+    data?: Record<string, unknown>;
+}
+/** A completed job entry in the ring buffer. */
+interface CompletedJobInfo {
+    runId: string;
+    jobId: string;
+    jobName: string;
+    status: string;
+    startedAt: number;
+    completedAt: number;
+    durationMs: number;
+}
+interface InMemoryExecutionTrackerOptions {
+    /** Callback to forward status updates to coordinator via P2P. */
+    onStatusForward?: (update: StatusUpdate) => void;
+    /** Maximum number of recent completed jobs to keep. Default: 50. */
+    recentJobsLimit?: number;
+    /** Optional observer registry for broadcasting to CLI observers. */
+    observerRegistry?: ObserverRegistry;
+}
+/** In-memory state for a single job within a run. */
+interface JobState {
+    name: string;
+    status: string;
+    startedAt?: number;
+    completedAt?: number;
+}
+/** In-memory state for a single execution run. */
+interface RunState {
+    workflowName: string;
+    provider: string;
+    repoIdentifier: string;
+    sha: string;
+    ref: string;
+    startedAt: number;
+    jobs: Map<string, JobState>;
+}
+export declare class InMemoryExecutionTracker {
+    private readonly onStatusForward?;
+    private readonly recentJobsLimit;
+    private readonly observerRegistry?;
+    private readonly runs;
+    private readonly recentJobs;
+    constructor(options: InMemoryExecutionTrackerOptions);
+    /**
+     * Record a new execution run with its initial jobs.
+     * Signature matches ExecutionTracker.onExecutionStarted (positional args).
+     */
+    onExecutionStarted(runId: string, workflowName: string, provider: string, repoIdentifier: string, ref: string, sha: string, _deliveryId: string | null, _providerContext: Record<string, unknown>, _triggerDecision: Record<string, unknown> | null, jobs: Array<{
+        jobId: string;
+        jobName: string;
+        matrixValues?: Record<string, unknown>;
+    }>): Promise<void>;
+    /**
+     * Update job status. Forwards to coordinator callback if configured.
+     */
+    onJobStatus(runId: string, jobId: string, status: string, timestamp: number, agentId?: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Update step status. Forwards to coordinator callback if configured.
+     */
+    onStepStatus(runId: string, jobId: string, stepIndex: number, stepName: string, status: string, timestamp: number, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Get the current status of a run.
+     */
+    getRunStatus(runId: string): RunState | null;
+    /**
+     * Get recent completed jobs (most recent first).
+     */
+    getRecentJobs(): CompletedJobInfo[];
+    private addToRecentJobs;
+}
+export {};
+//# sourceMappingURL=in-memory-execution-tracker.d.ts.map

package/dist/worker/in-memory-job-queue.d.ts

@@ -0,0 +1,74 @@
+/**
+ * In-memory job queue for worker nodes.
+ *
+ * Workers receive jobs directly from the coordinator via P2P dispatch,
+ * not from a database queue. This implementation satisfies the JobQueue
+ * interface with ephemeral in-memory storage, allowing the dispatcher
+ * subsystem to work unchanged on workers.
+ *
+ * Jobs enqueued here (when no agent is immediately available) are stored
+ * in memory and dequeued when an agent with matching labels connects.
+ */
+import { DispatchQueueStatus, type QueuedJobInput, type QueuedJob } from '../queue/job-queue.js';
+export declare class InMemoryJobQueue {
+    private readonly jobs;
+    /** Enqueue a job in memory and return its ID. */
+    enqueue(input: QueuedJobInput): Promise<string>;
+    /**
+     * Returns a generated UUID for direct-dispatch tracking, or honors the
+     * caller's pre-allocated jobId when set (cluster reroute path).
+     */
+    insertDispatched(input: QueuedJobInput): Promise<string>;
+    /**
+     * Dequeue the first pending job matching the given labels.
+     *
+     * `agentMandatoryLabels` mirrors the DB-backed `JobQueue.dequeueForLabels`
+     * gate: a job is only dequeued when its `runsOnLabels` includes every
+     * label in the gate set. Empty (default) is a no-op for static / non-scaler
+     * agents — the gate trivially passes.
+     */
+    dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
+    /**
+     * Dequeue a specific pending job by id, validating that the agent's labels
+     * still satisfy the job's runsOn / excludeLabels and the agent's
+     * `mandatoryLabels` gate. Mirrors the DB-backed `JobQueue.dequeueById`
+     * used by `Dispatcher.dispatchBoundJob()` when a scaler-managed agent
+     * registers and the scaler had bound a queued jobId to that agent at
+     * spawn time. Returns null if the job is missing, no longer Pending,
+     * labels no longer match, or the agent's gate is not satisfied.
+     */
+    dequeueById(jobId: string, agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
+    /** Return count of pending jobs. */
+    getDepth(): Promise<number>;
+    /** No-op — workers don't track dispatch status in a queue. */
+    markDispatched(_jobId: string, _agentId: string): Promise<void>;
+    /** No-op. */
+    markFailed(_jobId: string, _reason: string): Promise<void>;
+    /** No-op. */
+    markCompleted(_jobId: string): Promise<void>;
+    /** No-op. */
+    markRecovering(_jobId: string): Promise<void>;
+    /** Return all pending jobs. */
+    getPendingJobs(): Promise<QueuedJob[]>;
+    /** Always returns empty array. */
+    getDispatchedJobIdsByRunId(_runId: string): Promise<string[]>;
+    /** Always returns null. */
+    getJobById(_jobId: string): Promise<{
+        id: string;
+        runId: string;
+        status: DispatchQueueStatus;
+    } | null>;
+    /** Always returns false. */
+    markFailedIfRecovering(_jobId: string, _reason: string): Promise<boolean>;
+    /** Always returns false. */
+    markDispatchedIfRecovering(_jobId: string): Promise<boolean>;
+    /** Always returns empty array. */
+    getJobsByStatus(_status: DispatchQueueStatus): Promise<Array<{
+        id: string;
+        runId: string;
+        status: DispatchQueueStatus;
+    }>>;
+    /** No-op — nothing to expire. */
+    markExpired(): Promise<number>;
+}
+//# sourceMappingURL=in-memory-job-queue.d.ts.map

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

@@ -0,0 +1,58 @@
+/**
+ * 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
+ * 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). */
+interface SafeTokenInfo {
+    id: string;
+    token_prefix: string;
+    labels: string | null;
+    agent_type: string;
+    created_by: string | null;
+    expires_at: Date | null;
+    revoked_at: null;
+}
+export declare class StaticAgentTokenStore {
+    private readonly tokens;
+    /**
+     * Create a static (long-lived) agent token.
+     */
+    createStatic(opts: {
+        labels?: string[];
+        createdBy?: string;
+    }): Promise<{
+        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.
+     */
+    validate(token: string): Promise<SafeTokenInfo | null>;
+    /**
+     * Revoke a token by ID.
+     *
+     * @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.
+     */
+    cleanupExpired(): Promise<number>;
+}
+export {};
+//# sourceMappingURL=static-agent-token-store.d.ts.map

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

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { InMemoryExecutionTracker } from './in-memory-execution-tracker.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { PeerClient } from '../cluster/peer-client.js';
+export interface WorkerStatusDeps {
+    instanceId: string;
+    executionTracker: InMemoryExecutionTracker;
+    agentRegistry: AgentRegistry;
+    peerClient: PeerClient;
+    startedAt: number;
+    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.
+ */
+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.
+ */
+export declare function createWorkerDrainHandler(deps: WorkerStatusDeps): (_req: IncomingMessage, res: ServerResponse) => void;
+//# sourceMappingURL=worker-status.d.ts.map

package/dist/worker-core.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Worker mode bootstrap for the orchestrator.
+ *
+ * Workers are orchestrators in 'worker' mode. They connect to a coordinator
+ * via PeerClient, receive rerouted jobs, dispatch them to local agents,
+ * and report progress back to the coordinator.
+ *
+ * Workers do NOT have:
+ * - Database access (no PG, no Kysely, no migrations)
+ * - Platform relay connection
+ * - Raft consensus
+ * - Secrets management (secrets arrive pre-resolved in job.reroute)
+ * - Webhook handling, dedup, event routing, trust store
+ * - Registration/source management
+ * - Cache infra (bundle/dep cache, build coordinator)
+ * - Concurrency tracking, ownership tracking
+ * - Config reloader
+ *
+ * Workers DO have:
+ * - ScalerManager (local scaler backends)
+ * - AgentRegistry (in-memory agent tracking)
+ * - Dispatcher (local agent dispatch)
+ * - PeerClient (coordinator connection)
+ * - PeerRegistry (coordinator tracking)
+ * - InMemoryExecutionTracker (local state with forwarding)
+ * - InMemoryJobQueue (no-op queue)
+ * - StaticAgentTokenStore (in-memory tokens)
+ * - StepLogBuffer (log chunk buffering)
+ * - ObserverRegistry (CLI observer support)
+ * - HTTP server with /health and agent WS endpoint
+ */
+import type { AppConfig } from './config.js';
+import { AgentRegistry } from './agent/registry.js';
+import { Dispatcher } from './agent/dispatcher.js';
+import { PeerClient, PeerRegistry } from './cluster/index.js';
+import { InMemoryExecutionTracker } from './worker/in-memory-execution-tracker.js';
+import { InMemoryJobQueue } from './worker/in-memory-job-queue.js';
+import { StaticAgentTokenStore } from './worker/static-agent-token-store.js';
+import { StepLogBuffer } from './reporting/step-log-buffer.js';
+import { ObserverRegistry } from './ws/observer-registry.js';
+import { ScalerManager } from './scaler/index.js';
+import type { ScalerConfig } from './scaler/index.js';
+/**
+ * Subsystems available in worker mode.
+ * Subset of OrchestratorSubsystems with in-memory replacements.
+ */
+interface WorkerSubsystems {
+    config: AppConfig;
+    agentRegistry: AgentRegistry;
+    dispatcher: Dispatcher;
+    peerRegistry: PeerRegistry;
+    /** Outbound PeerClients keyed by coord URL. Workers fan out so every coord can dispatch directly. */
+    peerClients: Map<string, PeerClient>;
+    /** Convenience: first PeerClient (deterministic insertion order) for legacy single-client APIs. */
+    peerClient: PeerClient;
+    executionTracker: InMemoryExecutionTracker;
+    jobQueue: InMemoryJobQueue;
+    tokenStore: StaticAgentTokenStore;
+    stepLogBuffer: StepLogBuffer;
+    observerRegistry: ObserverRegistry;
+    scalerManager: ScalerManager | null;
+    scalerConfig: ScalerConfig | null;
+}
+/**
+ * Bootstrap the orchestrator in worker mode.
+ *
+ * Initializes only worker-relevant subsystems, connects to the coordinator
+ * via PeerClient, and starts an HTTP server with agent WS and health endpoints.
+ */
+export declare function bootstrapWorker(config: AppConfig, _opts?: {
+    otelSdk?: unknown;
+}): Promise<WorkerSubsystems>;
+export {};
+//# sourceMappingURL=worker-core.d.ts.map

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

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ *
+ * Adding a new API method:
+ * 1. Add the typed method + return type in @kici-dev/sdk (api-types.ts)
+ * 2. Call registry.register('namespace.method', 'read', handler) here
+ *
+ * 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>;
+/**
+ * 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.
+ */
+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
+     */
+    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
+     */
+    handle(agentId: string, method: string, params: Record<string, unknown>, allowedRoles: ApiRole[]): Promise<unknown>;
+    /** Get all registered method names (for diagnostics). */
+    getMethods(): string[];
+}
+//# sourceMappingURL=agent-api-registry.d.ts.map