diff options
| -rw-r--r-- | .hermes-plugin/__init__.py | 6 | ||||
| -rw-r--r-- | .opencode/plugins/superpowers.js | 16 | ||||
| -rw-r--r-- | .pi/extensions/superpowers.ts | 7 | ||||
| -rw-r--r-- | docs/README.opencode.md | 4 | ||||
| -rw-r--r-- | docs/porting-to-a-new-harness.md | 15 | ||||
| -rw-r--r-- | tests/hermes/test_plugin.py | 18 | ||||
| -rw-r--r-- | tests/opencode/test-bootstrap-caching.mjs | 22 | ||||
| -rw-r--r-- | tests/opencode/test-session-bootstrap.mjs | 10 | ||||
| -rw-r--r-- | tests/pi/test-pi-extension.mjs | 49 |
9 files changed, 120 insertions, 27 deletions
diff --git a/.hermes-plugin/__init__.py b/.hermes-plugin/__init__.py index 7d4e1f5..3c5a207 100644 --- a/.hermes-plugin/__init__.py +++ b/.hermes-plugin/__init__.py @@ -108,7 +108,9 @@ def register(ctx): # pre_llm_call returning {"context": ...} is the documented injection path # (on_session_start return values are ignored, and ctx.inject_message # refuses from that hook — verified empirically 2026-07-23). The context is - # appended to the first turn's user message. + # appended to the first turn's user message. delegate_task children run + # with platform="subagent" and an empty history, so every child's first + # turn would otherwise get the controller bootstrap too. def pre_llm_call( session_id=None, user_message=None, @@ -118,7 +120,7 @@ def register(ctx): platform=None, **kwargs, ): - if is_first_turn: + if is_first_turn and platform != "subagent": return {"context": bootstrap} return None diff --git a/.opencode/plugins/superpowers.js b/.opencode/plugins/superpowers.js index 9659e80..d39c1ec 100644 --- a/.opencode/plugins/superpowers.js +++ b/.opencode/plugins/superpowers.js @@ -79,7 +79,7 @@ export const V1_MAPPING = `**Tool Mapping for OpenCode:** When skills request actions, substitute OpenCode equivalents: - Create or update todos → \`todowrite\` - \`Subagent (general-purpose):\` → \`task\` with \`subagent_type: "general"\` -- Invoke a skill → OpenCode's native \`skill\` tool +- Invoke a skill → OpenCode's native \`skill\` tool. Skill ids are bare names, so drop the \`superpowers:\` prefix skills use when they name each other (\`superpowers:brainstorming\` → \`skill\` with \`name: "brainstorming"\`) - Read files → \`read\` - Create, edit, or delete files → \`apply_patch\` - Run shell commands → \`bash\` @@ -97,7 +97,7 @@ export const V2_MAPPING = `**Tool Mapping for OpenCode:** When skills request actions, substitute OpenCode equivalents: - Create or update todos → OpenCode v2 has no todo tool; track the plan in a markdown file (or the harness's plan facility) instead - \`Subagent (general-purpose):\` → \`subagent\` with \`agent: "general"\` (give it \`description\` and \`prompt\`, optionally \`background\`; pass \`sessionID\` to continue a previous subagent) -- Invoke a skill → OpenCode's native \`skill\` tool +- Invoke a skill → OpenCode's native \`skill\` tool. Skill ids are bare names, so drop the \`superpowers:\` prefix skills use when they name each other (\`superpowers:brainstorming\` → \`skill\` with \`id: "brainstorming"\`) - Read files → \`read\` - Create, edit, or delete files → use \`patch\` with \`patchText\` when available; otherwise use \`write\` to create or overwrite files, \`edit\` for targeted changes, and \`shell\` for deletion - Run shell commands → \`shell\` (\`command\`, \`workdir\`, \`timeout\`, \`background\`) @@ -113,6 +113,11 @@ Use OpenCode's native \`skill\` tool to list and load skills.`; // regex work on every agent step. See #1202 for the full analysis. const _bootstrapCache = new Map(); // mapping -> bootstrap (null = file missing) +// Opening of every injected bootstrap part. The already-injected guards match +// it at the start of a part, so a prompt that merely mentions the tag (#2197) +// is not mistaken for the bootstrap. +const BOOTSTRAP_MARKER = '<EXTREMELY_IMPORTANT>\nYou have superpowers.'; + // Helper to generate bootstrap content (cached after first call per mapping) const getBootstrapContent = (toolMapping) => { // Return cached result on subsequent calls @@ -128,8 +133,7 @@ const getBootstrapContent = (toolMapping) => { const fullContent = fs.readFileSync(skillPath, 'utf8'); const { content } = extractAndStripFrontmatter(fullContent); - _bootstrapCache.set(toolMapping, `<EXTREMELY_IMPORTANT> -You have superpowers. + _bootstrapCache.set(toolMapping, `${BOOTSTRAP_MARKER} **IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.** @@ -249,7 +253,7 @@ export const SuperpowersPlugin = async ({ client, directory }) => { if (!firstUser || !firstUser.parts.length) return; // Guard: skip if first user message already contains bootstrap. - if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return; + if (firstUser.parts.some(p => p.type === 'text' && p.text.startsWith(BOOTSTRAP_MARKER))) return; // #2160: never restart the controller workflow inside task subagent // (child) sessions. V1 passes no input to this hook (verified in the @@ -356,7 +360,7 @@ async function setup(ctx) { if (!bootstrap || !event.messages || !event.messages.length) return; const firstUser = event.messages.find(m => m.role === 'user'); if (firstUser && (!firstUser.content || !firstUser.content.length)) return; - if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.includes('EXTREMELY_IMPORTANT'))) return; + if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.startsWith(BOOTSTRAP_MARKER))) return; // #2160: the request event carries the sessionID directly. Skip the // controller bootstrap when this prompt belongs to a task subagent diff --git a/.pi/extensions/superpowers.ts b/.pi/extensions/superpowers.ts index 2e948e9..3b38adf 100644 --- a/.pi/extensions/superpowers.ts +++ b/.pi/extensions/superpowers.ts @@ -24,10 +24,9 @@ export default function superpowersPiExtension(pi: ExtensionAPI) { injectBootstrap = true; }); - pi.on("agent_end", async () => { - injectBootstrap = false; - }); - + // Messages returned from a context handler are sent to the provider but never + // written to session history, so the bootstrap has to be injected into every + // provider request, on every prompt, for the whole session. pi.on("context", async (event) => { if (!injectBootstrap) return; if (event.messages.some(messageContainsBootstrap)) return; diff --git a/docs/README.opencode.md b/docs/README.opencode.md index 35e8226..252e2b5 100644 --- a/docs/README.opencode.md +++ b/docs/README.opencode.md @@ -148,7 +148,7 @@ Skills speak in actions rather than naming any one runtime's tools. The bootstra - "Create a todo" / "mark complete in todo list" → `todowrite` - `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration) -- "Invoke a skill" → OpenCode's native `skill` tool +- "Invoke a skill" → OpenCode's native `skill` tool with the bare skill name (`superpowers:brainstorming` → `name: "brainstorming"`) - "Read a file" → `read` - "Create a file" / "edit a file" / "delete a file" → `apply_patch` - "Run a shell command" → `bash` @@ -159,7 +159,7 @@ Skills speak in actions rather than naming any one runtime's tools. The bootstra - "Create a todo" → V2 has no todo tool of any kind; the mapping tells the model to track the plan in a markdown file (or the harness's plan facility) instead - `Subagent (general-purpose):` template → OpenCode's `subagent` tool with `agent: "general"` (or `"explore"`); pass `sessionID` to continue a previous subagent -- "Invoke a skill" → OpenCode's native `skill` tool +- "Invoke a skill" → OpenCode's native `skill` tool with the bare skill id (`superpowers:brainstorming` → `id: "brainstorming"`) - "Read a file" → `read` - "Create, edit, or delete files" → use `patch` with `patchText` when available; otherwise use `write` to create or overwrite files, `edit` for targeted changes, and `shell` for deletion - "Run a shell command" → `shell` (`command`, `workdir`, `timeout`, `background`) diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md index fa99a23..a48ecdf 100644 --- a/docs/porting-to-a-new-harness.md +++ b/docs/porting-to-a-new-harness.md @@ -428,10 +428,9 @@ messages break some models (#894). Three things you must replicate: harness-specific constant.) Cache the bootstrap content at module level so you're not re-reading and re-parsing `SKILL.md` on every call (#1202). - **Compaction.** If the harness compacts/summarizes history, re-inject - afterward. pi sets an `injectBootstrap` flag on `session_start` and - `session_compact`, clears it on `agent_end`, and inserts the message *after* - any leading compaction-summary messages. OpenCode relies on its per-step - re-injection plus the dedup guard. + afterward. pi re-injects on every `context` call and inserts the message + *after* any leading compaction-summary messages. OpenCode relies on its + per-step re-injection plus the dedup guard. - **Message-object shape is per-harness — discover yours, don't copy a literal.** The two references use *incompatible* shapes: pi builds `{ role, content: [{ type, text }], timestamp }`; OpenCode manipulates @@ -827,9 +826,11 @@ Use this as the live index; when in doubt, read the files, not this table. (Cursor). Use what your harness exports; the script re-derives the root itself. - **System-message injection.** Shape B injects a *user* message on purpose (#750, #894). Don't "fix" it to a system message. -- **Per-step vs per-turn callbacks.** OpenCode fires every step (per-call dedup - guard); pi fires per turn (lifecycle flag + `agent_end` reset). Copying one - harness's dedup strategy onto the other's callback frequency breaks injection. +- **Disarming injection after the first prompt.** If your harness's transform + output is not saved to session history (pi's `context` result is not), the + bootstrap must be injected into every provider request. A flag cleared on a + per-prompt event such as pi's `agent_end` drops the bootstrap after the first + prompt (#2083). - **Message-object shape is per-harness.** Shape B. pi and OpenCode use incompatible shapes; discover yours, don't copy a reference's object literal. - **Hunting for a skill-registration API that doesn't exist.** A harness with no diff --git a/tests/hermes/test_plugin.py b/tests/hermes/test_plugin.py index 57d619e..7c896a3 100644 --- a/tests/hermes/test_plugin.py +++ b/tests/hermes/test_plugin.py @@ -87,6 +87,24 @@ class TestBootstrapInjection: assert _fire_pre_llm(mock_ctx, is_first_turn=False) is None assert _fire_pre_llm(mock_ctx, is_first_turn=None) is None + def test_subagent_platform_skips_bootstrap_on_first_turn(self, mock_ctx): + plugin = _load_plugin() + plugin.register(mock_ctx) + assert ( + _fire_pre_llm(mock_ctx, is_first_turn=True, platform="subagent") + is None + ) + + def test_non_subagent_platforms_receive_bootstrap(self, mock_ctx): + plugin = _load_plugin() + plugin.register(mock_ctx) + for platform in ("cli", "desktop", "cron", "telegram"): + result = _fire_pre_llm( + mock_ctx, is_first_turn=True, platform=platform + ) + assert isinstance(result, dict) + assert BOOTSTRAP_MARKER in result["context"] + def test_hook_tolerates_future_kwargs(self, mock_ctx): plugin = _load_plugin() plugin.register(mock_ctx) diff --git a/tests/opencode/test-bootstrap-caching.mjs b/tests/opencode/test-bootstrap-caching.mjs index 386b7b1..39e4daa 100644 --- a/tests/opencode/test-bootstrap-caching.mjs +++ b/tests/opencode/test-bootstrap-caching.mjs @@ -76,6 +76,9 @@ const failures = scenario === 'present' if (scenario === 'present') { failures.push(...assertV2Bootstrap(result)); + // #2583: both flavors register bare skill ids and look them up exactly. + failures.push(...assertTeachesBareSkillIds('V1', bootstrapText(firstOutput), 'name')); + failures.push(...assertTeachesBareSkillIds('V2', v2Result.text, 'id')); } failures.push(...mappingFailures); @@ -202,6 +205,25 @@ function assertMappingConstants(mod) { return failures; } +// #2583: skills reference each other as `superpowers:<name>` (the Claude Code +// plugin namespace), but OpenCode V1 and V2 register bare ids (`brainstorming`) +// and their `skill` tools do an exact lookup, so a namespaced call fails with +// "Unable to load skill". When the injected bootstrap contains namespaced +// references, its tool mapping must tell the model to drop the prefix, using +// the flavor's `skill` parameter (V1 `name`, V2 `id`). +function assertTeachesBareSkillIds(flavor, text, param) { + const failures = []; + const refs = [...new Set(text.match(/superpowers:[a-z0-9-]+/g) || [])]; + if (refs.length === 0) return failures; + if (!text.includes('drop the `superpowers:` prefix')) { + failures.push(`expected ${flavor} bootstrap to tell the model to drop the superpowers: prefix (bootstrap references ${refs.join(', ')})`); + } + if (!text.includes(`\`superpowers:brainstorming\` → \`skill\` with \`${param}: "brainstorming"\``)) { + failures.push(`expected ${flavor} bootstrap to show superpowers:brainstorming loading as \`skill\` with \`${param}: "brainstorming"\``); + } + return failures; +} + // Drive setup() with a mock V2 ctx and fire the captured "context" hook on a // top-level (parentID-less) session. Returns the injected-part count and the // injected bootstrap text ('' when nothing was injected). diff --git a/tests/opencode/test-session-bootstrap.mjs b/tests/opencode/test-session-bootstrap.mjs index 31658d5..67b3118 100644 --- a/tests/opencode/test-session-bootstrap.mjs +++ b/tests/opencode/test-session-bootstrap.mjs @@ -139,6 +139,16 @@ for (const flavor of ['v1', 'v2']) { await unknown.invoke(noID); assert.equal(bootstrapCount(noID), 1); assert.deepEqual(unknown.lookups, []); + + // #2197: a prompt that merely mentions the bootstrap's tag is not the bootstrap. + const mentions = await makeHarness(flavor, (id) => reply(flavor, { id })); + const probe = makeEvent(flavor, `${flavor}-mentions-tag`); + (probe.messages[0].parts ?? probe.messages[0].content)[0].text = + "Is there an 'EXTREMELY_IMPORTANT' block in your context?"; + await mentions.invoke(probe); + assert.equal(bootstrapCount(probe), 1, `${flavor}: prompt mentioning the tag still gets bootstrap`); + await mentions.invoke(probe); + assert.equal(bootstrapCount(probe), 1, `${flavor}: prompt mentioning the tag, repeated event`); } function compactedEvent(sessionID) { diff --git a/tests/pi/test-pi-extension.mjs b/tests/pi/test-pi-extension.mjs index c79f710..65d65e0 100644 --- a/tests/pi/test-pi-extension.mjs +++ b/tests/pi/test-pi-extension.mjs @@ -34,6 +34,14 @@ function firstHandler(handlers, event) { return eventHandlers[0]; } +// Fire an event the way pi does: every registered handler runs, and an event +// the extension does not subscribe to is a no-op. +async function emit(handlers, event, payload) { + for (const handler of handlers.get(event) ?? []) { + await handler({ type: event, ...payload }, {}); + } +} + function textOf(message) { if (typeof message.content === 'string') return message.content; return message.content @@ -55,17 +63,16 @@ test('extension leaves package skill discovery to Pi and registers lifecycle hoo const { handlers } = await loadExtension(); assert.equal((handlers.get('resources_discover') ?? []).length, 0, 'extension must not bypass package skill filters'); - for (const event of ['session_start', 'session_compact', 'context', 'agent_end']) { + for (const event of ['session_start', 'session_compact', 'context']) { assert.equal((handlers.get(event) ?? []).length, 1, `missing ${event} handler`); } assert.equal((handlers.get('session_before_compact') ?? []).length, 0); }); -test('startup context injects the bootstrap as one user message until agent_end', async () => { +test('startup context injects the bootstrap as one user message', async () => { const { handlers } = await loadExtension(); const sessionStart = firstHandler(handlers, 'session_start'); const context = firstHandler(handlers, 'context'); - const agentEnd = firstHandler(handlers, 'agent_end'); await sessionStart({ type: 'session_start', reason: 'startup' }, {}); @@ -86,10 +93,40 @@ test('startup context injects the bootstrap as one user message until agent_end' const alreadyInjected = await context({ type: 'context', messages: result.messages }, {}); assert.equal(alreadyInjected, undefined, 'bootstrap should not duplicate when already present'); +}); + +// pi emits agent_start/agent_end around every user prompt, not once per +// session, and the messages a context handler returns are never written back +// to session history. So every provider request of every prompt needs the +// bootstrap injected again (#2083). +test('every provider request of every prompt in a session carries the bootstrap', async () => { + const { handlers } = await loadExtension(); + const context = firstHandler(handlers, 'context'); + + await emit(handlers, 'session_start', { reason: 'startup' }); - await agentEnd({ type: 'agent_end', messages: [] }, {}); - const afterEnd = await context({ type: 'context', messages: originalMessages }, {}); - assert.equal(afterEnd, undefined, 'startup bootstrap should clear after agent_end'); + const history = []; + const prompts = [ + { text: 'first prompt', providerRequests: 1 }, + { text: 'second prompt with a tool call', providerRequests: 2 }, + { text: 'third prompt', providerRequests: 1 }, + ]; + for (const [promptIndex, prompt] of prompts.entries()) { + history.push({ role: 'user', content: [{ type: 'text', text: prompt.text }], timestamp: promptIndex }); + await emit(handlers, 'agent_start', {}); + for (let request = 1; request <= prompt.providerRequests; request += 1) { + await emit(handlers, 'turn_start', {}); + const result = await context({ type: 'context', messages: structuredClone(history) }, {}); + const label = `prompt ${promptIndex + 1}, provider request ${request}`; + assert.ok(result, `${label}: bootstrap missing`); + assert.equal(result.messages.length, history.length + 1, `${label}: expected exactly one bootstrap message`); + assert.match(textOf(result.messages[0]), /You have superpowers/, `${label}: bootstrap not first`); + history.push({ role: 'assistant', content: [{ type: 'text', text: 'ok' }], timestamp: promptIndex }); + await emit(handlers, 'turn_end', {}); + } + await emit(handlers, 'agent_end', { messages: [] }); + await emit(handlers, 'agent_settled', {}); + } }); test('session_compact injects bootstrap after compaction summaries, not before compaction', async () => { |
