@staix/agent-hub 0.12.19 → 0.12.21

package/src/hub/routing.ts

@@ -4,6 +4,7 @@ import type { Task, TaskClass } from "./board.ts";
 import type { PeerId, PeerState } from "./envelope.ts";
 
 import { parseHubRoutes, type HubRoute } from "../models/route/config.ts";
+import { DEFAULT_STAY_SWITCH, type StaySwitchMode } from "../models/route/stage.ts";
 
 type Table = Record<string, unknown>;
 
@@ -26,10 +27,15 @@ export interface Routing {
   targets: Record<string, Table & { id: string }>;
   routes: Record<string, Table & { type: string }>;
   hub_routes?: Record<string, HubRoute>;
+  /** Session-aware stay/switch for `hub/auto` and hub stage routes (#197). */
+  stay_switch: StaySwitchMode;
+  max_switch_prefill_tokens: number;
   classes: Partial<Record<TaskClass, ClassPolicy>>;
-  signals: { pii_patterns: string[]; long_context_tokens: number };
+  /** `pii_screen` (issue #198): `local` adds the on-device or on-campus model screen to the patterns. */
+  signals: { pii_patterns: string[]; long_context_tokens: number; pii_screen: "off" | "local" };
   constraints: { pii: "local_only" | "off"; long_context: "skip_local" | "off"; budget_paused: "skip_peer" | "off" };
-  pi: { dgx_max_context_tokens: number; mlx_max_context_tokens: number };
+  /** `efficient_wait_ms`, opt-in (#199): how long a hub/auto request waits for a busy MLX slot before it moves to dgx/fast; absent, nothing moves for load. */
+  pi: { dgx_max_context_tokens: number; mlx_max_context_tokens: number; efficient_wait_ms?: number };
 }
 
 const TEMPLATE = join(import.meta.dir, "..", "..", "templates", "routing.toml");
@@ -46,19 +52,32 @@ export function loadRouting(cwd: string): Routing {
   }
   const raw = Bun.TOML.parse(text) as Partial<Routing>;
   if (!raw.local?.fixed_model) throw new Error("routing.toml: [local] fixed_model is required (the path that works without Switchyard)");
-  const signals = { pii_patterns: [], long_context_tokens: 120_000, ...raw.signals };
+  const signals = { pii_patterns: [], long_context_tokens: 120_000, pii_screen: "off" as const, ...raw.signals };
   for (const p of signals.pii_patterns) new RegExp(p); // a bad pattern fails here, at load, not in the middle of an assignment
+  if (signals.pii_screen !== "off" && signals.pii_screen !== "local") throw new Error('routing.toml: [signals] pii_screen must be "off" or "local"');
   const classes = raw.classes ?? {};
   for (const [name, policy] of Object.entries(classes)) {
     if (policy?.pi_backend !== undefined && policy.pi_backend !== "dgx" && policy.pi_backend !== "mlx") throw new Error(`routing.toml: [classes.${name}] pi_backend must be "dgx" or "mlx"`);
   }
   const pi = { dgx_max_context_tokens: 262_144, mlx_max_context_tokens: 16_000, ...(raw as any).pi };
   if (!(Number.isSafeInteger(pi.dgx_max_context_tokens) && pi.dgx_max_context_tokens > 0) || !(Number.isSafeInteger(pi.mlx_max_context_tokens) && pi.mlx_max_context_tokens > 0)) throw new Error("routing.toml: [pi] context limits must be positive integers");
+  // A dispatch gives up on a busy MLX slot after 120 s; a longer load wait would never move anything.
+  if (pi.efficient_wait_ms !== undefined && !(Number.isSafeInteger(pi.efficient_wait_ms) && pi.efficient_wait_ms >= 0 && pi.efficient_wait_ms < 120_000)) throw new Error("routing.toml: [pi] efficient_wait_ms must be an integer from 0 to 119999");
+  const { stay_switch, max_switch_prefill_tokens } = { ...DEFAULT_STAY_SWITCH, ...(raw as any) };
+  // Written after a table header, a top-level key lands in that table and would be ignored without a word.
+  const misplaced = (table: unknown, path: string): string | undefined => !table || typeof table !== "object" || Array.isArray(table) ? undefined
+    : Object.entries(table).map(([key, value]) => Object.hasOwn(DEFAULT_STAY_SWITCH, key) ? `${path}${key}` : misplaced(value, `${path}${key}.`)).find(Boolean);
+  const nested = Object.entries(raw).map(([key, value]) => misplaced(value, `${key}.`)).find(Boolean);
+  if (nested) throw new Error(`routing.toml: ${nested} is inside a table; stay_switch and max_switch_prefill_tokens are top-level keys, before any table`);
+  if (!["off", "shadow", "enforce"].includes(stay_switch)) throw new Error('routing.toml: stay_switch must be "off", "shadow" or "enforce" (a top-level key, before any table)');
+  if (!(Number.isSafeInteger(max_switch_prefill_tokens) && max_switch_prefill_tokens > 0)) throw new Error("routing.toml: max_switch_prefill_tokens must be a positive integer");
   return {
     local: raw.local,
     targets: raw.targets ?? {},
     routes: raw.routes ?? {},
     hub_routes: parseHubRoutes(raw.hub_routes),
+    stay_switch,
+    max_switch_prefill_tokens,
     classes,
     signals,
     constraints: { pii: "local_only", long_context: "skip_local", budget_paused: "skip_peer", ...raw.constraints },
@@ -111,6 +130,9 @@ export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, rou
   return out;
 }
 
+/** A peer's entry in a peer-indexed map: own keys only, so a peer named `constructor` is never an inherited Object member. */
+export const peerEntry = <T>(map: Readonly<Record<string, T>> | undefined, peer: string): T | undefined => (map && Object.hasOwn(map, peer) ? map[peer] : undefined);
+
 export interface Assignment {
   owner?: PeerId;
   reviewer?: PeerId;
@@ -118,6 +140,8 @@ export interface Assignment {
   route?: string;
   fixedModel?: string;
   piBackend?: "dgx" | "mlx";
+  /** Why the task's reserved owner (issue #207) was passed over; absent when it was honored or there is none. */
+  unreserved?: string;
   trace: string[];
 }
 
@@ -126,7 +150,7 @@ export interface Assignment {
  * prints its trace. `states`: effective bus states of attached peers (a peer that is not in the map is not attached).
  */
 export function assign(
-  task: Pick<Task, "class" | "signals">,
+  task: Pick<Task, "class" | "signals" | "reserved">,
   states: Record<PeerId, PeerState>,
   routing: Routing,
   opts: {
@@ -152,16 +176,19 @@ export function assign(
 ): Assignment {
   const policy = routing.classes[task.class];
   const trace: string[] = [`class ${task.class}${policy ? "" : " (no [classes] entry: only an explicit owner can take it)"}`, `signals: ${task.signals.join(", ") || "none"}`];
+  // A reserved owner (issue #207) is offered the task first. Named candidates (an assign, an escalation, a relay) replace it.
+  const reserved = opts.candidates ? undefined : task.reserved ?? undefined;
   // Readiness is an input like peer states (issue #34): a task that waits for others goes to nobody yet.
-  if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`] };
+  if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`, ...(reserved ? [`reserved owner ${reserved}: offered first once it is ready`] : [])] };
   const pii = task.signals.includes("pii") && routing.constraints.pii === "local_only";
 
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
-    if (!(peer in states)) return "not attached";
+    if (!Object.hasOwn(states, peer)) return "not attached";
     if (opts.exclude?.includes(peer)) return "excluded (declined or replaced)";
     if (states[peer] === "offline") return "offline";
     if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return "paused";
-    if (opts.failing?.[peer]) return `failing: ${opts.failing[peer]}`;
+    const failing = peerEntry(opts.failing, peer);
+    if (failing) return `failing: ${failing}`;
     if (pii && peer !== LOCAL) return "pii: on-prem peers only";
     if (peer === LOCAL && policy?.local_allowed === false) return "local_allowed = false for this class";
     if (peer === PI && policy?.local_allowed === false) return "local_allowed = false also excludes pi for this class";
@@ -176,7 +203,7 @@ export function assign(
 
   /** Quota that resets soonest gets used first: headroom per hour left in the window, at least 15 min (a task assigned that close to a reset mostly runs after it). */
   const drain = (p: PeerId): number | undefined => {
-    const q = opts.quota?.[p];
+    const q = peerEntry(opts.quota, p);
     return q?.resetsAt === undefined ? undefined : q.headroom / Math.max((q.resetsAt - (opts.now ?? 0)) / 3_600_000, 0.25);
   };
   /** Peers with readings swap places among themselves by drain rate; peers without (local, pi) keep theirs. */
@@ -193,11 +220,11 @@ export function assign(
   /** Demoted peers go behind the rest for this class (owners only); each group is then ordered by quota. */
   /** Reviewers with enough recorded reviews of this owner's work swap places by how those reviews held up. */
   const byRecord = (list: PeerId[], owner: PeerId | undefined): PeerId[] => {
-    const record = owner ? opts.reviews?.[owner] : undefined;
+    const record = owner ? peerEntry(opts.reviews, owner) : undefined;
     if (!record || !Object.keys(record).length) return list;
     trace.push(`  review record with ${owner} in ${task.class}: ${Object.entries(record).map(([r, s]) => `${r} ${s.n} reviews, ${Math.round(s.score * 100)}% held`).join("; ")}${opts.adaptive ? "" : " (review.adaptive is off)"}`);
     if (!opts.adaptive) return list;
-    const known = (p: PeerId) => (record[p] && record[p].n >= opts.adaptive!.min ? record[p].score : undefined);
+    const known = (p: PeerId) => { const r = peerEntry(record, p); return r && r.n >= opts.adaptive!.min ? r.score : undefined; };
     const slots = list.flatMap((p, i) => (known(p) === undefined ? [] : [i]));
     const sorted = slots.map((i) => list[i]!).sort((a, b) => known(b)! - known(a)!);
     const out = [...list];
@@ -205,7 +232,7 @@ export function assign(
     return out;
   };
   const rank = (ok: PeerId[], role: "owner" | "reviewer", owner?: PeerId): PeerId[] => {
-    const down = role === "owner" ? ok.filter((p) => opts.demoted?.[p]) : [];
+    const down = role === "owner" ? ok.filter((p) => peerEntry(opts.demoted, p)) : [];
     if (down.length) trace.push(`  demoted for ${task.class}: ${down.map((p) => `${p} (${opts.demoted![p]!.toFixed(1)} recent failures)`).join(", ")}`);
     const ranked = [...byDrain(ok.filter((p) => !down.includes(p))), ...byDrain(down)];
     // The review record comes after quota, so it decides among reviewers that have one: idle, then record, then quota.
@@ -221,16 +248,20 @@ export function assign(
     }
     const ranked = rank(ok, role, not);
     // Demotion applies to local and Pi too: a demoted one loses its place ahead of the cloud peers.
-    const localTier = ranked.filter((p) => (p === LOCAL || p === PI) && !(role === "owner" && opts.demoted?.[p]));
+    const localTier = ranked.filter((p) => (p === LOCAL || p === PI) && !(role === "owner" && peerEntry(opts.demoted, p)));
     if (localTier.length) return localTier.find((p) => states[p] === "idle") ?? localTier[0]; // local/Pi stays ahead of an idle cloud peer
     return ranked.find((p) => states[p] === "idle") ?? ranked[0];
   };
 
+  // The PII constraint, capability limits, exclusions and peer states still apply: when they pass it over, routing proceeds.
+  const unreserved = reserved ? blocked(reserved, "owner") : undefined;
+  if (reserved) trace.push(`reserved owner ${reserved}: ${unreserved ? `not honored, ${unreserved}; routing proceeds` : "honored"}`);
   // Never the task's current owner by default: a decline or an escalation has to reach the next peer in the list.
-  const wanted = opts.candidates ?? policy?.peers ?? [];
+  const wanted = reserved && !unreserved ? [reserved] : opts.candidates ?? policy?.peers ?? [];
   const owner = pick(wanted, "owner");
   trace.push(owner ? `owner: ${owner}` : "owner: none available, task stays proposed (ahub task assign <id> <peer>)");
-  if (owner && opts.held?.[owner]) trace.push(`  hold: ${owner}'s queue is held: ${opts.held[owner]} (it receives the task once the hold is resolved)`);
+  const ownerHold = owner ? peerEntry(opts.held, owner) : undefined;
+  if (ownerHold) trace.push(`  hold: ${owner}'s queue is held: ${ownerHold} (it receives the task once the hold is resolved)`);
 
   let reviewer: PeerId | undefined;
   if (task.class !== "review") {
@@ -242,7 +273,8 @@ export function assign(
       trace.push(`  reviewer candidates: [classes.review] peers ${classPeers.join(", ") || "none"}${rolePeers.length ? `; reviewer role ${rolePeers.join(", ")}` : ""}`);
       reviewer = pick([...new Set([...classPeers, ...rolePeers])], "reviewer", owner ?? opts.notReviewer);
       trace.push(reviewer ? `reviewer: ${reviewer}` : "reviewer: none, done will approve directly");
-      if (reviewer && opts.held?.[reviewer]) trace.push(`  hold: ${reviewer}'s queue is held: ${opts.held[reviewer]} (it receives the review once the hold is resolved)`);
+      const reviewerHold = reviewer ? peerEntry(opts.held, reviewer) : undefined;
+      if (reviewerHold) trace.push(`  hold: ${reviewer}'s queue is held: ${reviewerHold} (it receives the review once the hold is resolved)`);
     }
   }
   const route = policy?.route ?? routing.local.route;
@@ -250,7 +282,7 @@ export function assign(
   const piBackend = policy?.pi_backend;
   if (owner === LOCAL) trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
   if (owner === PI) trace.push(`pi decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
-  return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), trace };
+  return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), trace };
 }
 
 /**

package/src/hub/snapshots.ts

@@ -60,11 +60,12 @@ export function snapshot(repo: Repo): string | undefined {
       copyFileSync(index, env.GIT_INDEX_FILE);
       utimesSync(env.GIT_INDEX_FILE, atime, mtime);
     }
-    if (git(repo.top, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**"], env).status !== 0) return undefined;
+    // `ahub reset --all` archives hub.db (task text, PII included) under .agenthub/archive: never copy it either.
+    if (git(repo.top, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**", ":(exclude,glob)**/.agenthub/archive/**"], env).status !== 0) return undefined;
     // The copy starts from the user's index: hub state somebody tracked or staged is still in it, and the exclude above
     // only keeps `add` from touching it. Take it out explicitly; -f because staged state the hub has rewritten since
     // matches neither HEAD nor the file, which `rm --cached` otherwise refuses. Only the copy changes.
-    if (git(repo.top, ["rm", "-r", "-f", "--cached", "--quiet", "--ignore-unmatch", "--", ":(glob)**/.agenthub/state/**"], env).status !== 0) return undefined;
+    if (git(repo.top, ["rm", "-r", "-f", "--cached", "--quiet", "--ignore-unmatch", "--", ":(glob)**/.agenthub/state/**", ":(glob)**/.agenthub/archive/**"], env).status !== 0) return undefined;
     const r = git(repo.top, ["write-tree"], env);
     return r.status === 0 ? r.stdout.trim() : undefined;
   } finally {