@staix/agent-hub 0.12.28 → 0.12.30

package/src/hub/memory-profile.ts

@@ -0,0 +1,192 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import {
+  CandidateStore, MemoryStore, realPath, memoryHome, resolveProfile,
+  type BoundProfile, type ProfileInput, type StoreOptions,
+} from "@staix/agent-mem";
+import packageJson from "../../package.json";
+
+const EXPECTED_AGENT_MEM_VERSION = packageJson.dependencies["@staix/agent-mem"];
+
+/** Validate metadata located through the actual imported entry, never the hub pin alone. */
+export function assertAgentMemVersion(metadata: unknown, expectedVersion = EXPECTED_AGENT_MEM_VERSION): string {
+  if (!metadata || typeof metadata !== "object") throw new Error("cannot attest loaded agent-mem version");
+  const value = metadata as { name?: unknown; version?: unknown };
+  if (value.name !== "@staix/agent-mem" || typeof value.version !== "string"
+    || !/^\d+\.\d+\.\d+$/.test(value.version) || value.version !== expectedVersion) {
+    throw new Error("loaded agent-mem version does not match the exact dependency pin");
+  }
+  return value.version;
+}
+
+const loadedAgentMem = (() => {
+  try {
+    if (!new URL(import.meta.url).pathname.endsWith("/src/hub/memory-profile.ts")) throw new Error("unattested bundled memory implementation");
+    const entry = import.meta.resolve("@staix/agent-mem");
+    if (!new URL(entry).pathname.endsWith("/src/index.ts")) throw new Error("unknown agent-mem entry layout");
+    // The package exports src/index.ts. Bundles without this resolvable layout
+    // cannot attest the imported implementation and must refuse to open memory.
+    const metadata: unknown = JSON.parse(readFileSync(new URL("../package.json", entry), "utf8"));
+    const actual = metadata && typeof metadata === "object" && typeof (metadata as { version?: unknown }).version === "string"
+      ? (metadata as { version: string }).version : "unknown";
+    try { return { version: assertAgentMemVersion(metadata), valid: true }; }
+    catch { return { version: actual, valid: false }; }
+  } catch { return { version: "unknown", valid: false }; }
+})();
+export const AGENT_MEM_VERSION = loadedAgentMem.version;
+function assertLoadedAgentMem(): void {
+  if (!loadedAgentMem.valid) throw new Error("cannot attest loaded agent-mem version against the exact dependency pin");
+}
+export const MEMORY_PROFILE_UNAVAILABLE = "memory profile unavailable; inspect the selector and generation state, run ahub memory profile-check; use amem migrate --deactivate only to stop using the selected generation";
+const UNAVAILABLE = MEMORY_PROFILE_UNAVAILABLE;
+
+/** No handle was opened; distinct from an unavailable, still-bound handle. */
+export interface UnboundMemoryProfileReceipt {
+  state: "disabled" | "unavailable";
+  home: string;
+  agentMemVersion: string;
+  error?: string;
+  profile?: never;
+  generation?: never;
+  selectorRevision?: never;
+  skippedRows?: never;
+}
+
+export interface MemoryProfileReceipt {
+  profile: BoundProfile["kind"];
+  generation?: string;
+  state: "ready" | "unavailable";
+  selectorRevision: string;
+  home: string;
+  agentMemVersion: string;
+  error?: string;
+  skippedRows: number;
+}
+
+function canonicalHome(path: string): string {
+  if (existsSync(path)) return realPath(path);
+  const parent = dirname(path);
+  return parent === path ? resolve(path) : join(canonicalHome(parent), basename(path));
+}
+function sameProfile(a: BoundProfile, b: BoundProfile): boolean {
+  return a.home === b.home && a.dir === b.dir && a.kind === b.kind
+    && a.generation === b.generation && a.selectorRevision === b.selectorRevision;
+}
+function homeFor(opts: Pick<StoreOptions, "home">): string {
+  return canonicalHome(opts.home === undefined ? memoryHome() : join(canonicalHome(opts.home), "memory"));
+}
+function receipt(profile: BoundProfile, state: MemoryProfileReceipt["state"], skippedRows = 0): MemoryProfileReceipt {
+  return {
+    profile: profile.kind, ...(profile.generation === undefined ? {} : { generation: profile.generation }),
+    state, home: profile.home, selectorRevision: profile.selectorRevision, agentMemVersion: AGENT_MEM_VERSION, skippedRows,
+    ...(state === "unavailable" ? { error: UNAVAILABLE } : {}),
+  };
+}
+
+/** Inspect selection without constructing a store, index, or candidate sidecar. */
+export function selectedMemoryProfile(opts: StoreOptions = {}): MemoryProfileReceipt {
+  assertLoadedAgentMem();
+  return receipt(resolveProfile(homeFor(opts)), "ready");
+}
+
+export class MemoryProfileBinding {
+  readonly home: string;
+  readonly profile: BoundProfile;
+  readonly explicitProfile: ProfileInput;
+  private readonly options: Pick<StoreOptions, "home">;
+  private readonly directMemoryDir: string | undefined;
+  private unavailable = false;
+
+  constructor(opts: StoreOptions = {}, private readonly onUnavailable?: (neutralReason: string) => void, directMemoryDir?: string) {
+    assertLoadedAgentMem();
+    this.options = { home: opts.home };
+    this.directMemoryDir = directMemoryDir;
+    this.home = directMemoryDir === undefined ? homeFor(this.options) : canonicalHome(directMemoryDir);
+    this.profile = Object.freeze({ ...resolveProfile(this.home) });
+    this.explicitProfile = this.profile.kind === "shared-v1" ? "shared-v1" : Object.freeze({ generation: this.profile.generation! });
+  }
+
+  assertCurrent(): void {
+    if (this.unavailable) throw new Error(UNAVAILABLE);
+    try {
+      const currentHome = this.directMemoryDir === undefined ? homeFor(this.options) : canonicalHome(this.directMemoryDir);
+      const current = resolveProfile(currentHome);
+      if (currentHome !== this.home || !sameProfile(current, this.profile)) throw new Error(UNAVAILABLE);
+    } catch {
+      this.invalidate();
+      throw new Error(UNAVAILABLE);
+    }
+  }
+
+  /** Entry fence only; migration requires quiescing and closing all consumers first. */
+  run<T>(work: () => T): T {
+    this.assertCurrent();
+    return work();
+  }
+
+  private invalidate(): void {
+    if (this.unavailable) return;
+    this.unavailable = true;
+    try { this.onUnavailable?.(UNAVAILABLE); } catch { /* Observer failures cannot undo the latch. */ }
+  }
+
+  status(store?: MemoryStore): MemoryProfileReceipt {
+    try { this.assertCurrent(); } catch { /* Report the latched state without exposing metadata errors. */ }
+    let skippedRows = 0;
+    if (!this.unavailable && store) {
+      try { skippedRows = store.bridgeStatus()?.skippedRows ?? 0; } catch { this.invalidate(); }
+    }
+    return receipt(this.profile, this.unavailable ? "unavailable" : "ready", skippedRows);
+  }
+
+  candidateOptions(opts: { home?: string; now?: () => number } = {}): { home?: string; now?: () => number } {
+    this.assertCurrent();
+    const inheritedHome = this.directMemoryDir === undefined ? this.options.home
+      : homeFor({}) === this.home ? undefined : dirname(this.home);
+    const options = { ...opts, home: opts.home ?? inheritedHome };
+    if (homeFor(options) !== this.home) throw new Error(UNAVAILABLE);
+    return options;
+  }
+}
+
+export function openProfileMemory(opts: StoreOptions = {}, onUnavailable?: (neutralReason: string) => void): {
+  store: MemoryStore; binding: MemoryProfileBinding;
+} {
+  const binding = new MemoryProfileBinding(opts, onUnavailable);
+  binding.assertCurrent();
+  const raw = new MemoryStore({ ...opts, profile: binding.explicitProfile });
+  try {
+    binding.assertCurrent();
+    if (!sameProfile(raw.profile, binding.profile)) throw new Error(UNAVAILABLE);
+    // ponytail: entry checks exclude an in-flight cutover; quiesce and close
+    // consumers before migration. Upgrade to a public core pre-write hook if
+    // atomic cutover across an in-flight operation becomes required.
+    return { store: raw, binding };
+  } catch (error) {
+    raw.close();
+    throw error;
+  }
+}
+
+/** Bind a caller-owned store only when it exactly matches the current person selection. */
+export function bindProfileMemory(store: MemoryStore, onUnavailable?: (neutralReason: string) => void): {
+  store: MemoryStore; binding: MemoryProfileBinding;
+} {
+  const binding = new MemoryProfileBinding({}, onUnavailable, store.profile.home);
+  binding.assertCurrent();
+  if (!sameProfile(store.profile, binding.profile)) throw new Error(UNAVAILABLE);
+  return { store, binding };
+}
+
+export function openProfileCandidates(binding: MemoryProfileBinding, opts: { home?: string; now?: () => number } = {}): CandidateStore {
+  const options = binding.candidateOptions(opts);
+  const raw = new CandidateStore(options);
+  try {
+    binding.assertCurrent();
+    if (canonicalHome(raw.dir) !== binding.home) throw new Error(UNAVAILABLE);
+    return raw;
+  } catch (error) {
+    raw.close();
+    throw error;
+  }
+}

package/src/hub/memory-staleness.ts

@@ -0,0 +1,55 @@
+import { lstatSync, type Stats } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { nodePath } from "@staix/agent-mem";
+import { isDenied } from "../local/deny.ts";
+import { foldSegment } from "./permission-mode.ts";
+import { matchesPolicyLexically } from "./path-policy.ts";
+
+export const STALENESS_MAX_PROBES = 32;
+export interface StalenessOptions {
+  cwd: string;
+  privatePaths?: string[];
+  deny?: string[];
+  /** A metadata-only seam for privacy and budget regressions. */
+  probe?: (path: string) => Pick<Stats, "isSymbolicLink" | "isDirectory">;
+}
+
+/** One call-scoped budget/cache, shared by every displayed note. Unknown never produces a marker. */
+export function createStalenessProbe(options: StalenessOptions): (about: readonly string[]) => boolean {
+  const root = resolve(options.cwd), cache = new Map<string, boolean>();
+  let remaining = STALENESS_MAX_PROBES;
+  const allowed = (path: string) => {
+    const name = relative(root, resolve(root, path));
+    return !isDenied(name, options.deny) && !isDenied(foldSegment(name), options.deny?.map(foldSegment))
+      && !matchesPolicyLexically(root, name, [...(options.privatePaths ?? []), ...(options.deny ?? [])]);
+  };
+  const missing = (path: string): boolean => {
+    if (cache.has(path)) return cache.get(path)!;
+    cache.set(path, false);
+    if (!path || path.length > 4096 || isAbsolute(path) || /[\0\r\n]/.test(path) || path.split("/").includes("..") || !allowed(path)) return false;
+    const target = resolve(root, path), rel = relative(root, target);
+    if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) return false;
+    let current = root;
+    // ponytail: private/deny exclusion assumes a tree not modified during this call. A concurrent ancestor swap
+    // by a process running as you can expose one existence bit and is outside docs/security.md's threat model.
+    // Descriptor-anchored no-follow traversal is needed before supporting adversarial concurrent tree mutation.
+    for (const component of rel.split("/")) {
+      current = join(current, component);
+      if (!remaining || !allowed(current)) return false;
+      remaining--;
+      try {
+        const stat = (options.probe ?? lstatSync)(current);
+        // Never follow even a publicly named alias: its target could be private.
+        if (stat.isSymbolicLink()) return false;
+        if (current !== target && !stat.isDirectory()) return false;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") { cache.set(path, true); return true; }
+        return false;
+      }
+    }
+    return false;
+  };
+  // ponytail: file-level only, so a symbol removed from an existing file is unknown. Add a policy-gated symbol
+  // resolver with its own C3 privacy/budget tests before inspecting source contents.
+  return about => about.some(node => { const path = nodePath(node); return path !== undefined && missing(path); });
+}

package/src/hub/path-policy.ts

@@ -147,6 +147,14 @@ function globScope(root: string, lexical: string, actual: string, path: string,
   };
   return visit(root, start, 0, new Set());
 }
+/** Policy preflight without filesystem access. Callers must reject symlink traversal separately. */
+export function matchesPolicyLexically(cwd: string, path: string, paths: string[]): boolean {
+  const root = resolve(cwd), lexical = resolve(root, path);
+  return paths.some(entry => /[?*]/.test(entry)
+    ? patternScope(entry.split("/").filter(p => p && p !== "."), new Set([0]), relative(root, lexical), false)
+    : beneath(lexical, resolve(root, entry)));
+}
+
 /** Compare declared spelling, real targets and bounded aliases; legacy discovery errors fail closed. */
 export function matchesPolicy(cwd: string, path: string, paths: string[], includeParents = false): boolean {
   if (!paths.length) return false;

package/src/hub/project.ts

@@ -1,43 +1,10 @@
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { spawnSync } from "node:child_process";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { hubGitSync } from "./git.ts";
 
-const canonical = (path: string): string => {
-  const absolute = resolve(path);
-  try {
-    return realpathSync(absolute);
-  } catch {
-    const parent = dirname(absolute);
-    return parent === absolute ? absolute : join(canonical(parent), basename(absolute));
-  }
-};
-
-export function canonicalPath(path: string): string {
-  return canonical(path);
-}
-
-/**
- * realpathSync, except that Bun (1.3.14, and 1.4.2 still: #121) throws ENOENT for an existing path containing a
- * backslash (issue #26). Such a path goes to the system realpath, which handles it and returns every component as
- * stored on disk: guardPath checks names, and on a case-insensitive disk `.GIT/config` or `id_rſa` would otherwise
- * pass for another file. A missing path or a dangling symlink still throws, which guardPath relies on. Other paths take
- * realpathSync's answer unchanged.
- */
-export function realPath(path: string): string {
-  try {
-    return realpathSync(path);
-  } catch (error) {
-    if (!resolve(path).includes("\\")) throw error; // a relative path can sit under a backslash directory too
-    // The path as given: resolve() would fold a `..` after a symlink by text. GNU realpath accepts a dangling last
-    // component unless told -e; the BSD one on macOS refuses it by default.
-    const argv = process.platform === "darwin" ? ["/bin/realpath", "--", path] : ["realpath", "-e", "--", path];
-    const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8" });
-    if (r.status !== 0 || !r.stdout.endsWith("\n")) throw error;
-    return r.stdout.slice(0, -1);
-  }
-}
+import { canonicalPath as canonical } from "@staix/agent-mem/platform";
+export { canonicalPath, realPath } from "@staix/agent-mem/platform";
 
 function gitRoot(dir: string): string | undefined {
   const result = hubGitSync(["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });

package/src/hub/read-tools.ts

@@ -0,0 +1,127 @@
+import type { MemoryStore, View, Graph } from "@staix/agent-mem";
+import { looksSecret } from "@staix/agent-mem";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
+
+export const MEMORY_READ_TOOLS = new Set(["hub_memory_search", "hub_memory_show", "hub_memory_graph"]);
+const REFUSAL = "memory read unavailable";
+const bytes = (v: string) => Buffer.byteLength(v, "utf8");
+const excerpt = (text: string, max = 200): string => {
+  if (bytes(text) <= max) return text;
+  const points = Array.from(text), marker = " [incomplete]";
+  let length = 0, out = "";
+  for (const point of points) { if (length + bytes(point) + bytes(marker) > max) break; out += point; length += bytes(point); }
+  return out + marker;
+};
+function reject(): never { throw new PreEffectToolRefusal(REFUSAL); }
+export type MemoryScreen = <T extends { title: string | null; text: string }>(rows: T[]) => T[];
+
+/** Validate before capability logging, storage, or privacy work. Schemas alone do not enforce tool input. */
+export function validateMemoryRead(op: string, a: Record<string, unknown>): void {
+  if (!a || typeof a !== "object" || Array.isArray(a)) reject();
+  const string = (v: unknown, min: number, max: number): v is string => typeof v === "string" && bytes(v) >= min && bytes(v) <= max;
+  const array = (v: unknown, min: number, max: number): v is string[] => Array.isArray(v) && v.length > 0 && v.length <= 8 && v.every(s => string(s, min, max));
+  const limit = (max: number) => a.limit === undefined || (Number.isInteger(a.limit) && Number(a.limit) >= 1 && Number(a.limit) <= max);
+  const keys = op === "hub_memory_search" ? ["query", "limit"] : op === "hub_memory_show" ? ["ids"] : ["starts", "hops", "limit"];
+  if (Object.keys(a).some(k => !keys.includes(k))) reject();
+  if (op === "hub_memory_search" ? !string(a.query, 0, 200) || !limit(20)
+    : op === "hub_memory_show" ? !array(a.ids, 6, 64)
+    : !array(a.starts, 1, 200) || (a.hops !== undefined && a.hops !== 1 && a.hops !== 2) || !limit(120)) reject();
+}
+
+/** 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 {
+  validateMemoryRead(op, a);
+  const safe = (v: unknown): boolean => {
+    try {
+      const text = typeof v === "string" ? v : JSON.stringify(v);
+      return !looksSecret(text) && screen([{ title: null, text }]).length === 1;
+    } catch { return false; }
+  };
+  if (!safe(a)) reject();
+  if (!store) return JSON.stringify({ error: REFUSAL });
+  try {
+    const all = screen(store.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true })).filter(safe);
+    const resolve = (input: string): View => {
+      const id = input.replace(/^mem:/, "");
+      const aliases = [...new Set(all.flatMap(v => [v.id, ...(v.promotedFrom ? [v.promotedFrom] : [])]))];
+      const matched = aliases.includes(id) ? [id] : aliases.filter(v => v.startsWith(id));
+      if (id.length < 6) reject();
+      if (!matched.length) {
+        // Older promotion chains are resolved by the store, but only a fully screened visible terminal is exposed.
+        const redirected = store.get(id, project);
+        const visible = redirected && all.find(v => v.id === redirected.id);
+        if (visible) return visible;
+        reject();
+      }
+      if (matched.length !== 1) reject();
+      const found = all.find(v => v.id === matched[0]) ?? all.find(v => v.promotedFrom === matched[0]);
+      if (!found) reject();
+      return found;
+    };
+    const finish = (v: unknown) => { if (!safe(v)) reject(); return JSON.stringify(v); };
+    const order = (x: View, y: View) => Number(y.kind === "fail") - Number(x.kind === "fail") || y.at.localeCompare(x.at) || x.id.localeCompare(y.id);
+    if (op !== "hub_memory_graph") {
+      const show = op === "hub_memory_show", cap = show ? 8192 : 4096;
+      const query = String(a.query ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+      const rows = show ? [...new Map((a.ids as string[]).map(id => { const v = resolve(id); return [v.id, v]; })).values()]
+        : all.filter(v => !v.supersededBy && query.every(q => `${v.title ?? ""} ${v.text} ${v.about.join(" ")}`.toLowerCase().includes(q))).sort(order);
+      const lines: string[] = [];
+      const render = () => ({ lines, truncated: rows.length - lines.length });
+      for (const v of rows) {
+        if (lines.length >= (show ? 8 : Number(a.limit ?? 8))) break;
+        const header = `mem:${v.id} ${v.kind} ${v.tier} source:${v.source} peer:${v.peer} project:${v.project} at:${v.at}: `.replace(/\s+/g, " ");
+        const body = `${show && stale(v.about) ? "(stale?) " : ""}${v.title ? `${v.title}: ` : ""}${v.text}`.replace(/\s+/g, " ").trim();
+        lines.push(header + body);
+        if (bytes(JSON.stringify(render())) > cap) {
+          const points = Array.from(body);
+          let low = 0, high = points.length;
+          while (low < high) {
+            const mid = Math.ceil((low + high) / 2);
+            lines[lines.length - 1] = header + points.slice(0, mid).join("") + " [incomplete]";
+            if (bytes(JSON.stringify(render())) <= cap) low = mid; else high = mid - 1;
+          }
+          lines[lines.length - 1] = header + points.slice(0, low).join("") + " [incomplete]";
+          if (bytes(JSON.stringify(render())) > cap) lines.pop();
+        }
+      }
+      return finish(render());
+    }
+    const visible = new Map(all.map(v => [`mem:${v.id}`, v]));
+    const goals = new Map(store.goals(project).filter(safe).map(v => [`goal:${v.id}`, v]));
+    const starts = (a.starts as string[]).map(n => {
+      if (n.startsWith("mem:")) return `mem:${resolve(n).id}`;
+      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]>();
+    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) {
+        if ((n.id.startsWith("mem:") && !visible.has(n.id)) || (n.id.startsWith("goal:") && !goals.has(n.id))) continue;
+        const memory = visible.get(n.id), goal = goals.get(n.id);
+        // The dashboard graph already slices labels; model excerpts must retain a visible incompleteness marker.
+        const shown = { ...n, label: excerpt(memory ? memory.title ?? memory.text : goal ? goal.title : n.label) };
+        if (safe(shown)) nodes.set(n.id, shown);
+      }
+      for (const e of graph.edges) if (safe(e)) edges.set(JSON.stringify(e), e);
+    }
+    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 };
+    for (const n of eligibleNodes) {
+      if (out.nodes.length >= Number(a.limit ?? 60)) break;
+      out.nodes.push(n); out.truncated--;
+      if (bytes(JSON.stringify(out)) > (eligibleEdges.length ? 5120 : 6144)) { out.nodes.pop(); out.truncated++; }
+    }
+    const kept = new Set(out.nodes.map(n => n.id));
+    for (const e of eligibleEdges) {
+      if (!kept.has(e.from) || !kept.has(e.to) || out.edges.length >= 240) continue;
+      out.edges.push(e); out.truncated--;
+      if (bytes(JSON.stringify(out)) > 6144) { out.edges.pop(); out.truncated++; }
+    }
+    return finish(out);
+  } catch { return JSON.stringify({ error: REFUSAL }); }
+}