@alan512/experienceengine 0.1.3 → 0.2.0

package/dist/types/plugin.d.ts

@@ -1,4 +1,4 @@
-import type { EvaluationMode, ExperienceInput, InjectionMode, InjectionScorecard, TaskRun, ToolEvent } from "./domain.js";
+import type { EvaluationMode, ExperienceInput, InjectionMode, InjectionScorecard, RetrievalContext, TaskRun, ToolEvent } from "./domain.js";
 import type { ExperienceEngineConfig } from "../config/config-schema.js";
 export type HostPromptContext = {
     host?: TaskRun["host"];
@@ -28,6 +28,7 @@ export type PromptBuildResult = {
     scorecard?: InjectionScorecard;
     deliveryMode?: EvaluationMode;
     delivered?: boolean;
+    retrievalContext?: RetrievalContext;
     input: ExperienceInput;
 };
 export type ExperiencePlugin = {

package/docs/releases/v0.1.3.md

@@ -70,10 +70,11 @@ The default path now favors short product-facing explanations, while deeper insp
 This release trims duplicated public MCP schema in the Codex adapter without changing the current agent-first workflow:
 
 - merged duplicate feedback, scope-state, and node-lifecycle tools
-- shortened high-traffic prompt text
+- removed public MCP prompts after brokering the remaining high-impact workflows
 - kept repo summary as a resource-only read surface
+- kept routine read surfaces public while shifting long-tail admin, maintenance, and advanced inspect paths behind broker tools
 
-The result is a smaller public schema footprint with no change to the resource-first review flow.
+The result is a smaller public schema footprint with no change to the routine host-first review flow.
 
 ### Marketplace-Facing Metadata
 

package/docs/releases/v0.2.0.md

@@ -0,0 +1,85 @@
+# ExperienceEngine v0.2.0
+
+Release date: 2026-04-13
+
+## Summary
+
+`v0.2.0` is the first release that makes ExperienceEngine explicitly production-first.
+
+This release changes the product center of gravity in three ways:
+
+- live hint delivery is now governed more conservatively, with delivery-state gating and stronger harmful-hint containment
+- posttask feedback is no longer biased toward `success => helped`, and the system now supports structured per-node postmortem writeback
+- Codex lifecycle ownership is now deterministic through a wrapper and validation harness, instead of depending on nested host behavior alone
+
+This is a product-behavior release, not just a packaging or UX pass. That is why it moves to `v0.2.0`.
+
+## Included In This Release
+
+### Production-First Hint Governance
+
+ExperienceEngine now separates lifecycle maturity from live delivery safety more clearly.
+
+Key changes:
+
+- delivery-state governance now controls whether a node is:
+  - shadow-only
+  - conservative-only
+  - eligible
+  - quarantined
+- harmful nodes are removed from normal live delivery earlier
+- `priority_candidate` remains available for cautious first exposure, while ordinary `candidate` paths stay more conservative
+
+The result is that bad guidance is withdrawn faster, instead of being allowed to keep competing in the normal live path.
+
+### Posttask Per-Node Governance Writeback
+
+This release also upgrades the posttask review loop:
+
+- automatic feedback no longer treats successful completion as enough evidence to mark a hint as helped
+- posttask review now supports per-node `helped / harmed / uncertain` adjudication
+- runtime writeback is policy-gated, so model output does not directly mutate lifecycle without bounded checks
+
+This makes the experience library more trustworthy over time, especially for tasks where a hint may have been present but not actually helpful.
+
+### Selective Sync Second Opinion
+
+ExperienceEngine now supports a bounded synchronous LLM second-opinion layer for high-risk live hint decisions.
+
+It is intentionally selective, not always-on.
+
+This release includes:
+
+- the second-opinion gate itself
+- CLI observability for second-opinion activity in:
+  - `ee status`
+  - `ee doctor`
+  - `ee inspect --last --verbose`
+- a tighter trigger policy so second-opinion calls happen less often on low-value edge cases
+- explicit OpenAI-style token budgeting to reduce avoidable provider-side failures
+
+### Deterministic Codex Lifecycle Ownership
+
+Codex now has a deterministic wrapper path instead of relying only on nested model behavior to complete the ExperienceEngine lifecycle.
+
+Included:
+
+- `ee codex exec` wrapper for external lifecycle ownership
+- support for stdin prompt input and explicit EE session ids
+- a deterministic `codex-lifecycle` validation harness
+
+This makes Codex validation and operator workflows much less dependent on host randomness, quota windows, or nested tool-calling behavior.
+
+### OpenClaw Packaging And Runtime Reliability
+
+This release also folds in the OpenClaw stability fixes completed after `v0.1.3`:
+
+- safer packaged install behavior
+- cleaner runtime payload boundaries
+- more explicit learning-loop defaults and diagnostics
+
+## Notes
+
+- `v0.2.0` is still a local-first, single-machine product. It does not yet change the underlying SQLite architecture into a multi-session distributed design.
+- real-host second-opinion acceptance with free-provider routing still depends on third-party provider availability and quota conditions
+- the Codex wrapper path is now the recommended deterministic operator path for real release validation

package/docs/user-guide.md

@@ -251,9 +251,9 @@ When you inspect a specific node, ExperienceEngine now also shows a lightweight
 
 ## How MCP Interaction Works
 
-For `Codex` and `Claude Code`, ExperienceEngine is designed to work mainly through MCP.
+For `Codex` and `Claude Code`, ExperienceEngine is designed to keep routine review and management inside the host session first.
 
-That means after installation, you usually do not leave the agent session to manage ExperienceEngine. Instead, you ask the agent naturally and the agent can call ExperienceEngine MCP resources, prompts, and tools for you.
+That means after installation, you usually do not leave the agent session to manage ExperienceEngine. Instead, you ask the agent naturally and the host uses its native EE wiring for routine interaction.
 
 This is one host-specific implementation of the same shared product model described above:
 
@@ -275,14 +275,23 @@ Typical examples:
 
 ### MCP Interaction Model
 
-ExperienceEngine exposes three MCP categories:
+`Codex` exposes a layered MCP surface:
 
-- `Resources`
-  - read-only state like last interaction, recent history, nodes, doctor output, update state, and backups
-- `Prompts`
-  - reusable workflows that guide the agent to inspect or manage ExperienceEngine safely
-- `Tools`
-  - executable actions like feedback, scope toggles, node lifecycle changes, and high-impact operations
+- `Direct tools`
+  - core loop actions like lookup, recording important tool outcomes, finalize, last-feedback, capabilities, and doctor
+- `Routine read resources`
+  - read-only state like last interaction, recent history, repo summary, and routine node views
+- `Brokered advanced actions`
+  - lower-frequency inspect, admin, maintenance, and high-impact plan/execute flows exposed through a small broker tool surface instead of many direct schemas
+
+For `Codex`, this means routine host-native interaction stays discoverable, while long-tail admin and maintenance actions are reached through brokered actions rather than public prompts or one-tool-per-action registration.
+
+`Claude Code` still uses both `hooks` and `MCP`:
+
+- hooks drive runtime capture and injection
+- MCP drives inspect, control, and operational interaction
+
+So the two hosts share the same product model, but they do not expose the exact same interaction shape.
 
 For high-impact actions, ExperienceEngine does not execute immediately. It uses a:
 
@@ -352,12 +361,13 @@ These are operator-facing controls, not the preferred public onboarding path.
 
 ## Embedding Retrieval
 
-ExperienceEngine now supports a multi-provider embedding stack for semantic retrieval.
+ExperienceEngine now supports a multi-provider embedding stack inside a staged hybrid retrieval pipeline.
 
 Retrieval is now hybrid by default:
 
-- semantic retrieval remains the main recall path
-- lexical retrieval and query normalization help preserve engineering intent when the prompt wording shifts
+- query normalization and rewrite happen first so retrieval keeps engineering intent when prompt wording shifts
+- lexical and semantic retrieval are fused into one candidate shortlist instead of treating semantic retrieval as the unquestioned main path
+- policy enrichment stays separate from retrieval scoring, so maturity and governance signals do not replace retrieval evidence
 - reranking can promote a better-matching candidate above older score advantages, especially when an external reranker is configured
 
 Default behavior (`embeddingProvider = "api"`):
@@ -369,6 +379,12 @@ Default behavior (`embeddingProvider = "api"`):
 - if the API provider fails, ExperienceEngine falls back to the managed local model
 - if the local model fails, ExperienceEngine falls back to legacy hash-based retrieval
 
+Prompt-time behavior:
+
+- first-turn or prompt-only retrieval may not have any tool names or failure signatures yet
+- ExperienceEngine treats those fields as opportunistic evidence, not required retrieval inputs
+- when prompt-only evidence is sparse, lexical, semantic, and policy stages still run with the task summary and context summary alone
+
 Offline behavior (`embeddingProvider = "local"`):
 
 - the default local model is `Xenova/multilingual-e5-small`
@@ -414,6 +430,8 @@ ee install openclaw
 What happens:
 - ExperienceEngine installs as an OpenClaw plugin/runtime integration (not `src/adapters/`)
 - OpenClaw runtime events are used for intervention and persistence
+- OpenClaw uses the shared background learning loop by default
+- async hybrid posttask review stays disabled by default unless the runtime is explicitly overridden
 - management remains mostly through CLI fallback today
 - install ends with a short cold-start note so users know capture is active before the first formal hint appears
 
@@ -511,6 +529,9 @@ Useful commands:
 ```bash
 ee doctor codex
 ee upgrade codex
+ee codex exec -C /path/to/repo -s read-only "Say ok and exit."
+printf "Say ok and exit." | ee codex exec -C /path/to/repo -s read-only -
+ee codex exec --ee-session-id ci-smoke-1 -C /path/to/repo -s read-only "Say ok and exit."
 ```
 
 First validation:
@@ -529,6 +550,12 @@ Host note:
 - ExperienceEngine installs a longer `startup_timeout_sec` for Codex automatically
 - this avoids MCP handshake failures on slower local startups
 - if Codex still cannot see ExperienceEngine in new sessions, re-run `ee install codex`
+- `ee codex exec` is a deterministic wrapper for non-interactive runs
+- the wrapper owns `lookup -> child codex exec -> record -> finalize` outside the child process
+- for wrapped runs, ExperienceEngine removes the nested `experienceengine` MCP server from the child Codex config temporarily so lifecycle evidence is not double-written
+- use prompt `-` when you want the wrapper to read task instructions from stdin; child Codex still receives a wrapped prompt argument and does not inherit stdin
+- use `--ee-session-id <id>` when CI or debugging needs a stable ExperienceEngine session id
+- `codex exec review` is not wrapped yet; keep using native Codex review or the MCP/CLI surfaces for review workflows
 
 Developer validation docs:
 

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "experienceengine",
   "name": "ExperienceEngine",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Context-aware experience intervention controller for coding and debugging tasks.",
   "configSchema": {
     "type": "object",
@@ -28,6 +28,15 @@
         "type": "string",
         "description": "Directory used to store raw runtime payload captures."
       },
+      "distillerProvider": {
+        "type": "string",
+        "enum": ["openai", "anthropic", "gemini", "openrouter", "deepseek", "bedrock", "vertex_gemini", "groq", "openai_compatible"],
+        "description": "Distillation provider reused by phase 2 provider-backed explain."
+      },
+      "distillerModel": {
+        "type": "string",
+        "description": "Distillation model identifier reused by phase 2 provider-backed explain."
+      },
       "maxHints": {
         "type": "integer",
         "minimum": 1,
@@ -39,6 +48,44 @@
         "minimum": 0,
         "maximum": 1,
         "description": "Trigger threshold for intervention gating."
+      },
+      "hybridEnabled": {
+        "type": "boolean",
+        "description": "Enable the hybrid routing layer."
+      },
+      "hybridSyncExplainEnabled": {
+        "type": "boolean",
+        "description": "Allow bounded sync escalation for explicit explanation requests."
+      },
+      "hybridAsyncPostmortemEnabled": {
+        "type": "boolean",
+        "description": "Allow bounded async postmortem review for eligible completed runs."
+      },
+      "hybridAsyncPostmortemLlmEnabled": {
+        "type": "boolean",
+        "description": "Enable provider-backed postmortem_review in phase 3."
+      },
+      "hybridExplainLlmEnabled": {
+        "type": "boolean",
+        "description": "Enable provider-backed explain_decision in phase 2."
+      },
+      "hybridExplainProviderMode": {
+        "type": "string",
+        "enum": ["shared_distiller"],
+        "description": "Provider resolution mode for phase 2 explain_decision."
+      },
+      "hybridExplainModelProfileVersion": {
+        "type": "string",
+        "description": "Version label for the provider-backed explain_decision model profile."
+      },
+      "hybridPostmortemProviderMode": {
+        "type": "string",
+        "enum": ["shared_distiller"],
+        "description": "Provider resolution mode for phase 3 postmortem_review."
+      },
+      "hybridPostmortemModelProfileVersion": {
+        "type": "string",
+        "description": "Version label for the provider-backed postmortem_review model profile."
       }
     }
   },
@@ -61,11 +108,44 @@
       "label": "Capture Directory",
       "placeholder": "./data/runtime-captures"
     },
+    "distillerProvider": {
+      "label": "Distiller Provider"
+    },
+    "distillerModel": {
+      "label": "Distiller Model"
+    },
     "maxHints": {
       "label": "Max Hints"
     },
     "triggerThreshold": {
       "label": "Trigger Threshold"
+    },
+    "hybridEnabled": {
+      "label": "Hybrid Enabled"
+    },
+    "hybridSyncExplainEnabled": {
+      "label": "Hybrid Sync Explain Enabled"
+    },
+    "hybridAsyncPostmortemEnabled": {
+      "label": "Hybrid Async Postmortem Enabled"
+    },
+    "hybridAsyncPostmortemLlmEnabled": {
+      "label": "Hybrid Async Postmortem LLM Enabled"
+    },
+    "hybridExplainLlmEnabled": {
+      "label": "Hybrid Explain LLM Enabled"
+    },
+    "hybridExplainProviderMode": {
+      "label": "Hybrid Explain Provider Mode"
+    },
+    "hybridExplainModelProfileVersion": {
+      "label": "Hybrid Explain Model Profile Version"
+    },
+    "hybridPostmortemProviderMode": {
+      "label": "Hybrid Postmortem Provider Mode"
+    },
+    "hybridPostmortemModelProfileVersion": {
+      "label": "Hybrid Postmortem Model Profile Version"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alan512/experienceengine",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
   "description": "Experience governance for coding agents: learn from real task outcomes, inject reusable hints, and retire low-value guidance.",
   "license": "MIT",
@@ -11,7 +11,15 @@
   "openclaw": {
     "extensions": [
       "./dist/plugin/openclaw-plugin.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.1",
+      "minGatewayVersion": "2026.4.1"
+    },
+    "build": {
+      "openclawVersion": "2026.4.1",
+      "pluginSdkVersion": "2026.4.1"
+    }
   },
   "engines": {
     "node": ">=20.0.0"
@@ -32,28 +40,28 @@
     "scripts/claude-plugin",
     ".env.example"
   ],
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.14",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
   "scripts": {
     "build": "node scripts/build/clean-dist.mjs && tsc -p tsconfig.build.json && node scripts/build/copy-sqlite-schema.mjs",
     "dev": "tsx watch src/cli/index.ts",
     "evaluate:openclaw-baseline": "tsx src/cli/index.ts evaluate openclaw-baseline",
     "evaluate:openclaw-scenarios": "tsx src/cli/index.ts evaluate openclaw-scenarios --pack high-confidence",
+    "evaluate:codex-lifecycle": "tsx src/cli/index.ts evaluate codex-lifecycle",
     "maintenance:merge-warning-variants": "tsx scripts/maintenance/merge-warning-variants.ts",
     "runtime:promote-payload": "tsx scripts/openclaw/promote-runtime-payload.ts",
     "runtime:replay-fixture": "tsx scripts/openclaw/replay-runtime-fixture.ts",
-    "prepack": "pnpm build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "check": "pnpm typecheck && pnpm test && pnpm build"
-  },
-  "dependencies": {
-    "@huggingface/transformers": "^3.8.1",
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@types/node": "^22.13.14",
-    "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
-    "vitest": "^3.0.9"
   }
-}
+}

package/plugins/claude-code-experienceengine/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "experienceengine",
   "description": "Context-aware experience intervention controller for Claude Code.",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "author": {
     "name": "ExperienceEngine"
   },

package/plugins/claude-code-experienceengine/scripts/install-deps.sh

@@ -11,7 +11,7 @@ PACKAGE_ENTRY="${PACKAGE_DIR}/dist/cli/index.js"
 STAMP_PATH="${PLUGIN_DATA}/.experienceengine-plugin-version"
 EXPERIENCE_ENGINE_HOME_PATH="${EXPERIENCE_ENGINE_HOME:-${PLUGIN_DATA}/experienceengine-home}"
 STATE_PATH="${EXPERIENCE_ENGINE_HOME_PATH}/claude-marketplace-state.json"
-PACKAGE_VERSION="0.1.3"
+PACKAGE_VERSION="0.2.0"
 PACKAGE_SPEC="${EXPERIENCE_ENGINE_PLUGIN_PACKAGE_SPEC:-@alan512/experienceengine@${PACKAGE_VERSION}}"
 
 mkdir -p "${PLUGIN_DATA}"