@kici-dev/orchestrator 0.1.15 → 0.1.16

package/dist/firecracker/persist.d.ts

@@ -0,0 +1,14 @@
+import { type FirecrackerBridgeConfig } from './host-network.js';
+export declare const BOOT_SCRIPT_DIR = "/usr/local/lib/kici-firecracker";
+export declare const SYSTEMD_DIR = "/etc/systemd/system";
+export declare function persistUnitName(bridgeName: string): string;
+export declare function renderPersistUnit(bridgeName: string): string;
+/**
+ * Install the boot script + unit and `systemctl enable` it (enable only — the
+ * deploy/CLI provisions the bridge live in the same run, so the unit fires on
+ * the NEXT boot rather than re-churning nft now).
+ */
+export declare function installPersist(cfg: FirecrackerBridgeConfig, opts?: {
+    requireSudo?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=persist.d.ts.map

package/dist/index.js

@@ -233,6 +233,9 @@ var S3CacheStorage = class {
 		items.sort((a, b) => b.created - a.created);
 		return items.map((i) => i.key);
 	}
+	async getMetadata(key) {
+		return this.readMeta(key);
+	}
 	async copy(srcKey, destKey) {
 		const srcObj = this.objectKey(srcKey);
 		const destObj = this.objectKey(destKey);
@@ -445,6 +448,9 @@ var FilesystemCacheStorage = class {
 		entries.sort((a, b) => b.mtime - a.mtime);
 		return entries.map((e) => e.key);
 	}
+	async getMetadata(key) {
+		return this.readMeta(key);
+	}
 	async copy(srcKey, destKey) {
 		const srcPath = this.resolvePath(srcKey);
 		const destPath = this.resolvePath(destKey);
@@ -741,9 +747,10 @@ var DepCache = class {
 * delete the temp), so a crashed save never leaves a corrupt final entry.
 *
 * Eviction: per-org byte quota plus the TTL the backing CacheStorage already
-* enforces lazily on access. On a save that pushes the org over quota, oldest
-* entries (by createdAt) are evicted until under quota; each eviction is
-* logged. The companion `.hash` / `.size` sidecar objects carry the integrity
+* enforces lazily on access. On a save that pushes the org over quota,
+* least-recently-used entries (oldest `lastAccessedAt`, read from the storage
+* backend's metadata) are evicted until under quota; each eviction is logged.
+* The companion `.hash` / `.size` sidecar objects carry the integrity
 * hash and size accounting outside the tarball's own (presigned, metadata-less)
 * upload.
 */
@@ -923,7 +930,7 @@ var UserCache = class {
 	async readHash(key) {
 		return (await this.storage.get(`${key}.hash`))?.toString("utf-8") || void 0;
 	}
-	/** Evict oldest entries for the org until total tarball size <= the per-org quota. */
+	/** Evict least-recently-used entries for the org until total tarball size <= the per-org quota. */
 	async enforceQuota(ref) {
 		const { quotaBytes } = await this.resolveLimits(ref.org);
 		const orgPrefix = this.orgPrefix(ref);
@@ -940,8 +947,19 @@ var UserCache = class {
 			});
 		}
 		if (total <= quotaBytes) return;
-		for (let i = sized.length - 1; i >= 0 && total > quotaBytes; i--) {
-			const { key, size } = sized[i];
+		const candidates = [];
+		for (const e of sized) {
+			const meta = await this.storage.getMetadata(e.key);
+			const lastAccessed = meta ? new Date(meta.lastAccessedAt).getTime() : 0;
+			candidates.push({
+				key: e.key,
+				size: e.size,
+				lastAccessed
+			});
+		}
+		candidates.sort((a, b) => a.lastAccessed - b.lastAccessed);
+		for (const { key, size } of candidates) {
+			if (total <= quotaBytes) break;
 			await this.storage.delete(key);
 			await this.storage.delete(`${key}.hash`);
 			await this.storage.delete(`${key}.size`);

package/dist/orchestrator-core.d.ts

@@ -22,7 +22,7 @@ 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 { type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage } from '@kici-dev/engine';
 import { ScalerManager } from './scaler/index.js';
 import type { ScalerConfig } from './scaler/index.js';
 import type { CacheStorage } from './storage/index.js';
@@ -146,6 +146,14 @@ export interface OrchestratorSubsystems {
      * store. the metrics enforcement plan.
      */
     agentMetricsAggregator: AgentMetricsAggregator;
+    /**
+     * Peer-side fleet collect responder. On an inbound peer.logs.collect.request,
+     * assembles this node's subtree and streams it back. Wired into every outgoing
+     * PeerClient (the incoming peer-handler is wired directly in setupCluster).
+     * Armed after the fleet runtime is built, so calls before that resolve to a
+     * no-op.
+     */
+    fleetCollectResponder: (msg: PeerLogsCollectRequest, send: (out: PeerToPeerMessage) => boolean) => Promise<void>;
 }
 /**
  * Mode-specific hooks injected by each entry point.

package/dist/pipeline/processor.d.ts

@@ -30,9 +30,11 @@ import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { RunCoordinator } from '../cluster/coordinator.js';
+import type { TeamMembershipLookup } from '../approvals/team-membership-lookup.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import type { SecretResolver } from '../secrets/secret-resolver.js';
 import type { ContributorCache } from '../security/contributor-cache.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
 import type { LockFile as FullLockFile, LockWorkflow, SimulatedEvent, WebhookNormalizer } from '@kici-dev/engine';
 import { LockFileParseError } from '@kici-dev/engine';
 import type { EventRouter } from '../events/event-router.js';
@@ -213,6 +215,17 @@ export declare function extractCommitMessage(event: string, payload: unknown): s
  * Build a human-readable summary for a security hold check.
  */
 export declare function buildSecurityHoldSummary(reason: string, tier: string, contributorUsername?: string): string;
+/**
+ * Build the pending check-run description for a job/workflow approval hold,
+ * naming the clauses an approver must satisfy. `{team:X}` renders as
+ * "team X", `{user:Y}` as "user Y". An empty clause list (any eligible
+ * reviewer satisfies the hold) falls back to a generic message.
+ */
+export declare function summarizeApprovalClauses(clauses: ReadonlyArray<{
+    team: string;
+} | {
+    user: string;
+}>): string;
 /**
  * Dependencies for the processing pipeline.
  * All injected for testability. Fully provider-agnostic.
@@ -283,6 +296,12 @@ export interface ProcessingDeps {
     identityLinks?: IdentityLink[];
     /** ci_trust permission levels per user ID from Platform push. Optional -- defaults to empty. */
     orgMemberPermissions?: Map<string, PermissionLevel>;
+    /**
+     * Team-membership lookup pushed from the Platform (team name → member set).
+     * Consumed by the approval resolver to satisfy `{team}` approval clauses.
+     * Optional -- defaults to "no teams".
+     */
+    teamMembershipLookup?: TeamMembershipLookup;
     /** Global workflow policy for org-level permission enforcement. Optional -- if not set, global workflows are unrestricted. */
     globalWorkflowPolicy?: GlobalWorkflowPolicy;
     /** Inbound webhook delivery log writer. Optional -- if not set, deliveries are not persisted to event_log. */
@@ -296,6 +315,9 @@ export interface ProcessingDeps {
      *  created in server.ts and threaded through both the Platform-relay WS
      *  path and the generic webhook HTTP path. */
     contributorCache?: ContributorCache;
+    /** Access-log writer for the orchestrator audit stream. Optional -- if not
+     *  set, hold-creation audit rows (`held_run.request`) are skipped. */
+    accessLogWriter?: AccessLogWriter;
 }
 /**
  * Check if any trigger in the lock file workflows uses path filters.

package/dist/routes/fleet.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fleet log-collection admin routes.
+ *
+ * GET  /admin/fleet-topology  — enumerate the cluster (no fan-out) for
+ *                               `debug-bundle --fleet --list` / `--pick`.
+ * POST /admin/fleet-bundle     — drive the recursive fan-out and stream the
+ *                               assembled nested ZIP back as an octet-stream.
+ *
+ * Both are protected by the same Bearer admin-token auth as the other admin
+ * routes (token-manager validation).
+ */
+import { Hono } from 'hono';
+import type { TokenManager } from '../secrets/token-manager.js';
+import type { FleetRoutesDeps } from '../app.js';
+export interface FleetAdminRouteDeps {
+    fleet: FleetRoutesDeps;
+    tokenManager: TokenManager;
+}
+export declare function createFleetRoutes(deps: FleetAdminRouteDeps): Hono;
+//# sourceMappingURL=fleet.d.ts.map

package/dist/scaler/config.d.ts

@@ -89,6 +89,7 @@ export declare const firecrackerNetworkSchema: z.ZodObject<{
     bridgeName: z.ZodDefault<z.ZodString>;
     gateway: z.ZodDefault<z.ZodString>;
     netmask: z.ZodDefault<z.ZodString>;
+    table: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 /**
  * Zod schema for the complete scaler configuration file.
@@ -241,10 +242,10 @@ export declare const scalerFileSchema: z.ZodObject<{
         }, z.core.$strip>>;
         mandatoryLabels: z.ZodDefault<z.ZodArray<z.ZodString>>;
         roles: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            all: "all";
             builder: "builder";
             "init-runner": "init-runner";
-            all: "all";
-        }>>>, z.ZodTransform<string[] | undefined, ("builder" | "init-runner" | "all")[] | undefined>>;
+        }>>>, z.ZodTransform<string[] | undefined, ("all" | "builder" | "init-runner")[] | undefined>>;
         resourceCap: z.ZodOptional<z.ZodPipe<z.ZodObject<{
             maxCpu: z.ZodOptional<z.ZodNumber>;
             maxMemory: z.ZodOptional<z.ZodString>;
@@ -272,6 +273,7 @@ export declare const scalerFileSchema: z.ZodObject<{
         bridgeName: z.ZodDefault<z.ZodString>;
         gateway: z.ZodDefault<z.ZodString>;
         netmask: z.ZodDefault<z.ZodString>;
+        table: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**

package/dist/scaler/disk-guard.d.ts

@@ -0,0 +1,27 @@
+import { type ReapCounts } from './reap-orphans.js';
+import type { ScalerConfig } from './index.js';
+/** Default minimum free space before startup is allowed to proceed: 1 GiB. */
+export declare const DEFAULT_DISK_GUARD_THRESHOLD_BYTES: number;
+export interface DiskGuardResult {
+    reaped: boolean;
+    recovered: boolean;
+    freeBytesAfter: number;
+}
+interface DiskGuardOpts {
+    scalerConfig: ScalerConfig;
+    thresholdBytes?: number;
+    /** Injectable for tests. */
+    statfsFn?: (path: string) => Promise<{
+        bavail: bigint;
+        bsize: number;
+    }>;
+    reapFn?: (cfg: ScalerConfig) => Promise<ReapCounts>;
+}
+/**
+ * Run the disk guard. Returns reaped/recovered status; the caller decides
+ * whether to proceed or exit with backoff. No-ops (recovered=true) when there
+ * is no FC scaler or free space is already above threshold.
+ */
+export declare function runDiskGuard(opts: DiskGuardOpts): Promise<DiskGuardResult>;
+export {};
+//# sourceMappingURL=disk-guard.d.ts.map

package/dist/scaler/firecracker-backend.d.ts

@@ -61,10 +61,14 @@ export interface FirecrackerScalerBackendOptions {
     memSizeMib?: number;
     /** Bridge interface name for TAP attachment */
     bridgeName: string;
+    /** Network CIDR (e.g. '10.0.0.0/24'); supplies the prefix for the bridge gateway CIDR. */
+    cidr?: string;
     /** Gateway IP for guest networking */
     gateway: string;
     /** Netmask for guest networking */
     netmask: string;
+    /** nft table name for host-network diagnostics. @default 'kici' */
+    table?: string;
     /** 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. */
@@ -99,8 +103,10 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
     private readonly vcpuCount;
     private readonly memSizeMib;
     private readonly bridgeName;
+    private readonly cidr;
     private readonly gateway;
     private readonly netmask;
+    private readonly table;
     private readonly tokenStore?;
     private readonly tokenTtlMs;
     private readonly roles;
@@ -120,6 +126,18 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
     getActiveCount(): number;
     spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits): Promise<ManagedAgent>;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
+    /**
+     * Bridge config for host-network diagnostics (read-only snapshot).
+     * `bridgeCidr` is the gateway IP with the network prefix (e.g. '10.0.0.1/24'),
+     * which is exactly what `provisionBridge`/`verifyBridge` consume. The prefix
+     * comes from the configured network `cidr`; if absent, it is derived from the
+     * dotted `netmask`.
+     */
+    getBridgeConfig(): {
+        bridgeName: string;
+        bridgeCidr: string;
+        table: string;
+    };
     destroy(managedId: string): Promise<void>;
     shutdownAll(): Promise<void>;
     /**

package/dist/scaler/manager.d.ts

@@ -336,6 +336,12 @@ export declare class ScalerManager {
      * Returns null if the agent is not scaler-managed (standalone).
      */
     getBackendForAgent(agentId: string): string | null;
+    /**
+     * Get a backend instance by scaler name. Returns undefined for an unknown
+     * name. Used by diagnostics to reach backend-specific accessors (e.g. the
+     * Firecracker backend's `getBridgeConfig()`).
+     */
+    getBackend(name: string): ScalerBackend | undefined;
     /**
      * Get scaler-specific configuration metadata for a managed agent.
      * Returns undefined for non-scaler-managed (static) agents.

package/dist/scaler/nftables.d.ts

@@ -17,6 +17,10 @@ import type { NetworkPolicy } from './types.js';
  * - 'saddr': Match on source IP address (container backends)
  */
 export type NftMatchMode = 'iifname' | 'saddr';
+/** RFC1918 private address ranges. */
+export declare const RFC1918_RANGES: string[];
+/** Cloud metadata service range (AWS/GCP/Azure link-local). */
+export declare const METADATA_RANGE = "169.254.0.0/16";
 /**
  * Options for nft command execution.
  */

package/dist/scaler/reap-orphans.d.ts

@@ -0,0 +1,27 @@
+import type { ScalerConfig } from './index.js';
+/** Per-scaler orphan counts, keyed by scaler name. */
+export type ReapCounts = Record<string, number>;
+/**
+ * Reap orphan Firecracker resources (dead-VM chroots + TAPs) for every
+ * `firecracker` scaler in the config. Safe to run alongside a live
+ * orchestrator: the reap is liveness-driven and only touches dead VMs.
+ */
+export declare function reapFirecrackerOrphans(scalerConfig: ScalerConfig): Promise<ReapCounts>;
+/**
+ * Reap orphan container resources for every `container` scaler. Unlike the FC
+ * reap, container cleanup is unconditional (it removes every kici-managed
+ * container), so callers MUST ensure the orchestrator is NOT running before
+ * invoking this — otherwise live agents are killed. The CLI command enforces
+ * this via the /health gate.
+ */
+export declare function reapContainerOrphans(scalerConfig: ScalerConfig): Promise<ReapCounts>;
+/**
+ * Reap orphans for all supported backends. Firecracker is always reaped
+ * (liveness-driven, safe). Containers are reaped only when includeContainers
+ * is set (caller has confirmed the orchestrator is down).
+ */
+export declare function reapAllOrphans(opts: {
+    scalerConfig: ScalerConfig;
+    includeContainers: boolean;
+}): Promise<ReapCounts>;
+//# sourceMappingURL=reap-orphans.d.ts.map

package/dist/scaler/types.d.ts

@@ -248,6 +248,8 @@ export interface FirecrackerNetworkConfig {
     gateway?: string;
     /** Subnet mask for guest networking @default '255.255.255.0' */
     netmask?: string;
+    /** nft table name for this coordinator's host bridge @default 'kici' */
+    table?: string;
 }
 /**
  * Parsed and validated scaler configuration from YAML.