@staix/agent-hub 0.12.34 → 0.12.36

package/src/hub/config-apply.ts

@@ -8,6 +8,8 @@ import { catalogAssignments } from "./roles.ts";
 import { resolveProfile } from "./profiles.ts";
 import { taskSweepConfig } from "./task-sweep.ts";
 import { projectionConfig } from "./text-projection.ts";
+import { validateInstances, type InstancesConfig } from "./instances.ts";
+import { peerRosterConfig } from "./roster.ts";
 
 export type ApplyClass = "live" | "next use" | "restart";
 export interface ApplyRule { applies: ApplyClass; reason?: string }
@@ -108,6 +110,7 @@ const schema: Record<string, Check> = {
   ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.schema?.(nativeValidators) ?? {})),
   watchdog_ms: number(1, 2_147_483_647), kimi_cmd: argv, qwen_cmd: argv, jcode_cmd: argv, codex_bin: text, jcode_home: text, jcode_provider_profile: text,
   permission_modes: v => { permissionDefaults(v); }, protect_instruction_files: bool,
+  instances: v => { validateInstances(v); },
   batch_max: number(1, 100_000, true), batch_ms: number(0, 2_147_483_647), queue_cap: number(1, 1_000_000, true),
   memory: block({ enabled: bool, worker_url: text, inject_tokens: number(0, 1_000_000, true), brief_items: number(0, 10_000, true), native: bool,
     short_ttl_days: number(1, 3650, true), sync_interval_min: number(0, 1440, true), suggest_edges: bool }),
@@ -138,7 +141,14 @@ const schema: Record<string, Check> = {
   review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true) }), recovery: block({ auto_resume_after_crash: bool }),
   capabilities: map(strings), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
 };
-export function validateRawConfig(raw: unknown): asserts raw is Record<string, unknown> { block(schema)(raw, "config"); }
+export function validateRawConfig(raw: unknown, declarations?: InstancesConfig): asserts raw is Record<string, unknown> {
+  const value = object(raw, "config");
+  const instances = validateInstances(value.instances ?? declarations);
+  if (!Object.keys(instances).length) return block(schema)(raw, "config");
+  block({ ...schema, permission_modes: v => { permissionDefaults(v, instances); },
+    roster: v => { peerRosterConfig(v, instances); }, peers: v => { peerStartConfig(v, instances); },
+  })(raw, "config");
+}
 export function validateEffectiveConfig(value: unknown): asserts value is HubConfig {
   const raw = { ...object(value, "config") };
   delete raw.ignored; delete raw.retired; delete raw.permission_default_sources;
@@ -149,6 +159,7 @@ export function validateEffectiveConfig(value: unknown): asserts value is HubCon
 }
 
 const restart: Record<string, string> = {
+  instances: "Native instance identity, worktree, ports and account bindings are fixed at daemon startup",
   ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.restartReasons ?? {})),
   memory: "Open memory consumers, selected profile, client and sync timer must be quiesced together",
   omniroute: "Credentials and gateway clients are bound to relay ownership", mlx: "Model runtime ownership and device resources belong to this daemon",
@@ -174,7 +185,7 @@ export function configApply(key: string): ApplyRule {
       if (shape?.fields) { if (!Object.hasOwn(shape.fields, part)) return fail(key, "unknown configuration key"); check = shape.fields[part]; }
       else if (shape?.item) { if (shape.keys && !shape.keys.includes(part)) return fail(key, "unknown configuration key"); check = shape.item; }
       else if (index === 0 && (special[top]?.includes(part) || top === "checks" && /^[a-z][a-z0-9_]{0,47}$/.test(part))) break;
-      else if (["permission_modes", "catalog_roles", "profile_overrides", "text_projection", "peers"].includes(top)) break;
+      else if (["permission_modes", "catalog_roles", "profile_overrides", "text_projection", "peers", "instances"].includes(top)) break;
       else return fail(key, "unknown configuration key");
     }
   }

package/src/hub/config-reload.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { validateRawConfig, type ConfigLayer } from "./config-apply.ts";
 import { parseOverlay, parseRouting, type Routing } from "./routing.ts";
 import { CLASSES } from "./board.ts";
+import { validateInstances } from "./instances.ts";
 
 export const CONFIG_SOURCE_FILES = ["config.json", "config.local.json", "routing.toml", "routing.local.toml"] as const;
 export type ConfigSourceName = typeof CONFIG_SOURCE_FILES[number];
@@ -90,6 +91,15 @@ function validateRoutingRaw(value: unknown): void {
 /** Strict reloads never use routing's last-good fallback. Startup can retain its existing fallback explicitly. */
 export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: Routing): ConfigSources {
   const layers: ConfigLayer[] = [], trustLayers: ConfigSources["trustLayers"] = [];
+  let localRaw: Record<string, unknown> = {};
+  try { localRaw = JSON.parse(texts["config.local.json"] ?? "{}"); }
+  catch { if (!fallbackRouting) throw new Error(".agenthub/config.local.json: invalid JSON object"); }
+  let declared;
+  try { declared = validateInstances(localRaw?.instances); }
+  catch (error) {
+    if (!fallbackRouting) throw new Error(`.agenthub/config.local.json: ${(error as Error).message}`);
+    declared = validateInstances(undefined);
+  }
   for (const name of CONFIG_SOURCE_FILES) {
     const text = texts[name];
     if (text === null) continue;
@@ -104,7 +114,7 @@ export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: R
     }
     if (name === "config.json" || name === "config.local.json") {
       if (!fallbackRouting) {
-        try { validateRawConfig(raw); }
+        try { validateRawConfig(raw, declared); }
         catch (error) { throw new Error(`.agenthub/${name}: ${(error as Error).message}`); }
       }
       layers.push({ name, raw });

package/src/hub/config-trust.ts

@@ -29,7 +29,7 @@ export const MACHINE_LOCAL = [
   "terminal.open", // the command a hub-made TUI start runs to open a terminal (#269)
 ] as const;
 /** Legacy exported field list stays compatible; new policies use the complete list below. */
-export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "text_projection"] as const;
+export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "text_projection", "instances"] as const;
 
 /** A known repository, including an unreadable marker, must never be mistaken for a plain directory. */
 export function configRepositoryPresent(cwd: string): boolean {

package/src/hub/control-client.ts

@@ -8,7 +8,7 @@ export function stateDirFor(cwd: string): string {
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
 export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["task_cancel", "recovery_deferred_hub"] as const;
+export const DAEMON_FEATURES = ["task_cancel", "recovery_deferred_hub", "peer_instances"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;
 

package/src/hub/cost-governance.ts

@@ -0,0 +1,76 @@
+/** S10 cost evidence is metadata only. Legacy scope and incomplete readback remain unknown. */
+export interface ReviewScope { scope: "none" | "delta" | "full"; reviewers: number }
+export interface CostPlan { review?: ReviewScope; ci?: "focused" | "full" | "reuse" }
+export interface ReviewCost extends CostPlan { head?: string }
+export interface CostTask { repo: string; pr: number; private?: boolean; history: { event: string; at: number; reviewCost?: ReviewCost }[] }
+export interface CostPr { repo: string; pr: number; state: "OPEN" | "CLOSED" | "MERGED"; mergedAt?: number; complete: boolean; ciRuns?: { id: number; attempt: number }[]; reviews?: number }
+export interface CostRow { repo: string; pr: number; reviewRounds: number; ciRuns: number | null; ciReruns: number | null; fullReReviews: number; deltaReviews: number; reviewMs: number | null; unknownReviewScopes: number; githubReviews: number | null; complete: boolean }
+export interface CostReport { rows: CostRow[]; truncated: boolean }
+export function cleanCostPlan(input: unknown): CostPlan {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("invalid cost scope");
+  const value = input as Record<string, unknown>;
+  const result: CostPlan = {};
+  if (value.review !== undefined) {
+    const review = value.review as Record<string, unknown>;
+    if (!review || typeof review !== "object" || Array.isArray(review) || Object.keys(review).some(key => !["scope", "reviewers"].includes(key))
+      || !["none", "delta", "full"].includes(review.scope as string) || !Number.isSafeInteger(review.reviewers)
+      || (review.scope === "none" ? review.reviewers !== 0 : (review.reviewers as number) < 1 || (review.reviewers as number) > 8)) throw new Error("invalid review cost scope");
+    result.review = { scope: review.scope as ReviewScope["scope"], reviewers: review.reviewers as number };
+  }
+  if (value.ci !== undefined) {
+    if (!["focused", "full", "reuse"].includes(value.ci as string)) throw new Error("invalid CI cost scope");
+    result.ci = value.ci as CostPlan["ci"];
+  }
+  return result;
+}
+const validRepo = (repo: string) => /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.startsWith("-");
+const key = (repo: string, pr: number) => `${repo.toLowerCase()}#${pr}`;
+/** One round is a board review handoff, not one reviewer in a multi-reviewer round. CI attempts share a run id. */
+export function costMetrics(tasks: CostTask[], prs: CostPr[]): CostReport {
+  const withheld = new Set(tasks.filter(task => task.private).map(task => key(task.repo, task.pr)));
+  const rows: CostRow[] = [];
+  let truncated = tasks.length > 500 || prs.length > 200, historyLeft = 10_000;
+  const seen = new Set<string>();
+  for (const pr of prs.slice(0, 200)) {
+    const identity = key(pr.repo, pr.pr);
+    if (!validRepo(pr.repo) || !Number.isSafeInteger(pr.pr) || pr.pr < 1 || pr.state !== "MERGED" || withheld.has(identity) || seen.has(identity)) continue;
+    if (!tasks.some(task => !task.private && key(task.repo, task.pr) === identity)) continue;
+    seen.add(identity);
+    const rounds: { at: number; scope?: ReviewScope["scope"]; elapsed?: number }[] = [];
+    let complete = pr.complete && Number.isFinite(pr.mergedAt);
+    for (const task of tasks.slice(0, 500).filter(task => key(task.repo, task.pr) === identity)) {
+      const history = task.history.slice(0, Math.max(0, historyLeft)); historyLeft -= history.length;
+      if (history.length < task.history.length) { complete = false; truncated = true; }
+      let pending: typeof rounds[number] | undefined;
+      for (const event of [...history].sort((a, b) => a.at - b.at)) {
+        if (!Number.isFinite(event.at) || event.at < 0 || !Number.isFinite(pr.mergedAt) || event.at > pr.mergedAt!) continue;
+        if (event.event === "done") {
+          pending = { at: event.at, scope: event.reviewCost?.review?.scope }; rounds.push(pending);
+        } else if (pending && ["approved", "changes_requested"].includes(event.event)) { pending.elapsed = event.at - pending.at; pending = undefined; }
+      }
+    }
+    rounds.sort((a, b) => a.at - b.at);
+    const attempts = new Map<number, number>();
+    if (pr.ciRuns) for (const run of pr.ciRuns.slice(0, 100)) {
+      if (!Number.isSafeInteger(run.id) || run.id < 1 || !Number.isSafeInteger(run.attempt) || run.attempt < 1 || run.attempt > 10_000) { complete = false; continue; }
+      attempts.set(run.id, Math.max(attempts.get(run.id) ?? 0, run.attempt));
+    }
+    if (pr.ciRuns && pr.ciRuns.length > 100) { complete = false; truncated = true; }
+    if (!pr.ciRuns || pr.reviews === undefined || rounds.some(round => round.elapsed === undefined || round.scope === undefined)) complete = false;
+    rows.push({ repo: pr.repo.toLowerCase(), pr: pr.pr, reviewRounds: rounds.length,
+      ciRuns: pr.ciRuns ? attempts.size : null, ciReruns: pr.ciRuns ? [...attempts.values()].reduce((sum, n) => sum + n - 1, 0) : null,
+      fullReReviews: rounds.filter((round, index) => index > 0 && round.scope === "full").length,
+      deltaReviews: rounds.filter(round => round.scope === "delta").length,
+      reviewMs: rounds.every(round => round.elapsed !== undefined) ? rounds.reduce((sum, round) => sum + round.elapsed!, 0) : null,
+      unknownReviewScopes: rounds.filter(round => round.scope === undefined).length, githubReviews: pr.reviews ?? null, complete });
+  }
+  return { rows: rows.sort((a, b) => a.repo.localeCompare(b.repo) || a.pr - b.pr), truncated };
+}
+export function costBandProposals(report: CostReport, upper: Partial<Record<"reviewRounds" | "ciRuns" | "ciReruns" | "fullReReviews" | "deltaReviews" | "reviewMs", number>>): { repo: string; pr: number; metric: string; observed: number; upper: number }[] {
+  if (report.truncated) return [];
+  return report.rows.filter(row => row.complete).flatMap(row => Object.entries(upper).flatMap(([metric, limit]) => {
+    if (!["reviewRounds", "ciRuns", "ciReruns", "fullReReviews", "deltaReviews", "reviewMs"].includes(metric) || !Number.isFinite(limit) || limit! < 0) return [];
+    const observed = row[metric as keyof CostRow];
+    return typeof observed === "number" && observed > limit! ? [{ repo: row.repo, pr: row.pr, metric, observed, upper: limit! }] : [];
+  }));
+}

package/src/hub/crash.ts

@@ -1,4 +1,4 @@
-import { definitionOf } from "../adapters/registry.ts";
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
 import { chmodSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { JournalDelivery } from "./delivery-journal.ts";
@@ -56,17 +56,26 @@ const str = (v: unknown) => (typeof v === "string" && v ? v : undefined);
  * What can come back after a crash. `resume` holds the start arguments for peers the hub launches itself (Kimi through
  * ACP `session/load`, Pi through its session file, the local worker afresh); the others say what the user has to do.
  */
-export function crashPlan(records: SessionRecord[]): { peer: string; resume?: Record<string, string>; how: string; fresh?: Record<string, string>; tui?: true }[] {
+export function crashPlan(records: SessionRecord[], instances?: KindMap): { peer: string; resume?: Record<string, string>; how: string; fresh?: Record<string, string>; tui?: true }[] {
   return records.map(({ peer, meta }) => {
     const launch = (meta.launch && typeof meta.launch === "object" ? meta.launch : {}) as Record<string, unknown>;
     const model = str(launch.model);
-    const adapter = definitionOf(peer);
+    const adapter = definitionOf(peer, instances);
+    const extra = adapter !== undefined && definitionOf(peer) === undefined;
+    const command = extra ? `ahub ${adapter.cli.command} --as ${peer}` : `ahub ${peer}`;
     if (adapter?.session.resumeById) {
       const sessionId = adapter.session.crashIdentity?.(meta).sessionId;
-      if (!sessionId) return { peer, how: `${peer}: saved ACP session identity unavailable; start it deliberately with ahub ${peer}` };
+      if (!sessionId) return { peer, how: `${peer}: saved ACP session identity unavailable; start it deliberately with ${command}` };
       return { peer, resume: { sessionId, ...(model ? { model } : {}) }, how: `${peer}: the recorded conversation can be loaded again (ACP session/load)` };
     }
-    return { peer, ...(adapter?.session.crashPlan?.(meta) ?? { how: `${peer}: reconnects by itself if its client is still running` }) };
+    const native = adapter?.session.crashPlan?.(meta);
+    if (!native) return { peer, how: `${peer}: reconnects by itself if its client is still running` };
+    if (!extra) return { peer, ...native };
+    const prefix = `${adapter.kind}:`;
+    let how = native.how.startsWith(prefix) ? `${peer}:${native.how.slice(prefix.length)}` : `${peer}: ${native.how}`;
+    // Manual launch guidance selects this instance. Recorded headless resume prose can contain an opaque id, never a command.
+    if (!native.resume || native.tui) how = how.replace(`ahub ${adapter.cli.command}`, command);
+    return { peer, ...native, how };
   });
 }