@agfpd/iapeer-memory 0.1.13 → 0.2.0

package/src/surfaces/lock.ts

@@ -0,0 +1,72 @@
+/**
+ * Host-wide provision lock — the iapeer v1.2 contract obliges the provision
+ * command to TOLERATE PARALLEL CALLS (the locking the plugin manager used to
+ * give moved to the provider; §7 requirement 3). The core may fire
+ * provision-peer concurrently (peer births race sweeps); two unsynchronised
+ * read-merge-writes of the SAME settings.json would lose one writer's keys.
+ *
+ * Form: mkdir-based exclusive lock (atomic on every POSIX fs, no flock in
+ * Bun's stable API). One lock for the whole host — provision bodies are
+ * milliseconds of file I/O, serialising them is simpler and strictly safer
+ * than per-cwd granularity. Stale detection: a lock directory older than
+ * STALE_MS belongs to a crashed run — broken and re-taken (provision is
+ * idempotent by contract, a double-run repairs, never corrupts).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const RETRY_MS = 50;
+const DEFAULT_TIMEOUT_MS = 15_000;
+export const STALE_MS = 120_000;
+
+export type LockResult<T> =
+  | { acquired: true; result: T }
+  | { acquired: false; detail: string };
+
+function tryTake(lockDir: string): boolean {
+  try {
+    fs.mkdirSync(lockDir); // atomic: EEXIST when held
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function breakIfStale(lockDir: string): void {
+  try {
+    const stat = fs.statSync(lockDir);
+    if (Date.now() - stat.mtimeMs > STALE_MS) fs.rmdirSync(lockDir);
+  } catch {
+    // raced away or unreadable — the next tryTake decides
+  }
+}
+
+export function withProvisionLock<T>(opts: {
+  stateDir: string;
+  fn: () => T;
+  timeoutMs?: number;
+}): LockResult<T> {
+  const lockDir = path.join(opts.stateDir, "provision.lock.d");
+  fs.mkdirSync(opts.stateDir, { recursive: true });
+  const deadline = Date.now() + (opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  while (!tryTake(lockDir)) {
+    breakIfStale(lockDir);
+    if (Date.now() >= deadline) {
+      return {
+        acquired: false,
+        detail: `provision lock busy for ${Math.round((opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) / 1000)}s (${lockDir}) — another provision hung? stale locks self-break after ${STALE_MS / 1000}s`,
+      };
+    }
+    Bun.sleepSync(RETRY_MS);
+  }
+  try {
+    return { acquired: true, result: opts.fn() };
+  } finally {
+    try {
+      fs.rmdirSync(lockDir);
+    } catch {
+      // already gone (stale-broken by a peer) — nothing to release
+    }
+  }
+}

package/src/surfaces/sweep.ts

@@ -0,0 +1,170 @@
+/**
+ * Fleet-wide surfaces sweep — the package's own rail over fleet.json
+ * (ADR-009 v1.2). The core's birth-hook covers NEWBORNS via the slot's
+ * provision command; everything fleet-wide (init coverage of the existing
+ * fleet, update's «всё на местах» duty, verify --repair self-healing) walks
+ * the fleet map HERE — peer × session-runtime, claude and codex forms.
+ *
+ * Session runtimes are exactly {claude, codex}: telegram/notifier and other
+ * infra runtimes carry no session config surfaces. A peer entry without a
+ * runtimes array (pre-v1.2 map) is SKIPPED and reported — the next map
+ * re-write (same command) picks it up.
+ *
+ * The caller holds the provision lock around the WHOLE sweep (one
+ * acquisition, not per-peer — the sweep body is pure file I/O).
+ */
+
+import fs from "node:fs";
+import {
+  checkClaudePeer,
+  provisionClaudePeer,
+  unprovisionClaudePeer,
+  type SurfaceOutcome,
+} from "./claude.js";
+import { checkCodexPeer, provisionCodexPeer, unprovisionCodexPeer } from "./codex.js";
+import type { FleetPeer } from "../fleet.js";
+
+export const SESSION_RUNTIMES = ["claude", "codex"] as const;
+export type SessionRuntime = (typeof SESSION_RUNTIMES)[number];
+
+export type PeerSweepResult = {
+  personality: string;
+  runtime: SessionRuntime;
+  cwd: string;
+  /** worst action across the peer-runtime's surfaces */
+  ok: boolean;
+  outcomes: SurfaceOutcome[];
+};
+
+export type SweepSummary = {
+  results: PeerSweepResult[];
+  /** peers skipped: no session runtimes in the map entry / vanished cwd */
+  skipped: Array<{ personality: string; reason: string }>;
+};
+
+function sessionRuntimesOf(peer: FleetPeer): SessionRuntime[] {
+  return SESSION_RUNTIMES.filter((r) => peer.runtimes.includes(r));
+}
+
+export function sweepProvision(opts: {
+  fleet: FleetPeer[];
+  hooksDir: string;
+  port: number;
+}): SweepSummary {
+  const results: PeerSweepResult[] = [];
+  const skipped: SweepSummary["skipped"] = [];
+  for (const peer of opts.fleet) {
+    const runtimes = sessionRuntimesOf(peer);
+    if (runtimes.length === 0) {
+      skipped.push({
+        personality: peer.personality,
+        reason: peer.runtimes.length
+          ? `no session runtime (${peer.runtimes.join(",")})`
+          : "no runtimes in fleet map (pre-v1.2 entry) — re-write the map",
+      });
+      continue;
+    }
+    if (!fs.existsSync(peer.cwd)) {
+      skipped.push({ personality: peer.personality, reason: `cwd missing: ${peer.cwd}` });
+      continue;
+    }
+    for (const runtime of runtimes) {
+      const outcomes =
+        runtime === "codex"
+          ? provisionCodexPeer({ cwd: peer.cwd, port: opts.port })
+          : provisionClaudePeer({
+              cwd: peer.cwd,
+              hooksDir: opts.hooksDir,
+              port: opts.port,
+              personality: peer.personality,
+            });
+      results.push({
+        personality: peer.personality,
+        runtime,
+        cwd: peer.cwd,
+        ok: outcomes.every((o) => o.action !== "failed"),
+        outcomes,
+      });
+    }
+  }
+  return { results, skipped };
+}
+
+export function sweepUnprovision(opts: { fleet: FleetPeer[] }): SweepSummary {
+  const results: PeerSweepResult[] = [];
+  const skipped: SweepSummary["skipped"] = [];
+  for (const peer of opts.fleet) {
+    const runtimes = sessionRuntimesOf(peer);
+    if (runtimes.length === 0) {
+      skipped.push({ personality: peer.personality, reason: "no session runtime" });
+      continue;
+    }
+    // a vanished cwd is fine on the off-path — surfaces report `absent`
+    for (const runtime of runtimes) {
+      const outcomes =
+        runtime === "codex"
+          ? unprovisionCodexPeer({ cwd: peer.cwd })
+          : unprovisionClaudePeer({ cwd: peer.cwd });
+      results.push({
+        personality: peer.personality,
+        runtime,
+        cwd: peer.cwd,
+        ok: outcomes.every((o) => o.action !== "failed"),
+        outcomes,
+      });
+    }
+  }
+  return { results, skipped };
+}
+
+export type PeerCheckResult = {
+  personality: string;
+  runtime: SessionRuntime;
+  cwd: string;
+  ok: boolean;
+  problems: string[];
+};
+
+export function checkFleetSurfaces(opts: {
+  fleet: FleetPeer[];
+  hooksDir: string;
+  port: number;
+}): { checks: PeerCheckResult[]; skipped: Array<{ personality: string; reason: string }> } {
+  const checks: PeerCheckResult[] = [];
+  const skipped: Array<{ personality: string; reason: string }> = [];
+  for (const peer of opts.fleet) {
+    const runtimes = sessionRuntimesOf(peer);
+    if (runtimes.length === 0) {
+      skipped.push({
+        personality: peer.personality,
+        reason: peer.runtimes.length
+          ? `no session runtime (${peer.runtimes.join(",")})`
+          : "no runtimes in fleet map (pre-v1.2 entry)",
+      });
+      continue;
+    }
+    if (!fs.existsSync(peer.cwd)) {
+      skipped.push({ personality: peer.personality, reason: `cwd missing: ${peer.cwd}` });
+      continue;
+    }
+    for (const runtime of runtimes) {
+      const surfaceChecks =
+        runtime === "codex"
+          ? checkCodexPeer({ cwd: peer.cwd, port: opts.port })
+          : checkClaudePeer({
+              cwd: peer.cwd,
+              hooksDir: opts.hooksDir,
+              port: opts.port,
+              personality: peer.personality,
+            });
+      checks.push({
+        personality: peer.personality,
+        runtime,
+        cwd: peer.cwd,
+        ok: surfaceChecks.every((c) => c.ok),
+        problems: surfaceChecks.filter((c) => !c.ok).map((c) => `${c.surface}: ${c.detail}`),
+      });
+    }
+  }
+  return { checks, skipped };
+}

package/src/templates/skills.ts

@@ -0,0 +1,196 @@
+/**
+ * Embedded skill files — the DIRECT-surface form of the four session skills
+ * (ADR-009 v1.2: direct per-peer surfaces instead of the plugin socket).
+ * Bodies are the boris-accepted plugin skills (adapters/claude/skills, spot-
+ * checked against the live CLI 10.06) with exactly two deltas:
+ *
+ *   1. names are namespaced `iapeer-memory-*` (boris design input: direct
+ *      skills lose the plugin namespace `/iapeer-memory:name` — the prefix
+ *      replaces it; the `copywriter` collision class);
+ *   2. "plugin" wording → "session surfaces" where it described the socket
+ *      form (the socket is now files merged into the peer's cwd).
+ *
+ * provision-peer materialises them to `<cwd>/.claude/skills/<name>/SKILL.md`
+ * (bytes-compare, package-owned — overwritten on version change; the
+ * `iapeer-memory-` directory prefix is OUR namespace, unprovision removes
+ * every directory matching it).
+ */
+
+export type SkillName =
+  | "iapeer-memory-init"
+  | "iapeer-memory-status"
+  | "iapeer-memory-migrate"
+  | "iapeer-memory-distill";
+
+export const SKILL_NAMES: readonly SkillName[] = [
+  "iapeer-memory-init",
+  "iapeer-memory-status",
+  "iapeer-memory-migrate",
+  "iapeer-memory-distill",
+] as const;
+
+/** Directory-name prefix that marks a skill directory as OURS (the removal
+ *  glob of unprovision — the namespace promise of the `iapeer-memory-*`
+ *  naming). */
+export const SKILL_DIR_PREFIX = "iapeer-memory-";
+
+const SKILL_INIT = `---
+name: iapeer-memory-init
+description: "Use when the user asks to install, provision or initialize iapeer-memory on this host (\\"set up iapeer-memory\\", \\"init memory\\", \\"provision the vault\\"). Thin facade over \`iapeer-memory init\`: the procedure lives in the package CLI, not here."
+allowed-tools: ["Bash", "AskUserQuestion"]
+---
+
+# Provision iapeer-memory on this host
+
+The session surfaces are only a socket (ADR-009) — provisioning is owned by
+the package CLI. Do not improvise installation steps around it.
+
+1. Locate the CLI: \`command -v iapeer-memory || ls ~/.local/bin/iapeer-memory\`.
+   Missing → run via \`npx @agfpd/iapeer-memory\` instead.
+2. Init is two-mode. On a tty it prompts; your Bash calls have NO tty, so
+   without \`--vault\` init refuses (silently provisioning a default storage
+   path is forbidden). Collect the answers from the user first
+   (AskUserQuestion), then run:
+   \`iapeer-memory init --vault PATH --locale en|ru
+   [--embedding-endpoint URL] [--reranker-endpoint URL]\`.
+   Do NOT ask for the human owner: init reads the iapeer registry and uses
+   the single natural peer by itself (don't ask what the stack already
+   knows). Pass \`--human NAME\` only when the registry can't answer (zero or
+   several natural peers) and the user wants a human role.
+3. Init prints a step table (deps → vault → config → binary → templates →
+   roles → fleet → watcher → surfaces → slot → sweep → guide) and is
+   idempotent: on exit 1 re-running init is the official repair path,
+   together with \`iapeer-memory verify --repair\`.
+4. A host that is already provisioned and only version-stale wants the
+   update story, not init: \`npx @agfpd/iapeer-memory@latest update\`.
+
+After success, check the chain with the \`iapeer-memory-status\` skill.
+(\`iapeer onboard\` runs this same init from the core's host phase —
+full-stack onboarding already covers memory.)
+`;
+
+const SKILL_STATUS = `---
+name: iapeer-memory-status
+description: "Use when the user asks for the iapeer-memory status (\\"memory status\\", \\"is the vault index alive\\", \\"check iapeer-memory\\", \\"is memoryd running\\"). Read-only facade over \`iapeer-memory status\`: package ↔ surfaces link first, then the CLI's own diagnostics. Never repairs anything."
+allowed-tools: ["Bash"]
+---
+
+# iapeer-memory status — read-only diagnostics
+
+The session surfaces are the socket, the package is the system (ADR-009).
+This skill's first duty is to DIAGNOSE A BROKEN LINK between them — a
+session whose surfaces are wired but whose system is missing must say so
+explicitly.
+
+1. **Socket → system link**: \`command -v iapeer-memory || ls ~/.local/bin/iapeer-memory\`.
+   Missing → report: "session surfaces present, package missing — the socket
+   has no system behind it; run: npx @agfpd/iapeer-memory init". Stop here.
+2. **Everything else**: run \`iapeer-memory status\` and relay its table —
+   verify checks (config, memory-slot, memoryd heartbeat, notifier watcher,
+   role doctrine versions, per-peer surfaces), slot-file, mcp-endpoint
+   probe, search pipeline, inbox load. Exit 1 = something needs attention.
+
+Reading the table: \`search\` shows the LIVE per-component pipeline from the
+running memoryd (bm25/embedding/reranker/graph) and falls back to the
+static config view when memoryd is down; a growing \`inbox\` count means the
+Index curator is not keeping up.
+`;
+
+const SKILL_MIGRATE = `---
+name: iapeer-memory-migrate
+description: "Use when the user asks to migrate harness auto-memory into iapeer-memory (\\"migrate memory\\", \\"move auto-memory to the vault\\", \\"перенеси auto-memory\\"), or when connecting a peer that has accumulated Claude auto-memory. Facade over \`iapeer-memory migrate\`: the skill resolves the claude-specific SOURCE directory, the deterministic engine does the rest (dry-run → confirm → apply, with backups)."
+argument-hint: "<agent> [<project-dir>]"
+allowed-tools: ["Bash", "AskUserQuestion"]
+---
+
+# Migrate Claude auto-memory into the vault
+
+The engine (\`iapeer-memory migrate\`) is source-agnostic — THIS skill owns the
+claude-specific knowledge of where auto-memory lives. (The codex source is
+NOT wired yet: its live format is unverified — never guess it.)
+
+## Resolve the source directory
+
+- **Launchd/persistent peer** (no \`<project-dir>\` argument):
+  \`SOURCE=~/.claude/agent-memory/<agent>/\`
+- **Project session** (\`<project-dir>\` given): the slug is the absolute
+  path with every non-alphanumeric character replaced by \`-\` — dots too:
+  \`/a/b.c\` → \`-a-b-c\` (so \`~/.iapeer/...\` yields a double dash). When in
+  doubt, \`ls ~/.claude/projects/\` and match.
+  \`SOURCE=~/.claude/projects/<slug>/memory/\`
+
+No directory or no \`.md\` files inside → nothing to migrate; say so and stop.
+
+## Run
+
+1. Dry-run first: \`iapeer-memory migrate --source "$SOURCE" --agent <agent>\`
+   — show the user the plan verbatim (per-file type → subtype mapping,
+   skip lists, totals).
+2. Ask for confirmation (AskUserQuestion).
+3. Apply: same command + \`--apply\`. Per-file backups land under
+   \`~/.iapeer/state/iapeer-memory/migrate-backups/\` before conversion; an
+   existing target note is never overwritten.
+4. Report: migrated/skipped/errors + backup path.
+
+## After migration
+
+A \`feedback\` note that is semantically a pitfall cannot be told apart
+deterministically — re-filing such notes to \`pitfall\` is the agent's manual
+step afterwards (the iapeer-memory-distill skill covers it).
+`;
+
+const SKILL_DISTILL = `---
+name: iapeer-memory-distill
+description: "Use when the user asks the agent to clean up its own memory (\\"distill your memory\\", \\"прибери свою память\\", \\"clean up your operative notes\\"). Deep MANUAL distillation of the agent's own agent-memory folder, in-session, user in the loop — deeper than the DreamWeaver weekly tick: fact-checks, re-filing, promoting team knowledge to canon."
+allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
+---
+
+# Distill your own agent memory
+
+You are cleaning YOUR OWN folder: \`<vault>/06_Agent_Memory/<your personality>/\`
+(RU locale: \`06_Оперативка_агентов/<…>/\`). Identity comes from
+\`PEER_PERSONALITY\` — if it is empty, refuse: you cannot know whose memory
+you are touching. An absent/empty folder = nothing to distill; say so and stop.
+
+## The link-watershed rule (before ANY identity-changing operation)
+
+Deleting, renaming or replacing a note splits on the wikilink graph — query
+the note's connections first (vault_graph MCP tool):
+
+- **0 incoming + 0 outgoing** → isolated; act directly (\`rm\` / rename).
+- **≥1 link in either direction** → the note is part of the graph; set
+  \`status\` to the deprecated token instead and (if needed) write a
+  replacement note. The Index archives it on its PERMANENT_CHANGED pass.
+
+Body edits that keep identity (rewording, updating description, switching
+subtype) need no graph check.
+
+## Passes
+
+1. **Inventory**: list every note; for each — subtype, status, age, one-line
+   gist.
+2. **Dedup**: near-duplicate notes about one topic → merge into the
+   strongest one, deprecate the rest (watershed rule).
+3. **Compress**: bloated notes → tighten to the essentials; notes are
+   injected into readers' contexts, bloat costs the whole team tokens.
+4. **Verify**: notes asserting local facts (paths, flags, versions) —
+   re-check the fact cheaply where possible; stale → fix or deprecate.
+5. **Re-file**: \`feedback\` notes that are semantically pitfalls (a rule
+   born from one incident) → subtype \`pitfall\`; other mis-filed subtypes
+   likewise.
+6. **Promote**: material useful to the whole team → draft into the inbox
+   folder (canon style: self-contained, objective), keep the personal
+   angle in your memory note with an inline \`[[draft title]]\` link.
+7. **Report**: summary to the user — counts per pass, anything that needs
+   their decision.
+
+Confirm with the user between passes 6 and 7 when the promote list is
+non-empty — moving knowledge to canon is visible to the whole team.
+`;
+
+export const SKILL_BODIES: Record<SkillName, string> = {
+  "iapeer-memory-init": SKILL_INIT,
+  "iapeer-memory-status": SKILL_STATUS,
+  "iapeer-memory-migrate": SKILL_MIGRATE,
+  "iapeer-memory-distill": SKILL_DISTILL,
+};