@staix/agent-hub 0.15.0 → 0.17.0

package/src/hub/read-tools.ts

@@ -1,3 +1,4 @@
+import type { MemoryCodeOverlay } from "./memory-code-overlay.ts";
 import type { MemoryStore, View, Graph } from "@staix/agent-mem";
 import { looksSecret } from "@staix/agent-mem";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
@@ -29,7 +30,7 @@ export function validateMemoryRead(op: string, a: Record<string, unknown>): void
 }
 
 /** Read-only model projection. Counts and caps are computed only after screening whole records and metadata. */
-export function memoryRead(store: MemoryStore | undefined, project: string, screen: MemoryScreen, op: string, a: Record<string, unknown>, stale: (about: readonly string[]) => boolean = () => false): string {
+export function memoryRead(store: MemoryStore | undefined, project: string, screen: MemoryScreen, op: string, a: Record<string, unknown>, stale: (about: readonly string[]) => boolean = () => false, code?: MemoryCodeOverlay): string {
   validateMemoryRead(op, a);
   const safe = (v: unknown): boolean => {
     try {
@@ -93,7 +94,9 @@ export function memoryRead(store: MemoryStore | undefined, project: string, scre
       if (n.startsWith("goal:") && !goals.has(n)) reject();
       return n;
     });
-    const nodes = new Map<string, Graph["nodes"][number]>(), edges = new Map<string, Graph["edges"][number]>();
+    type Node = Graph["nodes"][number] & { derived?: true; head?: string; codeNeighbour?: true };
+    type Edge = Omit<Graph["edges"][number], "rel"> & { rel: string; derived?: true; head?: string };
+    const nodes = new Map<string, Node>(), edges = new Map<string, Edge>();
     for (const start of starts) {
       const graph = store.graph(project, start, Number(a.hops ?? 1), Number.MAX_SAFE_INTEGER);
       for (const n of graph.nodes) {
@@ -105,12 +108,27 @@ export function memoryRead(store: MemoryStore | undefined, project: string, scre
       }
       for (const e of graph.edges) if (safe(e)) edges.set(JSON.stringify(e), e);
     }
+    const overlay = code && /^[a-f0-9]{40}$/.test(code.head ?? "") && starts.some(id => id.startsWith("symbol:")) ? code : undefined;
+    if (overlay) {
+      for (const node of overlay.nodes) if (!nodes.has(node.id) && node.head === overlay.head && node.derived && safe(node)) nodes.set(node.id, node);
+      for (const edge of overlay.edges) if (edge.head === overlay.head && edge.derived && edge.rel === "calls" && safe(edge)) edges.set(JSON.stringify(edge), edge);
+      for (const note of overlay.notes) {
+        const value = visible.get(note.id);
+        if (!value || !safe(note)) continue;
+        nodes.set(note.id, { id: note.id, type: "memory", label: excerpt(value.title ?? value.text), kind: value.kind, codeNeighbour: true });
+        for (const about of value.about) if (overlay.nodes.some(node => node.id === about)) {
+          const edge = { from: note.id, to: about, rel: value.kind === "fail" ? "rules_out" : "about" };
+          edges.set(JSON.stringify(edge), edge);
+        }
+      }
+    }
     const screenedEdges = [...edges.values()].filter(e => nodes.has(e.from) && nodes.has(e.to));
     const connected = new Set(screenedEdges.flatMap(e => [e.from, e.to]));
     const rank = (n: Graph["nodes"][number]) => n.kind === "fail" ? 0 : starts.includes(n.id) ? 1 : n.type !== "memory" ? 2 : 3;
     const eligibleNodes = [...nodes.values()].filter(n => connected.has(n.id) || starts.includes(n.id)).sort((x, y) => rank(x) - rank(y) || x.id.localeCompare(y.id));
     const eligibleEdges = screenedEdges.sort((x, y) => JSON.stringify(x).localeCompare(JSON.stringify(y)));
-    const out: Graph & { truncated: number } = { nodes: [], edges: [], truncated: eligibleNodes.length + eligibleEdges.length };
+    const out: { nodes: Node[]; edges: Edge[]; truncated: number; code?: { state: "known" | "unknown"; head?: string; truncated: boolean; countsFloor: boolean } } = { nodes: [], edges: [], truncated: eligibleNodes.length + eligibleEdges.length,
+      ...(code ? { code: { state: overlay?.state ?? "unknown", ...(overlay?.head ? { head: overlay.head } : {}), truncated: code.truncated, countsFloor: code.countsFloor } } : {}) };
     for (const n of eligibleNodes) {
       if (out.nodes.length >= Number(a.limit ?? 60)) break;
       out.nodes.push(n); out.truncated--;

package/src/hub/sdlc.ts

@@ -36,6 +36,8 @@ export type SdlcMode = "off" | "advise" | "enforce";
 export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; /** #481 S7: optional control bands per metric; absent means none. */ bands?: BandsConfig; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
 export interface PlanReviewReceipt {
   planner: string;
+  planAuthor?: string | null;
+  selfReview?: true;
   planningRevision: number;
   recordedAt: number;
   scope?: CostPlan;
@@ -206,6 +208,11 @@ export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined =
     next.localResult = raw.localResult as SdlcReceipt["localResult"];
   }
   if (raw.redFirst !== undefined) next.redFirst = parseRedFirst(raw.redFirst);
+  return receiptIdentity(next, previous, raw);
+}
+
+function receiptIdentity(next: SdlcReceipt, previous: SdlcReceipt, raw: Record<string, unknown>): SdlcReceipt {
+  const checklist = raw.criteria ?? raw.phase;
   // A test receipt never carries across a different linked issue or artifact.
   if (raw.redFirst === undefined && (next.repo !== previous.repo || next.issue !== previous.issue || next.pr !== previous.pr)) delete next.redFirst;
   // An acceptance names one spec issue; relinking the receipt to another drops it (#481 S1).
@@ -221,6 +228,33 @@ export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined =
   return next;
 }
 
+export interface PlanningIssueIdentity { repo?: string | null; issue?: number | null }
+/** Planning can change only the linked issue identity, never lifecycle evidence. */
+export function planningIssueIdentity(value: unknown): PlanningIssueIdentity {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("planning sdlc identity must be an object");
+  const raw = value as Record<string, unknown>, keys = Object.keys(raw);
+  if (!keys.length || keys.some(key => key !== "repo" && key !== "issue")) throw new Error("planning sdlc identity takes repo/issue only");
+  const result: PlanningIssueIdentity = {};
+  if (Object.hasOwn(raw, "repo")) {
+    if (raw.repo !== null && (!repo(raw.repo) || raw.repo.length > 400)) throw new Error("planning sdlc.repo: expected owner/repository or null");
+    result.repo = raw.repo as string | null;
+  }
+  if (Object.hasOwn(raw, "issue")) {
+    if (raw.issue !== null && !id(raw.issue)) throw new Error("planning sdlc.issue: expected a positive integer or null");
+    result.issue = raw.issue as number | null;
+  }
+  return result;
+}
+export function planningIssueReceipt(value: unknown, previous: SdlcReceipt | undefined, config: SdlcConfig): SdlcReceipt {
+  const identity = planningIssueIdentity(value);
+  if (identity.repo !== null && identity.issue !== null) return sdlcReceipt(identity, previous, config);
+  const old = previous ?? { stage: config.stages[0] ?? "spec" }, next = { ...old };
+  if (Object.hasOwn(identity, "repo")) { if (identity.repo === null) delete next.repo; else next.repo = identity.repo!; }
+  if (Object.hasOwn(identity, "issue")) { if (identity.issue === null) delete next.issue; else next.issue = identity.issue!; }
+  return receiptIdentity(next, old, {});
+}
+
+
 export function parsePrEvidence(value: unknown): PrEvidence {
   const p = value as Record<string, any>;
   if (!p || !sha(p.headRefOid) || !["OPEN", "CLOSED", "MERGED"].includes(p.state) || !Array.isArray(p.statusCheckRollup) || !Array.isArray(p.files) || p.files.length > 1000) throw new Error("PR readback: invalid or incomplete structured evidence");

package/src/hub/settings.ts

@@ -56,7 +56,7 @@ export const SETTINGS: readonly SettingDef[] = [
   ...["interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"].map((key): SettingDef => ({ key: `task_sweep.${key}`, group: "Switches", label: `Task sweep: ${key}`, type: "number", min: 1, max: 2_147_483_647 / (key === "interval_s" ? 1000 : 60_000), store: "config", applies: "live", risk: "raises", path: ["task_sweep", key] })),
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "live", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
   { key: "tasks.escalate_after", group: "Routing", label: "Escalate after N consecutive changes_requested", type: "integer", min: 1, max: 10, store: "config", applies: "live", risk: "raises", path: ["tasks", "escalate_after"] },
-  { key: "planner", group: "Roles", label: "Planner (the one peer that plans)", type: "enum", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
+  { key: "planner", group: "Roles", label: "Planners (task-local selection)", type: "peers", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "next use", risk: "safe", path: ["catalog_roles", peer] })),
   { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `roster.${peer}`, group: "Roster", label: `${peer}: participates`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", peer] })),
@@ -84,6 +84,7 @@ export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home"
 export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): readonly SettingDef[] {
   const resolve = adapterCatalog?.definitionOf ?? definitionOf;
   const extra: SettingDef[] = [];
+  const plannerValues = [...PLANNER_PEERS];
   const headless = (peer: string): SettingDef => Object.freeze({ key: `peers.${peer}.start_mode`, group: "Start", label: `${peer}: start mode (headless only)`,
     type: "enum", values: Object.freeze(["headless"]), store: "config", applies: "next use", risk: "raises", floor: "headless", path: Object.freeze(["peers", peer, "start_mode"]) });
   for (const adapter of adapterCatalog?.definitions ?? []) {
@@ -108,6 +109,10 @@ export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAda
     const adapter = resolve(peer, instances);
     if (!adapter) continue;
     const entry = Object.getOwnPropertyDescriptor(instances!, peer)?.value;
+    if (PEER.test(peer) && peer.startsWith(`${adapter.kind}-`) && /^[a-z0-9][a-z0-9-]*$/.test(peer.slice(adapter.kind.length + 1))
+      && adapter.projection?.plannerEligible === true
+      && (!adapter.instances?.roles || adapter.instances.roles.includes("planner"))
+      && (!adapter.routing?.allowedRoles || adapter.routing.allowedRoles.includes("planner"))) plannerValues.push(peer);
     const readOnly = entry && typeof entry === "object" && !types.isProxy(entry) && Object.getOwnPropertyDescriptor(entry, "readOnly")?.value === true && !!adapter.permission.genericAcp?.readOnly;
     const copy = (base: SettingDef, key: string): SettingDef => Object.freeze({ ...base, key,
       label: base.label.replace(`${adapter.kind}:`, `${peer}:`),
@@ -126,7 +131,9 @@ export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAda
     } satisfies SettingDef));
     extra.push(headless(peer));
   }
-  return extra.length ? Object.freeze([...SETTINGS, ...extra]) : SETTINGS;
+  const settings = plannerValues.length === PLANNER_PEERS.length ? SETTINGS : SETTINGS.map(def => def.key === "planner"
+    ? Object.freeze({ ...def, values: Object.freeze(plannerValues) }) : def);
+  return extra.length ? Object.freeze([...settings, ...extra]) : settings;
 }
 
 /** The definition of a key, or why there is none. */
@@ -159,6 +166,14 @@ export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonl
     return [...raw] as string[];
   }
   if (def.type === "peers") {
+    if (def.key === "planner") {
+      const peers = typeof raw === "string" ? [raw] : raw;
+      if (!Array.isArray(peers) || peers.length === 0 || peers.length > PEERS_MAX || new Set(peers).size !== peers.length
+        || peers.some(peer => typeof peer !== "string" || !PEER.test(peer) || !(def.values ?? PLANNER_PEERS).includes(peer))) {
+        throw new Error(`${def.key} must be one of ${(def.values ?? PLANNER_PEERS).join(", ")}, or a list of one to ${PEERS_MAX} distinct eligible planner peer ids`);
+      }
+      return peers.length === 1 ? peers[0] as string : [...peers] as string[];
+    }
     if (!Array.isArray(raw) || raw.length > PEERS_MAX || raw.some((p) => typeof p !== "string" || !PEER.test(p)) || new Set(raw).size !== raw.length) throw new Error(`${def.key} takes up to ${PEERS_MAX} distinct peer ids`);
     return [...(raw as string[])];
   }

package/src/hub/settled-roles.ts

@@ -11,15 +11,27 @@ export interface SettledRoles {
 /** Resolve the runtime planner fallback without changing the configured policy role map. */
 export function resolveSettledRoles(
   policyRoles: Readonly<Record<string, readonly string[]>>,
-  planner: string | undefined,
+  planner: string | readonly string[] | undefined,
   rostered: (peer: string) => boolean,
+  /** Extra ids are eligible only through the host's validated startup catalog, never a kind-name fallback. */
+  plannerCapable?: (peer: string) => boolean,
 ): SettledRoles {
   const roles = Object.fromEntries(Object.entries(policyRoles).map(([peer, list]) => [peer, [...list]]));
-  const pinned = (PLANNER_PEERS as readonly string[]).includes(planner ?? "") ? planner! : undefined;
+  const eligible = (peer: unknown): peer is string => typeof peer === "string" && /^[a-z][a-z0-9-]{0,31}$/.test(peer)
+    && !["user", "hub", "digest"].includes(peer) && ((PLANNER_PEERS as readonly string[]).includes(peer) || plannerCapable?.(peer) === true);
+  let pinned: readonly string[] | undefined;
+  if (typeof planner === "string") {
+    // Direct callers historically ignored an unknown scalar; configuration validation rejects it before this resolver.
+    if (eligible(planner)) pinned = [planner];
+  } else if (planner !== undefined) {
+    if (!Array.isArray(planner) || planner.length < 1 || planner.length > 8 || new Set(planner).size !== planner.length || !planner.every(eligible))
+      throw new Error("planner list must contain 1..8 distinct eligible peer ids");
+    pinned = planner;
+  }
   let source: SettledRoles["source"];
   if (pinned) {
     for (const peer of Object.keys(roles)) roles[peer] = roles[peer]!.filter(role => role !== "planner");
-    roles[pinned] = ["planner", ...(roles[pinned] ?? [])];
+    for (const peer of pinned) roles[peer] = ["planner", ...(roles[peer] ?? [])];
     source = "setting";
   } else if (Object.entries(roles).some(([peer, list]) => list.includes("planner") && rostered(peer))) source = "roles";
   else {

package/src/hub/task-sweep.ts

@@ -78,6 +78,9 @@ export interface PlannerGroomingOptions {
   limits: Record<string, number>;
   wip: Record<string, number>;
   states: Record<string, string>;
+  /** Public ID/dependency context may include approved intermediate phases. */
+  dependencies?: ReadonlyMap<number, readonly number[]>;
+  dependencyTruncated?: boolean;
   blockers?: readonly { task: number; code: string }[];
   issues?: ReadonlyMap<string, { repo: string; issue: number; state: "OPEN" | "CLOSED"; editedAt: string; lastEditedAt?: string | null }>;
   reviewedIssues?: ReadonlyMap<number, { editedAt: string }>;
@@ -105,10 +108,28 @@ function groomingPath(value: string): string | undefined {
 /** Read-only ids/codes projection. Callers retain authority, privacy screening and the current metadata snapshot. */
 export function plannerGrooming(tasks: readonly Task[], options: PlannerGroomingOptions): { items: GroomingItem[]; unknown: number[]; truncated: boolean } {
   const items: GroomingItem[] = [], unknown = new Set<number>(), seen = new Set<string>();
-  let truncated = tasks.length > GROOMING_TASK_LIMIT;
+  let truncated = tasks.length > GROOMING_TASK_LIMIT || options.dependencyTruncated === true;
   const repository = groomingRepo(options.repository);
   // ponytail: bounded O(500²) snapshot; add revision-keyed paging/indexing before supporting larger complete boards.
-  const snapshot = tasks.slice(0, GROOMING_TASK_LIMIT).filter(task => task.state !== "approved" && (task.state !== "cancelled" || task.history.some(entry => entry.supersededBy))).sort((a, b) => a.id - b.id);
+  const graphRows = tasks.slice(0, GROOMING_TASK_LIMIT);
+  const graph = new Map<number, readonly number[]>(graphRows.map(task => [task.id, task.deps ?? []]));
+  let context = 0;
+  for (const [id, deps] of options.dependencies ?? []) {
+    if (context++ >= GROOMING_TASK_LIMIT) { truncated = true; break; }
+    if (!graph.has(id)) graph.set(id, deps);
+  }
+  const reach = new Map<number, Set<number>>();
+  const dependencies = (id: number): Set<number> => {
+    const cached = reach.get(id); if (cached) return cached;
+    const found = new Set<number>(), pending = [...graph.get(id) ?? []];
+    while (pending.length) {
+      const next = pending.pop()!;
+      if (found.has(next) || !graph.has(next)) continue;
+      found.add(next); pending.push(...graph.get(next) ?? []);
+    }
+    reach.set(id, found); return found;
+  };
+  const snapshot = graphRows.filter(task => task.state !== "approved" && (task.state !== "cancelled" || task.history.some(entry => entry.supersededBy))).sort((a, b) => a.id - b.id);
   const add = (item: GroomingItem) => {
     const key = JSON.stringify(item);
     if (seen.has(key)) return;
@@ -198,7 +219,8 @@ export function plannerGrooming(tasks: readonly Task[], options: PlannerGrooming
     if (repositories.get(task.id) !== repositories.get(right.id)) continue;
     const a = positions.get(task.id)!, b = positions.get(right.id)!;
     if ([...a.paths].some(path => [...b.paths].some(other => overlaps(path, other))) || [...a.symbols].some(symbol => [...b.symbols].some(other => symbolsOverlap(symbol, other)))) add({ kind: "overlap", task: task.id, related: [right.id] });
-    if ([...issueIds.get(task.id)!].some(issue => issueIds.get(right.id)!.has(issue))) add({ kind: "duplicate", task: task.id, related: [right.id] });
+    if (!dependencies(task.id).has(right.id) && !dependencies(right.id).has(task.id)
+      && [...issueIds.get(task.id)!].some(issue => issueIds.get(right.id)!.has(issue))) add({ kind: "duplicate", task: task.id, related: [right.id] });
   }
   for (const blocker of (options.blockers ?? []).slice(0, GROOMING_TASK_LIMIT)) {
     if (!positions.has(blocker.task)) continue;