@kici-dev/orchestrator 0.0.0 → 0.1.1

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

@@ -0,0 +1,96 @@
+import { type Kysely } from 'kysely';
+import type { Database, AgentTokenRow } from '../db/types.js';
+/**
+ * Safe token row shape returned from list/validate (excludes token_hash).
+ */
+export type SafeAgentTokenRow = Omit<AgentTokenRow, 'token_hash'>;
+/**
+ * Manages agent authentication tokens.
+ *
+ * Tokens are kat_ + 64 hex chars (32 random bytes = 256 bits).
+ * Only the SHA-256 hash is stored; the plaintext is returned once at generation time.
+ */
+export declare class AgentTokenStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Create a static (long-lived) agent token.
+     *
+     * Static tokens have no expiry and are intended for manually-registered agents.
+     *
+     * @param opts.labels - Optional agent labels this token is authorized for.
+     * @param opts.createdBy - Optional creator identifier (e.g. "cli:admin").
+     * @returns The plaintext token (shown once) and the DB row ID.
+     */
+    createStatic(opts: {
+        labels?: string[];
+        createdBy?: string;
+    }): Promise<{
+        token: string;
+        id: string;
+    }>;
+    /**
+     * Create an ephemeral (short-lived) agent token.
+     *
+     * Ephemeral tokens are issued by the scaler for auto-provisioned agents
+     * and expire after the specified TTL.
+     *
+     * @param agentId - The agent ID this token is for (used as created_by).
+     * @param labels - Agent labels this token is authorized for.
+     * @param ttlMs - Time-to-live in milliseconds.
+     * @returns The plaintext token (shown once).
+     */
+    createEphemeral(agentId: string, labels: string[], ttlMs: number): Promise<string>;
+    /**
+     * Validate a plaintext token against stored hashes.
+     *
+     * Checks that the token exists, is not revoked, and has not expired.
+     * On success, fires a non-blocking update to last_seen_at.
+     *
+     * @param token - The plaintext token to validate.
+     * @returns The token row (without hash) if valid, null otherwise.
+     */
+    validate(token: string): Promise<SafeAgentTokenRow | null>;
+    /**
+     * Revoke a token by ID.
+     *
+     * Sets revoked_at to now. Returns true if the token was revoked,
+     * false if it was already revoked or not found.
+     *
+     * @param id - The token row ID to revoke.
+     * @returns True if the token was newly revoked.
+     */
+    revoke(id: string): Promise<boolean>;
+    /**
+     * List all non-revoked tokens (excludes token_hash for security).
+     *
+     * @param opts.agentType - Optional filter by agent type ('static' | 'ephemeral').
+     * @returns Array of token rows without the hash field.
+     */
+    list(opts?: {
+        agentType?: string;
+    }): Promise<SafeAgentTokenRow[]>;
+    /**
+     * Clean up expired ephemeral tokens.
+     *
+     * Deletes rows where `expires_at < now()` and `agent_type = 'ephemeral'`.
+     * Called periodically by the orchestrator (every 60s) to keep the
+     * table from growing without bound.
+     *
+     * Optional `onBeforeDelete` callback is invoked once with the list
+     * of expired token IDs **before** the DELETE runs. The orchestrator
+     * uses this to call `agentRegistry.disconnectByTokenId(id)` for
+     * each expired row, so any in-flight WS that survived the
+     * per-token kick timer (e.g. across a process restart that wiped
+     * the in-memory `tokenExpiryTimers` map) is still kicked. Closes
+     * the sister gap to the revocation finding.
+     *
+     * @param opts.onBeforeDelete - Optional sync/async callback invoked
+     *   with expired token IDs before the DELETE.
+     * @returns Number of deleted rows.
+     */
+    cleanupExpired(opts?: {
+        onBeforeDelete?: (tokenIds: string[]) => void | Promise<void>;
+    }): Promise<number>;
+}
+//# sourceMappingURL=token-store.d.ts.map

package/dist/app.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Hono application factory for the customer orchestrator.
+ *
+ * Creates the HTTP + WebSocket application with:
+ * - Agent WebSocket endpoint at /ws for agent connections
+ * - Webhook endpoint for direct webhook ingestion (Hybrid/Independent)
+ * - Source-tarball serve endpoint at /api/v1/cache/source/:hash
+ * - Health/readiness check endpoints
+ * - Prometheus metrics endpoint
+ * - Request ID and logging middleware
+ * - 25MB body size limit
+ *
+ * Pattern follows packages/platform/src/app.ts: returns { app, injectWebSocket }.
+ */
+import type { Kysely } from 'kysely';
+import type pg from 'pg';
+import { type ColdStore } from '@kici-dev/shared';
+import type { AppConfig } from './config.js';
+import type { Database } from './db/types.js';
+import type { AgentRegistry } from './agent/registry.js';
+import type { Dispatcher } from './agent/dispatcher.js';
+import type { RunCoordinator } from './cluster/coordinator.js';
+import type { PeerRegistry } from './cluster/peer-registry.js';
+import type { JobQueue } from './queue/job-queue.js';
+import type { DedupCache } from './webhook/dedup.js';
+import type { LockFileCache } from './lockfile-cache.js';
+import type { PlatformClient } from './ws/platform-client.js';
+import type { ScalerManager } from './scaler/manager.js';
+import type { ProviderRegistry } from './provider-registry.js';
+import type { SourceCache } from './cache/index.js';
+import type { BuildCoordinator } from './cache/index.js';
+import type { DepCache } from './cache/index.js';
+import type { PendingBuildTracker } from './cache/index.js';
+import type { PendingInitTracker } from './cache/index.js';
+import type { PendingDynamicTracker } from './cache/index.js';
+import type { CacheStorage } from './storage/types.js';
+import { type CommitStatusReporter } from './reporting/commit-status.js';
+import type { ExecutionTracker } from './reporting/execution-tracker.js';
+import type { LogWriter } from './reporting/log-writer.js';
+import type { LogStorage } from './reporting/log-storage.js';
+import type { StepLogBuffer } from './reporting/step-log-buffer.js';
+import type { SourceLocationData } from './reporting/check-run-summary.js';
+import type { Hono as HonoType } from 'hono';
+import type { PeerWsLike } from './cluster/peer-handler.js';
+import type { PeerToPeerMessage } from '@kici-dev/engine';
+import type { AgentTokenStore } from './agent/token-store.js';
+import type { OwnershipTracker } from './agent/ownership-tracker.js';
+import type { ObserverRegistry } from './ws/observer-registry.js';
+import type { TokenManager } from './secrets/token-manager.js';
+import type { SecretResolver } from './secrets/secret-resolver.js';
+import { type AdminRouteDeps } from './routes/admin.js';
+import type { RegistrationStore } from './registration/registration-store.js';
+import type { RegistrationIndex } from './registration/registration-index.js';
+import type { CronScheduler } from './cron/cron-scheduler.js';
+import { type ConfigRouteDeps } from './routes/admin-config.js';
+import type { ConcurrencyGroupTracker } from './concurrency/group-tracker.js';
+import type { ConcurrencyQueueManager } from './concurrency/queue-manager.js';
+import type { EventRouter } from './events/event-router.js';
+import type { EventStore } from './events/event-store.js';
+import type { EventEmitter } from './events/event-emitter.js';
+import type { GlobalWorkflowPolicy } from './security/global-workflow-policy.js';
+import type { EventLogWriter } from './webhook/event-log.js';
+import type { AccessLogWriter } from './audit/access-log.js';
+import type { GenericSourceManager } from './webhook/generic-sources.js';
+import type { TrustStore } from './events/trust-store.js';
+import type { EnvironmentStore } from './environments/environment-store.js';
+import type { VariableStore } from './environments/variable-store.js';
+import type { HeldRunStore } from './environments/held-runs.js';
+import type { ContributorCache } from './security/contributor-cache.js';
+import { AgentMetricsAggregator } from './metrics/agent-metrics-aggregator.js';
+/**
+ * All dependencies needed to create the orchestrator Hono app.
+ */
+export interface AppDependencies {
+    config: AppConfig;
+    db: Kysely<Database>;
+    pool: pg.Pool;
+    registry: AgentRegistry;
+    dispatcher: Dispatcher;
+    jobQueue: JobQueue;
+    dedup: DedupCache;
+    lockFileCache: LockFileCache;
+    providerRegistry: ProviderRegistry;
+    platformClient?: PlatformClient;
+    scalerManager?: ScalerManager;
+    /** Bundle cache for compiled workflow bundles. Optional — requires S3 storage. */
+    sourceCache?: SourceCache;
+    /** Build coordinator for deduplicating concurrent builds. Optional — requires bundle cache. */
+    buildCoordinator?: BuildCoordinator;
+    /** Dep cache for dependency tarballs. Optional — requires S3 storage. */
+    depCache?: DepCache;
+    /** Cache storage backend (S3) for metadata operations on upload completion. */
+    cacheStorage?: CacheStorage;
+    /**
+     * Filesystem cache backend handle. Only set when KICI_STORAGE_TYPE is
+     * `filesystem`. Drives the /api/v1/cache/blob/* HTTP route that serves and
+     * receives signed-URL blob traffic the filesystem backend mints.
+     */
+    fsCache?: {
+        basePath: string;
+        signingSecret: string;
+        ttlMs: number;
+    };
+    /** Pending build tracker for build-then-execute coordination. Optional — requires bundle cache. */
+    pendingBuilds?: PendingBuildTracker;
+    /** Pending init tracker for init-then-execute coordination. */
+    pendingInits?: PendingInitTracker;
+    /** Pending dynamic tracker for DynamicJobFn evaluation coordination. */
+    pendingDynamics?: PendingDynamicTracker;
+    /** Commit status reporter for setting pending/success/failure/error on commits. Optional. */
+    commitStatusReporter?: CommitStatusReporter;
+    /** Execution tracker for DB persistence of execution state. Optional — requires database. */
+    executionTracker?: ExecutionTracker;
+    /** Log writer for persisting agent log chunks. Optional — requires database. */
+    logWriter?: LogWriter;
+    /** Log storage backend for persisting webhook payloads and step logs. Optional — requires S3 storage. */
+    logStorage?: LogStorage;
+    /** Step log buffer for enriched check run summaries. Optional — requires execution tracker. */
+    stepLogBuffer?: StepLogBuffer;
+    /** Agent token store for validating agent auth tokens. Required when agentAuth='token'. */
+    tokenStore?: AgentTokenStore;
+    /** Job ownership tracker for validating agent messages. Optional — requires database. */
+    ownershipTracker?: OwnershipTracker;
+    /** Admin API route dependencies. Optional -- only mounted when secrets management is configured. */
+    adminDeps?: AdminRouteDeps;
+    /** Config admin API route dependencies. Optional -- mounted when config management is available. */
+    configRouteDeps?: ConfigRouteDeps;
+    /** Event router for internal event delivery. Optional -- if not set, event routing is inactive. */
+    eventRouter?: EventRouter;
+    /** Event store. Optional -- mounted when admin DLQ admin route should be available. */
+    eventStore?: EventStore;
+    /** Event emitter for system events (workflow/job complete). Optional -- if not set, system events are skipped. */
+    eventEmitter?: EventEmitter;
+    /** Generic webhook source manager. Optional -- if not set, generic webhooks are disabled. */
+    genericSourceManager?: GenericSourceManager;
+    /** Trust store for cross-repo event trust. Optional -- if not set, trust management admin routes are unavailable. */
+    trustStore?: TrustStore;
+    /** Observer registry for broadcasting status/log updates to CLI observers. Optional -- if not set, observer features are inactive. */
+    observerRegistry?: ObserverRegistry;
+    /** Token manager for authenticating test trigger and observer connections. Optional -- requires secrets subsystem. */
+    tokenManager?: TokenManager;
+    /** Secret resolver for test run secret context resolution. Optional -- if not set, test runs have no secret access. */
+    secretResolver?: SecretResolver;
+    /** Cron scheduler for refreshing last-fired cache after registration changes. Optional — requires database. */
+    cronScheduler?: CronScheduler;
+    /** Registration store for admin registration routes. Optional -- mounted when registration system is initialized. */
+    registrationStore?: RegistrationStore;
+    /** Registration index for admin registration routes. Optional -- mounted when registration system is initialized. */
+    registrationIndex?: RegistrationIndex;
+    /** Environment store for resolving environment configs. Optional -- if not set, environment resolution is inactive. */
+    environmentStore?: EnvironmentStore;
+    /** Variable store for resolving environment variables. Optional -- if not set, environment vars are not merged. */
+    variableStore?: VariableStore;
+    /** Held run store for persisting protection rule holds. Optional -- if not set, holds are not persisted. */
+    heldRunStore?: HeldRunStore;
+    /** Global workflow policy for org-level permission enforcement. Optional -- if not set, global workflows are dispatched without permission checks. */
+    globalWorkflowPolicy?: GlobalWorkflowPolicy;
+    /** Inbound webhook delivery log writer. Optional -- if not set, deliveries are not persisted to event_log. */
+    eventLogWriter?: EventLogWriter;
+    /** Cold-store handle (Phase E). Optional -- when present, admin event-log routes can serve archived rows. */
+    coldStore?: ColdStore | null;
+    /** Read + mutation attribution log writer. Optional -- if not set, access_log rows are not written. */
+    accessLogWriter?: AccessLogWriter;
+    /** In-memory concurrency group tracker. Optional -- if not set, concurrency is disabled. */
+    concurrencyTracker?: ConcurrencyGroupTracker;
+    /** DB-backed concurrency queue manager. Optional -- if not set, concurrency is disabled. */
+    concurrencyQueueManager?: ConcurrencyQueueManager;
+    /** Optional callback when agent sends encrypted secret outputs on job success. */
+    onSecretOutputs?: (runId: string, jobId: string, secretOutputs: Record<string, {
+        agentPublicKey: string;
+        encrypted: string;
+    }>) => Promise<void>;
+    /** Cluster health routes (Hono app). Always mounted (cluster always on). */
+    clusterHealthRoutes: HonoType;
+    /** Peer WS handler for incoming peer connections. Always mounted (cluster always on). */
+    peerHandler: {
+        handleConnection: (ws: PeerWsLike, remoteIp?: string) => void;
+        sendToPeer: (targetInstanceId: string, msg: PeerToPeerMessage) => boolean;
+        getConnectionCount: () => number;
+    };
+    /** Optional join handler for direct peer join requests. */
+    onJoinRequest?: (msg: import('@kici-dev/engine').JoinRequest) => Promise<import('@kici-dev/engine').JoinResponse>;
+    /** Optional callback when agent inventory changes (connect/disconnect). Triggers peer heartbeat broadcast. */
+    onAgentInventoryChanged?: () => void;
+    /** Run coordinator for multi-orch claim/reroute. Optional -- if not set, jobs dispatch locally. */
+    coordinator?: RunCoordinator;
+    /** Peer registry for aggregating infrastructure across cluster. Optional. */
+    peerRegistry?: PeerRegistry;
+    /** Contributor permission cache. Optional -- threaded through from server.ts
+     *  so membership-related webhooks invalidate matching entries immediately
+     *  (instead of waiting for the 15-minute TTL). */
+    contributorCache?: ContributorCache;
+    /**
+     * Shared aggregator for agent-pushed metrics. When omitted, app.ts
+     * constructs its own — kept optional so existing tests still work
+     * without touching every call site. Production wiring threads the
+     * subsystem-built instance through so the Platform-bound MetricsReporter
+     * can read the same store and Mimir gets agent metrics per-org.
+     */
+    agentMetricsAggregator?: AgentMetricsAggregator;
+}
+/**
+ * In-memory cache for step source locations extracted from lock files.
+ * Keyed by `workflowName:jobName`, stores source location arrays indexed by step index.
+ * Populated during webhook processing, used by CommitStatusReporter for annotations.
+ */
+export declare class SourceLocationStore {
+    private readonly cache;
+    private key;
+    set(workflowName: string, jobName: string, locations: Array<SourceLocationData | undefined>): void;
+    get(workflowName: string, jobName: string): SourceLocationData[] | undefined;
+}
+/**
+ * Create Hono application with all routes and middleware.
+ *
+ * @param deps - Application dependencies (injected for testability)
+ * @returns Object with Hono app instance and injectWebSocket function
+ */
+export declare function createApp(deps: AppDependencies): {
+    app: import("hono/hono-base").HonoBase<import("hono/types").BlankEnv, import("hono/types").BlankSchema, string, string>;
+    injectWebSocket: (server: import("http").Server | import("http2").Http2Server | import("http2").Http2SecureServer) => void;
+    onSourceLocationsExtracted: (workflowName: string, jobName: string, locations: Array<{
+        file: string;
+        line: number;
+        column: number;
+    } | undefined>) => void;
+    /**
+     * Wake up the FIFO-next queued concurrency waiter for `(group, routingKey)`.
+     * Called by orchestrator-core when a slot is released (run completion,
+     * cancellation, supersession). No-op when concurrency is disabled.
+     */
+    tryDispatchNextQueued: ((group: string, routingKey: string) => Promise<void>) | undefined;
+};
+//# sourceMappingURL=app.d.ts.map

package/dist/audit/access-log.d.ts

@@ -0,0 +1,92 @@
+import type { Kysely } from 'kysely';
+import { type ColdStore } from '@kici-dev/shared';
+import { type AccessLogAction, type AccessLogItem, type AccessLogOutcome, type AccessLogRateLimiter, type AccessLogSource, type AccessLogTargetType, type ActorPrincipal, type ActorType } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+export interface AccessLogRecord {
+    orgId: string | null;
+    routingKey: string | null;
+    actor: ActorPrincipal;
+    action: AccessLogAction;
+    target: {
+        type: AccessLogTargetType;
+        id: string;
+    } | null;
+    requestId: string | null;
+    source: AccessLogSource;
+    outcome: AccessLogOutcome;
+    errorMessage?: string | null;
+}
+export interface AccessLogQueryFilter {
+    orgId?: string;
+    actorType?: ActorType;
+    actorId?: string;
+    action?: AccessLogAction;
+    source?: AccessLogSource;
+    outcome?: AccessLogOutcome;
+    targetType?: AccessLogTargetType;
+    targetId?: string;
+    fromTimestamp?: Date | string;
+    toTimestamp?: Date | string;
+    /** Full-text search over error_message (trigram-indexed). */
+    q?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface AccessLogQueryResult {
+    items: AccessLogItem[];
+    nextCursor: string | null;
+}
+/**
+ * Best-effort writer for the orchestrator `access_log` table. Records one
+ * row per read / orchestrator-admin mutation attributable to an
+ * ActorPrincipal. Callers get their actor from the incoming Platform proxy
+ * message (`msg.actor`) or from the admin HTTP auth chain.
+ *
+ * Failure mode: insert errors are logged and swallowed — a broken
+ * access_log table MUST NOT take down dashboard reads. Use `secret_audit_log`
+ * for the always-consistent secret mutation path; `access_log` is the
+ * read + broad-surface audit stream.
+ */
+export declare class AccessLogWriter {
+    private readonly db;
+    private coldStore;
+    private readonly rateLimiter;
+    constructor(db: Kysely<Database>, coldStore?: ColdStore, rateLimiter?: AccessLogRateLimiter);
+    /**
+     * Late-binding setter for the cold-store handle. orchestrator-core
+     * builds AccessLogWriter before the cold-store singleton, then
+     * attaches it via this setter (mirrors AuditLogger.setColdStore).
+     */
+    setColdStore(coldStore: ColdStore | null): void;
+    record(entry: AccessLogRecord): Promise<void>;
+    /**
+     * Phase D: delegates to `loadAccessLogRange` so cold-store rows are
+     * merged transparently when pagination crosses the warm cutoff. The
+     * caller-visible `{items, nextCursor}` shape is preserved. NO
+     * --include-archived flag — access_log is "paginated/transparent"
+     * per design §7 row 11.
+     */
+    query(filter: AccessLogQueryFilter): Promise<AccessLogQueryResult>;
+    /**
+     * Detail lookup by row id. Hot first; on miss falls back to a single
+     * cold-store tenant scan filtering by `id`. Mirrors the
+     * `loadEventLogByDeliveryId` pattern in `load-event-log-range.ts` —
+     * cold-store is partitioned by `(tenant_id, day)` with no cross-tenant
+     * `id` index, so the caller MUST scope the cold scan to one tenant.
+     *
+     * `opts.orgId` supplies the tenant scope. When omitted, only the
+     * synthetic `__orchestrator__` tenant is scanned (matches the
+     * NULL-org_id rows the orchestrator itself emits via
+     * `cold-store-archive` / `cold-store-purge`). The CLI exposes this as
+     * `kici-admin access-log show <id> --org-id <orgId>`.
+     *
+     * Best-effort contract: a cold-store error logs a warn line and
+     * returns null, matching `loadAccessLogRange` and
+     * `loadEventLogByDeliveryId`. A transient S3 outage MUST NOT
+     * manufacture a misleading 404-vs-500 distinction at the HTTP layer.
+     */
+    getById(id: string, opts?: {
+        orgId?: string;
+    }): Promise<AccessLogItem | null>;
+}
+//# sourceMappingURL=access-log.d.ts.map

package/dist/audit/sampling-rate-limiter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * In-memory rate limiter shared by AccessLogWriter and AuditLogger to enforce
+ * the per-action / per-actor caps defined in the engine's
+ * `POLICY_BY_ACTION` table (one row per minute per actor for diagnostics-class
+ * reads).
+ *
+ * Implementation: a single Map keyed by `${action}:${actorKey}` whose value
+ * is the last permit timestamp. The token bucket is implicit — a permit is
+ * granted iff `now - last >= floor(60_000 / perMinutePerActor)`. On each
+ * permit() call we lazily prune entries older than 5 minutes so memory
+ * stays bounded for long-lived orchestrators.
+ *
+ * Thread-safety: Node's single-threaded event loop guarantees the
+ * read-then-write below is atomic per call. No locking needed.
+ */
+import type { AccessLogAction, AccessLogRateLimiter } from '@kici-dev/engine';
+/**
+ * Implementation of `AccessLogRateLimiter` (engine interface). Constructed
+ * once per orchestrator process and injected into both
+ * `AccessLogWriter` and `AuditLogger`.
+ */
+export declare class SamplingRateLimiter implements AccessLogRateLimiter {
+    private readonly buckets;
+    private readonly now;
+    private lastPruneAt;
+    /**
+     * @param now  Time source override (test seam). Defaults to `Date.now`.
+     */
+    constructor(now?: () => number);
+    permit(action: AccessLogAction, actorKey: string, perMinute: number): boolean;
+    /**
+     * Drop entries older than PRUNE_TTL_MS. Called opportunistically from
+     * `permit()` so memory stays bounded without a background timer. With the
+     * 1-row/min/actor cap the map is naturally tiny (it grows by one entry
+     * per active actor and prunes after five minutes of silence).
+     */
+    private maybePrune;
+    /** Test-only: introspect the bucket size. */
+    size(): number;
+}
+//# sourceMappingURL=sampling-rate-limiter.d.ts.map

package/dist/cache/build-coordinator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Build coordinator for coalescing concurrent build requests.
+ *
+ * Ensures only one build runs per content hash. Subsequent requests
+ * for the same hash coalesce on the same Promise, avoiding duplicate
+ * compilation work.
+ *
+ * On success: all waiters resolve.
+ * On failure: all waiters reject with the build error.
+ * On timeout: all waiters reject with a timeout error.
+ */
+export declare class BuildCoordinator {
+    private readonly inFlight;
+    private readonly timeoutMs;
+    constructor(options?: {
+        timeoutMs?: number;
+    });
+    /**
+     * Ensure a build is running for the given content hash.
+     *
+     * If already in-flight, returns the existing promise (coalescing).
+     * If not, calls triggerBuild() and tracks the promise.
+     *
+     * @param contentHash - The content hash identifying the bundle to build
+     * @param triggerBuild - Async function that performs the actual build
+     */
+    ensureBuild(contentHash: string, triggerBuild: () => Promise<void>): Promise<void>;
+    /**
+     * Check if a build is currently in-flight for a content hash.
+     */
+    isBuilding(contentHash: string): boolean;
+    /**
+     * Get the number of in-flight builds (for metrics/debugging).
+     */
+    getInFlightCount(): number;
+    /**
+     * Run triggerBuild with a timeout. Rejects with a descriptive
+     * error if the build exceeds timeoutMs.
+     */
+    private runWithTimeout;
+}
+//# sourceMappingURL=build-coordinator.d.ts.map

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

@@ -0,0 +1,51 @@
+/**
+ * Dependency-specific cache layer wrapping CacheStorage.
+ *
+ * Stores and retrieves dependency tarballs keyed by lockfileHash + platform + arch.
+ * Shared CacheStorage backend with SourceCache (same S3 bucket).
+ * Refreshes TTL on reads (touch-on-read).
+ *
+ * Cache key format: deps/{platform}-{arch}/{lockfileHash}.tar.gz
+ */
+import type { CacheStorage } from '../storage/types.js';
+export declare class DepCache {
+    private readonly storage;
+    private readonly maxTarballBytes;
+    constructor(options: {
+        storage: CacheStorage;
+        maxTarballBytes?: number;
+    });
+    /** Check if a dep tarball exists in cache. */
+    has(lockfileHash: string, platform: string, arch: string): Promise<boolean>;
+    /**
+     * Get a pre-signed download URL for the dep tarball (for agent delivery).
+     * Refreshes TTL on hit.
+     */
+    getUrl(lockfileHash: string, platform: string, arch: string): Promise<string | null>;
+    /**
+     * Get a pre-signed download URL and the tarball content hash (if available).
+     * Returns null on cache miss. Hash may be undefined for old entries stored
+     * before integrity tracking was added.
+     */
+    getUrlAndHash(lockfileHash: string, platform: string, arch: string): Promise<{
+        url: string;
+        hash?: string;
+    } | null>;
+    /**
+     * Get a pre-signed upload URL for direct agent-to-S3 upload.
+     */
+    getUploadUrl(lockfileHash: string, platform: string, arch: string): Promise<string>;
+    /**
+     * Store a dep tarball in cache.
+     * Throws if tarball exceeds max size (per user decision).
+     */
+    store(lockfileHash: string, platform: string, arch: string, tarballData: Buffer): Promise<void>;
+    /**
+     * Compute SHA-256 hash of a tarball buffer.
+     * Used by build agents to compute the hash for depsHash protocol field.
+     */
+    static computeHash(data: Buffer): string;
+    /** Remove a dep tarball from cache. */
+    remove(lockfileHash: string, platform: string, arch: string): Promise<boolean>;
+}
+//# sourceMappingURL=dep-cache.d.ts.map

package/dist/cache/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Cache module for customer-workflow source tarballs and dependency tarballs.
+ *
+ * SourceCache: content-hash-keyed storage for `.kici/` source tarballs
+ *   (`source/{contentHash}.tar.gz`).
+ * BuildCoordinator: deduplicates concurrent build requests.
+ * DepCache: lockfileHash-keyed storage for dependency tarballs.
+ */
+export { SourceCache } from './source-cache.js';
+export { BuildCoordinator } from './build-coordinator.js';
+export { DepCache } from './dep-cache.js';
+export { PendingBuildTracker } from './pending-builds.js';
+export { PendingInitTracker } from './pending-inits.js';
+export type { InitResult } from './pending-inits.js';
+export { PendingDynamicTracker } from './pending-dynamics.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,14 @@
+/**
+ * Pending build tracker for coordinating build-then-execute pipeline.
+ *
+ * The orchestrator dispatches a build job and waits for the build agent to
+ * finish before retrieving cache URLs and dispatching execution jobs. The
+ * underlying tracker logic lives in `PendingTracker<void>`; this subclass
+ * just wires the build-specific logger prefix and disconnect error.
+ */
+import { PendingTracker } from './pending-tracker.js';
+export declare class PendingBuildTracker extends PendingTracker<void> {
+    constructor();
+    resolve(jobId: string): void;
+}
+//# sourceMappingURL=pending-builds.d.ts.map

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

@@ -0,0 +1,15 @@
+/**
+ * Pending dynamic-eval tracker for coordinating DynamicJobFn evaluation pipeline.
+ *
+ * The orchestrator dispatches a dynamic eval job for runtime job generation and
+ * waits for the agent to evaluate the DynamicJobFn and return the generated
+ * `LockJob[]` array. The underlying tracker logic lives in
+ * `PendingTracker<LockJob[]>`; this subclass wires the dynamic-eval-specific
+ * logger prefix and disconnect error.
+ */
+import type { LockJob } from '@kici-dev/engine';
+import { PendingTracker } from './pending-tracker.js';
+export declare class PendingDynamicTracker extends PendingTracker<LockJob[]> {
+    constructor();
+}
+//# sourceMappingURL=pending-dynamics.d.ts.map

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

@@ -0,0 +1,19 @@
+/**
+ * Pending init tracker for coordinating init-then-execute pipeline.
+ *
+ * The orchestrator dispatches an init job for dynamic environment resolution
+ * and waits for the agent to return the resolved field values
+ * (environmentName, env, concurrencyGroup). The underlying tracker logic lives
+ * in `PendingTracker<InitResult>`; this subclass wires the init-specific
+ * logger prefix and disconnect error.
+ */
+import { PendingTracker } from './pending-tracker.js';
+export interface InitResult {
+    environmentName?: string;
+    env?: Record<string, string>;
+    concurrencyGroup?: string;
+}
+export declare class PendingInitTracker extends PendingTracker<InitResult> {
+    constructor();
+}
+//# sourceMappingURL=pending-inits.d.ts.map