@staix/agent-hub 0.19.0 → 0.21.0

package/src/hub/config-trust.ts

@@ -26,10 +26,16 @@ export const MACHINE_LOCAL = [
   "local.read_allow",
   "local.bash_network",
   "local.network_allow", // the hosts the egress proxy opens (#65)
+  "local.doc_read", // #515: gives the local worker a document reader; a committed config may not hand a model more tools on someone else's machine
+  "local.web_fetch", // #515b: lets a model request pages from listed hosts; a committed config may not choose where a model's requests go on someone else's machine
   "terminal.open", // the command a hub-made TUI start runs to open a terminal (#269)
+  "tasks.auto_pull", // #785 P1c: lets the hub start work on its own; a committed config may not turn it on for someone else's machine
+  "folder_triggers", // #512c: entries make the hub read a folder and propose a task per new file; a committed config may not point the hub at a folder on someone else's machine
+  "schedules", // #512: entries make the hub propose tasks on a timer; a committed config may not create work on someone else's machine
+  "corpus.paths", // #510: folders the hub reads as evidence; a committed config may not point the hub at a folder on someone else's machine
 ] as const;
 /** Legacy exported field list stays compatible; new policies use the complete list below. */
-export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "action_policy", "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "adapters", "adapter_modules", "text_projection", "instances"] as const;
+export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "rooms", "tasks.queue_backpressure", "context.max_assignment_used", "action_policy", "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "adapters", "adapter_modules", "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 {
@@ -95,6 +101,7 @@ const drop = (file: Record<string, unknown>, path: string) => {
  * once resolved to the project root). A committed copy of the template sets them to defaults and asks git nothing.
  */
 export function stripUntrusted(file: Record<string, unknown>, defaults: object, cwd: string, name: string): string | undefined {
+  if (name !== "config.local.json") delete file.rooms;
   const localOnly = name !== "config.local.json" && file.action_policy !== undefined;
   if (localOnly) delete file.action_policy;
   const originNotice = localOnly ? "action_policy ignored: only .agenthub/config.local.json may set it" : undefined;

package/src/hub/context-window.ts

@@ -9,7 +9,7 @@ export function readNativeContext(definition: AdapterDefinition | undefined, val
 
 /** Native active-context occupancy, separate from accumulated billable usage (#185). */
 export interface ContextReading {
-  source: "claude_statusline" | "codex_token_usage" | "acp_usage_update";
+  source: "claude_statusline" | "codex_token_usage" | "acp_usage_update" | "jcode_usage_update";
   sessionId: string;
   measuredAt: number;
   tokens: number | null;
@@ -24,8 +24,8 @@ export interface ContextView {
   used: number | null;
   freshness: "fresh" | "stale" | "unknown";
 }
-export interface ContextConfig { gate: number; stale_min: number }
-export const DEFAULT_CONTEXT: ContextConfig = { gate: 0, stale_min: 30 };
+export interface ContextConfig { gate: number; stale_min: number; max_assignment_used?: number }
+export const DEFAULT_CONTEXT: ContextConfig = { gate: 0, stale_min: 30, max_assignment_used: 0 };
 export const unknownContext = (): ContextView => ({ source: null, measuredAt: null, tokens: null, window: null, used: null, freshness: "unknown" });
 /** Invalid/stale readings hide the value but never rearm a threshold already crossed. */
 export class ContextWindows {
@@ -46,6 +46,11 @@ export class ContextWindows {
     if (over && !crossed && this.crossing(peer, reading) === false) return;
     this.high.set(peer, { sessionId: reading.sessionId, crossed: over });
   }
+  /** Copy native evidence without changing the checkpoint latch or collecting new telemetry. */
+  admission(peer: string, currentSession: string | undefined, attached: boolean): ContextAdmissionSnapshot {
+    const reading = this.readings.get(peer);
+    return { ...(reading ? { reading: { ...reading } } : {}), sessionId: currentSession, attached };
+  }
   /** Reconsider a held crossing after release, using only the still-fresh reading and current native session. */
   retry(peer: string, currentSession: string | undefined): void {
     const reading = this.readings.get(peer);
@@ -59,3 +64,28 @@ export class ContextWindows {
     return { source: r.source, measuredAt: positive(r.measuredAt) ? r.measuredAt : null, tokens: valid ? r.tokens : null, window: r.window, used: valid ? r.used : null, freshness: !valid ? stale ? "stale" : "unknown" : r.used === null ? "unknown" : "fresh" };
   }
 }
+
+/** Host-only snapshot: session identifiers never enter routing traces or task history. */
+export interface ContextAdmissionSnapshot {
+  reading?: ContextReading;
+  sessionId?: string;
+  attached: boolean;
+}
+export interface ContextAdmissionPolicy { max_used: number; stale_min: number }
+export interface ContextAdmission {
+  policy: ContextAdmissionPolicy;
+  peers: Readonly<Record<string, ContextAdmissionSnapshot>>;
+}
+/** Pure new-work admission; unknown supplies no positive or negative context evidence. */
+export function contextHeadroom(policy: ContextAdmissionPolicy, snapshot: ContextAdmissionSnapshot | undefined, now: number): { blocked: boolean; note: string } | undefined {
+  if (!Number.isFinite(policy.max_used) || policy.max_used <= 0 || policy.max_used > 1) return undefined;
+  const r = snapshot?.reading;
+  if (!r || !snapshot.attached || !snapshot.sessionId || r.sessionId !== snapshot.sessionId
+      || !positive(now) || !positive(r.measuredAt) || r.measuredAt > now
+      || !positive(policy.stale_min) || now - r.measuredAt > policy.stale_min * 60_000
+      || r.used === null || !nonnegative(r.used) || r.used > 1) {
+    return { blocked: false, note: "context headroom: unknown (no fresh current-session reading)" };
+  }
+  const blocked = r.used >= policy.max_used;
+  return { blocked, note: `context headroom: used ${r.used} ${blocked ? "at or above" : "below"} max ${policy.max_used}` };
+}

package/src/hub/control-client.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { projectContext } from "./project.ts";
-import { externalAdapterMetadata, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
+import { externalAdapterMetadata, externalInstanceCatalog, type ExternalInstanceCatalog, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
 
 export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
@@ -9,7 +9,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 = ["external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated"] as const;
+export const DAEMON_FEATURES = ["conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated"] 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;
 
@@ -166,6 +166,18 @@ export class ControlClient {
     });
   }
 
+  /** Read inert instance policy only from this authenticated, still-current daemon connection. */
+  async readExternalInstanceCatalog(projectRoot: string, timeoutMs = 3000): Promise<ExternalInstanceCatalog> {
+    const epoch = this.instanceId;
+    if (!epoch || !this.isOpen || !["external_adapter_instances", "external_adapter_modules", "peer_instances"].every(feature => this.features.includes(feature))) throw new Error("running hub lacks a live external instance catalog");
+    const reply = await this.request({ t: "status" }, timeoutMs);
+    const status = reply.status;
+    if (!this.isOpen || this.instanceId !== epoch || reply.ok === false || !status || status.instanceId !== epoch || status.cwd !== projectRoot) throw new Error("external instance catalog observation changed");
+    const catalog = externalInstanceCatalog(status.externalInstanceCatalog);
+    if (catalog.epoch !== epoch || catalog.projectRoot !== projectRoot) throw new Error("external instance catalog binding changed");
+    return catalog;
+  }
+
   /** `timeoutMs`: for calls a person waits on. The hub has its own budget; this one only makes sure the CLI never hangs. */
   request(msg: Record<string, unknown>, timeoutMs = 30_000): Promise<any> {
     if (this.ws.readyState !== WebSocket.OPEN) return Promise.resolve({ ok: false, error: "hub connection is not open" });

package/src/hub/corpus-config.ts

@@ -0,0 +1,34 @@
+// agent-hub #510 (hub task #331): the `corpus` config block. Pure on purpose: it is read by the config schema, which the Claude channel bundle reaches, so it
+// imports nothing that touches the file system. The index and the vault refusal are in `corpus.ts`.
+
+export const MAX_CORPUS_ROOTS = 16;
+export const MAX_CORPUS_PATH_CHARS = 1024;
+
+export interface CorpusConfig { paths: string[] }
+
+/** Why a path is not accepted, or undefined. A path is absolute or project-relative; `~` is never expanded, so what the person typed is what is read. */
+export function corpusPathProblem(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return "a corpus path is a non-empty string";
+  if (value.length > MAX_CORPUS_PATH_CHARS) return `a corpus path is at most ${MAX_CORPUS_PATH_CHARS} characters`;
+  if (/[\x00-\x1f\x7f]/.test(value)) return "a corpus path has no control characters";
+  if (value.startsWith("~")) return "write the absolute path: ~ is not expanded";
+  if (value !== value.trim()) return "a corpus path has no leading or trailing spaces";
+  return undefined;
+}
+
+/** The checked block. `corpus.paths` names read-only folders of plain notes; nothing here reads the disk (the vault check does, per index refresh). */
+export function corpusConfig(input: unknown): CorpusConfig {
+  if (input === undefined) return { paths: [] };
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("corpus must be an object");
+  const block = input as Record<string, unknown>;
+  for (const key of Object.keys(block)) if (key !== "paths") throw new Error(`corpus.${key}: unknown key`);
+  if (block.paths === undefined) return { paths: [] };
+  if (!Array.isArray(block.paths) || block.paths.length > MAX_CORPUS_ROOTS) throw new Error(`corpus.paths takes a list of at most ${MAX_CORPUS_ROOTS} folders`);
+  const out: string[] = [];
+  block.paths.forEach((path, index) => {
+    const problem = corpusPathProblem(path);
+    if (problem) throw new Error(`corpus.paths[${index}]: ${problem}`);
+    if (!out.includes(path as string)) out.push(path as string);
+  });
+  return { paths: out };
+}

package/src/hub/corpus-evidence.ts

@@ -0,0 +1,184 @@
+import { sanitize } from "./envelope.ts";
+import { CorpusIndex, MAX_CORPUS_READS, MAX_FRONTMATTER_BYTES, MAX_NOTE_BYTES, MAX_HEADINGS, parseNote, type NoteRecord } from "./corpus.ts";
+
+export const MAX_CORPUS_EVIDENCE = 6;
+export const MAX_CORPUS_EVIDENCE_ITEM_BYTES = 768;
+export const MAX_CORPUS_EVIDENCE_BYTES = 4096;
+
+export interface CorpusEvidencePolicy {
+  allowed(): boolean;
+  version(): string;
+  /** Screen the complete, fresh note plus its raw metadata before any excerpt is produced. */
+  safe(text: string, paths: readonly string[]): boolean;
+}
+
+export interface CorpusEvidence { id: string; kind: "note"; text: string }
+
+const normalize = (text: string): string => text.normalize("NFKC").toLowerCase();
+const words = (text: string): string[] => [...new Set(normalize(text).match(/[\p{L}\p{N}]{2,}/gu) ?? [])];
+const score = (query: readonly string[], text: string): number => {
+  const haystack = normalize(text);
+  return query.reduce((total, word) => total + (haystack.includes(word) ? 1 : 0), 0);
+};
+
+/** Slugs retain Unicode letters and numbers, fold case, and use hyphens for punctuation or whitespace. */
+export function headingSlug(heading: string): string {
+  return normalize(heading).replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "") || "section";
+}
+
+/** Escape only the delimiters in the citation grammar; Unicode and its spelling remain literal. */
+function escapeCitationPart(value: string): string {
+  return value.replace(/[\\,#\[\]]/g, char => `\\${char}`);
+}
+
+export function noteCitationId(baseId: string, slug: string): string {
+  const id = `${escapeCitationPart(baseId)}#${escapeCitationPart(slug)}`;
+  if (!isNoteCitation(id)) throw new Error("unsupported note citation id");
+  return id;
+}
+
+/** A syntactic guard for note citations. Callers still need to match the full ID against evidence they actually supplied. */
+export function isNoteCitation(id: string): boolean {
+  if (!id.startsWith("note:") || Buffer.byteLength(id) > 1024 || Array.from(id).some(char => { const point = char.codePointAt(0)!; return point <= 0x1f || point === 0x7f; })) return false;
+  let separator = -1, escaped = false;
+  for (let i = 5; i < id.length; i++) {
+    const char = id[i]!;
+    if (escaped) { if (!["\\", ",", "[", "]", "#"].includes(char)) return false; escaped = false; continue; }
+    if (char === "\\") { escaped = true; continue; }
+    if (char === "#") { if (separator >= 0) return false; separator = i; continue; }
+    if (char === "," || char === "[" || char === "]") return false;
+  }
+  return !escaped && separator > 5 && separator < id.length - 1 && id.slice(5, separator).includes("/");
+}
+
+interface Section { slug: string; heading?: string; body: string }
+
+function contentStart(lines: readonly string[]): number {
+  if (lines[0]?.trimEnd() !== "---") return 0;
+  let bytes = 0;
+  for (let i = 1; i < lines.length; i++) {
+    bytes += Buffer.byteLength(lines[i]!) + 1;
+    if (bytes > MAX_FRONTMATTER_BYTES) return lines.length;
+    if (/^(---|\.\.\.)\s*$/.test(lines[i]!)) return i + 1;
+  }
+  return lines.length;
+}
+
+/** Split prose using the same Markdown heading expression and fenced-code rules as parseNote. */
+function sections(text: string): Section[] {
+  const lines = text.split(/\r?\n/), start = contentStart(lines), bodyLines = lines.slice(start);
+  let endOfSections = bodyLines.length;
+  const boundaries: { line: number; text: string }[] = [];
+  let fence: string | undefined;
+  for (let i = 0; i < bodyLines.length; i++) {
+    const line = bodyLines[i]!;
+    const marker = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (marker) { const mark = marker[1]![0]!; if (!fence) fence = mark; else if (fence === mark) fence = undefined; continue; }
+    if (fence) continue;
+    const heading = /^ {0,3}(#{1,6})\s+(.+?)(?:\s+#+)?\s*$/.exec(line);
+    const cleanHeading = heading ? parseNote(line).headings[0]?.text : undefined;
+    if (cleanHeading) {
+      // A heading beyond the metadata cap is still a section boundary, never content of the preceding citation.
+      if (boundaries.length >= MAX_HEADINGS) { endOfSections = i; break; }
+      boundaries.push({ line: i, text: cleanHeading });
+    }
+  }
+
+  const occupied = new Set<string>();
+  const allocate = (raw: string): string => {
+    const base = headingSlug(raw);
+    let candidate = base, suffix = 2;
+    while (occupied.has(candidate)) candidate = `${base}-${suffix++}`;
+    occupied.add(candidate);
+    return candidate;
+  };
+  const hasIntro = boundaries.length === 0 || bodyLines.slice(0, boundaries[0]!.line).some(line => line.trim());
+  const result: Section[] = [];
+  if (hasIntro) {
+    occupied.add("top");
+    const end = boundaries[0]?.line ?? bodyLines.length;
+    result.push({ slug: "top", body: bodyLines.slice(0, end).join("\n").trim() });
+  }
+  for (let i = 0; i < boundaries.length; i++) {
+    const heading = boundaries[i]!;
+    const end = boundaries[i + 1]?.line ?? endOfSections;
+    result.push({ slug: allocate(heading.text), heading: heading.text, body: bodyLines.slice(heading.line + 1, end).join("\n").trim() });
+  }
+  if (!result.length) result.push({ slug: "top", body: bodyLines.join("\n").trim() });
+  return result;
+}
+
+function metadata(record: NoteRecord): string {
+  return JSON.stringify({ id: record.id, root: record.root, path: record.path, title: record.title, frontmatter: record.frontmatter, tags: record.tags, aliases: record.aliases, headings: record.headings });
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+  let out = "", bytes = 0;
+  for (const char of text) {
+    const size = Buffer.byteLength(char);
+    if (bytes + size > maxBytes) break;
+    out += char; bytes += size;
+  }
+  return out;
+}
+
+function truncateExcerpt(text: string, maxBytes: number): string {
+  if (Buffer.byteLength(text) <= maxBytes) return text;
+  const marker = " [cut]", markerBytes = Buffer.byteLength(marker);
+  if (maxBytes < markerBytes) return "";
+  return `${truncateUtf8(text, maxBytes - markerBytes)}${marker}`;
+}
+
+function permitted(policy: CorpusEvidencePolicy): boolean {
+  try { return policy.allowed(); } catch { return false; }
+}
+
+/** Metadata-first retrieval with a fresh, whole-note privacy screen before any excerpt leaves this module. */
+export function corpusEvidence(query: string, index: CorpusIndex, policy: CorpusEvidencePolicy): CorpusEvidence[] {
+  if (!query.trim() || !permitted(policy)) return [];
+  let version: string;
+  try { version = policy.version(); } catch { return []; }
+  index.refresh();
+  if (!permitted(policy)) return [];
+  const terms = words(query);
+  if (!terms.length) return [];
+  // ponytail: ceiling is 32 metadata-ranked candidates; upgrade by adding a query index over approved note text, never by opening every note body.
+  const candidates = index.notes().map(record => ({ record, score: score(terms, [record.title, record.path, ...record.tags, ...record.aliases, ...record.headings.map(h => h.text)].filter(Boolean).join(" ")) }))
+    .filter(item => item.score > 0).sort((a, b) => b.score - a.score || a.record.id.localeCompare(b.record.id)).slice(0, MAX_CORPUS_READS);
+  const reads = index.readMany(candidates.map(item => item.record.id));
+  if (!permitted(policy)) return [];
+  let currentVersion: string;
+  try { currentVersion = policy.version(); } catch { return []; }
+  if (currentVersion !== version) return [];
+
+  const out: CorpusEvidence[] = [];
+  let aggregate = 0;
+  for (const read of reads) {
+    const record = read.record;
+    const currentMetadata = metadata(record);
+    if (Buffer.byteLength(read.text) > MAX_NOTE_BYTES) continue;
+    try { if (!policy.safe(`${read.text}\n${currentMetadata}`, [read.path, record.path, record.id])) continue; }
+    catch { continue; }
+    const currentScore = score(terms, [record.title, record.path, ...record.tags, ...record.aliases, ...record.headings.map(h => h.text)].filter(Boolean).join(" "));
+    if (!currentScore) continue;
+    const noteSections = sections(read.text);
+    const candidatesForNote = noteSections.map(section => ({ section, score: score(terms, `${section.heading ?? ""} ${section.body}`) }))
+      .sort((a, b) => b.score - a.score);
+    const best = candidatesForNote[0]?.section;
+    if (!best) continue;
+    const rawExcerpt = [best.heading ? `# ${best.heading}` : "", best.body].filter(Boolean).join("\n");
+    const safeText = sanitize(rawExcerpt);
+    let id: string;
+    try { id = noteCitationId(record.id, best.slug); } catch { continue; }
+    const remainingText = MAX_CORPUS_EVIDENCE_BYTES - aggregate - Buffer.byteLength(id);
+    if (!id || remainingText <= 0) continue;
+    const text = truncateExcerpt(safeText, Math.min(MAX_CORPUS_EVIDENCE_ITEM_BYTES, remainingText));
+    if (!text) continue;
+    const cost = Buffer.byteLength(id) + Buffer.byteLength(text);
+    out.push({ id, kind: "note", text });
+    aggregate += cost;
+    if (out.length >= MAX_CORPUS_EVIDENCE) break;
+  }
+  try { if (policy.version() !== version || !permitted(policy)) return []; } catch { return []; }
+  return out;
+}