eagle-mem 4.10.13 → 4.11.0

package/docs/agent-compatibility/opencode.md

@@ -0,0 +1,71 @@
+# OpenCode Compatibility
+
+Last verified: 2026-06-02
+
+## Official Sources
+
+- Plugins reference: https://opencode.ai/docs/plugins/
+- Config reference: https://opencode.ai/docs/config/
+- Config schema: https://opencode.ai/config.json
+
+## Installed Surface Verified Locally
+
+- OpenCode CLI: `opencode --version` reported `1.14.24`.
+- OpenCode plugin package: `@opencode-ai/plugin@1.14.24`.
+- Resolved config path: `~/.config/opencode/opencode.json`.
+- Global plugin directory: `~/.config/opencode/plugins/`.
+
+## Behavior Relied On
+
+- OpenCode local plugins are JavaScript or TypeScript modules placed in `.opencode/plugins/` for project scope or `~/.config/opencode/plugins/` for global scope.
+- Files in those plugin directories are loaded automatically at startup.
+- NPM plugins are declared with the top-level `plugin` array in `opencode.json`, but Eagle Mem uses the global local-plugin directory so it does not need to mutate the user plugin array.
+- Plugin functions receive a context object with `project`, `directory`, `worktree`, `client`, and `$`, then return a hooks object.
+- The plugin event bus includes `session.created`, `session.updated`, `session.idle`, `session.compacted`, `session.deleted`, `message.updated`, `message.part.updated`, and `todo.updated`.
+- Direct hook keys include `chat.message`, `tool.execute.before`, `tool.execute.after`, `shell.env`, and `experimental.session.compacting`.
+- `tool.execute.before` can deny a tool call by throwing an error and can mutate `output.args` before execution.
+- `tool.execute.after` receives tool output fields that can be annotated for the model.
+- `experimental.session.compacting` fires before compaction and can push additional strings into `output.context`.
+- `opencode --pure` runs without external plugins; doctor checks should report that Eagle Mem OpenCode support depends on non-pure OpenCode sessions.
+
+## Eagle Mem Mapping
+
+- `chat.message` maps to Eagle Mem `SessionStart` once per session and `UserPromptSubmit` on each user message.
+- `tool.execute.before` maps to Eagle Mem `PreToolUse`; denial becomes a thrown OpenCode plugin error and `updatedInput` mutates `output.args`.
+- `tool.execute.after` maps to Eagle Mem `PostToolUse`; additional context is appended to the tool output so the agent can see guardrail or stale-memory hints.
+- `todo.updated` maps OpenCode todos into Eagle Mem task records through synthetic `TaskCreated` and `TaskUpdate` hook payloads.
+- `session.idle` maps to Eagle Mem `Stop` using the latest assistant text accumulated from message events.
+- `session.deleted` maps to Eagle Mem `SessionEnd`.
+- `experimental.session.compacting` maps to Eagle Mem compact recall by running `SessionStart` with `source=compact` and appending the returned context.
+
+## Eagle Mem Files Depending On This
+
+- `integrations/opencode_eagle_mem_plugin.js`
+- `lib/opencode-hooks.sh`
+- `lib/common.sh`
+- `scripts/install.sh`
+- `scripts/update.sh`
+- `scripts/uninstall.sh`
+- `scripts/doctor.sh`
+- `scripts/test.sh`
+- `hooks/session-start.sh`
+- `hooks/user-prompt-submit.sh`
+- `hooks/pre-tool-use.sh`
+- `hooks/post-tool-use.sh`
+- `hooks/stop.sh`
+- `hooks/session-end.sh`
+
+## Fixtures And Tests
+
+- `tests/fixtures/agent-hooks/opencode-chat-message.json`
+- `tests/fixtures/agent-hooks/opencode-tool-execute-before.json`
+- `tests/fixtures/agent-hooks/opencode-tool-execute-after.json`
+- `tests/fixtures/agent-hooks/opencode-todo-updated.json`
+- `tests/fixtures/agent-hooks/opencode-session-compacting.json`
+- `tests/test_agent_compatibility_docs_gate.sh`
+- `tests/test_opencode_hooks_config.sh`
+- `tests/test_opencode_plugin_adapter.sh`
+
+## Reverification Notes
+
+When editing OpenCode support, re-read the plugins and config docs first. If OpenCode changes plugin load order, local plugin directories, hook names, `tool.execute.*` mutation semantics, `chat.message` payloads, or compaction hooks, update these fixtures before implementation.

package/hooks/post-tool-use.sh

@@ -122,6 +122,7 @@ esac
 
 project=$(eagle_project_from_hook_input "$input")
 [ -z "$project" ] && exit 0
+eagle_hook_observability_begin "$input" "PostToolUse"
 
 # Ensure session row exists before inserting observations (FK constraint).
 # PostToolUse can race SessionStart — the session row might not exist yet.
@@ -249,5 +250,12 @@ eagle_posttool_decision_surface "$tool_name" "$fp" "$project" "$agent"
 if ! eagle_insert_observation "$session_id" "$project" "$tool_name" "$tool_summary" "$files_read" "$files_modified" "$output_bytes" "$output_lines" "$command_category" "$agent"; then
     eagle_log "ERROR" "PostToolUse: observation insert failed for session=$session_id tool=$tool_name"
 fi
+eagle_hook_observability_set_detail "$(jq -nc \
+    --arg tool "$tool_name" \
+    --arg summary "$tool_summary" \
+    --arg files_read "$files_read" \
+    --arg files_modified "$files_modified" \
+    '{tool_name:$tool, summary:$summary, files_read:($files_read | fromjson? // []), files_modified:($files_modified | fromjson? // [])}')"
+eagle_hook_observability_complete 0
 
 exit 0

package/hooks/pre-tool-use.sh

@@ -33,6 +33,7 @@ esac
 [ ! -f "$EAGLE_MEM_DB" ] && exit 0
 project=$(eagle_project_from_hook_input "$input")
 [ -z "$project" ] && exit 0
+eagle_hook_observability_begin "$input" "PreToolUse"
 
 context=""
 updated_input=""
@@ -382,15 +383,23 @@ Use the existing context, run a narrower search, or bypass once with:
     ;;
 esac
 
-[ -z "$context" ] && [ -z "$updated_input" ] && exit 0
+if [ -z "$context" ] && [ -z "$updated_input" ]; then
+    eagle_hook_observability_set_detail "$(jq -nc --arg tool "$tool_name" --arg action "no_action" '{tool_name:$tool, action:$action}')"
+    eagle_hook_observability_complete 0
+    exit 0
+fi
 
 # Codex PreToolUse now natively receives both blocking decisions and advisory context.
 # Removing the old early-exit to align Codex's pre-tool capabilities with Claude and Antigravity.
 
 if [ -n "$updated_input" ]; then
+    eagle_hook_observability_set_detail "$(jq -nc --arg tool "$tool_name" --arg action "updated_input" '{tool_name:$tool, action:$action}')"
+    eagle_hook_observability_complete 0
     jq -nc --arg ctx "$context" --argjson ui "$updated_input" \
         '{"hookSpecificOutput":{"hookEventName":"PreToolUse","updatedInput":$ui,"additionalContext":$ctx}}'
 else
+    eagle_hook_observability_set_detail "$(jq -nc --arg tool "$tool_name" --arg action "additional_context" '{tool_name:$tool, action:$action}')"
+    eagle_hook_observability_complete 0
     jq -nc --arg ctx "$context" '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":$ctx}}'
 fi
 

package/hooks/session-end.sh

@@ -24,6 +24,7 @@ agent=$(eagle_agent_source_from_json "$input")
 cwd=$(echo "$input" | jq -r '.cwd // empty')
 project=$(eagle_project_from_hook_input "$input")
 [ -z "$project" ] && exit 0
+eagle_hook_observability_begin "$input" "SessionEnd"
 
 # Final sweep: re-capture all task files to catch status changes
 # Claude Code may update task status without triggering PostToolUse
@@ -40,6 +41,8 @@ fi
 
 eagle_end_session "$session_id"
 eagle_log "INFO" "SessionEnd: session=$session_id marked completed"
+eagle_hook_observability_set_detail "$(jq -nc --arg action "session_completed" '{action:$action}')"
+eagle_hook_observability_complete 0
 
 # Prune observations older than 90 days (keeps DB size bounded)
 eagle_prune_observations 90 "$project"

package/hooks/session-start.sh

@@ -35,6 +35,7 @@ codex_compact=0
 
 project=$(eagle_project_from_hook_input "$input")
 [ -z "$project" ] && exit 0
+eagle_hook_observability_begin "$input" "SessionStart"
 
 p_esc=$(eagle_sql_escape "$project")
 recall_scope=$(eagle_recall_project_scope_from_cwd "$cwd" "$project")
@@ -655,7 +656,13 @@ regression_risks: [risk, ...]
 fi
 
 if [ -n "$context" ]; then
+    eagle_hook_observability_set_detail "$(jq -nc \
+        --arg source_type "$source_type" \
+        --arg recall_scope "$recall_scope" \
+        --argjson injected_chars "${#context}" \
+        '{source_type:$source_type, recall_scope:$recall_scope, injected_chars:$injected_chars}')"
     eagle_emit_context_for_agent "$agent" "SessionStart" "$context"
 fi
+eagle_hook_observability_complete 0
 
 exit 0

package/hooks/stop.sh

@@ -31,6 +31,7 @@ agent=$(eagle_agent_source_from_json "$input")
 
 project=$(eagle_project_from_hook_input "$input")
 [ -z "$project" ] && exit 0
+eagle_hook_observability_begin "$input" "Stop"
 
 eagle_log "INFO" "Stop: session=$session_id project=$project transcript=$transcript_path agent=$agent"
 
@@ -237,7 +238,7 @@ if [ "$needs_enrichment" -eq 1 ]; then
     # lifecycle timeouts and make the hook look broken to users.
     if [ "${EAGLE_MEM_STOP_ENRICH:-0}" != "1" ]; then
         defer_enrichment=1
-        eagle_log "INFO" "Stop: LLM enrichment skipped — fast hook path (provider=$provider)"
+        eagle_log "INFO" "Stop: LLM enrichment skipped on fast hook path; provider=$provider"
     elif [ "$provider" != "none" ] && [ -n "$text_content" ]; then
         excerpt=$(echo "$text_content" | tail -c 3000)
 
@@ -399,10 +400,18 @@ fi
 if [ -n "$request" ] || [ -n "$completed" ] || [ -n "$learned" ]; then
     if eagle_insert_summary "$session_id" "$project" "$request" "$investigated" "$learned" "$completed" "$next_steps" "$files_read" "$files_modified" "$notes" "$decisions" "$gotchas" "$key_files" "$agent"; then
         eagle_log "INFO" "Stop: summary saved for session=$session_id"
+        eagle_insert_event "$project" "$session_id" "$agent" "memory_created" "" "Stop" "ok" "$(jq -nc --arg source "summary" '{source:$source}')" >/dev/null 2>&1 || true
     else
         eagle_log "ERROR" "Stop: summary insert FAILED for session=$session_id — check DB constraints"
     fi
 fi
+eagle_hook_observability_set_detail "$(jq -nc \
+    --argjson files_read "$files_read" \
+    --argjson files_modified "$files_modified" \
+    --arg request "$request" \
+    --arg completed "$completed" \
+    '{request_chars:($request | length), completed_chars:($completed | length), files_read:$files_read, files_modified:$files_modified}')"
+eagle_hook_observability_complete 0
 
 if [ "$defer_enrichment" -eq 1 ] && [ "${EAGLE_MEM_STOP_BACKGROUND_ENRICH:-1}" = "1" ] && [ -n "$text_content" ]; then
     mkdir -p "$EAGLE_MEM_DIR/tmp" 2>/dev/null || true

package/hooks/user-prompt-submit.sh

@@ -30,11 +30,22 @@ recall_scope=$(eagle_recall_project_scope_from_cwd "$cwd" "$project")
 [ -z "$recall_scope" ] && recall_scope="$project"
 codex_compact=0
 [ "$agent" = "codex" ] && codex_compact=1
+eagle_hook_observability_begin "$input" "UserPromptSubmit"
 
 # ─── Context pressure detection (turn counter since last compact) ──
 # Must run before any early exits so every prompt is counted
 
 context=""
+summary_matches=0
+memory_matches=0
+code_matches=0
+summary_refs="[]"
+memory_refs="[]"
+code_refs="[]"
+
+count_pipe_rows() {
+    awk -F'|' '($1 != "" || $2 != "") { c++ } END { print c + 0 }'
+}
 
 if [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
     counter_file="$EAGLE_MEM_DIR/.turn-counter.${session_id}"
@@ -85,6 +96,9 @@ fi
 # Skip short prompts — not enough signal for meaningful search
 word_count=$(echo "$user_prompt" | wc -w | tr -d ' ')
 if [ "$word_count" -lt 3 ]; then
+    eagle_insert_recall_event "$session_id" "$recall_scope" "$cwd" "$agent" "$user_prompt" "" 0 0 0 "${#context}" "skipped_short_prompt" "" >/dev/null 2>&1 || true
+    eagle_hook_observability_set_detail "$(jq -nc --arg recall_status "skipped_short_prompt" --argjson injected_chars "${#context}" '{recall_status:$recall_status, injected_chars:$injected_chars}')"
+    eagle_hook_observability_complete 0
     eagle_emit_context_for_agent "$agent" "UserPromptSubmit" "$context"
     exit 0
 fi
@@ -105,6 +119,9 @@ fts_query=$(echo "$user_prompt" | tr -cs '[:alnum:]' ' ' | tr '[:upper:]' '[:low
     }')
 
 if [ -z "$fts_query" ]; then
+    eagle_insert_recall_event "$session_id" "$recall_scope" "$cwd" "$agent" "$user_prompt" "" 0 0 0 "${#context}" "skipped_no_query" "" >/dev/null 2>&1 || true
+    eagle_hook_observability_set_detail "$(jq -nc --arg recall_status "skipped_no_query" --argjson injected_chars "${#context}" '{recall_status:$recall_status, injected_chars:$injected_chars}')"
+    eagle_hook_observability_complete 0
     eagle_emit_context_for_agent "$agent" "UserPromptSubmit" "$context"
     exit 0
 fi
@@ -113,19 +130,27 @@ fi
 
 lower_prompt=$(printf '%s' "$user_prompt" | tr '[:upper:]' '[:lower:]')
 if printf '%s\n' "$lower_prompt" | grep -Eq '(orchestrat|worker|parallel|multi-agent|multi agent|split|lane|scope out|plan and get started|broad|full codebase|release|publish|ship)'; then
+    auto_orchestration=$(eagle_auto_orchestrate_from_prompt "$project" "$session_id" "$agent" "$user_prompt" "$cwd" "broad_prompt" 2>/dev/null || true)
+    if [ -n "$auto_orchestration" ]; then
+        IFS='|' read -r auto_name auto_id auto_lane_count _auto_lanes_json <<< "$auto_orchestration"
+        context+="
+Eagle Mem orchestration: detected broad work and created durable orchestration '$auto_name' with $auto_lane_count lanes.
+- Inspect it with: eagle-mem orchestrate --name $auto_name
+- Lanes already exist as durable tasks; update them instead of relying on memory alone.
+"
+    fi
     if [ "$codex_compact" -eq 1 ]; then
         context+="
 Eagle Mem orchestration:
-- For broad work, you run eagle-mem orchestrate yourself.
-- Use durable lanes, opposite-agent workers, and concise user-visible status.
+- Continue from the durable lanes Eagle already created.
+- Keep lane/task status current as work progresses.
 "
     else
         context+="=== Eagle Mem: Orchestration Protocol ===
-If this request is broad enough to split into worker lanes, YOU run the orchestration commands. Do not ask the user to run them.
+Eagle has already detected broad work and registered durable orchestration state.
 
 Use:
-  eagle-mem orchestrate init \"<goal>\"
-  eagle-mem orchestrate lane add <key> --agent codex|claude-code --desc \"<self-contained scope>\" --validate \"<command>\"
+  eagle-mem orchestrate --name auto
   eagle-mem orchestrate lane start|block|complete <key>
 
 Keep this mostly invisible to the user; surface only concise status or handoff when useful.
@@ -146,6 +171,8 @@ memory_limit=3
 
 results=$(eagle_search_summaries "$fts_query" "$recall_scope" "$summary_limit")
 memory_results=$(eagle_search_agent_memories "$fts_query" "$recall_scope" "$memory_limit" 2>/dev/null || true)
+summary_matches=$(printf '%s\n' "$results" | count_pipe_rows)
+memory_matches=$(printf '%s\n' "$memory_results" | count_pipe_rows)
 
 if [ -n "$results" ] || [ -n "$memory_results" ]; then
     if [ "$codex_compact" -eq 1 ]; then
@@ -195,6 +222,13 @@ Eagle Mem recalls:
             context+="
 "
         fi
+        summary_refs=$(printf '%s' "$summary_refs" | jq -c \
+            --arg created_at "$created_at" \
+            --arg agent "$summary_agent" \
+            --arg request "$req" \
+            --arg completed "$completed" \
+            --arg learned "$learned" \
+            '. + [{created_at:$created_at, agent:$agent, request:$request, completed:$completed, learned:$learned}]' 2>/dev/null || printf '[]')
     done <<< "$results"
 
     while IFS='|' read -r mname mtype mdesc msnippet _mfile _mupdated morigin; do
@@ -219,6 +253,12 @@ Eagle Mem recalls:
             context+="
 "
         fi
+        memory_refs=$(printf '%s' "$memory_refs" | jq -c \
+            --arg name "$mname" \
+            --arg type "$mtype" \
+            --arg description "$mdesc" \
+            --arg agent "$morigin" \
+            '. + [{name:$name, type:$type, description:$description, agent:$agent}]' 2>/dev/null || printf '[]')
     done <<< "$memory_results"
 fi
 
@@ -226,6 +266,7 @@ fi
 has_chunks=$(eagle_count_code_chunks "$project")
 if [ "${has_chunks:-0}" -gt 0 ]; then
     code_results=$(eagle_search_code_chunks "$fts_query" "$project" "$code_limit")
+    code_matches=$(printf '%s\n' "$code_results" | count_pipe_rows)
 
     if [ -n "$code_results" ]; then
         if [ "$codex_compact" -eq 1 ]; then
@@ -246,11 +287,27 @@ Relevant code:
             [ -n "$lang" ] && context+=" ($lang)"
             context+="
 "
+            code_refs=$(printf '%s' "$code_refs" | jq -c \
+                --arg file "$fpath" \
+                --arg start_line "$sline" \
+                --arg end_line "$eline" \
+                --arg language "$lang" \
+                '. + [{file:$file, start_line:$start_line, end_line:$end_line, language:$language}]' 2>/dev/null || printf '[]')
         done <<< "$code_results"
     fi
 fi
 
-[ -z "$context" ] && exit 0
+if [ -z "$context" ]; then
+    eagle_insert_recall_event "$session_id" "$recall_scope" "$cwd" "$agent" "$user_prompt" "$fts_query" "$summary_matches" "$memory_matches" "$code_matches" 0 "no_context" "" "$summary_refs" "$memory_refs" "$code_refs" >/dev/null 2>&1 || true
+    eagle_hook_observability_set_detail "$(jq -nc \
+        --arg recall_status "no_context" \
+        --argjson summary_matches "${summary_matches:-0}" \
+        --argjson memory_matches "${memory_matches:-0}" \
+        --argjson code_matches "${code_matches:-0}" \
+        '{recall_status:$recall_status, summary_matches:$summary_matches, memory_matches:$memory_matches, code_matches:$code_matches, injected_chars:0}')"
+    eagle_hook_observability_complete 0
+    exit 0
+fi
 
 if [ "$codex_compact" -eq 1 ]; then
     context+="
@@ -264,5 +321,21 @@ IMPORTANT: If directly useful, start with one short Eagle Mem attribution line,
 "
 fi
 
+eagle_insert_recall_event "$session_id" "$recall_scope" "$cwd" "$agent" "$user_prompt" "$fts_query" "$summary_matches" "$memory_matches" "$code_matches" "${#context}" "ok" "" "$summary_refs" "$memory_refs" "$code_refs" >/dev/null 2>&1 || true
+eagle_insert_event "$recall_scope" "$session_id" "$agent" "context_injected" "" "UserPromptSubmit" "ok" "$(jq -nc \
+    --argjson summary_matches "${summary_matches:-0}" \
+    --argjson memory_matches "${memory_matches:-0}" \
+    --argjson code_matches "${code_matches:-0}" \
+    --argjson injected_chars "${#context}" \
+    '{summary_matches:$summary_matches, memory_matches:$memory_matches, code_matches:$code_matches, injected_chars:$injected_chars}')" >/dev/null 2>&1 || true
+eagle_hook_observability_set_detail "$(jq -nc \
+    --arg recall_status "ok" \
+    --argjson summary_matches "${summary_matches:-0}" \
+    --argjson memory_matches "${memory_matches:-0}" \
+    --argjson code_matches "${code_matches:-0}" \
+    --argjson injected_chars "${#context}" \
+    '{recall_status:$recall_status, summary_matches:$summary_matches, memory_matches:$memory_matches, code_matches:$code_matches, injected_chars:$injected_chars}')"
+eagle_hook_observability_complete 0
+
 eagle_emit_context_for_agent "$agent" "UserPromptSubmit" "$context"
 exit 0