@staix/agent-hub 0.11.0 → 0.12.1

package/src/hub/tasks.ts

@@ -29,6 +29,12 @@ export interface TasksDeps {
   quota?: () => Record<PeerId, { headroom: number; resetsAt?: number }>;
   /** Reviewer choice from recorded review outcomes (issue #35); off unless the project config turns it on. */
   review?: { adaptive: boolean; min_reviews: number };
+  /** Peers whose recent deliveries all failed, with the reason (issue #89); routing skips them. */
+  failing?: () => Record<PeerId, string>;
+  /** Peers whose queue a needs_review delivery holds, with the hold detail (issue #90); routing explains the hold, never rejects. */
+  held?: () => Record<PeerId, string>;
+  /** Roles from `.agenthub/config.json` (issue #92): peers with the reviewer role join the reviewer candidates. */
+  roles?: Record<string, string[]>;
   /** Optional: name a class for a task proposed without one. `onCampus` says whether the model call stays on campus. */
   triage?: { classify: (title: string, detail: string) => Promise<TaskClass | undefined>; onCampus: () => Promise<boolean> };
 }
@@ -111,6 +117,17 @@ export class Tasks {
     return this.isPii(task) ? { ...rest, refs: {}, plan: {}, title: "[pii]", detail: "[pii]" } : { ...rest, title, detail, history: history.slice(-5) };
   }
 
+  /** Console results expose direct approval and delivery holds, not just the chosen peer ids. */
+  resultLine(task: Task): string {
+    const base = `task #${task.id}: ${task.state}, owner ${task.owner ?? "none"}, reviewer ${task.reviewer ?? "none"}`;
+    const noReview = task.class !== "review" && !task.reviewer && OPEN.includes(task.state) && !this.waitsFor(task).length
+      ? this.noReviewer(assign(task, this.states(), this.d.routing(), { candidates: task.owner ? [task.owner] : [], notReviewer: task.owner ?? undefined, ...this.weights(task.class) }))
+      : undefined;
+    const held = task.owner ? this.d.held?.()[task.owner] : undefined;
+    const holdText = held ? `${task.owner}'s queue is held (${held}); it receives the task once the hold is resolved` : undefined;
+    return [base, noReview, holdText].filter(Boolean).join("; ");
+  }
+
   private states(): Record<PeerId, PeerState> {
     return Object.fromEntries([...this.d.bus.peers.keys()].map((id) => [id, this.d.bus.stateOf(id)]));
   }
@@ -164,11 +181,18 @@ export class Tasks {
     return new Set(task.history.slice(since + 1).filter((h) => h.event === "changes_requested").map((h) => h.by));
   }
 
+  /** Peer health and roles the daemon feeds routing (issues #89, #90, #92): failing peers are skipped, held queues explained. */
+  private health() {
+    const failing = this.d.failing?.();
+    const held = this.d.held?.();
+    return { ...(failing ? { failing } : {}), ...(held ? { held } : {}), ...(this.d.roles ? { roles: this.d.roles } : {}) };
+  }
+
   /** What assignment weighs besides states and policy: quota, demotion and the review record. */
   private weights(cls: TaskClass) {
     const now = Date.now();
     const quota = this.d.quota?.();
-    return { now, demoted: this.demoted(cls, now), reviews: this.reviewRecord(cls), ...(quota ? { quota } : {}), ...(this.d.review?.adaptive ? { adaptive: { min: this.d.review.min_reviews } } : {}) };
+    return { ...this.health(), now, demoted: this.demoted(cls, now), reviews: this.reviewRecord(cls), ...(quota ? { quota } : {}), ...(this.d.review?.adaptive ? { adaptive: { min: this.d.review.min_reviews } } : {}) };
   }
 
   /**
@@ -334,7 +358,7 @@ export class Tasks {
         // Awaits run between tasks (briefs, memory): re-read, and stop for anything that changed meanwhile.
         const task = this.d.board.get(id);
         if (!task || task.owner !== peer || !OPEN.includes(task.state) || this.d.bus.stateOf(peer) !== "offline") continue;
-        if (!assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), peer] }).owner) continue;
+        if (!assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), peer], ...this.health() }).owner) continue;
         try {
           const back = task.state === "in_progress" ? this.d.board.update(task.id, HUB, "released", { state: "proposed" }, why) : task;
           const next = await this.assignOwner(back, HUB, { exclude: [peer], event: "reassigned", note: why });
@@ -365,6 +389,21 @@ export class Tasks {
 
   private declined = (task: Task) => task.history.filter((h) => h.event === "declined").map((h) => h.by);
 
+  /** Why the task will approve directly at done: no reviewer could be picked, and who was skipped (issue #92). */
+  private noReviewer(a: Assignment): string {
+    const skipped = a.trace.flatMap((l) => {
+      const m = /^ {2}reviewer candidate (\S+): skipped, (.*)$/.exec(l);
+      return m ? [`${m[1]} (${m[2]})`] : [];
+    });
+    return `no reviewer: done will approve directly${skipped.length ? ` (skipped: ${skipped.join("; ")})` : ""}`;
+  }
+
+  private announceRouting(task: Task, a: Assignment): void {
+    if (task.class !== "review" && !a.reviewer) this.d.notify(`task ${this.publicTitle(task)}: ${this.noReviewer(a)}`);
+    const hold = a.owner ? this.d.held?.()[a.owner] : undefined;
+    if (hold) this.d.notify(`task ${this.publicTitle(task)}: ${a.owner}'s queue is held (${hold}); the task arrives once the hold is resolved`);
+  }
+
   private async assignOwner(task: Task, by: PeerId, opts: { candidates?: PeerId[]; event?: string; note?: string; clearOnFail?: boolean; exclude?: PeerId[]; context?: string; claim?: boolean } = {}): Promise<Task> {
     const waits = this.waitsFor(task);
     const a = assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), ...(opts.exclude ?? []), ...(opts.event === "escalated" && task.owner ? [task.owner] : [])], ...(opts.candidates ? { candidates: opts.candidates } : {}), waitsFor: waits, ...this.weights(task.class) });
@@ -383,6 +422,7 @@ export class Tasks {
       this.announceOverlap(next, hits);
       this.tellEarlierOwners(next, hits);
     }
+    this.announceRouting(next, a);
     if (opts.claim && a.owner === by) {
       const claimed = this.d.board.update(next.id, by, "accepted", { state: "in_progress" });
       this.d.notify(`task ${this.publicTitle(claimed)} claimed by ${by}`);
@@ -396,7 +436,7 @@ export class Tasks {
     const pii = this.isPii(task);
     const brief = pii ? undefined : await this.d.briefs?.forTask(task.owner!, task).catch(() => undefined);
     const rejected = task.history.filter((h) => h.event === "changes_requested").map((h) => `- ${h.by}: ${this.screen(task, h.note ?? "", "review note", a.owner)}`);
-    const facts = [`class ${task.class}`, a.owner === PI ? `backend pi/${a.piBackend ?? "dgx"}` : "", task.refs.paths?.length ? `paths ${task.refs.paths.join(", ")}` : "", task.refs.branch ? `branch ${task.refs.branch}` : "", a.reviewer ? `reviewer ${a.reviewer}` : "no reviewer"].filter(Boolean).join("; ");
+    const facts = [`class ${task.class}`, a.owner === PI ? `backend pi/${a.piBackend ?? "dgx"}` : "", task.refs.paths?.length ? `paths ${task.refs.paths.join(", ")}` : "", task.refs.branch ? `branch ${task.refs.branch}` : "", a.reviewer ? `reviewer ${a.reviewer}` : task.class === "review" ? "no reviewer" : this.noReviewer(a)].filter(Boolean).join("; ");
     const plan = planText(task.plan);
     const body = [
       `Task #${task.id} [${task.class}] ${task.title}`,
@@ -438,7 +478,7 @@ export class Tasks {
     for (const t of this.d.board.list("proposed")) {
       const last = t.history.at(-1)?.event;
       if (!t.deps?.length || t.owner || this.offered.has(t.id) || (last !== "blocked" && last !== "ready") || this.waitsFor(t).length) continue;
-      if (!assign(t, this.states(), this.d.routing(), { exclude: this.declined(t) }).owner) continue; // nobody attached can take it yet
+      if (!assign(t, this.states(), this.d.routing(), { exclude: this.declined(t), ...this.health() }).owner) continue; // nobody attached can take it yet
       await this.offerReady(t, "nothing left to wait for");
     }
   }

package/src/local/proxy.ts

@@ -47,11 +47,29 @@ export function allowed(list: string[], host: string, port: number): boolean {
 const INTERNAL = new BlockList();
 // IPv4 nets as leading octets: the package check refuses private address literals in published files.
 for (const [a, b, bits] of [[0, 0, 8], [10, 0, 8], [100, 64, 10], [127, 0, 8], [169, 254, 16], [172, 16, 12], [192, 168, 16], [198, 18, 15], [224, 0, 3]] as const) INTERNAL.addSubnet(`${a}.${b}.0.0`, bits, "ipv4");
-for (const [net, bits] of [["::", 96], ["fc00::", 7], ["fe80::", 10], ["fec0::", 10], ["ff00::", 8]] as const) INTERNAL.addSubnet(net, bits, "ipv6");
+// RFC 8215's local-use NAT64 prefix puts the IPv4 address where the operator's prefix length says: refused outright.
+for (const [net, bits] of [["::", 96], ["fc00::", 7], ["fe80::", 10], ["fec0::", 10], ["ff00::", 8], ["64:ff9b:1::", 48]] as const) INTERNAL.addSubnet(net, bits, "ipv6");
+// The well-known NAT64 prefix (issue #82): with DNS64, a name whose only record is an internal IPv4 address comes back
+// as 64:ff9b::<that address>, and the NAT64 gateway carries the connection there. Its IPv4 address is what counts.
+const NAT64 = new BlockList();
+NAT64.addSubnet("64:ff9b::", 96, "ipv6");
+
+/** The IPv4 address in the last 32 bits of an IPv6 address, whatever its spelling. */
+function lastIPv4(v6: string): string {
+  const [head = "", tail] = new URL(`http://[${v6}]`).hostname.slice(1, -1).split("::");
+  const h = head ? head.split(":") : [];
+  const t = tail ? tail.split(":") : [];
+  const all = tail === undefined ? h : [...h, ...Array<string>(8 - h.length - t.length).fill("0"), ...t];
+  const [a = 0, b = 0] = all.slice(6).map((g) => parseInt(g, 16));
+  return `${a >> 8}.${a & 255}.${b >> 8}.${b & 255}`;
+}
 
 /** Loopback, private, link-local, site-local, unspecified, carrier-grade NAT, benchmark, multicast or reserved. */
 export function isInternal(address: string): boolean {
+  // Only a non-global address carries a zone (`fe80::1%en0`, `::1%lo0`), and BlockList cannot parse one: internal.
+  if (address.includes("%")) return true;
   const family = isIP(address);
+  if (family === 6 && NAT64.check(address, "ipv6")) return isInternal(lastIPv4(address));
   return family !== 0 && INTERNAL.check(address, family === 6 ? "ipv6" : "ipv4");
 }
 
@@ -75,7 +93,8 @@ export function startEgressProxy(opts: { allow: string[]; log: (line: string) =>
       head = Buffer.concat([head, chunk]);
       const end = head.indexOf("\r\n\r\n");
       if (end < 0) {
-        if (head.length > 8192) refuse(client, 431, "request header too large");
+        // Once: later chunks of the same request must not refuse (and log) again. Nothing of the header is logged.
+        if (head.length > 8192) client.off("data", onData), refuse(client, 431, "request header too large", "a request");
         return;
       }
       client.off("data", onData);
@@ -114,14 +133,22 @@ export function startEgressProxy(opts: { allow: string[]; log: (line: string) =>
     const upstream = connect({ host: address, port, allowHalfOpen: true });
     sockets.add(upstream);
     upstream.on("close", () => sockets.delete(upstream));
+    let open = false;
     upstream.once("connect", () => {
+      open = true;
       client.write(`${http} 200 Connection Established\r\n\r\n`);
       if (rest.length) upstream.write(rest);
       client.pipe(upstream);
       upstream.pipe(client);
       client.resume();
     });
-    upstream.on("error", () => (client.writable && !client.destroyed ? refuse(client, 403, `${host}:${port} is unreachable`) : client.destroy()));
+    // Before the tunnel opens a failure is a refusal, logged with the error code only (never its text). After, the
+    // stream is the client's TLS: an HTTP answer would corrupt it, so the client is just closed.
+    upstream.on("error", (e: NodeJS.ErrnoException) => {
+      if (open || !client.writable || client.destroyed) return void client.destroy();
+      const code = /^E[A-Z]{2,20}$/.test(e.code ?? "") ? `, ${e.code}` : "";
+      refuse(client, 403, `${host}:${port} is unreachable${code}`, `${host}:${port}`);
+    });
     client.on("close", () => upstream.destroy());
   };
 

package/src/local/sandbox.ts

@@ -59,21 +59,20 @@ const NETWORK_MACH_SERVICES = ["com.apple.dnssd.service", "com.apple.trustd", "c
 const PROXY_MACH_SERVICES = ["com.apple.trustd", "com.apple.trustd.agent"];
 
 /**
- * Network for the commands: none, direct (`local.bash_network: "direct"`, everything, kept for one release), or only
+ * Network for the commands: none, direct (`local.bash_network: "direct"`, everything, until 0.13.0), or only
  * the hub's egress proxy on a loopback port (#65), which opens allowlisted hosts.
  */
 export type SandboxNetwork = boolean | { proxyPort: number };
 
 /**
- * `base` "deny" (issue #39) starts from `(deny default)` and allows only what commands need: running and reading the
- * system, toolchain and project directories, writing the project and temp. "allow" is the profile of 0.9 and earlier,
- * kept for one release behind `local.sandbox: "allow-default"`. The denies at the end apply to both.
+ * Starts from `(deny default)` (issue #39) and allows only what commands need: running and reading the system,
+ * toolchain and project directories, writing the project and a temp dir of their own. The allow-default profile of
+ * 0.9 and earlier was removed in 0.12.0 (issue #83).
  */
-export function profile(cwd: string, network: SandboxNetwork, readAllow: string[] = [], deny: string[] = [], base: "deny" | "allow" = "deny"): string {
+export function profile(cwd: string, network: SandboxNetwork, readAllow: string[] = [], deny: string[] = []): string {
   const home = homedir();
   const inHome = (p: string) => (p.startsWith("~/") ? join(home, p.slice(2)) : p);
   const root = realPath(cwd);
-  const tmp = realPath(tmpdir());
   const gitDirs = externalGitDirs(root);
   const creds = [".ssh", ".aws", ".gnupg", ".config/gh", ".config/gcloud", ".kube", ".docker", ".netrc", ".npmrc", ".omniroute", ".claude", ".codex", ".kimi-code", "Library/Keychains"];
   const dev = developerDir();
@@ -81,38 +80,28 @@ export function profile(cwd: string, network: SandboxNetwork, readAllow: string[
   const subpaths = (paths: string[]) => paths.map((p) => `(subpath ${q(p)})`).join(" ");
   const globals = (names: string[]) => names.map((n) => `(global-name ${q(n)})`).join(" ");
   const proxy = typeof network === "object" ? `(allow network-outbound (remote ip ${q(`localhost:${network.proxyPort}`)}))` : undefined;
-  const start = base === "deny"
-    ? [
-        "(deny default)",
-        "(allow process-fork)",
-        // Runs from the system, toolchain and project directories only; a script runs through an allowed interpreter.
-        // The user's temp dir and /private/tmp are shared with every other process: each command gets its own (#63).
-        `(allow process-exec ${subpaths([...SYSTEM_READABLE, ...readable])})`,
-        "(allow signal (target same-sandbox))",
-        "(allow process-info* (target same-sandbox))",
-        "(allow sysctl-read)",
-        `(allow mach-lookup ${globals([...MACH_SERVICES, ...(proxy ? PROXY_MACH_SERVICES : network ? NETWORK_MACH_SERVICES : [])])})`,
-        '(allow ipc-posix-shm-read-data ipc-posix-shm-read-metadata (ipc-posix-name "apple.shm.notification_center"))',
-        "(allow file-read-metadata)",
-        `(allow file-read* (literal "/") ${subpaths([...SYSTEM_READABLE, "/dev"])} ${subpaths(readable)})`,
-        '(allow file-ioctl (regex #"^/dev/"))',
-        ...(proxy ? [proxy] : network ? ["(allow network*)"] : []),
-      ]
-    : [
-        "(allow default)",
-        ...(network === true ? [] : ["(deny network*)", ...(proxy ? [proxy] : [])]),
-        // Home is default-deny for reads: whatever a command reads can end up in the model's answer, and that answer
-        // is shared with agents that run on cloud subscriptions (~/.claude.json, app tokens, browser profiles ...).
-        `(deny file-read* (subpath ${q(home)}))`,
-        `(allow file-read-metadata (subpath ${q(home)}))`,
-        `(allow file-read* ${subpaths(readable)})`,
-      ];
+  const start = [
+    "(deny default)",
+    "(allow process-fork)",
+    // Runs from the system, toolchain and project directories only; a script runs through an allowed interpreter.
+    // The user's temp dir and /private/tmp are shared with every other process: each command gets its own (#63).
+    `(allow process-exec ${subpaths([...SYSTEM_READABLE, ...readable])})`,
+    "(allow signal (target same-sandbox))",
+    "(allow process-info* (target same-sandbox))",
+    "(allow sysctl-read)",
+    `(allow mach-lookup ${globals([...MACH_SERVICES, ...(proxy ? PROXY_MACH_SERVICES : network ? NETWORK_MACH_SERVICES : [])])})`,
+    '(allow ipc-posix-shm-read-data ipc-posix-shm-read-metadata (ipc-posix-name "apple.shm.notification_center"))',
+    "(allow file-read-metadata)",
+    `(allow file-read* (literal "/") ${subpaths([...SYSTEM_READABLE, "/dev"])} ${subpaths(readable)})`,
+    '(allow file-ioctl (regex #"^/dev/"))',
+    ...(proxy ? [proxy] : network ? ["(allow network*)"] : []),
+  ];
   const places = `${creds.map((c) => `(subpath ${q(join(home, c))})`).join(" ")} ${denyRegexes(root, deny, false).join(" ")}`;
   return [
     "(version 1)",
     ...start,
     "(deny file-write*)",
-    `(allow file-write* (subpath ${q(root)}) ${base === "deny" ? "" : `(subpath ${q(tmp)}) (subpath "/private/tmp") `}(regex #"^/dev/") ${gitDirs.map((d) => `(subpath ${q(d)})`).join(" ")})`,
+    `(allow file-write* (subpath ${q(root)}) (regex #"^/dev/") ${gitDirs.map((d) => `(subpath ${q(d)})`).join(" ")})`,
     // Inside cwd: nothing that runs later outside the sandbox, nothing that reconfigures the hub.
     `(deny file-write* (subpath ${q(join(root, ".agenthub"))}) ${[join(root, ".git"), ...gitDirs].map((d) => `(subpath ${q(join(d, "hooks"))}) (literal ${q(join(d, "config"))})`).join(" ")})`,
     `(deny file-read* file-write* ${creds.map((c) => `(subpath ${q(join(home, c))})`).join(" ")})`,

package/src/omniroute/client.ts

@@ -124,6 +124,29 @@ export class OmniRoute {
     return undefined;
   }
 
+  /** Authenticated model inventory; upstream response bodies never enter diagnostics. */
+  async models(): Promise<string[]> {
+    const base = await this.base();
+    if (!base) throw new Error("no model gateway is configured or reachable (see ahub doctor)");
+    const key = this.apiKey();
+    if (!key) throw new Error("no OmniRoute API key (see ahub doctor)");
+    const response = await fetch(`${base}/models`, { headers: { authorization: `Bearer ${key}`, ...this.accessHeaders(base) }, signal: AbortSignal.timeout(4000) });
+    if (!response.ok) throw new Error(`model inventory failed: HTTP ${response.status}`);
+    const body = await response.json() as { data?: { id?: unknown }[] };
+    if (!Array.isArray(body.data)) throw new Error("model inventory returned no model list");
+    return body.data.flatMap((m) => typeof m?.id === "string" ? [m.id] : []);
+  }
+
+  /** A listed model can still lack provider credentials: prove it accepts a minimal call before attaching. */
+  async checkModel(model: string, inventory?: string[]): Promise<void> {
+    if (!(inventory ?? await this.models()).includes(model)) throw new Error(`model ${model} is not served by the gateway`);
+    try {
+      await this.chat({ model, messages: [{ role: "user", content: "agent-hub model availability check: reply OK" }], max_tokens: 1 }, { signal: AbortSignal.timeout(10_000) });
+    } catch {
+      throw new Error(`model ${model} is not usable (availability call failed; check gateway credentials and provider health)`);
+    }
+  }
+
   async chat(body: { model: string; messages: ChatMessage[]; tools?: unknown[]; max_tokens?: number }, opts: ChatOptions = {}): Promise<ChatResult> {
     const base = opts.via ?? (await this.base());
     if (!base) throw new Error("no model gateway is configured or reachable (omniroute.urls in .agenthub/config.json; see ahub doctor)");

package/src/pi/extension.ts

@@ -1,3 +1,4 @@
+import { assistantTokens } from "./usage.ts";
 type ExtensionAPI = any;
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -15,6 +16,7 @@ const models = (() => {
 let pollStarted = false;
 let toolSteps = 0;
 let lastActivity = 0;
+let usageSeq = 0;
 let forcedFailure = "";
 const maxSteps = Number(process.env.AGENTHUB_PI_MAX_STEPS ?? 30);
 let shutdown: (() => void) | undefined;
@@ -89,6 +91,13 @@ export default function(pi: ExtensionAPI): void {
     const cancelled = !forcedFailure && message?.stopReason === "aborted";
     await post("/event", { type: "agent_end", text: text ?? "", failed, cancelled, ...(failed ? { error: forcedFailure || message?.errorMessage || message?.stopReason } : {}) });
   });
+  pi.on("message_end", async (event: any) => {
+    const tokens = assistantTokens(event.message);
+    if (tokens === undefined) return;
+    // Message-end is the sole usage source: agent_end carries those same messages again.
+    try { await post("/event", { type: "tokens", id: `usage-${++usageSeq}`, tokens }); }
+    catch { /* telemetry must not break a native turn */ }
+  });
   pi.on("message_update", async () => {
     const now = Date.now();
     if (now - lastActivity < 1000) return;

package/src/pi/usage.ts

@@ -0,0 +1,14 @@
+/** Pi 0.86 assistant usage, including cache reads/writes. Unknown shapes are not estimates. */
+export function assistantTokens(message: unknown): number | undefined {
+  if (!message || typeof message !== "object") return undefined;
+  const m = message as { role?: unknown; usage?: unknown };
+  if (m.role !== "assistant" || !m.usage || typeof m.usage !== "object") return undefined;
+  const u = m.usage as Record<string, unknown>;
+  const count = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+  if (count(u.totalTokens)) return u.totalTokens;
+  if (!count(u.input) || !count(u.output)) return undefined;
+  const parts = [u.input, u.output, u.cacheRead ?? 0, u.cacheWrite ?? 0];
+  if (!parts.every(count)) return undefined;
+  const total = parts.reduce((n, v) => n + v, 0);
+  return Number.isSafeInteger(total) ? total : undefined;
+}

package/templates/config.json

@@ -23,7 +23,7 @@
     "cf_client_id_file": "",
     "cf_client_secret_file": ""
   },
-  "local": { "deny": [], "bash_network": false, "max_steps": 30, "read_allow": [], "sandbox": "deny-default" },
+  "local": { "deny": [], "bash_network": false, "max_steps": 30, "read_allow": [] },
   "approvals": { "timeout_s": 120 },
   "tasks": { "release_after_min": 30 },
   "checks": { "timeout_s": 600 },