@jmylchreest/aide-plugin 0.0.66 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.66",
+  "version": "0.1.0",
   "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

@@ -0,0 +1,289 @@
+---
+name: reflect
+description: Run the instinct parser catalogue against this session's observe events to surface candidate patterns for promotion to memories. Two-pass: gather candidates, judge intent, write proposals.
+triggers:
+  - reflect on this
+  - reflect on the session
+  - find instincts
+  - extract instincts
+  - propose instincts
+---
+
+# Reflect
+
+Extract candidate **instincts** — patterns repeatedly observed in this session
+that might be worth promoting to durable memories.
+
+## Your role as the agent running this skill
+
+You **propose, the user approves**. Nothing this skill does writes a memory
+or marks anything superseded without an explicit yes from the user.
+
+Detectors emit proposals into a holding bucket (they're never auto-promoted
+to memories). When this skill runs, your job is to make those proposals
+*reviewable* — to add the judgement that mechanical matching can't:
+
+1. **Classify intent** of user prompts in convergence windows — was the
+   user actually correcting the previous edit, or just commenting?
+2. **Rewrite the content into a useful memory** — see below. This is the
+   most important step; the detector's content is a `[DRAFT — rewrite…]`
+   placeholder, never the finished memory.
+3. **Judge semantic conflicts** — which existing memories (if any) does
+   this proposal supersede?
+4. **Recommend an action** — accept (with rewritten content + supersedes),
+   reject (why), or leave open for the user to think about.
+
+Then **stop and ask**. Surface each proposal to the user with your
+recommendation. Wait for explicit approval before running
+`aide reflect accept|reject`. The CLI is the write surface; your role is
+to make the user's approval decision as well-informed as possible, not to
+make it for them.
+
+Concretely: do not chain "list proposals → accept proposals" in the same
+turn. List, summarise, recommend, **wait**, then act on user instruction.
+
+## Why rewriting is the default, not the exception
+
+The detector emits an **observation** ("`cat` was run 5 times in 1 minute").
+That's a structural signal, not a useful memory. A useful memory captures:
+
+- **Why** the repetition / convergence happened (the underlying need or
+  mistake the agent kept circling around).
+- **What** the canonical alternative is (a specific file path, command,
+  pattern, or piece of project knowledge).
+- **Scope** (this codebase / this kind of task / this directory).
+
+The agent reviewing the proposal does this synthesis by reading the
+evidence snapshot. The detector can't — it only knows the count.
+
+Bad memory (the raw template): *"In this project, `cat` is run repeatedly.
+Cache its output."*
+
+Good memory (after agent synthesis): *"When investigating the aide
+README for plugin/config questions, the file is stable per commit and the
+config table sits around lines 11-25 — inject the slice via Read with
+offset/limit instead of re-`cat`-ing the whole file."*
+
+The proposal's content field literally starts with `[DRAFT — rewrite with
+concrete context before accepting]` to make this obvious. If you accept
+without rewriting, you've stored noise.
+
+## How this skill differs from the automatic Stop hook
+
+- The **Stop hook** (`AIDE_REFLECT=1` env or `reflect.enabled=true` in
+  `.aide/config/aide.json`) runs `aide reflect run` automatically at session
+  end. Deterministic-only: marker matching for convergence, pure counting
+  for repetition. No supersession beyond structural `instinct_key:*` matches.
+- **This skill** adds a second pass: it lists user-prompt candidates that
+  fall in convergence-relevant windows, you judge intent in-context, you
+  search for semantically conflicting memories, then you feed everything
+  back. Higher-quality output, no extra API cost — uses tokens you'd be
+  spending anyway.
+
+## Session resolution
+
+All commands below default to the **current session** — `aide` finds it by
+checking, in order: an explicit `--session=<id>` flag, the `AIDE_SESSION_ID`
+env var (set by OpenCode automatically; not by Claude Code), then the
+session of the most recent observe event. Pass `--session=<id>` to target
+a specific session, or run `./.aide/bin/aide reflect current-session` to
+see what would be resolved.
+
+## Steps
+
+### 1. Get candidate prompts
+
+```bash
+./.aide/bin/aide reflect candidates
+```
+
+Returns JSON like:
+
+```json
+{
+  "session_id": "abc123",
+  "guidance": "For each prompt, judge whether it was correcting...",
+  "asks": ["intent"],
+  "prompts": [
+    {
+      "id": "01JF...A",
+      "timestamp": "...",
+      "text": "no don't add async — it should stay sync",
+      "preceding_edit": "Edit src/api/users.ts",
+      "following_edit": "Edit src/api/users.ts",
+      "file_path": "src/api/users.ts"
+    }
+  ]
+}
+```
+
+If `prompts` is empty, skip to step 4 (deterministic run only).
+
+### 2. Classify each prompt
+
+For each prompt, judge its `intent` using the surrounding edit context:
+
+- `corrective` — the user was redirecting the assistant's last action
+- `positive` — the user was affirming the assistant's last action ("perfect", "ship it", "lgtm")
+- `neutral` — neither corrective nor affirming (e.g. a new task, a question)
+
+Build a JSON array:
+
+```json
+[
+  {"id": "01JF...A", "intent": "corrective", "confidence": 0.95},
+  {"id": "01JF...B", "intent": "neutral"}
+]
+```
+
+### 3. Run with classifications
+
+```bash
+./.aide/bin/aide reflect run \
+  --classifications-json='[{"id":"01JF...A","intent":"corrective"}]'
+```
+
+Returns a JSON summary: `{"proposals_written": N, "shapes": {...}}`.
+
+### 4. (Deterministic fallback) Run without classifications
+
+If step 1 returned no candidates, just run deterministically:
+
+```bash
+./.aide/bin/aide reflect run
+```
+
+### 5. List proposals and summarise for the user
+
+```
+mcp__plugin_aide_aide__instinct_proposals_list { "status": "open" }
+```
+
+Summarise each new proposal's `summary` field for the user. Don't act on
+anything yet — let them decide.
+
+### 6. You decide what gets superseded
+
+This is where your judgement matters most. The structural auto-supersession
+(same `instinct_key:*` tag) only catches instinct-on-instinct dedup. The
+interesting case is when a new instinct contradicts a **manually-set**
+memory the user wrote earlier — e.g. a "documentation standard: always run
+rustdoc" memory being superseded by a new "rustdoc runs repeatedly, cache
+it" instinct.
+
+Mechanical matching can't catch that. You can. Process:
+
+1. Extract the key subject from the proposal (e.g. "rustdoc", a file path,
+   a command name).
+2. `mcp__plugin_aide_aide__memory_search { "query": "<subject>" }`
+3. Read each result. Judge — **you are the judge**:
+   - Does the new instinct's guidance *contradict* this memory's guidance?
+   - Does it *replace* it with a better recommendation?
+   - Or does it just touch the same topic without conflicting?
+4. Only collect IDs that genuinely conflict. False positives create silent
+   memory loss; bias toward "leave it" when uncertain.
+5. Surface your reasoning to the user before acting: "I think proposal X
+   supersedes memory Y because Z — accept with `--supersedes=Y`?"
+
+### 7. Rewrite the content, then present recommendations — do not auto-act
+
+For each proposal:
+
+1. **Read the evidence snapshot** via `mcp__plugin_aide_aide__instinct_inspect`.
+2. **Synthesise the underlying lesson**. What was the agent (you, or a past
+   you) actually trying to achieve? Why did the pattern repeat / converge?
+   What's the canonical alternative for this codebase?
+3. **Draft the rewritten memory content**. Skip the `[DRAFT — …]` template
+   text from the proposal; write a useful instinct from scratch.
+4. **Present to the user** with the rewrite inline:
+
+> Proposal `01JF…` (repetition, `rustdoc` × 7 in 5 min). Reading the
+> evidence: 6 of the 7 calls were `rustdoc --no-deps` checking the same
+> public crate while iterating on a doctest. I'd accept with this
+> rewritten content and supersede memory `01JD…` ("always run rustdoc")
+> because the new guidance refines, not contradicts, that one:
+>
+> > "When iterating on a single doctest, `cargo test --doc <module>`
+> > re-runs only that doctest in ~1s; reserve `rustdoc --no-deps` for
+> > final pre-commit verification across all crates."
+>
+> Command:
+> `aide reflect accept 01JF… --supersedes=01JD… \
+>   --content="When iterating on a single doctest…"`
+
+Then **wait**. The user might say:
+- "yes" → run the command verbatim
+- "yes but tweak the wording to …" → adjust `--content=` and re-present
+- "accept but don't supersede" → drop `--supersedes`
+- "reject — that's not actually a pattern, I asked you to repeat for testing"
+  → run reject with that reason
+- "leave them open, I'll review later" → do nothing, you're done
+
+If the evidence doesn't support a meaningful rewrite — e.g. the events are
+a test trigger, a one-off, a data artifact — **recommend reject**. A
+proposal with no useful synthesis is noise; promoting it pollutes the
+memory store.
+
+### 8. Execute the user's decision via the CLI
+
+Only after the user has chosen — writes are CLI-only per aide convention:
+
+```bash
+# Accept with rewritten content (the default — see step 7):
+./.aide/bin/aide reflect accept <proposal-id> --content="<your synthesised memory>"
+
+# Accept with rewritten content AND supersession:
+./.aide/bin/aide reflect accept <proposal-id> \
+  --content="<your synthesis>" \
+  --supersedes=<mem-id1>,<mem-id2>
+
+# Accept verbatim (the [DRAFT…] template lands as the memory — almost
+# never what you want, included only for completeness):
+./.aide/bin/aide reflect accept <proposal-id>
+
+# Reject (with reason for the audit trail):
+./.aide/bin/aide reflect reject <proposal-id> --reason="not useful"
+```
+
+Supersession unions two sources:
+
+1. **Structural (auto)** — instinct memories sharing the same
+   `instinct_key:*` tag (cheap dedup; same Bash command for repetition,
+   same file path for convergence).
+2. **Semantic (via `--supersedes`)** — IDs from step 6. Works for any
+   memory including manually-set ones with no instinct tags.
+
+Each superseded record gets `superseded` + `superseded_by:<new-id>` tags;
+the new memory gets `supersedes:<csv>` pointing back. Superseded records
+stay in the bucket for audit but are filtered out of default queries.
+
+## Inspecting evidence
+
+```
+mcp__plugin_aide_aide__instinct_inspect { "id": "<ulid>" }
+```
+
+The `evidence.snapshot` array contains the observe events that triggered the
+pattern.
+
+## Opt-in toggle for the Stop hook
+
+```bash
+export AIDE_REFLECT=1      # also: true, on, yes — any truthy value
+```
+
+When unset or set to a falsy value (`0`, `false`, `off`, `no`), the Stop hook
+is a no-op. This skill still works regardless — it's manually invoked, not
+gated by the env var.
+
+## Shape catalogue
+
+- **repetition** — Bash commands run > N times in a session, suggesting the
+  agent forgot it already had the answer. Pure counting, no LLM input needed.
+- **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.

package/skills/swarm/SKILL.md

@@ -6,6 +6,10 @@ triggers:
   - parallel agents
   - spawn agents
   - multi-agent
+  - halt agent
+  - pause swarm
+  - stop agent
+  - resume agent
 ---
 
 # Swarm Mode
@@ -221,7 +225,28 @@ When all 5 stages are complete:
 });
 ```
 
-### 4. Monitor Progress
+### Mid-flight control
+
+Once stories are launched, you can intervene without killing/restarting agents.
+All control writes go through `aide agent` and reach the subagent on its
+**next tool call** (worst case ≈ duration of an in-flight Bash/Edit). The
+signal hook (`src/hooks/agent-signals.ts`) gates on a subagent's
+`parent_session` being set — orchestrator/solo sessions see zero overhead.
+
+- **Inspect**: `./.aide/bin/aide agent list --parent=$(./.aide/bin/aide reflect current-session) --json`
+- **Halt cleanly**: `./.aide/bin/aide agent halt <agent-id> --reason="repeated rustdoc — see new instinct"`
+  Next tool call is blocked with the reason surfaced to the model.
+- **Pause / resume**: `./.aide/bin/aide agent pause <agent-id>` then `./.aide/bin/aide agent resume <agent-id>`.
+  Paused agents can only call `message_send`/`message_list`/`message_ack`/`state_get`.
+- **Mid-flight instruction**: `./.aide/bin/aide message send --from=orchestrator --to=<agent-id> --priority=high "scope drifted — focus on auth.ts only"`.
+  Surfaced as `additionalContext` on the subagent's next tool call.
+- **Soft deadline**: `./.aide/bin/aide agent deadline <agent-id> 30m` — warns at < 5min remaining; halts at 0.
+
+When to intervene vs. let it run: prefer letting agents finish a stage and
+review at the next checkpoint. Use mid-flight halt only for clearly-wrong
+directions (infinite loops, scope drift, depleted budget with no progress).
+
+### Monitor Progress
 
 Use TaskList to see all story progress:
 

package/skills/swarm-status/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: swarm-status
+description: Inspect a running swarm — show the agent tree, current tools, halts/pauses, and recent task/message activity for the orchestrator's own swarm.
+triggers:
+  - swarm status
+  - what are the agents doing
+  - show swarm
+  - agent status
+  - check agents
+---
+
+# Swarm Status
+
+Quick orchestrator-side inspection of a live swarm. Run this when you want
+to see what your spawned subagents are doing right now without halting them
+or opening the aide-web dashboard.
+
+## Steps
+
+### 1. Resolve current session (your own)
+
+```bash
+./.aide/bin/aide reflect current-session
+```
+
+Use that ID as `<parent>` below — it's the orchestrator session that owns
+the swarm.
+
+### 2. List agents in this swarm
+
+```bash
+./.aide/bin/aide agent list --parent=<parent> --json
+```
+
+Returns one record per registered subagent with `parent_session`,
+`namespace`, `status`, `halt`, `paused`, `deadline`.
+
+### 3. Active tasks for this swarm
+
+```bash
+./.aide/bin/aide task list --parent-session=<parent> --json
+```
+
+Filters the project-wide task bucket to ones tagged with this swarm's
+parent. Look for tasks stuck in `claimed` without progress.
+
+### 4. Recent messages
+
+```bash
+./.aide/bin/aide message list --parent-session=<parent>
+```
+
+Cross-agent comms within this swarm. High-priority messages from the
+orchestrator are surfaced to subagents on their next tool call by the
+signals hook.
+
+### 5. Summarise for the user
+
+Group by agent. For each, report:
+
+- Status (running / paused / halted)
+- Current tool (read `agent:<id>:currentTool` via `aide state get currentTool --agent=<id>` if you want this)
+- Any flags (halt with reason, pause)
+- Open tasks they hold
+- Deadline if set
+
+Example output:
+
+```
+Swarm <parent-id-short> — 3 agents
+
+agent-auth (running):
+  current: Edit src/auth/handler.ts
+  tasks: 2 in_progress
+  no flags
+
+agent-payments (paused):
+  reason: scope drift — investigating
+  tasks: 1 claimed (#42)
+  paused 3m ago
+
+agent-docs (halted):
+  reason: repeated rustdoc — see new instinct
+  halted 12m ago
+```
+
+### When to use halts vs. messages
+
+- **Halt** if the agent is clearly off-track or burning budget with no
+  progress. The halt blocks tool calls; the model will respond once with
+  the halt reason then stop.
+- **High-priority message** if you want to redirect without stopping —
+  arrives as `additionalContext` on the next tool call so the model can
+  read it and adjust.
+
+Both are sent via `aide` CLI:
+
+```bash
+./.aide/bin/aide agent halt <agent-id> --reason="..."
+./.aide/bin/aide message send --from=orchestrator --to=<agent-id> \
+  --priority=high "redirect: focus on auth.ts only"
+```
+
+## Not for
+
+This skill is read-only orchestration. Use the `swarm` skill itself to
+launch new agents or resolve worktrees at the end.

package/src/core/context-guard.ts

@@ -19,6 +19,7 @@ import { resolve, isAbsolute, normalize, extname } from "path";
 import { tmpdir } from "os";
 import { join } from "path";
 import { debug } from "../lib/logger.js";
+import { isTruthy } from "../lib/hook-utils.js";
 import { getPreviousRead, checkFileReadFreshness } from "./read-tracking.js";
 
 const SOURCE = "context-guard";
@@ -248,7 +249,7 @@ export function checkSmartReadHint(
   }
 
   // Require code watcher to be enabled
-  if (process.env.AIDE_CODE_WATCH !== "1") {
+  if (!isTruthy(process.env.AIDE_CODE_WATCH)) {
     return { shouldHint: false };
   }
 

package/src/core/mcp-sync.ts

@@ -26,6 +26,7 @@ import {
 import { join, dirname } from "path";
 import { homedir } from "os";
 import * as TOML from "smol-toml";
+import { findProjectRoot } from "../lib/project-root.js";
 
 // =============================================================================
 // Types
@@ -178,11 +179,13 @@ function aideUserMcpPath(): string {
 }
 
 function aideProjectMcpPath(cwd: string): string {
-  return join(cwd, ".aide", "config", "mcp.json");
+  const { root } = findProjectRoot(cwd);
+  return join(root, ".aide", "config", "mcp.json");
 }
 
 function journalPath(cwd: string): string {
-  return join(cwd, ".aide", "config", "mcp-sync.journal.json");
+  const { root } = findProjectRoot(cwd);
+  return join(root, ".aide", "config", "mcp-sync.journal.json");
 }
 
 function userJournalPath(): string {

package/src/core/read-tracking.ts

@@ -13,6 +13,7 @@ import { execFileSync } from "child_process";
 import { isAbsolute, relative, resolve } from "path";
 import { setState, getState } from "./aide-client.js";
 import { debug } from "../lib/logger.js";
+import { isTruthy } from "../lib/hook-utils.js";
 
 const SOURCE = "read-tracking";
 
@@ -50,7 +51,7 @@ export function recordFileRead(
   cwd: string,
   filePath: string,
 ): void {
-  if (process.env.AIDE_CODE_WATCH !== "1") return;
+  if (!isTruthy(process.env.AIDE_CODE_WATCH)) return;
 
   try {
     const relPath = toRelativePath(cwd, filePath);
@@ -73,7 +74,7 @@ export function getPreviousRead(
   cwd: string,
   filePath: string,
 ): string | null {
-  if (process.env.AIDE_CODE_WATCH !== "1") return null;
+  if (!isTruthy(process.env.AIDE_CODE_WATCH)) return null;
 
   try {
     const relPath = toRelativePath(cwd, filePath);
@@ -113,39 +114,17 @@ export function checkFileReadFreshness(
   }
 }
 
-/**
- * Record a token event via `aide token record`.
- * Fire-and-forget — errors are logged but not propagated.
- */
-export function recordTokenEvent(
-  binary: string,
-  cwd: string,
-  eventType: string,
-  tool: string,
-  filePath: string,
-  tokens: number,
-  tokensSaved: number = 0,
-): void {
-  try {
-    const args = ["token", "record", eventType, tool, filePath, String(tokens)];
-    if (tokensSaved > 0) {
-      args.push(String(tokensSaved));
-    }
-    execFileSync(binary, args, {
-      cwd,
-      timeout: 3000,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    debug(SOURCE, `Token event: ${eventType} ${tool} ${filePath} tokens=${tokens} saved=${tokensSaved}`);
-  } catch (err) {
-    debug(SOURCE, `Failed to record token event: ${err}`);
-  }
+export function previewContent(text: string, maxChars = 300): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= maxChars) return collapsed;
+  return collapsed.slice(0, maxChars - 1) + "…";
 }
 
 /**
  * Record an arbitrary observe event via `aide observe record`.
- * Use when you need richer fields than recordTokenEvent (per-skill name with
- * a stable subtype, attrs, etc.). Fire-and-forget.
+ * Prefer `emitInjectionEvent` for `kind=injection` callers — this raw
+ * recorder is reserved for non-injection kinds (e.g. `hook` user_prompt
+ * events). Fire-and-forget.
  */
 export function recordObserveEvent(
   binary: string,
@@ -183,3 +162,47 @@ export function recordObserveEvent(
     debug(SOURCE, `Failed to record observe event: ${err}`);
   }
 }
+
+/**
+ * Emit a `kind=injection` observe event for any hook that pushes
+ * `additionalContext` back to the harness. Centralises field naming so the
+ * Injections page can group/colour consistently.
+ *
+ * `subtype` should come from a small fixed taxonomy:
+ *   memory | decision | session_memory | skill | enrichment | guard |
+ *   signal | pruning
+ *
+ * `source` is the emitting hook name (e.g. "search-enrichment"); it lands in
+ * both `file` and `name` so the UI can show "who injected this" without
+ * forcing every caller to invent a unique `name`.
+ *
+ * Fire-and-forget; failures are logged at debug level and never thrown.
+ */
+export function emitInjectionEvent(
+  binary: string,
+  cwd: string,
+  opts: {
+    source: string;
+    subtype: string;
+    content: string;
+    sessionId?: string;
+    name?: string;
+    attrs?: Record<string, string>;
+  },
+): void {
+  const baseAttrs: Record<string, string> = {
+    source_id: opts.source,
+    source_kind: opts.subtype,
+    content_preview: previewContent(opts.content, 2000),
+  };
+  recordObserveEvent(binary, cwd, {
+    kind: "injection",
+    name: opts.name ?? opts.source,
+    category: "inject",
+    subtype: opts.subtype,
+    tokens: Math.round(opts.content.length / 3.0),
+    file: opts.source,
+    session: opts.sessionId,
+    attrs: { ...baseAttrs, ...(opts.attrs ?? {}) },
+  });
+}

package/src/core/search-enrichment.ts

@@ -21,6 +21,7 @@
 
 import { execFileSync } from "child_process";
 import { debug } from "../lib/logger.js";
+import { isTruthy } from "../lib/hook-utils.js";
 
 const SOURCE = "search-enrichment";
 
@@ -73,7 +74,7 @@ export function checkSearchEnrichment(
   }
 
   // Require code watcher to be enabled (implies code index exists)
-  if (process.env.AIDE_CODE_WATCH !== "1") {
+  if (!isTruthy(process.env.AIDE_CODE_WATCH)) {
     return { shouldEnrich: false };
   }