@kici-dev/orchestrator 0.1.19 → 0.1.21

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

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/cli/commands/source-manifest.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `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;
+}
+/** 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