Working document of the
crewbee-v2fork. Status: implemented; maintainer follow-up and validation described below. Port author: Alessandro Muzzi (local fork~/Projects/crewbee-v2, branchfeat/opencode-v2-port).
- Supported hosts: OpenCode V1 1.18.29+ (1.x) and V2 2.2.0+ (2.x). Older V1 loaders do not support the dual default definition; use an older CrewBee release with those hosts. The V2 SDK is pinned to 2.2.0. Do not infer support for all V1/V2 versions from the entrypoint shape.
- The default export provides V1
serverand V2setup. Internal V2 setup functions are not exposed as standalone legacy plugin functions. - Setup/install detects the CLI major version and writes V1
plugintuples or V2pluginsobjects accordingly. Without a detectable CLI, it preserves the existing format (V1 for a new config). V2 can normalize legacy configuration. Key-only migrations count as changes and are persisted; plugin options are preserved. Uninstall removes CrewBee entries without migrating foreign plugin entries. - Doctor and release-intent detection read both formats, including tuple/object package references.
- Each delegation invocation gets its own session facade and abort signal. Foreground admission waits for execution; background execution is launched without awaiting by the engine while its promise observes execution errors. Explicit background cancellation uses the child-session interrupt API.
- V2 model selection persists on a session. A retry without an explicit model selects the host default instead of accidentally reusing the failed model.
- V2 has no session todo API: checkpoint/delegation continuity is preserved, while todo snapshots are explicitly empty.
- Regression tests cover configuration persistence, release detection, retained plugin options, agent/tool projection, foreground completion, background completion/failure/cancellation, concurrent cancellation isolation, model fallback, compaction, and cleanup. These deterministic host tests do not claim live model quality or full Desktop UX validation.
scripts/smoke-opencode-host.mjs <executable> <1|2>verifies real host loading in isolated config/data/cache directories without sending a model request. CI runs it against 1.18.29 and 2.2.0. Both versions also passed locally on Windows during the maintainer follow-up. The packed-package smoke verifies the installed artifact's V1 entry; V2 behavioral coverage uses the deterministic host fixture.
The original contributor's investigation and implementation notes follow as historical context; the support contract above supersedes preliminary recommendations below.
CrewBee cannot be loaded by OpenCode V2. The published package (crewbee@0.1.24) implements
the OpenCode V1 plugin API (entrypoint = V1 plugin function), while V2 requires a default
export object with id + setup(ctx).
The port is feasible: the affected area is limited to src/adapters/opencode/** (5,162
lines including delegation), src/install/** (config key) and src/update/refresh.ts.
No domain logic (Team library, projection, prompt building) has to be rewritten: only the
contract with the host changes.
Estimated risk: medium. The delicate part is delegation (task/subagent), because in V2
the tool is called subagent, the session event has a different shape and the todo API no
longer exists.
| Component | Version | Note |
|---|---|---|
| opencode (installed) | 2.1.3 | /opt/homebrew/Cellar/opencode-v2/2.1.3/bin/opencode (homebrew-core opencode = 2.1.2) |
@opencode/plugin (V2 SDK) |
2.1.3 | inspected for the real types |
@opencode/plugin latest on npm |
2.2.0 | not aligned with the local binary |
@opencode-ai/plugin (V1 SDK) |
1.19.4 latest / 1.15.10 used by CrewBee | V1 line |
crewbee npm latest |
0.1.24 | depends on @opencode-ai/plugin@1.14.48 |
CrewBee upstream main |
3efe39b (2026-07-25) |
package.json → @opencode-ai/plugin@1.15.10 |
| node / npm | 20.20.2 / 10.8.2 | bun not installed (upstream tests use node --test) |
Reference documentation used: https://opencode.ai/v2/docs/build/plugins,
.../build/plugins/migrate-v1, .../build/plugins/server, .../agents, .../tools.
Isolated install in a temporary HOME, crewbee@0.1.24 downloaded from npm, then:
$ opencode plugin add crewbee
Plugin "crewbee" installed and added to .../.config/opencode/opencode.json
$ opencode plugin list
ID VERSION SOURCE
- - crewbee
Server log (role=server):
msg="loading plugin" id=crewbee entrypoint=file://.../crewbee/dist/opencode-plugin.mjs
level=WARN message="failed to load plugin" target=crewbee
cause=PluginModule.LoadError: Plugin must export a default definition with an id and an effect or setup function.
(cause: SchemaError(Expected object at ["default"]))
Consequences: no projected agents (opencode debug agents lists only build, compaction, …),
no task/delegate_status/delegate_cancel tools, no session binding.
V1 counter-proof (same package, opencode-ai@1.19.4): the plugin loads and projects
coding-coordination-leader, coding-executor, coding-codebase-explorer, coding-reviewer, …
⇒ the problem is exclusively the plugin contract, not the CrewBee logic.
Summary with files/lines (references to main @ 3efe39b):
| # | V1 surface | CrewBee usage | File |
|---|---|---|---|
| 1 | PluginInput.client (V1 SDK) |
sessions, providers, log | plugin.ts, logging.ts, delegation/*.ts |
| 2 | PluginInput.directory / .worktree (string) |
project root / delegation state | plugin.ts:38, delegation/store.ts |
| 3 | PluginInput.project |
— | unused |
| 4 | config hook |
agent injection + default_agent |
config-hook.ts:73-123 |
| 5 | tool hook (map) |
task, delegate_status, delegate_cancel |
plugin.ts:50-55, delegation/tools.ts |
| 6 | event hook |
background delegation completion | event-hook.ts |
| 7 | chat.message hook |
session↔team binding | chat-message-hook.ts |
| 8 | tool.definition hook |
no-op | tool-hooks.ts:76-78 |
| 9 | tool.execute.before hook |
alias → config key of subagent_type |
tool-hooks.ts:80-99 |
| 10 | tool.execute.after hook |
task output normalization | tool-hooks.ts:101-125 |
| 11 | experimental.chat.system.transform hook |
injects CrewBee runtime context | system-transform-hook.ts |
| 12 | experimental.session.compacting hook |
todo snapshot + continuity context | compaction-hook.ts |
| 13 | client.session.create/prompt/promptAsync/messages/abort/todo |
delegation engine | delegation/tools.ts, output.ts, continuity.ts |
| 14 | client.config.providers() |
model availability filter | model-availability.ts:30 |
| 15 | client.app.log({body}) |
structured logging | logging.ts:14 |
| 16 | tool() helper (zod) + string ToolResult |
tool definition | delegation/tools.ts:25-33 |
| 17 | V1 agent format (prompt, permission map, disable, tools) |
agent projection | projection.ts:254-344 |
| 18 | plugin: [...] config key (V1 key) |
installation | install/opencode-config-file.ts:126 |
| 19 | Plugin type = function (input, options) => Hooks |
entrypoint | plugin.ts:19-86 |
| V1 | V2 |
|---|---|
export const P: Plugin = async (ctx) => ({ ...hooks }) |
export default Plugin.define({ id: "crewbee", async setup(ctx) { ... } }) |
ctx = PluginInput |
ctx = Context (domain by domain) |
options (2nd argument) |
ctx.options |
dispose() returned |
return () => {...} from setup |
event hook |
ctx.event.subscribe({ types, signal }) → AsyncIterable |
| — | id required (storage scoping, diagnostics) |
| V1 | V2 |
|---|---|
ctx.client.app.log({body}) |
❌ does not exist → console.log/warn (server window) |
ctx.directory |
ctx.location.directory |
ctx.worktree (string) |
❌ not a string → use ctx.location.directory |
ctx.project |
ctx.location.project |
ctx.client.config.providers() |
ctx.provider.list() / ctx.model.list() |
ctx.client.session.* |
ctx.session.* (different signatures) |
| V1 | V2 | Notes |
|---|---|---|
config (mutating cfg.agent, cfg.default_agent) |
ctx.agent.transform(editor) |
editor.add/update/remove/list/get, editor.default(id) |
tool map |
ctx.tool.transform(editor) |
editor.add({name, description, input: JSONSchema, execute}) |
chat.message |
ctx.session.hook("prompt", cb) |
event: {sessionID, messageID, prompt:{text,files,agents,skills}, metadata, delivery} |
tool.execute.before |
ctx.tool.hook("execute.before", cb) |
event: {tool, sessionID, agent, messageID, id, input} — input is mutable |
tool.execute.after |
ctx.tool.hook("execute.after", cb) |
event: {..., status, result} — result = Tool.Result (content, metadata) |
experimental.chat.system.transform |
ctx.session.hook("context", cb) |
event.system = SystemPart[] (not string[]) → push {type:"text", text} |
experimental.session.compacting |
ctx.session.hook("compaction", cb) |
event extends SessionContext (system, messages, options, tools) |
event |
ctx.event.subscribe({types, signal}) |
V2 events: session.idle, session.status, session.deleted, session.execution.failed, session.compaction.ended |
| V1 | V2 |
|---|---|
tool({description, args: zodShape, execute}) |
editor.add({name, description, input: JSONSchema, execute}) |
zod args |
JSON Schema input |
returns string |
returns { content: string | Content[], output?, metadata? } |
ctx.metadata({title, metadata}) |
context.progress({...}) + result.metadata |
ctx.abort (AbortSignal) |
context.signal |
ctx.ask(...) |
ctx.permission.assert(...) (not used by CrewBee) |
delegation tool name: task |
V2 native tool: subagent (permission action subagent) |
V1 (client.session.*) |
V2 (ctx.session.*) |
|---|---|
create({path:{id}, body:{parentID,title}}) |
create({ parentID, title }) |
prompt({path:{id}, body:{agent,model,parts}}) |
prompt({ sessionID, text }) + switchAgent({sessionID, agent}) + switchModel({sessionID, model}) |
promptAsync (background) |
❌ does not exist → prompt() is already non-blocking (inbox admission); wait({sessionID}) waits |
messages({path:{id}}) → [{info, parts}] |
context({sessionID}) → SessionMessageInfo[] (union: type:"assistant", content:[{type:"text",text}]) |
abort({path:{id}}) |
interrupt({sessionID, resume:false}) |
todo({path:{id}}) |
❌ does not exist in V2 → degradation (see §7.4) |
V1 (projection.ts:254-274) |
V2 |
|---|---|
name |
id (+ display name) |
prompt |
system |
permission: {edit:{allow:[…]}, bash:"ask"} |
permissions: [{action, resource, effect}] (last rule wins) |
model: "provider/model" |
model: "provider/model#variant" or {providerID, model, variant} |
temperature / top_p |
request.body is not yet sent (2.1.3) → see §7.5 |
mode: "primary"|"subagent" |
mode: "primary"|"subagent"|"all" |
disable: true |
disabled: true |
tools: {…} |
❌ does not exist → tool filtering via permissions (deny per action) |
hidden |
hidden ✔ |
options.crewbee (ownership marker) |
request.body? no → use metadata/internal marker (see §7.6) |
V2 permission actions (from docs/agents): shell, edit, subagent, read, glob, grep,
webfetch, websearch, skill, question, external_directory, doom_loop, *.
| V1 | V2 |
|---|---|
session.idle |
session.idle ✔ |
session.status |
session.status ✔ |
session.deleted |
session.deleted ✔ |
session.error |
❌ → session.execution.failed |
session.compacted |
❌ → session.compaction.ended |
dependencies:@opencode-ai/plugin@1.15.10→@opencode/plugin@2.1.3(aligned with the 2.1.3 binary).exports: kept{".": "./dist/opencode-plugin.mjs", "./server": …}✔ (V2 accepts././server).scripts/build-opencode-plugin.mjs: unchanged (esbuild bundlessrc/adapters/opencode/plugin.ts). Verify that the bundle no longer contains residual imports from@opencode-ai/plugin(theimport typedeclarations disappear, butzodremains necessary for schemas → in V2 we will use pure JSON Schema for tools).types:dist/src/adapters/opencode/plugin.d.ts→ ok.
New structure:
import { Plugin } from "@opencode/plugin";
export default Plugin.define({
id: "crewbee",
async setup(ctx) {
// 1. auto-repair config file (ctx.location.directory instead of ctx.worktree)
// 2. load + validate TeamLibrary
// 3. bootstrap (availableModels from ctx.model.list())
// 4. ctx.agent.transform(...) → project agents + default agent
// 5. ctx.tool.transform(...) → register task/subagent + delegate_status + delegate_cancel
// 6. ctx.session.hook("prompt") → session binding
// 7. ctx.session.hook("context")→ runtime context in the system prompt
// 8. ctx.session.hook("compaction") → continuity
// 9. ctx.tool.hook("execute.before"/"execute.after") → alias/result
// 10. ctx.event.subscribe() → background delegation completion
return () => controller.abort(); // cleanup
},
});Decision: a single V2 entrypoint file + a legacy V1 adapter (plugin.v1.ts) that
exports the current implementation, so OpenCode 1.x compatibility can be kept in the same
package (dual shape: V2 default + V1 server, as suggested by the
"Support V1 and V2 from one package" guide). To decide with the user: keep V1 or cut V1.
- Remove the
confighook and the merge logic overcfg.agent(config-merge.tsremains only for collision/ownership logic, no longer for mutating the config). - New:
ctx.agent.transform((editor) => { for (const agent of projected) editor.add(toV2Agent(agent)); editor.default(defaultKey) }). editor.update(id, ...)to update already-present agents (idempotency on reload).- Attention: transforms are replayable and synchronous → load the data (model registry, Team library)
before registering and capture it in the closure; to reload:
ctx.agent.reload().
createOpenCodeAgentDefinition()→ newcreateV2AgentDefinition(agent)producing:{ id, name, description, mode, hidden, model, system, permissions, color?, steps? }.prompt→system(same text produced bycreateOpenCodeAgentPrompt).model: string"provider/model#variant"(same content as today).- Ownership marker: V2
Agent.Infohas nooptions⇒ use therequest.bodyfield? no. → use a free field not allowed by the schema ⇒ decide: keep the marker in an in-memoryMapin the plugin (ownership = "agent created by CrewBee" can be deduced from thecoding-*prefix / from the fact that it was registered by this plugin) and usectx.agent.list()for the check.
Mechanical conversion:
{edit: {allow:["*.ts"], deny:[".env"]}}→[{action:"edit", resource:"*.ts", effect:"allow"}, {action:"edit", resource:".env", effect:"deny"}]{bash:"ask"}→[{action:"shell", resource:"*", effect:"ask"}]- V1 action-only (
doom_loop,question,todowrite,webfetch,websearch) → V2 actions (doom_loop,question,webfetch,websearch;todowritedoes not exist in V2 → map toskill? no: drop it). task(V1) →subagent(V2), withresource= the allowed CrewBee member agent id.write/patch/multiedit→edit;lsp_diagnostics→ n/a in V2 (remove);delegate_task→subagent.
- V2 tool definition:
inputas JSON Schema (no zod). - Tool name: register
subagent(overriding the V2 builtin) while also keepingtaskas a deprecated alias, or onlytask? To decide: I recommendsubagent(consistent with the V2 native tool), accepting bothagentandsubagent_typeas parameters. execute.before: rewriteevent.input.subagent_type/event.input.agent(V2inputis mutable).execute.after: the result is aTool.Result; normalizeresult.content(string) andresult.metadata.ctx.metadata({title})→context.progress({...})andresult.metadata.ctx.abort→context.signal.- Delegation semantics (V1 → V2):
- foreground:
session.create({parentID,title})→session.switchAgent({sessionID, agent: configKey})→session.switchModel({sessionID, model})→session.prompt({sessionID, text: envelope})→session.wait({sessionID})→session.context({sessionID})to extract the assistant text. - background: same thing without
wait(V2promptadmits and returns) + state tracking viasession.idle/session.execution.failedevents. session.abort→session.interrupt({sessionID, resume:false}).- text extraction: adapt
delegation/output.tsto the newSessionMessageInfoformat (type:"assistant",content:[{type:"text",text}]); the anchor (message index) must be recomputed because the message count changes shape. - "model not found" fallback handling: in V2 the error arrives as
SessionError/ exception from the prompt → same pattern (retry withoutmodel).
- foreground:
- V1 received
{sessionID, agent, model}; the V2prompthook gives{sessionID, messageID, prompt, delivery}. - The problem: the
prompthook does not expose the selected agent nor the model ⇒ the agent must be read fromctx.session.get({sessionID})(the session hasagentandmodel). Verify during implementation whetherSession.Infoexposesagent(V2 yes:agentandmodelinSessionInfo). - More reliable alternative: use the
session.agent.selected(V2) event for the binding, andctx.session.hook("prompt")only as a fallback ⇒ recommended.
output.system.push(string)→event.system.push({type:"text", text: string}).- Apply only to the "primary" flow (the
contexthook runs for the agent loop; for compaction/title use separate hooks) — verifyevent.kind/agentto avoid polluting auxiliary requests.
output.context.push(...)does not exist in V2 →event.system.push({type:"text", text: continuityContext}).captureTodoSnapshotusesclient.session.todo(nonexistent in V2) → degrade (§7.4).
- Replace V1 event names with V2 ones (§5.7).
session.error→session.execution.failed;session.compacted→session.compaction.ended.- Payload: V2 events have
{type, data}(notproperties) → adaptresolveSessionID. - Loop
for await (const event of ctx.event.subscribe({types:[...], signal}))with anAbortControlleraborted in the cleanup returned bysetup.
ctx.client.app.log({body})does not exist in V2 →console.log/console.warnwith a[crewbee]prefix. Verify that the output ends up in~/.local/share/opencode/log/opencode.log(the server captures plugin stdout/stderr in-process) → mandatory empirical verification.
client.config.providers()→ctx.provider.list()and/orctx.model.list(). In V2Provider.Infohasmodelsas a Map (not an object) → adapt the extraction ofproviderID/modelID(attention:Model.Info.idvsmodelID).
captureTodoSnapshot→ no todo API in V2 ⇒ empty snapshot + note. Alternative: read thetodowritetool state from the session transcript (ctx.session.context({sessionID})→ messages withtodowritetool parts) — implementable if the transcript retains the tool input (verify).
- Uses
ctxonly for logging ⇒ adapt the signature to V2Contextor accept an injected logger. - The rest (npm registry, lock, state file) is host-independent ✔.
- Writes
config.plugin = [...](V1 key). In V2 the key isplugins. - Handle the migration: read
plugin(legacy, still accepted by the V2 schema as a deprecated field) andplugins; write intoplugins; keeppluginintact if it contains other plugins. removeCrewBeePluginEntriesmust clean both keys.- Entry format: V2 accepts
"crewbee","crewbee@1.2.3","@scope/pkg", absolute paths andfile://. → for the local fork use an absolute path to the installed package (e.g."plugins": ["/Users/…/Projects/crewbee-v2"]) or publish to npm.
findCrewBeePluginEntriesmust readplugins(and legacyplugin).- Add to the doctor a check of the OpenCode version (
opencode --version→ major 2 ⇒ V2 plugin) and of the loaded SDK version.
- The tools CrewBee registers are
task/delegate_status/delegate_cancel⇒ in V2 the first becomessubagent(taskaccepted as alias). Update the registry and tests.
tests/opencode/* and tests/install/* assume the V1 contract (cfg.agent shapes, permission map,
tool.execute.before(input, output), chat.message). List:
tests/opencode/agent-ordering.test.mjs— agent shape: adapt to V2 expectations.tests/opencode/delegate-task.test.mjs—createDelegateToolswith a fake V1 client → adapt.tests/opencode/plugin-task-alias.test.mjs—subagent_typealias → new format.tests/opencode/model-availability.test.mjs—client.config.providers()→ctx.model.list().tests/opencode/partial-team-load.test.mjstests/install/plugin-entry.test.mjs—pluginkey →plugins.tests/install/config-writer.test.mjs,doctor.test.mjs,install-user.test.mjs,uninstall.test.mjs.
New tests to add:
tests/opencode/v2-agent-transform.test.mjs—Plugin.define+setupwith a fake ctx ⇒ verify thatctx.agent.transformis called with the correct V2 definitions.tests/opencode/v2-tool-registration.test.mjs— verifyeditor.addwith JSON Schema andexecute.tests/opencode/v2-hook-mapping.test.mjs— hook mapping (prompt/context/compaction/tool).
V2 calls the native tool subagent with permission action subagent. CrewBee redefines its
behavior (delegation to Team members). Proposal: register subagent (overriding the
builtin) accepting agent | subagent_type, description, prompt, background, task_id;
keep task as a secondary alias for compatibility with existing prompts.
Alternative: do not override the builtin and delegate to the native subagent, but CrewBee's
control over alias/permissions/nesting would be lost.
In V1 chat.message provided agent and model. In V2 the prompt hook does not.
Proposal: listen to the session.agent.selected (+ session.model.selected) event for the
binding, and use ctx.session.get({sessionID}) as a fallback.
V1 session.prompt was blocking (waited for the reply). In V2 prompt admits and returns immediately.
Proposal: foreground = prompt + session.wait({sessionID}); background = prompt without wait.
No todo API in V2. Proposal: empty snapshot with an explicit note in the continuity context;
optionally derive the todos from the transcript (todowrite tool parts).
In V2 request.body is not yet sent with model requests (2.1.3, official warning).
Proposal: do not set per-agent temperature; if essential, use the hook
ctx.session.hook("context", e => e.options.temperature = ...) filtered by event.agent.
V2 Agent.Info has no options.crewbee. Proposal: keep an in-memory Set<string> with the
configKeys projected by CrewBee and use ctx.agent.list() for the "do not mutate other people's agents" check.
V2 has no per-agent tools. Proposal: translate requestedTools into permission rules
(deny on the corresponding action) + a prompt listing the allowed tools.
Keep the V1 implementation in the same package (default = V2, server = V1) so OpenCode 1.x
users are not broken, or release V2 only (simpler, but breaks the 1.x line).
To decide with the user.
V2 installs npm plugins in ~/.cache/opencode/npm/<pkg>@<ver>/<ts>/node_modules/<pkg> and
enables them with the plugins key in the global config.
Options for the fork:
- Local path (immediate, no publish):
"plugins": ["/Users/alessandro.muzzi/Projects/crewbee-v2"]in~/.config/opencode/opencode.json. V2 accepts local directories withpackage.json+exports. - Private npm / personal registry (
npm login+ publish under your own scope): the cleanest path for distribution; requiresnpm publishand a name likecrewbee-v2. - Local tarball installed into
~/.cache/opencode/npm/…by hand: fragile.
To decide with the user. For development → option 1; for real use → option 2.
- Unit —
npm test(the repo usesnode --test;buildrequirestsc): extend the existing tests to the new V2 modules. - Typecheck —
npm run typecheckwith@opencode/plugin@2.1.3. - Simulator —
npm run simulate:opencodeandsimulate:compact: adapt them (they simulate the V1 runtime). - Real integration on opencode 2.1.3 (automated script in
scripts/):- isolated
HOME+opencode service set port <port>(avoids conflicts with the real service) opencode plugin add <path>/ config withpluginsopencode plugin list→ must show activeopencode debug agents→ CrewBee agents (coding-*) must appearopencode debug config→pluginskey present- server log: no
failed to load plugin; presence of[crewbee]logs - functional test: start a session,
taska Team member, verify the result and thedelegate_statusstate.
- isolated
- V1 non-regression (if compatibility is kept): same test with
opencode-ai@1.19.4.
- Upstream:
https://github.com/CrewBeeLab/CrewBee(MIT). - Personal fork: created on the user's GitHub account (no
ghCLI was present at the time nor a valid personal GitHub SSH key:ssh -T git@github.com→ Permission denied). → requiredgh auth loginor a PAT, or a fork created manually in the browser. - Recommended workflow: branch
feat/opencode-v2-porton the fork → PR towards upstream (or keep private if preferred). - Versioning:
0.2.0-v2.0.0or1.0.0? Proposal: 0.2.0 with thepluginskey and V2 support, deprecating V1.
- F1 — Preparation: GitHub fork (credentials), working copy
~/Projects/crewbee-v2, branchfeat/opencode-v2-port✔ (done) - F2 — Update
package.json:@opencode/plugin@2.1.3, remove@opencode-ai/plugin; alignexports - F3 — New
src/adapters/opencode/plugin-v2.tswithPlugin.define({id:"crewbee", setup}) - F4 —
agent-transform.ts:ctx.agent.transform+editor.default(replacesconfig-hook.ts) - F5 —
projection.ts: new V2 agent formatter (system,permissions,model,disabled) - F6 —
permission-mapper.ts: map V1 → V2permissionsarray (task→subagent) - F7 —
delegation/tools.ts: V2 tools (subagent/task+delegate_status+delegate_cancel), JSON Schema,result.content - F8 —
tool-hooks.ts:execute.before(mutable input) /execute.after(Tool.Result) - F9 —
chat-message-hook.ts→ binding viasession.agent.selected+session.getfallback - F10 —
system-transform-hook.ts→ctx.session.hook("context")withSystemPart - F11 —
compaction-hook.ts→ctx.session.hook("compaction")+ todo degradation - F12 —
event-hook.ts→ctx.event.subscribe()+ V2 event renames - F13 —
logging.ts→ console with[crewbee]prefix; verify flush into the server log - F14 —
model-availability.ts→ctx.model.list()/ctx.provider.list() - F15 —
update/refresh.ts→ V2Contextsignature - F16 —
install/opencode-config-file.ts→pluginskey + migration fromplugin - F17 —
install/doctor.ts/uninstall.ts→ new key + OpenCode version check - F18 — Update
src/runtime/registries/plugin-tools.ts(task → subagent) - F19 — Update existing tests + add V2 tests
- F20 — Update simulators (
simulators/opencode-*.mjs) to the V2 runtime - F21 —
npm run typecheck && npm test && npm run build - F22 — End-to-end verification script on real opencode 2.1.3 (isolated HOME, dedicated port)
- F23 — Documentation:
docs/guide/installation.md(V2), README,docs/developer/release.md - F24 — Publish (npm) or local setup with path; verify
opencode plugin list→ active
| Risk | Impact | Mitigation |
|---|---|---|
subagent tool not overridable |
CrewBee delegation unusable | verify in F7 with a real test; otherwise do not override and use the native subagent |
Non-blocking prompt in V2 |
foreground delegation returns immediately | session.wait({sessionID}) |
temperature not applicable |
less deterministic agents | use the context hook (options.temperature) |
| Ownership marker lost | overwriting other people's agents | in-memory Set + editor.list() |
todowrite tool absent in V2 |
poorer continuity context | empty snapshot + note; optional transcript parsing |
| Divergence from upstream | merge difficulty | atomic commits per area, changelog in the PR |
| Rollback | — | the fork does not touch main; uninstall = remove the entry from plugins + opencode plugin remove |
- GitHub fork: create the fork on the user's account? Which username? Requires
gh auth login(interactive) or a PAT, or the fork is created manually and I push to the remote? - V1 support: keep the dual implementation (V1 + V2) in the same package, or cut V1?
(Recommendation: keep V1 for a few releases, with
default= V2 andserver= V1.) - Package name:
crewbee(local fork) orcrewbee-v2/@scope/crewbee? - Distribution: publish to npm (public or private scope) vs local path only?
- Tool: override the builtin
subagent(recommended) or register onlytaskas a new tool? - Per-agent temperature: give up (recommended, given the V2 warning) or implement via the
contexthook?
- Local branch:
feat/opencode-v2-port(committed on explicit user request only). - Build:
npm run buildOK; bundledist/opencode-plugin.mjs1.9MB, only Node builtins as external dependencies. - Tests:
npm test→ 107/107 pass. - Empirical verification on OpenCode 2.1.3 (isolated HOME): the plugin loads,
ctx.agent.transformprojects the 8 CrewBee agents (primary leader visible, host agentsbuild/plan/general/explorehidden+demoted to subagent),ctx.tool.transformregisterssubagent(builtin override) +task(alias) +delegate_status+delegate_cancel,ctx.session.hook("prompt"/"context"/"compaction")registered,event.subscribemanually filtered. - Local install (dev): use the form
{ "package": "file:/Users/alessandro.muzzi/Projects/crewbee-v2" }in thepluginsarray of~/.config/opencode/opencode.json. The loader installs the package into~/.cache/opencode/npm/file:/...and resolves thedist/opencode-plugin.mjsentrypoint. - Production install (after the fork):
opencode plugin add github:<user>/crewbee-v2(Git package specifier). - Dependencies:
@opencode/plugin@2.1.3and@opencode-ai/plugin@1.15.10as devDeps (types only);zod@^4.1.8+yamlas runtime deps.