feat(sdk,surface): plugin registry — flows add helper-<name> (#305) by kjgbot · Pull Request #336 · AgentWorkforce/flows

kjgbot · 2026-09-11T18:45:02Z

Closes #305. Plugin registry per SURFACE.md §3. Codex agent spec-J-plugin on finn-mini; head 72eb9a9.

🤖 Generated with Claude Code

Note

Medium Risk
Introduces a new authored execution and journal effect path plus npm-driven project mutation; kernel is unchanged but plugin preflight and effect lowering affect run/check behavior for flows using helpers.

Overview
Adds a minimal plugin registry slice so projects can install community helpers with flows add helper-<name> (npm @flows/helper-*), record them in flows.json plugins, and optionally pick up flows-plugin.d.ts for Ctx augmentation.

Install & contract: cli/add.ts runs npm install, validates flows-plugin.json (verbs, mandatory preflight, JSON Schema args), probes credentials and HTTP(S) HEAD targets, and refuses undeclared @flows/helper-* packages in node_modules. Only lowersTo: "effect" is supported; triggers, gates, and other primitives fail with plugin_unsupported.

Check & run: TypeScript flows check loads declared plugins via pluginSearchStart; plugin refusal kinds join the closed preflight taxonomy. The authored executor Object.assigns manifest-driven namespaces onto f and lowers calls through runPluginEffect: a short-lived journal worker, agent effect confirm/complete, lease renewal, and a 30s dispatch deadline with child-run cancel on timeout.

Docs & tests: SURFACE §3 documents the slice; evidence file captures focused vitest/kernel runs. Offline testdata/plugins fixtures back add/load/effect tests.

^{Reviewed by Cursor Bugbot for commit 5656647. Bugbot is set up for automated code reviews on this repo. Configure here.}

coderabbitai · 2026-09-11T18:45:08Z

Important

🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 4e67ebd2-f8bb-4e9a-bdfb-278d42faa9f6

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

cursor

Stale Bugbot comment from a previous run.

cursor

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 512e31e. Configure here.}

cursor · 2026-09-11T19:15:50Z

+      }
+      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
+      return receipt.output;
+    }), deadline]);


Deadline race abandons plugin execution

High Severity

The 30s dispatch timer starts at the beginning of runPluginEffect and is raced against budget.execute. When a flow has a budget, that wait includes the serialized queue behind other budgeted steps, so a concurrent f.agent/f.llm/f.run longer than 30s can fail the plugin with a spurious dispatch timeout. Winning the race also abandons the still-running budget.execute promise, which later rejects without a handler after run.start settles.

^{Reviewed by Cursor Bugbot for commit 512e31e. Configure here.}

cursor · 2026-09-11T19:15:50Z

+    }
+    const plugin = readPlugin(join(root, 'node_modules', packageName), packageName);
+    await probePlugin(plugin);
+    if (!existsSync(join(plugin.directory, 'src/index.js'))) throw new PluginError('plugin_manifest_invalid', 'Plugin requires src/index.js.');


Failed add blocks later flow runs

Medium Severity

flows add runs npm install before manifest validation and credential/server probes, and it does not roll back on failure. loadPlugins then treats any leftover @flows/helper-* in node_modules as plugin_unlisted. A refused add (missing credentials, bad manifest, unreachable server) leaves every later TypeScript flows check and flows run failing until the package is removed by hand.

Additional Locations (1)

packages/sdk/src/plugin-loader.ts#L51-L55

^{Reviewed by Cursor Bugbot for commit 512e31e. Configure here.}

kjgbot · 2026-09-11T19:52:00Z

maintainability lens — PASS

Maintainability review — PR #336 (plugin registry slice)

Concerns

1. flows.json plugin validation is duplicated three ways. packages/sdk/src/cli/add.ts:14-16, packages/sdk/src/plugin-loader.ts:44-48, and packages/sdk/src/cli/check.ts:201-205 each reimplement the "plugins is an optional array of strings" rule with slightly different error messages and error classes (PluginError vs CheckFailure). Add a field to flows.json.plugins in six months and three sites need matched edits; only the loader's copy has a chance of surfacing the drift. Consolidate through one validator.

2. Fall-through after worker_error in authored-plugin-effect.ts:98-107 is either dead defense or a silent success bug. If diagnostic !== undefined, the code calls readCompletedStepOutput, expecting it to throw step_failed. If it doesn't throw, control falls to the second read and the failure is returned as success. Nothing in the code says this "cannot happen" — a future reader will refactor one branch or the other and change behavior. Either assert the invariant or restructure so the two paths are visibly exclusive.

3. loadPlugins only walks node_modules/@flows/ (plugin-loader.ts:53). The scope is baked in and the manifest merely requires helper-<name>. A plugin installed under any other scope is silently invisible — no refusal, no warning. If a follow-up ever supports third-party scopes, the "unlisted plugin" check will misfire. Comment the constraint or refuse on installation.

4. Brittle npm error classification. cli/add.ts:22 distinguishes plugin_unknown from plugin_install_failed via /E404|404 Not Found/. This is grep-on-vendor-string; if npm changes its error text, we silently downgrade to plugin_install_failed and lose the taxonomy that PLUGIN_FAILURE_KINDS promises.

5. Daemon-startup retry loop in the live test (plugin-loader.test.ts:70-74) is timing-sensitive: 100 attempts × 20ms = 2s ceiling on a 15s test timeout, with the daemon binary path derived from env-dependent guesses. If CI is slow enough for the daemon to take >2s to accept connections, the test fails without pointing at the real cause.

Notes

plugin-loader.ts and cli/add.ts are written as dense one-liners with multi-clause conditionals; readable, but a stranger will spend real time parsing them. Line-breaking for clarity would not hurt.
The 30-second dispatch deadline in authored-plugin-effect.ts:71 is hardcoded and undocumented; worth a const DISPATCH_DEADLINE_MS = 30_000 with a short comment.
pathPart (line 148) is fine but its purpose ("stable surface path segment") isn't stated.

No blockers.

REVIEW_PASSED

kjgbot · 2026-09-11T19:52:02Z

history lens — PASS

Blockers: none under the HISTORY lens. I inspected the supplied diff, recent commit history, repository instructions, RFC decisions, operational records, and PR commit messages.

Notes

The plugin worker preserves the lease-renewal fix recorded in DRIVE-LOG’s September 9 account of fix(sdk): renew agent leases while CLI steps execute #249. packages/sdk/src/authored-plugin-effect.ts:63–74 wraps provider execution in withWorkerLease. Its dispatch deadline is cleared when work begins (:52–55), avoiding a fixed 30-second limit on provider execution.
RFC decision drive: WP-13: Fix SDK test failures from sandbox environment gaps #13 explicitly permits surface plugins targeting existing primitives. packages/sdk/src/authored-plugin-effect.ts:115–118 creates an existing agent step; packages/sdk/src/plugin-manifest.ts:71–75 refuses unsupported targets. This adds no kernel primitive.
The runtime uses the journal effect protocol, supplies the kernel-issued idempotency key, and propagates journal errors (packages/sdk/src/authored-plugin-effect.ts:66–88). I found no demonstrated reintroduction of the historical record-before-perform implementation.
Commit messages 499e2ecc and 512e31e3 describe installation/contracts and declaration/setup enforcement, respectively. Neither claims passing acceptance tests, complete recovery, or production readiness.

Concerns, not blockers

docs/SURFACE.md:509–513 explicitly defers bundling/pinning, declarative preflight, and interrupted-effect recovery. The PR describes a minimal slice and points to these follow-ups. Those limitations do not establish regression of previously completed behavior.
The evidence needs updating for the expanded tests: docs/evidence/spec-J-plugin-registry.md:18–32 records five loader tests and omits the new worker-test file from its focused command, while packages/sdk/tests/plugin-loader.test.ts:26–46 adds declaration cases. Treat that capture as historical evidence, not proof of the final diff. The document explicitly acknowledges the unsuccessful full SDK run (docs/evidence/spec-J-plugin-registry.md:95–99).

This verdict is a history review; I did not rerun tests.

REVIEW_PASSED

kjgbot · 2026-09-11T19:52:03Z

structure lens — MISSING

kjgbot · 2026-09-11T19:52:04Z

🎯 review-swarm: FAILED (M:pass H:pass S:missing)

Lens transcripts posted as sibling comments above.

Session-Id: 01a09168-b666-7ae2-9f29-0ea10e48b894 Session-Id: 01a091dd-02a2-7820-8006-4430d2a5c76e Session-Id: efeda5df-9b7c-48d4-b2ce-957f5bef0a82

Session-Id: 01a091dd-02a2-7820-8006-4430d2a5c76e Session-Id: efeda5df-9b7c-48d4-b2ce-957f5bef0a82

@flows/helper-* packages installed in node_modules but absent from flows.json plugins now emit plugin_unlisted (plugin-loader.ts). The existing PREFLIGHT_FAILURE_KINDS walker did not have a scenario for this refusal, so PR#336's linux-x64-artifact failed on set parity. Adds a scoped fixture creating an unlisted helper directory and asserts the loader refuses it. Session-Id: efeda5df-9b7c-48d4-b2ce-957f5bef0a82

cursor Bot reviewed Sep 11, 2026

View reviewed changes

Comment thread packages/sdk/src/plugin-loader.ts

Comment thread packages/sdk/src/authored-plugin-effect.ts

miyaontherelay force-pushed the feat/spec-J-plugin-registry branch from 72eb9a9 to 512e31e Compare September 11, 2026 19:10

cursor Bot reviewed Sep 11, 2026

View reviewed changes

miyaontherelay and others added 3 commits September 11, 2026 22:19

feat(sdk,surface): plugin registry — flows add + plugin contract (#305)

41906cd

Session-Id: 01a09168-b666-7ae2-9f29-0ea10e48b894 Session-Id: 01a091dd-02a2-7820-8006-4430d2a5c76e Session-Id: efeda5df-9b7c-48d4-b2ce-957f5bef0a82

fix(sdk): require declared plugins and bound worker initialization

f4cfc54

Session-Id: 01a091dd-02a2-7820-8006-4430d2a5c76e Session-Id: efeda5df-9b7c-48d4-b2ce-957f5bef0a82

kjgbot force-pushed the feat/spec-J-plugin-registry branch from 512e31e to 5656647 Compare September 11, 2026 20:24

kjgbot merged commit 5ab55e0 into main Sep 11, 2026
8 of 10 checks passed

kjgbot deleted the feat/spec-J-plugin-registry branch September 11, 2026 20:36

Navigation Menu

feat(sdk,surface): plugin registry — flows add helper-<name> (#305) - #336

feat(sdk,surface): plugin registry — flows add helper-<name> (#305)#336
kjgbot merged 3 commits into
mainfrom
feat/spec-J-plugin-registry

kjgbot commented Sep 11, 2026 •

edited by cursor Bot

Loading

Uh oh!

coderabbitai Bot commented Sep 11, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Sep 11, 2026

Uh oh!

cursor Bot Sep 11, 2026

Uh oh!

kjgbot commented Sep 11, 2026

Uh oh!

kjgbot commented Sep 11, 2026

Uh oh!

kjgbot commented Sep 11, 2026

Uh oh!

kjgbot commented Sep 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kjgbot commented Sep 11, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Sep 11, 2026

Choose a reason for hiding this comment

Deadline race abandons plugin execution

Uh oh!

cursor Bot Sep 11, 2026

Choose a reason for hiding this comment

Failed add blocks later flow runs

Uh oh!

kjgbot commented Sep 11, 2026

maintainability lens — PASS

Maintainability review — PR #336 (plugin registry slice)

Concerns

Notes

Uh oh!

kjgbot commented Sep 11, 2026

history lens — PASS

Uh oh!

kjgbot commented Sep 11, 2026

structure lens — MISSING

Uh oh!

kjgbot commented Sep 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kjgbot commented Sep 11, 2026 •

edited by cursor Bot

Loading

coderabbitai Bot commented Sep 11, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading