@kici-dev/orchestrator 0.1.20 → 0.1.22

package/dist/agent/dispatcher.d.ts

@@ -13,6 +13,18 @@ export interface DispatchMetrics {
     /** Set the queue depth gauge. */
     setQueueDepth(depth: number): void;
 }
+/**
+ * Narrow slice of `HostRosterStore` the dispatcher needs for the host-restart
+ * flow. Kept as an interface so the dispatcher doesn't import the full store
+ * (which pulls in engine label matchers) and to make the reboot logic testable
+ * with a tiny in-memory stub.
+ */
+export interface HostRosterRebootStore {
+    /** True when the host's reboot-pending deadline is still in the future. */
+    isRebootPending(agentId: string, nowMs: number): Promise<boolean>;
+    /** Clear the reboot-pending flag (down-then-up release on reconnect). */
+    clearRebootPending(agentId: string): Promise<void>;
+}
 /**
  * Result of a dispatch attempt.
  */
@@ -120,6 +132,8 @@ export declare class Dispatcher {
     private readonly recoveringJobs;
     /** Grace period = 2x max reconnection delay. */
     private get gracePeriodMs();
+    /** Host roster store for the reboot-pending gate; undefined ⇒ flow inert. */
+    private readonly rosterStore?;
     constructor(deps: {
         registry: AgentRegistry;
         queue: JobQueue;
@@ -139,6 +153,14 @@ export declare class Dispatcher {
         getAckTimeoutMs?: (job: QueuedJob) => Promise<number>;
         /** Cancel + disconnect an agent whose dispatch ack deadline expired. */
         onAckTimeout?: (agentId: string, jobId: string, runId: string) => void;
+        /**
+         * Host roster store, used for the workflow-level host-restart flow: gate the
+         * pinned-drain off for a reboot-pending agent, and treat a reboot-pending
+         * agent's disconnect as the expected reboot (complete its in-flight job
+         * success rather than starting the recovery-fail timer). Omitted ⇒ the
+         * reboot-pending behavior is inert (every host reads not-pending).
+         */
+        rosterStore?: HostRosterRebootStore;
     });
     /**
      * Dispatch a job to a matching agent, or queue it if none available.
@@ -181,6 +203,20 @@ export declare class Dispatcher {
      * Dequeues matching jobs from the queue while the agent has capacity,
      * calling onDispatch for each.
      */
+    /**
+     * Drop agents whose reboot-pending flag is set from a candidate list. Used by
+     * the label-routed dispatch path so a post-restart job is never sent to a host
+     * that is about to reboot. No-op when no roster store is wired.
+     */
+    private filterRebootPending;
+    /**
+     * Release a reboot-pending host on its real reconnect (down-then-up). Clears
+     * the persisted flag so the very next `onAgentAvailable` drain dispatches the
+     * held post-restart job. Call this ONLY from the (re-)register path — a fresh
+     * connection after the box rebooted — never from a still-connected drain
+     * trigger (job completion / agent.status), which must keep the gate closed.
+     */
+    releaseRebootPending(agentId: string): Promise<void>;
     onAgentAvailable(agentId: string): Promise<void>;
     /** Record that a job began executing on its agent. */
     markJobStarted(jobId: string): void;
@@ -239,6 +275,14 @@ export declare class Dispatcher {
      * asynchronously when recovery timers expire).
      */
     onAgentDisconnect(agentId: string): Promise<string[]>;
+    /**
+     * Reboot-pending agent disconnected: complete its in-flight started job(s) as
+     * success (the restart job, which already reported success, may already be
+     * terminal — `markCompleted` is a no-op / guarded in that case). Never starts
+     * a recovery timer. Untracks the jobs so the reconnect does not reconcile a
+     * phantom in-flight set.
+     */
+    private completeInFlightForReboot;
     /** Drop grace-window entries owned by an agent. */
     private cleanupGraceEntriesForAgent;
     /**

package/dist/agent/host-roster-reaper.d.ts

@@ -1,6 +1,6 @@
 import type { HostRosterStore } from './host-roster.js';
 export interface HostRosterReaperOptions {
-    store: Pick<HostRosterStore, 'reapEphemeralPastTtl' | 'countStaticUnreachable'>;
+    store: Pick<HostRosterStore, 'reapEphemeralPastTtl' | 'countStaticUnreachable' | 'listExpiredRebootPending' | 'clearRebootPending'>;
     ttlMs: number;
     /** Grace window for the connected-but-stale case in `countStaticUnreachable`. */
     graceMs: number;
@@ -30,6 +30,7 @@ export declare class HostRosterReaper {
     private readonly graceMs;
     private readonly scanIntervalMs;
     private readonly setUnreachableGauge;
+    private readonly rebootSweep;
     private timer;
     private isLeader;
     constructor(opts: HostRosterReaperOptions);

package/dist/agent/host-roster.d.ts

@@ -1,6 +1,8 @@
 import { type Kysely } from 'kysely';
-import { type LabelMatcher } from '@kici-dev/engine';
+import { type HostInventoryEntry, type InventorySelector, type LabelMatcher } from '@kici-dev/engine';
 import type { Database, HostRosterRow } from '../db/types.js';
+/** Typed host-vars bag carried by roster rows (`string | number | boolean`). */
+export type HostProperties = Record<string, string | number | boolean>;
 /**
  * Derived (read-time) status of a roster host. Never a stored mutable column:
  * status is computed from the shared `last_seen` + `connected_instance_id` so
@@ -33,6 +35,8 @@ export interface MatchedHost {
     status: HostStatus;
     platform: string | null;
     arch: string | null;
+    /** Typed host-vars bag (parsed from `host_properties`). */
+    properties: HostProperties;
 }
 export interface UpsertHostInput {
     agentId: string;
@@ -43,6 +47,13 @@ export interface UpsertHostInput {
     platform: string;
     arch: string;
     instanceId: string;
+    /**
+     * Agent-reported typed host-vars. Shallow-merged into any existing bag on
+     * conflict (agent-reported keys win; operator-declared keys the agent does
+     * not report are preserved). Omitted ⇒ no change to the stored bag on update,
+     * `{}` on insert.
+     */
+    properties?: HostProperties;
 }
 /** Minimal row shape `deriveHostStatus` reads (the store row or the CLI row). */
 export interface HostStatusRow {
@@ -60,6 +71,12 @@ export interface HostStatusRow {
  * `stale` (scaled down, awaiting reap).
  */
 export declare function deriveHostStatus(row: HostStatusRow, nowMs: number, graceMs: number): HostStatus;
+/**
+ * Normalize a stored `host_properties` value into a typed host-vars bag. The pg
+ * driver returns parsed JSON for a `jsonb` column, but accept a JSON string too
+ * (defensive for non-pg paths / tests). Non-object / null reads back as `{}`.
+ */
+export declare function parseHostProperties(value: unknown): HostProperties;
 /**
  * Durable, cluster-shared roster of every agent the cluster has ever enrolled.
  *
@@ -84,6 +101,7 @@ export declare class HostRosterStore {
         agentId: string;
         labels: string[];
         hostname?: string;
+        properties?: HostProperties;
     }): Promise<void>;
     get(agentId: string): Promise<HostRosterRow | null>;
     listAll(): Promise<HostRosterRow[]>;
@@ -95,6 +113,23 @@ export declare class HostRosterStore {
      * registry alone cannot name an expected-but-absent host.
      */
     findMatching(include: readonly (readonly LabelMatcher[])[], exclude: readonly LabelMatcher[], graceMs: number): Promise<MatchedHost[]>;
+    /**
+     * Map a roster row to the canonical {@link HostInventoryEntry} — the queryable
+     * shape returned by the `inventory.query`/`inventory.get` RPC and typed on the
+     * SDK's `ctx.kici.inventory`. Status is derived the same way `findMatching`
+     * derives it (live + fresh ⇒ ready; declared-but-absent static ⇒ unreachable;
+     * ephemeral past ttl ⇒ stale).
+     */
+    toInventoryEntry(row: HostRosterRow, graceMs: number): HostInventoryEntry;
+    /**
+     * Query the roster as canonical {@link HostInventoryEntry} records. With a
+     * selector, reuses `findMatching`'s label filtering (server-side, glob/regex);
+     * property filtering is done client-side in the workflow. Omit the selector ⇒
+     * every host.
+     */
+    queryInventory(selector: InventorySelector | undefined, graceMs: number): Promise<HostInventoryEntry[]>;
+    /** Single-host inventory lookup; null when the agent is not in the roster. */
+    getInventory(agentId: string, graceMs: number): Promise<HostInventoryEntry | null>;
     /**
      * Count `static` (declared) hosts whose derived status is `unreachable` —
      * the "declared-but-absent" alarm population. Reuses the single-source
@@ -104,7 +139,25 @@ export declare class HostRosterStore {
      * depends on `graceMs`).
      */
     countStaticUnreachable(graceMs: number): Promise<number>;
+    /** Remove a host from the roster by agent id. Returns rows deleted. */
+    removeStatic(agentId: string): Promise<number>;
     /** Delete ephemeral rows whose last_seen is older than ttl. Returns count. */
     reapEphemeralPastTtl(ttlMs: number): Promise<number>;
+    /**
+     * Mark a host as about-to-reboot until `until`. Set by the `host.requestReboot`
+     * API handler when an agent's `restartHost()` step runs. While the value is in
+     * the future, the host's disconnect is the expected reboot and its pinned
+     * post-restart job is held.
+     */
+    setRebootPending(agentId: string, until: Date): Promise<void>;
+    /** Clear the reboot-pending flag (on reconnect, deadline expiry, or cancel). */
+    clearRebootPending(agentId: string): Promise<void>;
+    /** True when the host has a reboot-pending deadline still in the future at `nowMs`. */
+    isRebootPending(agentId: string, nowMs: number): Promise<boolean>;
+    /**
+     * Agent ids whose reboot-pending deadline has passed at `nowMs`. The deadline
+     * sweep clears these; the held post-restart job then hits the queue timeout.
+     */
+    listExpiredRebootPending(nowMs: number): Promise<string[]>;
 }
 //# sourceMappingURL=host-roster.d.ts.map

package/dist/agent/registry.d.ts

@@ -120,6 +120,12 @@ interface AgentMetadata {
      * `lifecycle_class`. `null` / undefined when auth mode is `none`.
      */
     tokenAgentType?: 'static' | 'ephemeral' | null;
+    /**
+     * Agent-reported typed host-vars (the `KICI_PROPERTIES` bag), threaded from
+     * the `agent.register` message into the roster upsert (shallow-merged with
+     * any operator-declared properties). Undefined ⇒ the agent reported none.
+     */
+    properties?: Record<string, string | number | boolean>;
 }
 /**
  * Subset of `HostRosterStore` the registry reconciles into. Optional — when no
@@ -136,6 +142,7 @@ export interface RosterReconciler {
         platform: string;
         arch: string;
         instanceId: string;
+        properties?: Record<string, string | number | boolean>;
     }): Promise<void>;
     markDisconnected(agentId: string, instanceId: string): Promise<void>;
     stampLastSeen(agentId: string, instanceId: string): Promise<void>;
@@ -307,6 +314,21 @@ export declare class AgentRegistry {
      * Update the last heartbeat timestamp for an agent.
      */
     updateHeartbeat(agentId: string): boolean;
+    /**
+     * Compact, allocation-cheap snapshot of every registered agent's routing
+     * facts. Used by the dispatcher to log WHY a job found no backend (required
+     * labels vs each agent's labels / capacity), which is otherwise invisible —
+     * a `queued-no-backend` outcome alone doesn't say whether the label set
+     * mismatched, the agent was at capacity, or no agent was connected at all.
+     */
+    agentSummaries(): Array<{
+        agentId: string;
+        labels: string[];
+        platform: string;
+        arch: string;
+        activeJobs: number;
+        maxConcurrency: number;
+    }>;
     /**
      * Get a single agent entry by ID.
      */

package/dist/app.d.ts

@@ -151,6 +151,11 @@ export interface AppDependencies {
      * Platform client + config are in scope; passed into the admin source routes.
      */
     resolveSourceWebhookUrl?: AdminRouteDeps['resolveSourceWebhookUrl'];
+    /**
+     * Resolves the org-scoped GitHub webhook URL for the manifest setup
+     * pre-flight (before any App exists). Passed into the admin source routes.
+     */
+    resolveGithubWebhookUrl?: AdminRouteDeps['resolveGithubWebhookUrl'];
     /** 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. */

package/dist/approvals/step-approval-bridge.d.ts

@@ -17,6 +17,11 @@ export interface StepApprovalRequest {
     reason: string;
     /** Per-gate timeout (seconds); falls back to the org default. */
     timeoutSeconds?: number;
+    /** Computed drift payload for a `when: 'drift'` gate; persisted on the hold. */
+    payload?: {
+        summaryMarkdown: string;
+        drift: unknown;
+    };
 }
 /** Dependencies injected into the bridge. */
 export interface StepApprovalBridgeDeps {

package/dist/cli/commands/source-manifest.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `kici-admin source add github --manifest` — the one-click GitHub App setup
+ * flow. Drives GitHub's App Manifest flow end-to-end: builds a pre-configured
+ * manifest (KiCI's exact permissions/events/webhook URL), hands it to GitHub via
+ * an auto-submitting form, catches the returned short-lived setup code over a
+ * localhost loopback (or copy-paste in --no-browser mode), exchanges it for the
+ * App's id + private key + webhook secret, then reuses the existing source
+ * storage + Platform-registration path.
+ *
+ * The private-key-bearing conversion happens entirely here on the orchestrator
+ * host — it never transits the Platform (sovereignty invariant).
+ */
+import type { AdminApiClient } from '../api-client.js';
+import { waitForInstallation, verifyRepoAccess, type GithubAppCredentials } from '../../providers/github/manifest.js';
+import { startManifestLoopback } from '../loopback-callback.js';
+export interface ManifestSetupOptions {
+    name: string;
+    noBrowser?: boolean;
+    githubOrg?: string;
+    /**
+     * Self-hosted webhook URL override. When set, it is baked verbatim into the
+     * App manifest's `hook_attributes.url` and the platform-mode webhook-URL
+     * resolution is skipped — so the flow works even where the auto-resolved KiCI
+     * platform URL is unavailable. KiCI adds no ingress at this URL; the operator
+     * owns delivery. Advanced/self-hosted only.
+     */
+    webhookUrl?: string;
+}
+/** Injectable boundary so unit tests can stub GitHub + the browser + stdin. */
+export interface ManifestSetupDeps {
+    startLoopback: typeof startManifestLoopback;
+    openBrowser: (url: string) => void | Promise<void>;
+    readLine: (prompt: string) => Promise<string>;
+    convert: (code: string) => Promise<GithubAppCredentials>;
+    waitForInstallation: typeof waitForInstallation;
+    verifyRepoAccess: typeof verifyRepoAccess;
+    /** Persist a created App's PEM to a 0600 file for orphan-app recovery. */
+    writeRecoveryFile: (appId: string, pem: string) => string;
+}
+export declare const realManifestSetupDeps: ManifestSetupDeps;
+export declare function runGithubManifestSetup(opts: ManifestSetupOptions, client: AdminApiClient, deps?: ManifestSetupDeps): Promise<void>;
+//# sourceMappingURL=source-manifest.d.ts.map

package/dist/cli/loopback-callback.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ephemeral localhost server that backs the GitHub App manifest setup flow.
+ * Serves the auto-submitting manifest form at `/` and catches GitHub's redirect
+ * (`/cb?code=…&state=…`). The setup code is exchanged for credentials in the
+ * CLI, never on the Platform — this loopback keeps the whole flow on the
+ * orchestrator host (mirrors the `kici login` browser-OAuth loopback).
+ */
+export interface ManifestLoopback {
+    /** http://127.0.0.1:<port>/cb — GitHub redirect target. */
+    redirectUrl: string;
+    /** http://127.0.0.1:<port>/ — serves the manifest form. */
+    formUrl: string;
+    waitForCode(timeoutMs: number): Promise<{
+        code: string;
+        state: string;
+    }>;
+    close(): void;
+}
+export declare function startManifestLoopback(opts: {
+    state: string;
+    manifestJson: string;
+    createUrl: string;
+}): Promise<ManifestLoopback>;
+//# sourceMappingURL=loopback-callback.d.ts.map

package/dist/cli/open-browser.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Open a URL in the operator's default browser, best-effort. Used by the GitHub
+ * App manifest setup flow to launch the create / install pages. Failure is
+ * non-fatal — the caller always prints the URL too, so a headless host (or a
+ * blocked launcher) just falls back to copy-paste.
+ *
+ * `KICI_BROWSER_CMD` overrides the launcher: `none` suppresses it entirely
+ * (E2E / headless capture), any other value is run with `{url}` substituted —
+ * mirroring the `kici login` convention.
+ */
+export declare function openBrowserBestEffort(url: string): void;
+//# sourceMappingURL=open-browser.d.ts.map

package/dist/cli/service/compose.d.ts

@@ -7,6 +7,18 @@
  * platform with Docker or Podman installed.
  */
 import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions, DiscoveredInstance, LaunchSpec } from './types.js';
+/** Container runtime binary (`podman` or `docker`); compose form is `${runtime} compose`. */
+type Runtime = 'podman' | 'docker';
+/**
+ * Detect which container runtime is available.
+ * Tries podman compose first, then docker compose.
+ *
+ * Exported so the orchestrator installer can resolve the runtime once when
+ * injecting the `KICI_DEPLOY_CONTAINER_RUNTIME` env var for a compose deploy.
+ *
+ * @throws When neither runtime is found.
+ */
+export declare function detectRuntime(): Runtime;
 export declare class ComposeServiceManager implements ServiceManager {
     private runtime;
     /** Get the runtime binary (`podman` or `docker`), detecting it if not already done. */
@@ -24,4 +36,5 @@ export declare class ComposeServiceManager implements ServiceManager {
     list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
     readLaunchSpec(_config: ServiceConfig): Promise<LaunchSpec | null>;
 }
+export {};
 //# sourceMappingURL=compose.d.ts.map

package/dist/cli/service/deploy-env.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Deployment-identity env injection for the orchestrator installer.
+ *
+ * The orchestrator reports its own deployment shape (systemd / launchd /
+ * windows / compose) in `source.register` so the dashboard can build the
+ * correct `kici-admin` invocation. The shape is only knowable at install time
+ * (a running container can't learn its own container name), so the installer
+ * injects it into the orchestrator's env file via these `KICI_DEPLOY_*` vars.
+ */
+import type { ServicePlatform } from './types.js';
+/** Inputs the installer already has when it writes the env file. */
+export interface DeployEnvInput {
+    platform: ServicePlatform;
+    /** The service / container name the installer assigns (= ServiceConfig.name). */
+    serviceName: string;
+    /** Container runtime, only meaningful for the `compose` platform. */
+    containerRuntime?: 'podman' | 'docker';
+}
+/**
+ * Build the `KICI_DEPLOY_*` env lines for a given deployment shape. The mode
+ * line is always emitted; container name + runtime are emitted only for the
+ * `compose` platform (the only shape with a container to `exec` into).
+ */
+export declare function buildDeployEnvLines(input: DeployEnvInput): string[];
+/**
+ * Append the freshly-computed deploy lines to existing env-file content,
+ * idempotently: any pre-existing `KICI_DEPLOY_*` line is stripped first so a
+ * re-install / upgrade heals the shape rather than duplicating it.
+ */
+export declare function upsertDeployEnvLines(existingContent: string, lines: string[]): string;
+//# sourceMappingURL=deploy-env.d.ts.map