@jmylchreest/aide-plugin 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "aide plugin for OpenCode and Codex CLI — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",

package/skills/reflect/SKILL.md

@@ -139,18 +139,24 @@ Build a JSON array:
 ### 3. Run with classifications
 
 ```bash
-./.aide/bin/aide reflect run \
+./.aide/bin/aide reflect run --llm \
   --classifications-json='[{"id":"01JF...A","intent":"corrective"}]'
 ```
 
 Returns a JSON summary: `{"proposals_written": N, "shapes": {...}}`.
 
-### 4. (Deterministic fallback) Run without classifications
+The `--llm` flag puts the runner in LLM mode, which runs the `RequiresLLM`
+detectors (convergence, friction) in addition to repetition. The Stop hook
+never passes it, so those detectors only ever surface in this reviewed pass.
 
-If step 1 returned no candidates, just run deterministically:
+### 4. Run in LLM mode without classifications
+
+If step 1 returned no candidates, still run with `--llm` (not bare) so
+friction and the marker-based convergence pass fire — only the LLM-graded
+convergence intent is skipped:
 
 ```bash
-./.aide/bin/aide reflect run
+./.aide/bin/aide reflect run --llm
 ```
 
 ### 5. List proposals and summarise for the user
@@ -283,7 +289,17 @@ gated by the env var.
 - **convergence** — `Edit A` → user corrective marker → `Edit B` on the same
   file → optional positive signal. Marker-based by default, upgrades to
   LLM-classified when intent labels are provided via step 3.
-
-Detectors declare a `RequiresLLM` capability. The CLI Stop hook
-(`aide reflect run`) runs only `RequiresLLM=false` detectors automatically;
-LLM-required detectors are skipped unless this skill provides classifications.
+- **friction** — the same tool failing repeatedly on the same target (a Bash
+  command that keeps erroring, an Edit that won't apply to a file). Gathered
+  from the observe `Error` field; the lesson worth keeping is usually the
+  *fix*, which you supply by reading the evidence. `RequiresLLM` — never
+  auto-fires in the Stop hook.
+
+Detectors declare a `RequiresLLM` capability — two tiers:
+
+- **Deterministic tier** (`RequiresLLM=false`: repetition) runs automatically
+  in the Stop hook. Must be high-precision; nothing reviews it before it lands
+  as a proposal.
+- **LLM tier** (`RequiresLLM=true`: convergence, friction) runs only in this
+  reviewed pass, when the skill passes `--llm` (step 3/4). Higher recall is
+  fine — you judge each proposal before anything is promoted.

package/src/cli/codex-config.ts

@@ -218,6 +218,21 @@ function generateHooksJson(hookPrefix: string): CodexHooksJson {
           ],
         },
       ],
+      // Failed tool calls arrive on a separate event (PostToolUse fires on
+      // success only); route them to tool-observe so the friction detector
+      // sees the failure. Same script — it reads the top-level error fields.
+      PostToolUseFailure: [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: `${hookPrefix} tool-observe`,
+              timeout: 3,
+            },
+          ],
+        },
+      ],
       Stop: [
         {
           matcher: "*",

package/src/core/context-pruning/dedup.ts

@@ -128,8 +128,13 @@ export class DedupStrategy implements PruneStrategy {
   ): PruneResult {
     const normalized = toolName.toLowerCase();
 
-    // Only apply to safe tools
-    if (!SAFE_DEDUP_TOOLS.has(normalized)) {
+    // Only apply to safe tools. Try exact match first, then suffix fallback so
+    // harness-prefixed MCP names (mcp__plugin_aide_aide__code_outline,
+    // mcp__aide__code_outline) all resolve via the bare suffix entry.
+    const isSafe =
+      SAFE_DEDUP_TOOLS.has(normalized) ||
+      SAFE_DEDUP_TOOLS.has(normalized.split("__").pop() ?? "");
+    if (!isSafe) {
       return { output, modified: false, bytesSaved: 0 };
     }
 

package/src/core/context-pruning/tracker.ts

@@ -143,29 +143,6 @@ export class ContextPruningTracker {
     return { ...this.stats };
   }
 
-  /**
-   * Get a context pressure value (0.0 - 1.0).
-   * This is a heuristic based on estimated context bytes and pruning ratio.
-   * Higher values mean more context pressure.
-   */
-  getContextPressure(): number {
-    // Use 128K tokens ≈ 512KB as a rough "full context" estimate
-    const estimatedCapacity = 512 * 1024;
-    const usageRatio = Math.min(
-      1.0,
-      this.stats.estimatedContextBytes / estimatedCapacity,
-    );
-
-    // If we're pruning a lot, that's also a pressure signal
-    const pruneRatio =
-      this.stats.totalCalls > 0
-        ? this.stats.prunedCalls / this.stats.totalCalls
-        : 0;
-
-    // Weighted: 70% usage, 30% prune ratio
-    return Math.min(1.0, usageRatio * 0.7 + pruneRatio * 0.3);
-  }
-
   /** Clear history (e.g., on compaction). */
   reset(): void {
     this.history = [];

package/src/core/memory-query.ts

@@ -0,0 +1,63 @@
+/**
+ * Memory query helper — platform-agnostic.
+ *
+ * Thin wrapper around `aide memory list … --format=json` so callers don't each
+ * re-implement the spawn + parse. Returns the parsed entries; filtering,
+ * sorting, and mapping are left to the caller (their needs differ — session
+ * partials filter by tag, the resume path sorts by createdAt).
+ */
+
+import { execFileSync } from "child_process";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "memory-query";
+
+/** Shape of an entry from `aide memory list --format=json`. */
+export interface MemoryEntry {
+  id: string;
+  category?: string;
+  content: string;
+  tags?: string[];
+  createdAt?: string;
+}
+
+export interface ListMemoriesOptions {
+  /** Comma-separated tag filter passed to `--tags=`. */
+  tags?: string;
+  /** Include memories tagged `forget` / `partial` (passes `--all`). */
+  all?: boolean;
+  /** Max rows to return (passes `--limit=`). Defaults to the CLI default. */
+  limit?: number;
+}
+
+/**
+ * Run `aide memory list` with the given filters and return parsed entries.
+ * Returns an empty array on any failure (missing binary, parse error, etc.).
+ */
+export function listMemoriesJson(
+  binary: string,
+  cwd: string,
+  opts: ListMemoriesOptions = {},
+): MemoryEntry[] {
+  try {
+    const args = ["memory", "list", "--format=json"];
+    if (opts.tags) args.push(`--tags=${opts.tags}`);
+    if (opts.all) args.push("--all");
+    if (opts.limit !== undefined) args.push(`--limit=${opts.limit}`);
+
+    const output = execFileSync(binary, args, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    }).trim();
+
+    if (!output || output === "[]" || output === "null") return [];
+
+    const parsed: MemoryEntry[] = JSON.parse(output);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch (err) {
+    debug(SOURCE, `memory list failed (non-fatal): ${err}`);
+    return [];
+  }
+}

package/src/core/partial-memory.ts

@@ -16,6 +16,8 @@
 
 import { execFileSync } from "child_process";
 import { debug } from "../lib/logger.js";
+import { listMemoriesJson, type MemoryEntry } from "./memory-query.js";
+import { categorizePartials, renderBulletSection } from "./session-text.js";
 
 const SOURCE = "partial-memory";
 
@@ -152,55 +154,25 @@ export function storePartialMemory(
   }
 }
 
-/** Shape returned by `aide memory list --format=json`. */
-interface PartialMemoryEntry {
-  id: string;
-  tags: string[];
-  content: string;
-}
-
 /**
  * Query session partials and map to a caller-chosen type.
  *
- * Runs `aide memory list --tags=partial --format=json`, filters to the
- * given session, and maps each match through `mapFn`.
+ * Lists all `partial`-tagged memories, filters to the given session, and maps
+ * each match through `mapFn`.
  */
 function querySessionPartials<T>(
   binary: string,
   cwd: string,
   sessionId: string,
-  mapFn: (m: PartialMemoryEntry) => T,
-  label: string,
+  mapFn: (m: MemoryEntry) => T,
 ): T[] {
-  try {
-    const sessionTag = `session:${sessionId}`;
-
-    const output = execFileSync(
-      binary,
-      [
-        "memory",
-        "list",
-        "--tags=partial",
-        "--all", // Include even if tagged forget (shouldn't be, but defensive)
-        "--format=json",
-        "--limit=500",
-      ],
-      {
-        cwd,
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: 5000,
-      },
-    ).trim();
-
-    if (!output || output === "[]") return [];
-
-    const memories: PartialMemoryEntry[] = JSON.parse(output);
-    return memories.filter((m) => m.tags?.includes(sessionTag)).map(mapFn);
-  } catch (err) {
-    debug(SOURCE, `Failed to gather ${label}: ${err}`);
-    return [];
-  }
+  const sessionTag = `session:${sessionId}`;
+  const memories = listMemoriesJson(binary, cwd, {
+    tags: "partial",
+    all: true, // Include even if tagged forget (shouldn't be, but defensive)
+    limit: 500,
+  });
+  return memories.filter((m) => m.tags?.includes(sessionTag)).map(mapFn);
 }
 
 /**
@@ -214,13 +186,7 @@ export function gatherPartials(
   cwd: string,
   sessionId: string,
 ): string[] {
-  return querySessionPartials(
-    binary,
-    cwd,
-    sessionId,
-    (m) => m.content,
-    "partials",
-  );
+  return querySessionPartials(binary, cwd, sessionId, (m) => m.content);
 }
 
 /**
@@ -231,13 +197,7 @@ export function gatherPartialIds(
   cwd: string,
   sessionId: string,
 ): string[] {
-  return querySessionPartials(
-    binary,
-    cwd,
-    sessionId,
-    (m) => m.id,
-    "partial IDs",
-  );
+  return querySessionPartials(binary, cwd, sessionId, (m) => m.id);
 }
 
 /**
@@ -287,58 +247,16 @@ export function buildSummaryFromPartials(
   gitCommits: string[],
   gitFiles: string[],
 ): string | null {
-  const summaryParts: string[] = [];
-
-  // Deduplicate and categorise partials
-  const fileChanges = new Set<string>();
-  const commands: string[] = [];
-  const tasks: string[] = [];
-  const other: string[] = [];
+  const { files, commands, tasks } = categorizePartials(partials);
+  // Merge file changes from partials and git, preserving order, de-duped.
+  const allFiles = Array.from(new Set([...files, ...gitFiles]));
 
-  for (const p of partials) {
-    if (p.startsWith("Created file: ") || p.startsWith("Edited file: ")) {
-      fileChanges.add(p.replace(/^(Created|Edited) file: /, ""));
-    } else if (p.startsWith("Ran command: ")) {
-      commands.push(p.replace("Ran command: ", ""));
-    } else if (p.startsWith("Completed task: ")) {
-      tasks.push(p.replace("Completed task: ", ""));
-    } else {
-      other.push(p);
-    }
-  }
-
-  if (tasks.length > 0) {
-    summaryParts.push(
-      `## Tasks\n${tasks
-        .slice(0, 5)
-        .map((t) => `- ${t}`)
-        .join("\n")}`,
-    );
-  }
-
-  if (gitCommits.length > 0) {
-    summaryParts.push(
-      `## Commits\n${gitCommits.map((c) => `- ${c}`).join("\n")}`,
-    );
-  }
-
-  // Merge file changes from partials and git
-  const allFiles = new Set([...fileChanges, ...gitFiles]);
-  if (allFiles.size > 0) {
-    const files = Array.from(allFiles).slice(0, 15);
-    summaryParts.push(
-      `## Files Modified\n${files.map((f) => `- ${f}`).join("\n")}`,
-    );
-  }
-
-  if (commands.length > 0) {
-    summaryParts.push(
-      `## Commands\n${commands
-        .slice(0, 10)
-        .map((c) => `- ${c}`)
-        .join("\n")}`,
-    );
-  }
+  const summaryParts = [
+    renderBulletSection("Tasks", tasks, 5),
+    renderBulletSection("Commits", gitCommits),
+    renderBulletSection("Files Modified", allFiles, 15),
+    renderBulletSection("Commands", commands, 10),
+  ].filter((s): s is string => s !== null);
 
   const summary = summaryParts.join("\n\n");
   return summary.length >= 50 ? summary : null;

package/src/core/session-checkpoint-logic.ts

@@ -0,0 +1,170 @@
+/**
+ * Session checkpoint logic — platform-agnostic.
+ *
+ * Builds a structured "session checkpoint" before context compaction, so the
+ * work-so-far is recoverable after the harness summarises the conversation.
+ *
+ * Why a checkpoint and not just a flat summary: aide has structured stores of
+ * its own (task tree, git state) that a mechanical roll-up can pull from
+ * without any LLM. The checkpoint shape mirrors the parts of MiMo-Code's
+ * checkpoint that are derivable without LLM judgment — task state, work
+ * accomplished, files touched, live resources — and is intentionally bounded
+ * (capped lists) rather than "compressed", since the hook has no model access.
+ *
+ * The sections that genuinely need LLM judgment (verbatim user intent,
+ * cross-task discovered knowledge) are deliberately omitted here — fabricating
+ * them mechanically would be worse than leaving them out.
+ */
+
+import { execFileSync } from "child_process";
+import { debug } from "../lib/logger.js";
+import { categorizePartials, renderBulletSection } from "./session-text.js";
+
+const SOURCE = "session-checkpoint";
+
+/** Structured inputs for a checkpoint. All optional sections are omitted when empty. */
+export interface CheckpointInput {
+  sessionId: string;
+  /** Raw partial-memory content strings for this session (from partial-memory). */
+  partials: string[];
+  /** Git oneline commit subjects made during the session. */
+  commits: string[];
+  /** Pre-rendered task-tree lines (icon + summary). See getTaskTree. */
+  taskTree?: string[];
+  /** One-line live runtime state, e.g. "branch main · 3 uncommitted file(s)". */
+  liveState?: string;
+}
+
+interface TaskEntry {
+  id?: string;
+  title?: string;
+  description?: string;
+  status?: string;
+}
+
+/** Map a task status to a MiMo-style status icon. */
+function statusIcon(status: string | undefined): string {
+  switch ((status ?? "").toLowerCase()) {
+    case "done":
+    case "complete":
+    case "completed":
+      return "✅";
+    case "claimed":
+    case "in_progress":
+    case "in-progress":
+      return "🔄";
+    case "blocked":
+      return "🟡";
+    case "abandoned":
+      return "❌";
+    default:
+      return "🔵"; // pending / open / unknown
+  }
+}
+
+/**
+ * Render the current task tree from the swarm task store.
+ *
+ * Returns one line per task (`<icon> <summary> [status]`), capped. Empty array
+ * when no tasks exist (the common case for solo, non-swarm sessions) or when
+ * the task store can't be read — the checkpoint simply omits the section.
+ */
+export function getTaskTree(binary: string, cwd: string): string[] {
+  try {
+    const output = execFileSync(binary, ["task", "list", "--json"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    }).trim();
+
+    if (!output || output === "[]" || output === "null") return [];
+
+    const tasks: TaskEntry[] = JSON.parse(output);
+    if (!Array.isArray(tasks)) return [];
+
+    return tasks.slice(0, 15).map((t) => {
+      const label = t.title || t.description || t.id || "task";
+      const status = t.status ? ` [${t.status}]` : "";
+      return `${statusIcon(t.status)} ${label}${status}`;
+    });
+  } catch (err) {
+    debug(SOURCE, `Failed to read task tree (non-fatal): ${err}`);
+    return [];
+  }
+}
+
+/**
+ * Describe volatile runtime state — current branch and uncommitted file count.
+ * Returns undefined when not a git repo or git is unavailable.
+ */
+export function getGitLiveState(cwd: string): string | undefined {
+  try {
+    const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 3000,
+    }).trim();
+
+    const porcelain = execFileSync("git", ["status", "--porcelain"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 3000,
+    }).trim();
+
+    const dirtyCount = porcelain
+      ? porcelain.split("\n").filter((l) => l.trim()).length
+      : 0;
+    const parts: string[] = [];
+    if (branch) parts.push(`branch ${branch}`);
+    parts.push(`${dirtyCount} uncommitted file(s)`);
+    return parts.join(" · ");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build a structured session checkpoint from already-gathered inputs.
+ *
+ * Pure function (no IO) so it is unit-testable. Sections with no content are
+ * omitted entirely. Returns null when the result carries no substantive
+ * content (mirrors the >=50-char guard used elsewhere).
+ */
+export function buildSessionCheckpoint(input: CheckpointInput): string | null {
+  const {
+    files,
+    commands,
+    tasks: completed,
+    other,
+  } = categorizePartials(input.partials);
+
+  const sections: string[] = [
+    "# Session checkpoint",
+    "_Structured snapshot written before context compaction. Use it to resume work; the verbatim conversation is the ground truth where they disagree._",
+  ];
+
+  const contentSections = [
+    renderBulletSection("Task state", input.taskTree ?? []),
+    renderBulletSection("Work completed", completed, 10),
+    renderBulletSection("Commits", input.commits),
+    renderBulletSection("Files touched", files, 15),
+    renderBulletSection("Commands run", commands, 10),
+    renderBulletSection("Other", other, 10),
+  ].filter((s): s is string => s !== null);
+  sections.push(...contentSections);
+
+  // Live resources is a single line, not a bullet list.
+  if (input.liveState) {
+    sections.push(`## Live resources\n${input.liveState}`);
+  }
+
+  // sections[0..1] are the header + instruction line; require at least one
+  // content section before we consider the checkpoint worth persisting.
+  if (sections.length <= 2) return null;
+
+  const checkpoint = sections.join("\n\n");
+  return checkpoint.length >= 50 ? checkpoint : null;
+}

package/src/core/session-resume-logic.ts

@@ -0,0 +1,104 @@
+/**
+ * Session resume logic — platform-agnostic.
+ *
+ * When a session resumes or restarts after a compaction, re-inject the most
+ * recent session checkpoint so the agent rebuilds working context instead of
+ * relearning it. This is aide's plugin-side equivalent of MiMo-Code's context
+ * reconstruction: a plugin can't rebuild the host's conversation, but it can
+ * inject the last checkpoint at the SessionStart boundary the host gives us.
+ *
+ * No LLM is involved — we surface the structured checkpoint verbatim and let
+ * the main agent reconcile it against the (authoritative) live conversation.
+ */
+
+import { listMemoriesJson, type MemoryEntry } from "./memory-query.js";
+
+/** SessionStart `source` values for which a resume injection is warranted. */
+const RESUME_SOURCES = new Set(["resume", "compact"]);
+
+/**
+ * Query the newest checkpoint memory for this session.
+ *
+ * Prefers `checkpoint`-tagged memories (the structured snapshot written by the
+ * PreCompact hook); falls back to `session-summary`-tagged memories so this
+ * works even where the structured-checkpoint feature isn't present. Prefers an
+ * entry tagged for the current session, but falls back to the newest checkpoint
+ * overall (a resumed session may be assigned a fresh id by the host).
+ */
+export function getLatestCheckpoint(
+  binary: string,
+  cwd: string,
+  sessionId: string,
+): string | null {
+  for (const tag of ["checkpoint", "session-summary"]) {
+    const found = queryNewest(binary, cwd, sessionId, tag);
+    if (found) return found;
+  }
+  return null;
+}
+
+function queryNewest(
+  binary: string,
+  cwd: string,
+  sessionId: string,
+  tag: string,
+): string | null {
+  // checkpoints are tagged `partial`, so --all is required to see them.
+  const memories = listMemoriesJson(binary, cwd, {
+    tags: tag,
+    all: true,
+    limit: 200,
+  });
+  if (memories.length === 0) return null;
+
+  const byTime = (a: MemoryEntry, b: MemoryEntry) =>
+    (b.createdAt ?? "").localeCompare(a.createdAt ?? "");
+
+  const sessionTag = `session:${sessionId}`;
+  const scoped = memories
+    .filter((m) => m.tags?.includes(sessionTag))
+    .sort(byTime);
+  const newest = (scoped.length > 0 ? scoped : [...memories].sort(byTime))[0];
+
+  return newest?.content?.trim() || null;
+}
+
+/**
+ * Render a resume block from checkpoint content. Pure (no IO), unit-testable.
+ *
+ * The verify-before-act reminder is load-bearing: the checkpoint is a snapshot
+ * that may be stale relative to the live conversation, so the agent must treat
+ * it as a starting point, not ground truth.
+ */
+export function renderResumeContext(content: string): string {
+  return [
+    "## Resuming session — last checkpoint",
+    "",
+    "<system-reminder>",
+    "This is a snapshot from before the session was compacted/resumed. Use it to " +
+      "rebuild your bearings, but VERIFY against the current conversation and the " +
+      "actual files before acting — re-read a file rather than trusting the snapshot " +
+      "where they could disagree.",
+    "</system-reminder>",
+    "",
+    content,
+  ].join("\n");
+}
+
+/**
+ * Build the resume context block to append at SessionStart.
+ *
+ * Returns null when the source isn't a resume/compact, or when no checkpoint
+ * exists — callers append nothing in that case.
+ */
+export function buildResumeContext(
+  binary: string,
+  cwd: string,
+  sessionId: string,
+  source: string | undefined,
+): string | null {
+  if (!source || !RESUME_SOURCES.has(source)) return null;
+  const content = getLatestCheckpoint(binary, cwd, sessionId);
+  if (!content) return null;
+  return renderResumeContext(content);
+}