@kici-dev/orchestrator 0.0.0 → 0.1.1

package/dist/lockfile-cache.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Provider-agnostic LRU cache for lock files.
+ *
+ * Wraps any LockFileFetcher with an in-memory LRU cache.
+ * Cache key: `{repoIdentifier}:{ref}` -- the fetcher handles
+ * content-addressable keying internally if the provider supports it.
+ *
+ * Replaces the old GitHub-specific LockFileCache in github/lockfile.ts.
+ */
+import type { LockFileFetcher, LockFile } from '@kici-dev/engine';
+export declare class LockFileCache {
+    private readonly cache;
+    private hits;
+    private misses;
+    constructor(options: {
+        max: number;
+        ttl: number;
+    });
+    /**
+     * Fetch the lock file for a repository at a specific ref,
+     * using the provided fetcher and LRU caching.
+     *
+     * @param fetcher - Provider-specific lock file fetcher
+     * @param repoIdentifier - Provider-specific repo identifier (e.g., "owner/repo")
+     * @param ref - Git ref (branch, tag, or commit SHA)
+     * @param credentials - Provider-specific credentials
+     * @returns Parsed lock file, or null if not found
+     */
+    get(fetcher: LockFileFetcher, repoIdentifier: string, ref: string, credentials: unknown): Promise<LockFile | null>;
+    /**
+     * Get cache statistics for metrics/monitoring.
+     */
+    getStats(): {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+}
+//# sourceMappingURL=lockfile-cache.d.ts.map

package/dist/metrics/agent-metrics-aggregator.d.ts

@@ -0,0 +1,116 @@
+/**
+ * In-memory aggregator for agent-pushed metrics.
+ *
+ * Agents push their OTel metrics snapshots via the WS `agent.metrics` message.
+ * This aggregator stores the latest snapshot per agent and produces a
+ * cardinality-bounded view by **collapsing all agents within the same
+ * scaler pool into one series per (metric, labels, scaler)**. The
+ * `agent_id` label is intentionally NOT emitted — including it would
+ * make Mimir cardinality grow with the number of agents that have ever
+ * existed (every ephemeral firecracker microVM minted a fresh ID), which
+ * is unbounded. The caller-side dashboard filters by `scaler` instead,
+ * which has a fixed enum of values (`stateful` / `container` /
+ * `firecracker` / `bare-metal`).
+ *
+ * Aggregation rules per metric kind:
+ *   - counter / upDownCounter / gauge → SUM across agents in the pool
+ *   - histogram → bucket-by-bucket SUM, plus summed `_count` / `_sum`
+ *
+ * Trade-off: counter rates are approximate during agent churn. If
+ * agent A reports `100` at t1 and disconnects, then agent B starts
+ * fresh at `0` for t2, the combined series steps 100 → 0 — which
+ * Prometheus interprets as a reset and `rate()` handles correctly.
+ * Over a longer window though (e.g. a day with many ephemeral agents
+ * appearing + disappearing), the integrated count can under-count.
+ * The orchestrator-side counters (`kici_orch_*`) are the canonical
+ * source for absolute totals; the agent counters here are for live
+ * "what's happening right now" panels.
+ *
+ * Cleanup: after an agent disconnects, its snapshot is retained for one
+ * configurable retention period (default 30s, ~2x scrape interval) so
+ * Prometheus can scrape it at least once before it disappears.
+ */
+/** Shape of a single metric data point pushed by the agent. */
+export interface MetricSnapshot {
+    name: string;
+    type: 'counter' | 'histogram' | 'gauge' | 'upDownCounter';
+    value?: number;
+    labels?: Record<string, string>;
+    buckets?: Array<{
+        le: number;
+        count: number;
+    }>;
+    count?: number;
+    sum?: number;
+}
+export declare class AgentMetricsAggregator {
+    private store;
+    private defaultRetentionMs;
+    /**
+     * Optional lookup: agentId → scaler backend name (e.g. `container`,
+     * `firecracker`, `bare-metal`). Returning null marks the agent as
+     * static / stateful — we then stamp the `scaler` label as `'stateful'`.
+     * Wired from ScalerManager.getBackendName in production. Tests can
+     * leave it undefined; in that case the `scaler` label is omitted.
+     */
+    private readonly getScalerForAgent?;
+    constructor(opts?: {
+        retentionMs?: number;
+        getScalerForAgent?: (agentId: string) => string | null;
+    });
+    /**
+     * Resolve the `scaler` label for one agentId. Centralized so both the
+     * structured snapshot (Mimir push) and the Prometheus text
+     * exporter (HTTP /metrics) stamp identical values.
+     */
+    private resolveScalerLabel;
+    /** Store or replace metrics for an agent. */
+    update(agentId: string, metrics: MetricSnapshot[]): void;
+    /** Mark an agent as disconnected (start the retention countdown). */
+    markDisconnected(agentId: string): void;
+    /** Remove entries where disconnectedAt + retentionMs < now. */
+    cleanup(retentionMs?: number): void;
+    /**
+     * Build a stable string key for grouping metrics across agents. The
+     * key encodes the metric name plus every label except `agent_id`
+     * (which is dropped) and including the resolved `scaler`. Sorted so
+     * insertion order can't sneak into the key.
+     */
+    private groupKey;
+    /**
+     * Walk every stored snapshot and bucket points into per-(metric, labels)
+     * groups, summing counter / gauge values and merging histogram buckets
+     * across all agents in each bucket. The bucketing key includes the
+     * `scaler` label and excludes `agent_id`, so the output is one series
+     * per (metric, labels-except-agent_id, scaler) combination.
+     *
+     * Returns one MetricSnapshot per group so both `getStructuredSnapshot`
+     * and `getPrometheusText` can iterate the same shape.
+     */
+    private aggregateAcrossAgents;
+    /**
+     * Produce a structured snapshot of all stored agent metrics in the
+     * `OrchMetrics['metrics']` wire shape — same format the orchestrator's
+     * own `MetricsReporter` produces from its OTel exporter. Used by the
+     * Platform-bound Mimir push pipeline so agent metrics land in Mimir
+     * per-org alongside `kici_orch_*` .
+     *
+     * Output is **already aggregated across agents per scaler** — see the
+     * class docstring for the cardinality rationale and counter trade-off.
+     *
+     * Runs `cleanup()` first so disconnected agents past their retention
+     * window stop being emitted.
+     */
+    getStructuredSnapshot(): MetricSnapshot[];
+    /**
+     * Produce Prometheus exposition text for all stored agent metrics,
+     * aggregated across agents per scaler. See `getStructuredSnapshot` for
+     * the aggregation rules. Runs auto-cleanup before generating output.
+     *
+     * Groups metrics by name and emits `# TYPE` directives so Prometheus
+     * correctly interprets histograms, counters, and gauges.
+     */
+    getPrometheusText(): string;
+    private formatHistogram;
+}
+//# sourceMappingURL=agent-metrics-aggregator.d.ts.map

package/dist/metrics/metrics-reporter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Periodic metrics reporter that collects OTel metrics and pushes them
+ * to the Platform via WebSocket as `orch.metrics` messages.
+ *
+ * The Platform aggregates these metrics from all orchestrators and exposes
+ * them on its `/metrics` endpoint for Prometheus scraping.
+ */
+import type { OrchMetrics } from '@kici-dev/engine';
+import type { AgentMetricsAggregator } from './agent-metrics-aggregator.js';
+export declare class MetricsReporter {
+    private timer?;
+    private readonly send;
+    private readonly intervalMs;
+    private readonly agentMetricsAggregator?;
+    constructor(opts: {
+        send: (msg: OrchMetrics) => void;
+        intervalMs?: number;
+        /**
+         * If provided, the reporter concatenates the aggregator's structured
+         * snapshot onto its own snapshot before sending — so agent metrics
+         * (`kici_agent_*`) land in Mimir per-org alongside `kici_orch_*`.
+         * Each agent metric carries an `agent_id` label injected by the
+         * aggregator. See the metrics enforcement plan.
+         */
+        agentMetricsAggregator?: AgentMetricsAggregator;
+    });
+    /** Start periodic metric collection and push. */
+    start(): void;
+    /** Stop the periodic reporter. */
+    stop(): void;
+    /** Collect current metrics and send as orch.metrics message. */
+    collectAndSend(): Promise<void>;
+    /** Collect a snapshot of all current OTel metrics. */
+    collectSnapshot(): Promise<OrchMetrics['metrics']>;
+    /** Map OTel DataPointType to wire format type string. */
+    private mapDataPointType;
+    /** Extract string labels from OTel Attributes. */
+    private extractLabels;
+}
+//# sourceMappingURL=metrics-reporter.d.ts.map

package/dist/metrics/prometheus.d.ts

@@ -0,0 +1,261 @@
+/** Set the current number of active agents. */
+export declare function setAgentsActive(value: number): void;
+/** Set the current config version number. */
+export declare function setConfigVersion(value: number): void;
+/** Set the current number of stale runs detected. */
+export declare function setStaleRunsCurrent(value: number): void;
+interface ScalerUsageRow {
+    scaler: string;
+    machinePool?: string;
+    cpus: number;
+    memBytes: number;
+}
+/**
+ * Replace the current scaler-usage breakdown.
+ *
+ * Called by ScalerManager whenever a reservation lands or releases. Caller is
+ * responsible for including a `scaler="__global__"` row for the orchestrator-wide
+ * total and one row per active machine pool (with `machinePool` set) reflecting
+ * the on-disk ledger snapshot. Per-scaler rows omit `machinePool`.
+ */
+export declare function setScalerUsageBreakdown(rows: ScalerUsageRow[]): void;
+/** Increment the spawn-refusal counter (called by ScalerManager when a request fails the cap check). */
+export declare function incScalerSpawnRefusals(): void;
+/**
+ * Update the dispatch-queue depth breakdown used by the Prometheus gauges.
+ *
+ * Called by the orchestrator's periodic depth refresher after polling the
+ * JobQueue. Normalizes the input so the gauge callback can emit explicit
+ * zero series for known statuses even when the queue is empty.
+ */
+export declare function setDispatchQueueDepthBreakdown(snapshot: {
+    byStatus: Partial<Record<'pending' | 'dispatched', number>>;
+    byLabel: Record<string, number>;
+}): void;
+/**
+ * Total webhooks received by the orchestrator.
+ * Labels:
+ * - source: relay (from Platform) | direct (webhook endpoint)
+ * - event: GitHub event type (push, pull_request, etc.)
+ */
+export declare const webhooksReceivedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total webhooks processed with outcome.
+ * Labels:
+ * - result: matched (triggered workflow) | skipped (no match) | error (processing failure)
+ */
+export declare const webhooksProcessedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Duration of trigger matching operations (lock file evaluation).
+ * Buckets: 1ms to 5s covering fast rejects through complex evaluations.
+ */
+export declare const triggerMatchDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Total deduplication cache hits (duplicate webhooks rejected).
+ */
+export declare const dedupHitsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total source cache hits (`.kici/` source tarball found for content hash).
+ */
+export declare const sourceCacheHitsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total source cache misses (no source tarball cached for content hash).
+ */
+export declare const sourceCacheMissesTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total dep cache hits (dependency tarball found for lockfile hash).
+ */
+export declare const depCacheHitsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total dep cache misses (no dependency tarball for lockfile hash).
+ */
+export declare const depCacheMissesTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Duration of build agent operations in seconds.
+ * Tracks how long it takes to compile a workflow bundle via a build agent.
+ * Buckets: 1s to 10min covering fast to slow compilations.
+ */
+export declare const buildDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Total execution runs tracked.
+ * Labels:
+ * - status: running | success | failed | cancelled
+ */
+export declare const executionsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Duration of execution runs in seconds.
+ * Buckets: 1s to 30min covering fast to long pipelines.
+ */
+export declare const executionDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Total steps executed.
+ * Labels:
+ * - status: running | success | failed | skipped
+ */
+export declare const stepsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total GitHub check run API calls (create + update + stale_cleanup).
+ * Labels:
+ * - operation: create | update | stale_cleanup
+ */
+export declare const githubCheckRunTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total log chunks received from agents.
+ */
+export declare const logChunksReceivedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total log bytes written to storage backend.
+ */
+export declare const logBytesStoredTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total number of scaler config reload operations.
+ * Labels:
+ * - result: attempted | success | failed
+ */
+export declare const scalerConfigReloadsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total number of config reload operations.
+ * Labels:
+ * - result: success | failed | attempted
+ * - source: sighup | http | cluster | cli
+ */
+export declare const configReloadTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total number of stale runs detected and marked as failed.
+ */
+export declare const staleRunsDetectedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Time between job becoming stale and detection (seconds).
+ * Buckets: 10s to 10min covering typical scan intervals.
+ */
+export declare const staleDetectionDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Number of webhook-trigger registrations matched when an inbound generic
+ * webhook fans out across sources in the same org.
+ *
+ * Recorded once per inbound webhook on the cross-source dispatch path
+ * (including zero-match cases). Label `event` is the inbound event name
+ * (NOT the literal 'generic_webhook' — see Pitfall 1 in 28.4 RESEARCH).
+ *
+ * Buckets cover small fan-outs (1-2 typical) through large org-wide fan-outs.
+ *
+ * NOTE: dashboard panel for `kici_cross_source_fanout_size` not yet added —
+ * follow-up per .claude/rules/monitoring.md (out of scope for plan 28.4-02).
+ */
+export declare const crossSourceFanoutSize: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Errors encountered during cross-source webhook dispatch.
+ *
+ * Labels:
+ * - reason: 'clone_token' (issuance failed) | 'bundle_missing' (registration's
+ *   provider bundle not found in registry)
+ *
+ * NOTE: dashboard panel for `kici_cross_source_errors_total` not yet added —
+ * follow-up per .claude/rules/monitoring.md (out of scope for plan 28.4-02).
+ */
+export declare const crossSourceErrorsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Counter for universal-git source registration errors at orchestrator
+ * startup or config reload. A non-zero rate indicates at least one
+ * `generic_webhook_sources` row with a non-null `git_config` could not be
+ * promoted to a provider bundle — the row stays in the DB but its routing
+ * key has no bundle, so webhooks for it will fall through to the generic
+ * bundle's payload-only path.
+ *
+ * Labels:
+ * - reason: 'invalid_config' (Zod parse failed) | 'bundle_build' (factory
+ *   threw) | 'registration' (providerRegistry.registerByRoutingKey threw)
+ */
+export declare const universalGitRegistrationErrorsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Counter for trust-resolution paths that were refused because the
+ * numeric provider id was absent (on either side) or did not match an
+ * identity link. Under the strict policy these refusals resolve the
+ * contributor to `unknown` regardless of username overlap.
+ *
+ * Labels:
+ * - reason: 'event_missing' (webhook payload had no sender.id) |
+ *   'link_missing' (a username-matched link has provider_user_id NULL) |
+ *   'id_mismatch' (a username-matched link has a different provider_user_id)
+ */
+export declare const trustMatchRefusedNoIdTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const eventDispatchSuccessTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const eventRetryTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const eventDlqTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const eventLeaseExpirationsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const eventAttemptsHistogram: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/** Set the current DLQ depth gauge. Refreshed by the leader-only retry scanner each tick. */
+export declare function setEventDlqDepth(value: number): void;
+/**
+ * Reason values for the `kici_orch_install_secrets_decisions_total` counter.
+ * The single source of truth — the resolver and tests both reference these
+ * constants, so adding a new reject path requires extending the union here.
+ */
+export declare const InstallSecretsDecisionReason: {
+    readonly Ok: "ok";
+    readonly MalformedRef: "malformed_ref";
+    readonly InvalidUrlScheme: "invalid_url_scheme";
+    readonly MissingEnvStore: "missing_env_store";
+    readonly MissingSecretResolver: "missing_secret_resolver";
+    readonly EnvNotFound: "env_not_found";
+    readonly ProtectionRuleBlock: "protection_rule_block";
+    readonly MissingToken: "missing_token";
+    readonly MissingInstallEnv: "missing_install_env";
+};
+export type InstallSecretsDecisionReason = (typeof InstallSecretsDecisionReason)[keyof typeof InstallSecretsDecisionReason];
+/**
+ * Channel label for `kici_orch_install_secrets_npm_registry_used_total`.
+ * - `registries` is Option A (workflow-level `registries:` block).
+ * - `install_env` is Option C (committed `.kici/.npmrc` + `installEnv:`).
+ */
+export declare const InstallSecretsChannel: {
+    readonly Registries: "registries";
+    readonly InstallEnv: "install_env";
+};
+export type InstallSecretsChannel = (typeof InstallSecretsChannel)[keyof typeof InstallSecretsChannel];
+/**
+ * Total install-secrets resolution decisions.
+ *
+ * Labels:
+ * - decision: pass | reject
+ * - reason: ok (only with `pass`), or one of the reject reasons enumerated in `InstallSecretsDecisionReason`
+ *
+ * Pass series are emitted exactly once per resolver call that does any work
+ * (workflows declaring neither `registries:` nor `installEnv:` are NOT
+ * counted — that's the trivial early-return path and dashboard rates would
+ * be dominated by it).
+ */
+export declare const installSecretsDecisionsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total registry / installEnv entries that successfully resolved on a
+ * passing dispatch. Each entry contributes one increment, so a workflow
+ * with two `registries:` rows and one `installEnv:` entry adds three.
+ *
+ * Labels:
+ * - channel: registries (Option A workflow block) | install_env (Option C committed .npmrc + installEnv:)
+ * - provider: static today (long-lived `tokenSecret`); reserved for the typed RegistryProvider (aws-codeartifact, gcp-artifact-registry, …) when that lands
+ * - scope: the npm scope string like `@my-org`, the literal `default` for a no-scope default registry, or `-` for install_env entries (no scope concept on Option C)
+ */
+export declare const installSecretsRegistryUsedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Total dispatches where the orchestrator stripped registry tokens because
+ * the resolved contributor trust tier was not `trusted` (fork PRs from
+ * unknown contributors). Defense-in-depth: even if a misconfigured
+ * environment lacks a `minimum_trust` rule, this strip prevents tokens
+ * from leaving the orchestrator for those dispatches.
+ *
+ * Labels:
+ * - trust_tier: unknown | known (the `trusted` tier does not strip and therefore never fires this counter)
+ */
+export declare const installSecretsContributorStrippedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Per-environment latency of `secretResolver.resolveForJob` calls in the
+ * install-secrets path. Buckets mirror `triggerMatchDurationSeconds`:
+ * 1ms → 5s covers fast Postgres reads through pathological Vault timeouts.
+ *
+ * Labels:
+ * - environment: the environment name referenced in the qualified `<environment>:<secret>` ref (per-org count is typically <10)
+ */
+export declare const installSecretsTokenResolutionDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+export {};
+//# sourceMappingURL=prometheus.d.ts.map

package/dist/metrics/scheduled-jobs.d.ts

@@ -0,0 +1,20 @@
+/** Success/failure counter for each tick of each scheduled job. */
+export declare const jobRunsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Histogram of per-tick duration, seconds. */
+export declare const jobDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/** Unix timestamp (seconds) of the most recent successful tick. */
+export declare const jobLastSuccessTimestamp: {
+    set(labels: Record<string, string>, value: number): void;
+    reset(): void;
+};
+/** Unix timestamp (seconds) of the most recent failed tick. */
+export declare const jobLastFailureTimestamp: {
+    set(labels: Record<string, string>, value: number): void;
+    reset(): void;
+};
+/** Count of consecutive failures since last success. Resets to 0 on success. */
+export declare const jobConsecutiveFailures: {
+    set(labels: Record<string, string>, value: number): void;
+    reset(): void;
+};
+//# sourceMappingURL=scheduled-jobs.d.ts.map

package/dist/orchestrator-core.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Shared orchestrator bootstrap logic.
+ *
+ * Both server.ts (platform/hybrid) and standalone.ts (independent) delegate to
+ * bootstrapOrchestrator() for all startup/shutdown work that is identical
+ * between the two modes. Mode-specific behavior is injected via the
+ * OrchestratorHooks interface.
+ *
+ * This eliminates ~1300 lines of duplication that previously existed across
+ * the two entry points.
+ */
+import { type ColdStore } from '@kici-dev/shared';
+import type { AppConfig } from './config.js';
+import { ConfigReloader } from './config/reload.js';
+import { AgentRegistry } from './agent/registry.js';
+import { JobQueue } from './queue/job-queue.js';
+import { EventLogWriter } from './webhook/event-log.js';
+import { AccessLogWriter } from './audit/access-log.js';
+import { Dispatcher } from './agent/dispatcher.js';
+import { LockFileCache } from './lockfile-cache.js';
+import { DedupCache } from './webhook/dedup.js';
+import { ObserverRegistry } from './ws/observer-registry.js';
+import { AgentMetricsAggregator } from './metrics/agent-metrics-aggregator.js';
+import { SourceLocationStore } from './app.js';
+import { type PeerHeartbeat } from '@kici-dev/engine';
+import { ScalerManager } from './scaler/index.js';
+import type { ScalerConfig } from './scaler/index.js';
+import type { CacheStorage } from './storage/index.js';
+import { SourceCache, BuildCoordinator, DepCache, PendingBuildTracker, PendingInitTracker, PendingDynamicTracker } from './cache/index.js';
+import { CommitStatusReporter } from './reporting/commit-status.js';
+import { StepLogBuffer } from './reporting/step-log-buffer.js';
+import { type LogStorage } from './reporting/log-storage.js';
+import { ExecutionTracker, type ExecutionTrackerDeps } from './reporting/execution-tracker.js';
+import { LogWriter } from './reporting/log-writer.js';
+import { PeerRegistry, PeerClient, createPeerHandler, RaftNode, OrphanRecovery, RunCoordinator } from './cluster/index.js';
+import { SourceStore, SourceManager } from './sources/index.js';
+import { PgSecretStore, AuditLogger, SecretResolver } from './secrets/index.js';
+import type { SecretStore } from '@kici-dev/engine';
+import type { AdminRouteDeps } from './routes/admin.js';
+import { AgentTokenStore } from './agent/token-store.js';
+import { OwnershipTracker } from './agent/ownership-tracker.js';
+import { EventRouter } from './events/event-router.js';
+import { EventEmitter } from './events/event-emitter.js';
+import { TrustStore } from './events/trust-store.js';
+import { GenericSourceManager } from './webhook/generic-sources.js';
+import { RegistrationStore } from './registration/registration-store.js';
+import { RegistrationIndex } from './registration/registration-index.js';
+import { CronScheduler } from './cron/cron-scheduler.js';
+import { ProviderRegistry } from './provider-registry.js';
+import { JoinHandler } from './cluster/join-handler.js';
+import type { Kysely } from 'kysely';
+import type { Database } from './db/types.js';
+import type pg from 'pg';
+/**
+ * All subsystems that are created during bootstrap.
+ * Passed to hooks so mode-specific code can wire callbacks.
+ */
+export interface OrchestratorSubsystems {
+    config: AppConfig;
+    db: Kysely<Database>;
+    pool: pg.Pool;
+    providerRegistry: ProviderRegistry;
+    agentRegistry: AgentRegistry;
+    dispatcher: Dispatcher;
+    queue: JobQueue;
+    scalerManager: ScalerManager | null;
+    scalerConfig: ScalerConfig | null;
+    cacheStorage: CacheStorage | undefined;
+    sourceCache: SourceCache | undefined;
+    depCache: DepCache | undefined;
+    buildCoordinator: BuildCoordinator | undefined;
+    pendingBuilds: PendingBuildTracker | undefined;
+    pendingInits: PendingInitTracker;
+    pendingDynamics: PendingDynamicTracker;
+    commitStatusReporter: CommitStatusReporter;
+    stepLogBuffer: StepLogBuffer;
+    sourceLocationStore: SourceLocationStore;
+    logStorage: LogStorage;
+    logWriter: LogWriter;
+    observerRegistry: ObserverRegistry;
+    executionTracker: ExecutionTracker;
+    secretResolver: SecretResolver | null;
+    adminDeps: AdminRouteDeps | undefined;
+    pgSecretStore: PgSecretStore | undefined;
+    tokenStore: AgentTokenStore;
+    ownershipTracker: OwnershipTracker;
+    lockFileCache: LockFileCache;
+    dedup: DedupCache;
+    eventRouter: EventRouter;
+    eventEmitter: EventEmitter;
+    genericSourceManager: GenericSourceManager;
+    trustStore: TrustStore;
+    registrationStore: RegistrationStore;
+    registrationIndex: RegistrationIndex;
+    cronScheduler: CronScheduler;
+    peerRegistry: PeerRegistry;
+    raft: RaftNode;
+    coordinator: RunCoordinator;
+    orphanRecovery: OrphanRecovery;
+    peerHandler: ReturnType<typeof createPeerHandler>;
+    peerClients: Map<string, PeerClient>;
+    getLocalInventory: () => Omit<PeerHeartbeat, 'type'>;
+    broadcastHeartbeatToAllPeers: () => void;
+    broadcastAgentTokenRevoke: (tokenId: string) => void;
+    joinHandler: JoinHandler;
+    configReloader: ConfigReloader;
+    localConfigVersion: number;
+    sourceStore: SourceStore;
+    sourceManager: SourceManager;
+    /** Inbound webhook delivery log writer (event_log table + object-storage payloads). */
+    eventLogWriter: EventLogWriter;
+    /** Access log writer (read + mutation attribution for dashboard + admin). */
+    accessLogWriter: AccessLogWriter;
+    /**
+     * Long-lived cold-store handle. Read paths (dashboard, CLI) use this
+     * for transparent fallback to S3 when a row has aged out of PG. The
+     * scheduled archive cycle constructs its own ephemeral instance per
+     * tick (so SIGHUP-driven config reload picks up new bucket / prefix
+     * values without a restart) — these two instances are independent.
+     * `null` when cold-store is not enabled in the env.
+     */
+    coldStore: ColdStore | null;
+    /**
+     * In-memory aggregator for agent-pushed metrics. Constructed once at
+     * subsystem-build time so both the HTTP `/metrics` exposition path
+     * (orchestrator-side) and the Platform-bound MetricsReporter (which
+     * concatenates the agent snapshot before WS push so agent metrics
+     * land in Mimir per-org alongside `kici_orch_*`) reference the same
+     * store. the metrics enforcement plan.
+     */
+    agentMetricsAggregator: AgentMetricsAggregator;
+}
+/**
+ * Mode-specific hooks injected by each entry point.
+ */
+export interface OrchestratorHooks {
+    /** Logger prefix for mode-specific messages */
+    logPrefix: string;
+    /**
+     * Extra ExecutionTracker callbacks (e.g., Platform-mode forwards execution
+     * status and step status to the relay).
+     */
+    executionTrackerExtras?: (subsystems: OrchestratorSubsystems) => {
+        onExecutionStatusChange?: ExecutionTrackerDeps['onExecutionStatusChange'];
+        onStepStatusForward?: ExecutionTrackerDeps['onStepStatusForward'];
+        onJobStatusChange?: ExecutionTrackerDeps['onJobStatusChange'];
+        onRunEventEmit?: ExecutionTrackerDeps['onRunEventEmit'];
+        orgId?: string;
+    };
+    /**
+     * Called after the secrets subsystem is initialized.
+     * Server.ts uses this to create SecretResolver; standalone doesn't.
+     */
+    onSecretsInitialized?: (ctx: {
+        pgSecretStore: PgSecretStore;
+        backendStores: Map<string, SecretStore>;
+        db: Kysely<Database>;
+        auditLogger: AuditLogger;
+    }) => SecretResolver | null;
+    /**
+     * Called after all subsystems are built, before HTTP server starts.
+     * Mode-specific wiring (PlatformClient creation, peer client setup, etc.)
+     *
+     * Returns mode-specific dependencies to pass to createApp() and
+     * additional shutdown steps.
+     */
+    onSubsystemsReady: (subsystems: OrchestratorSubsystems) => Promise<{
+        /** Extra dependencies to merge into createApp() */
+        appDepsExtras?: Record<string, unknown>;
+        /** Extra ConfigReloader deps beyond shared ones */
+        configReloaderExtras?: {
+            onProviderChange?: (newConfig: AppConfig, oldConfig: AppConfig, subsystems: OrchestratorSubsystems) => Promise<void>;
+            onPlatformReconnect?: (newConfig: AppConfig) => Promise<void>;
+        };
+        /** Extra shutdown steps in order (run before shared shutdown) */
+        shutdownExtras?: Array<{
+            label: string;
+            fn: () => Promise<void> | void;
+        }>;
+        /** Called after HTTP server starts (e.g., PlatformClient.connect) */
+        onServerStarted?: () => Promise<void>;
+    }>;
+    /**
+     * Mode startup log message.
+     */
+    startupLogMessage: (port: number) => string;
+}
+export declare function bootstrapOrchestrator(config: AppConfig, hooks: OrchestratorHooks, options?: {
+    otelSdk?: {
+        shutdown(): Promise<void>;
+    };
+}): Promise<void>;
+//# sourceMappingURL=orchestrator-core.d.ts.map