@staix/agent-hub 0.12.30 → 0.12.32

package/src/hub/spec-read.ts

@@ -0,0 +1,120 @@
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import { spawn } from "node:child_process";
+import { hostExecutable } from "./host-executable.ts";
+import type { Task } from "./board.ts";
+import { childEnv, stopOwnedProcess, trackGroup } from "./child-process.ts";
+
+const BODY_LIMIT = 64 * 1024, RESULT_LIMIT = 80 * 1024, STDOUT_LIMIT = 512 * 1024;
+const REPO = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const bytes = (text: string) => Buffer.byteLength(text, "utf8");
+export interface SpecResult { number: number; title: string; state: string; updated_at: string; html_url: string; body: string; }
+/** PATH/shorter timeout are host-owned fixture seams, never tool inputs. */
+export interface SpecOptions { path?: string; timeoutMs?: number; projectDir?: string; }
+export interface FetchSpecOptions extends SpecOptions { screen: (whole: string) => boolean | Promise<boolean>; }
+/** Canonical owner/repo identity accepted by the fixed github.com fetch boundary. */
+export const isGitHubRepository = (repo: unknown): repo is string => typeof repo === "string" && REPO.test(repo);
+function validRepo(repo: string): void { if (!isGitHubRepository(repo)) throw new PreEffectToolRefusal("other repository"); }
+
+/** Resolve only task-bound issue references; foreign references never fall through to local #N. */
+export function specRefs(task: Pick<Task, "title" | "detail" | "refs"> & Partial<Pick<Task, "external">>, repo: string, options: { bareTitle?: boolean } = {}): number[] {
+  const references: { repo?: string; number: number }[] = [];
+  // Bare detail numbers name hub tasks. File paths are not issue references.
+  for (const section of [{ text: task.title, bare: true }, { text: task.detail, bare: false }]) {
+    for (const match of section.text.matchAll(/(?<![A-Za-z0-9_./-])(?:https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/issues\/([1-9][0-9]*)\b|([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([1-9][0-9]*)\b|#([1-9][0-9]*)\b)/g)) {
+      const qualified = match[1] ?? match[3];
+      if (!qualified && (!section.bare || options.bareTitle === false)) continue;
+      references.push({ repo: qualified, number: Number(match[2] ?? match[4] ?? match[5]) });
+    }
+  }
+  if (!references.length && task.external === undefined && !task.refs.repo) return [];
+  validRepo(repo);
+  if (task.refs.repo && task.refs.repo.toLowerCase() !== repo.toLowerCase()) throw new PreEffectToolRefusal("other repository");
+  const issues = new Set<number>();
+  if (task.external !== undefined) {
+    const source = task.external;
+    if (!source || source.provider !== "github" || typeof source.repo !== "string") throw new PreEffectToolRefusal("not found");
+    validRepo(source.repo);
+    if (source.repo.toLowerCase() !== repo.toLowerCase()) throw new PreEffectToolRefusal("other repository");
+    if (!Number.isSafeInteger(source.issue) || source.issue < 1 || typeof source.url !== "string"
+      || source.url.toLowerCase() !== `https://github.com/${repo}/issues/${source.issue}`.toLowerCase()) throw new PreEffectToolRefusal("not found");
+    issues.add(source.issue);
+  }
+  for (const reference of references) {
+    if (reference.repo && reference.repo.toLowerCase() !== repo.toLowerCase()) throw new PreEffectToolRefusal("other repository");
+    if (!Number.isSafeInteger(reference.number)) throw new PreEffectToolRefusal("not found");
+    issues.add(reference.number);
+    if (issues.size > 3) throw new PreEffectToolRefusal("too many spec references");
+  }
+  return [...issues];
+}
+
+interface GhResult { code: number; stdout: string; }
+/** One fixed-argv authenticated boundary, no shell, no retries and no retained stderr. */
+function gh(args: string[], opts: SpecOptions): Promise<GhResult> {
+  return new Promise((resolve, reject) => {
+    const env: NodeJS.ProcessEnv = { ...childEnv(), GH_HOST: "github.com", GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", ...(opts.path === undefined ? {} : { PATH: opts.path }) };
+    if (opts.path !== undefined) {
+      for (const key of ["GH_TOKEN", "GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN"]) delete env[key];
+      env.GH_CONFIG_DIR = opts.path;
+    }
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(hostExecutable("gh", opts.projectDir ?? process.cwd(), opts.path ?? process.env.PATH), args, { env, detached: true, stdio: ["ignore", "pipe", "ignore"] });
+      trackGroup(child);
+    }
+    catch { reject(new Error("gh unavailable")); return; }
+    let output: Buffer[] = [], size = 0, failure: string | undefined;
+    const stop = (reason: string) => {
+      if (failure) return;
+      failure = reason; output = [];
+      void stopOwnedProcess(child, { group: true, termMs: 100, killMs: 500 }).catch(() => {});
+    };
+    const timeout = opts.timeoutMs === undefined || !Number.isFinite(opts.timeoutMs) ? 15_000 : Math.max(1, Math.min(15_000, opts.timeoutMs));
+    const timer = setTimeout(() => stop("timeout"), timeout);
+    child.stdout?.on("data", (chunk: Buffer) => {
+      if (failure) return;
+      size += chunk.length;
+      if (size > STDOUT_LIMIT) stop("too large"); else output.push(chunk);
+    });
+    child.once("error", () => { clearTimeout(timer); reject(new Error("gh unavailable")); });
+    child.once("close", code => {
+      clearTimeout(timer);
+      if (failure) reject(new Error(failure));
+      else resolve({ code: code ?? 1, stdout: Buffer.concat(output).toString("utf8") });
+    });
+  });
+}
+
+/** Startup-only availability evidence; daemon caches it until restart. */
+export async function specAvailable(opts: SpecOptions = {}): Promise<{ available: boolean; reason?: string }> {
+  try {
+    const result = await gh(["auth", "status", "--hostname", "github.com"], opts);
+    return result.code === 0 ? { available: true } : { available: false, reason: "gh unauthenticated" };
+  } catch (error) { return { available: false, reason: error instanceof Error ? error.message : "gh unavailable" }; }
+}
+
+export async function fetchSpec(repo: string, n: number, opts: FetchSpecOptions): Promise<SpecResult> {
+  validRepo(repo);
+  if (!Number.isSafeInteger(n) || n < 1) throw new PreEffectToolRefusal("not found");
+  const raw = await gh(["api", "-X", "GET", `repos/${repo}/issues/${n}`], opts);
+  let value: unknown;
+  try { value = JSON.parse(raw.stdout); } catch { throw new Error(raw.code === 4 ? "unauthenticated" : "not found"); }
+  if (raw.code !== 0) {
+    const status = (value as { status?: unknown })?.status;
+    throw new Error(raw.code === 4 || status === 401 ? "unauthenticated" : "not found");
+  }
+  if (!value || typeof value !== "object") throw new Error("not found");
+  const row = value as Record<string, unknown>;
+  if (typeof row.repository_url !== "string" || row.repository_url.toLowerCase() !== `https://api.github.com/repos/${repo}`.toLowerCase()
+    || typeof row.html_url !== "string" || ![`https://github.com/${repo}/issues/${n}`, `https://github.com/${repo}/pull/${n}`].some(url => row.html_url!.toString().toLowerCase() === url.toLowerCase())) throw new PreEffectToolRefusal("other repository");
+  if (row.number !== n || typeof row.title !== "string" || typeof row.state !== "string" || typeof row.updated_at !== "string" || (row.body !== null && typeof row.body !== "string")) throw new Error("not found");
+  const result: SpecResult = { number: n, title: row.title, state: row.state, updated_at: row.updated_at, html_url: row.html_url, body: row.body ?? "" };
+  // GET completed without task/check mutations; these explicit complete-contract refusals withhold only its result.
+  const length = bytes(result.body);
+  if (length > BODY_LIMIT) throw new PreEffectToolRefusal(`spec too large (${length} > 65536); ask the reviewer to put the contract in the repo`);
+  if (bytes(JSON.stringify(result)) > RESULT_LIMIT) throw new PreEffectToolRefusal("too large");
+  let allowed = false;
+  try { allowed = await opts.screen(`${result.title}\n${result.body}`); } catch { /* policy unavailable withholds the entire spec */ }
+  if (allowed !== true) throw new PreEffectToolRefusal("spec withheld by privacy policy");
+  return result;
+}

package/src/hub/supervision.ts

@@ -1,4 +1,4 @@
-import type { HistoryEntry, Task, TaskMoveReason } from "./board.ts";
+import { isClosedTaskState, type HistoryEntry, type Task, type TaskMoveReason, type TaskStall } from "./board.ts";
 import { sanitize, type Kind, type Priority } from "./envelope.ts";
 
 export type SupervisionScope = "own" | "all" | "off";
@@ -11,7 +11,7 @@ export interface SupervisionFields {
   check?: "passed" | "failed" | "unknown";
   verdict?: "approved" | "changes_requested";
   reason?: SupervisionReason;
-  sweep?: "unaccepted-assignment" | "idle-owner" | "review-pending";
+  sweep?: "unaccepted-assignment" | "idle-owner" | "review-pending" | "ready-unassigned";
 }
 export interface SupervisionNotice {
   peer: string;
@@ -31,7 +31,7 @@ export interface SupervisionDeps {
   isPrivate: (task: Task) => boolean;
   /** false means not admitted, so latches must remain retryable. No separate batching timer. */
   emit: (notice: SupervisionNotice) => boolean | void;
-  approvalAgeMs?: number;
+  approvalAgeMs?: number | (() => number);
   now?: () => number;
   /** Durable round state belongs to the daemon's store, not the controller. */
   readRound?: (peer: string) => string | undefined;
@@ -102,23 +102,36 @@ export class SupervisionFeed {
     this.checkRound();
   }
 
+  /** Tasks owns durable cause/replan deduplication; the feed keeps its configured recipient and scope. */
+  taskStalled(stall: TaskStall): boolean {
+    const task = this.d.tasks().find(task => task.id === stall.task);
+    if (!task || isClosedTaskState(task.state) || !this.includes(task)) return false;
+    const cause = stall.cause;
+    const bits = [`#${stall.task}: stalled`, `cause ${cause.kind}`, `reason ${cause.code}`];
+    if (cause.peer) bits.push(`peer ${cause.peer}`);
+    if (cause.dependency !== undefined) bits.push(`dependency #${cause.dependency}`);
+    if (cause.refusals?.length) bits.push(`refusals ${cause.refusals.map(refusal => `${refusal.peer}:${refusal.code}`).join(", ")}`);
+    return this.send(`task:${stall.task}:stall`, bits.join("; "), "status", stall.task);
+  }
+
   peerOffline(peer: string): boolean {
-    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && t.state !== "approved" && (t.owner === peer || t.reviewer === peer))) return false;
+    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && !isClosedTaskState(t.state) && (t.owner === peer || t.reviewer === peer))) return false;
     return this.send(`peer:${peer}:offline`, `${peer}: offline`);
   }
 
   budgetPaused(peer: string, resetsAt?: number): boolean {
-    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && t.state !== "approved" && (t.owner === peer || t.reviewer === peer))) return false;
+    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && !isClosedTaskState(t.state) && (t.owner === peer || t.reviewer === peer))) return false;
     const resetDate = new Date(resetsAt ?? NaN);
     const reset = Number.isFinite(resetDate.getTime()) ? resetDate.toISOString() : "unknown";
     return this.send(`peer:${peer}:budget`, `${peer}: budget paused; reset ${reset}`, "status", undefined, "budget");
   }
 
   approvalWaiting(request: { id: string; peer: string; tool: string; createdAt: number }): boolean {
+    const approvalAgeMs = typeof this.d.approvalAgeMs === "function" ? this.d.approvalAgeMs() : this.d.approvalAgeMs ?? 60_000;
     const peer = this.recipient();
     const age = (this.d.now?.() ?? Date.now()) - request.createdAt;
     const key = `${peer}:${request.id}`;
-    if (!peer || !Number.isFinite(age) || age < (this.d.approvalAgeMs ?? 60_000) || this.approvals.has(key)) return false;
+    if (!peer || !Number.isFinite(age) || age < approvalAgeMs || this.approvals.has(key)) return false;
     const sent = this.send(`approval:${request.id}`, `${request.peer}: approval waiting; tool ${request.tool}; age ${Math.floor(age / 1000)}s; ask the person to answer it in ahub console`, "important");
     if (sent) this.approvals.add(key);
     return sent;
@@ -137,13 +150,16 @@ export class SupervisionFeed {
     const peer = this.recipient();
     if (!peer) return false;
     const tasks = this.d.tasks().filter((t) => this.includes(t));
-    if (!tasks.length || tasks.some((t) => t.state !== "approved")) return false;
+    if (!tasks.length || tasks.some((t) => !isClosedTaskState(t.state))) return false;
     const signature = tasks.map((t) => t.id).sort((a, b) => a - b).join(",");
     const previous = this.d.readRound?.(peer) ?? this.rounds.get(peer);
     const completed = new Set(previous?.split(",") ?? []);
     const newlyJoined = tasks.filter((t) => !completed.has(String(t.id)));
     if (!newlyJoined.length) return false;
-    const sent = this.send("round", `Supervision round complete: ${newlyJoined.length} task${newlyJoined.length === 1 ? "" : "s"} approved; report the results and open decisions to the person.`);
+    const count = `${newlyJoined.length} task${newlyJoined.length === 1 ? "" : "s"}`;
+    const cancelled = newlyJoined.filter(t => t.state === "cancelled").length;
+    const outcome = cancelled ? `${count} closed (${newlyJoined.length - cancelled} approved, ${cancelled} cancelled)` : `${count} approved`;
+    const sent = this.send("round", `Supervision round complete: ${outcome}; report the results and open decisions to the person.`);
     if (sent) {
       this.rounds.set(peer, signature);
       this.d.writeRound?.(peer, signature);

package/src/hub/task-sweep.ts

@@ -1,6 +1,6 @@
 import type { Task } from "./board.ts";
 
-export type SweepKind = "unaccepted-assignment" | "idle-owner" | "review-pending";
+export type SweepKind = "unaccepted-assignment" | "idle-owner" | "review-pending" | "ready-unassigned";
 export interface SweepRecord {
   kind: SweepKind;
   /** Index of the last real activity, distinguishing even events at the same time. */
@@ -14,11 +14,12 @@ export interface TaskSweepConfig {
   unaccepted_min: number;
   idle_min: number;
   review_min: number;
+  ready_min?: number;
   ladder_min: number;
   auto_reassign: boolean;
 }
 export const DEFAULT_TASK_SWEEP: TaskSweepConfig = {
-  enabled: false, interval_s: 300, unaccepted_min: 60, idle_min: 120, review_min: 120, ladder_min: 30, auto_reassign: false,
+  enabled: false, ready_min: 60, interval_s: 300, unaccepted_min: 60, idle_min: 120, review_min: 120, ladder_min: 30, auto_reassign: false,
 };
 
 /** Config cannot silently enable a sweep or reassignment through a truthy string. */
@@ -32,7 +33,7 @@ export function taskSweepConfig(input: unknown): TaskSweepConfig {
     if (typeof values[key] !== "boolean") throw new Error(`task_sweep.${key} must be a boolean`);
     out[key] = values[key];
   }
-  for (const key of ["interval_s", "unaccepted_min", "idle_min", "review_min", "ladder_min"] as const) {
+  for (const key of ["interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"] as const) {
     if (values[key] === undefined) continue;
     const value = values[key];
     if (typeof value !== "number" || !Number.isFinite(value) || value < 1 || value * (key === "interval_s" ? 1000 : 60_000) > 2_147_483_647) throw new Error(`task_sweep.${key} must be a bounded number of at least 1`);
@@ -42,16 +43,16 @@ export function taskSweepConfig(input: unknown): TaskSweepConfig {
 }
 
 /** Pure time/kind ladder; Tasks decides whether the responsible peer is available. */
-export function nextSweep(task: Task, config: TaskSweepConfig, now: number): SweepRecord | undefined {
+export function nextSweep(task: Task, config: TaskSweepConfig, now: number, ready = true): SweepRecord | undefined {
   if (!config.enabled || !Number.isFinite(now)) return undefined;
   const kind = task.state === "proposed" && task.owner ? "unaccepted-assignment"
     : task.state === "in_progress" && task.owner ? "idle-owner"
-      : task.state === "in_review" && task.reviewer ? "review-pending" : undefined;
+      : task.state === "in_review" && task.reviewer ? "review-pending" : task.state === "proposed" && !task.owner && !task.reviewer && ready ? "ready-unassigned" : undefined;
   if (!kind) return undefined;
   let activity = task.history.length - 1;
   while (activity >= 0 && (task.history[activity]?.sweep || task.history[activity]?.event === "memory reference started")) activity--;
   const at = task.history[activity]?.at ?? task.created;
-  const threshold = kind === "unaccepted-assignment" ? config.unaccepted_min : kind === "idle-owner" ? config.idle_min : config.review_min;
+  const threshold = kind === "ready-unassigned" ? config.ready_min ?? 60 : kind === "unaccepted-assignment" ? config.unaccepted_min : kind === "idle-owner" ? config.idle_min : config.review_min;
   if (now - at < threshold * 60_000) return undefined;
   const previous = task.history.flatMap((h) => h.sweep?.kind === kind && h.sweep.activity === activity ? [h.sweep] : []).at(-1);
   if (previous && (previous.step === 3 || now - previous.at < config.ladder_min * 60_000)) return undefined;