19 KiB
Global Agent plugin bridge (work in progress)
This stack starts from integration/plugin-ask-routing-acceptance at
2433cf0130d1c3274c56c39e5765349c2945de01. The parent confirmed this dependency;
its native Ask acceptance and integrated CI are still pending. This branch does
not modify the frozen candidate, #3986, #3998, or #4002.
The user approved a global conversation independent of a terminal or workspace, with a plugin-provided chat UI and selectable existing Agent backends. Core owns Agent execution, history, target authority, native approvals, credentials and audit. Global is not unrestricted inventory access or a background service.
Stage 1: dispatch authority
electron/plugins/agent/delegatedScope.cjs is a host-only authority. It does not
register plugin APIs, start an Agent or implement an orchestration loop.
issue(context, hostSnapshot)authenticates with the existing source binding. Host snapshots contain backend identity/revision, target kind/id/owner/revision, synchronous current-owner checks, and a supported capability subset. The public result contains only an opaque handle and expiry. Plugin parameters must never be used ashostSnapshot.begin(handle, context)returns an internal turn ticket and AbortController.dispatch(ticket, context, resolvedAction, execute)runs the common host policy adapter once, checks current target revisions after any approval wait, invokes the real dispatcher, and rejects late results.resolvedActionmust come from canonical host capability/argument resolution, not an unchecked plugin object.assertTurnguards outgoing events.finishandstopinvalidate the exact ticket. Runtime/plugin release, lock/hide invalidation and shutdown abort work.- Handles expire in five minutes. There are at most eight per runtime owner and 64 overall, with at most 32 explicit resources per scope. Expiry never silently refreshes a selection or revives an old turn.
The focused tests use the actual PluginAISourceBinding with synthetic host
registries, two terminal owners representing different workspaces, controlled
time, and deferred approval/native completion. They cover source/runtime/target
substitution, focus changes, revision changes across approval, policy denial,
Stop, release, lock, late completion and bounds. They do not yet prove actual MCP
or AgentRuntime dispatch; those remain integration gates.
Initial execution failed before test discovery because the new worktree has no
dependencies (ajv/dist/2020 missing). Running with the existing local worktree's
read-only CommonJS dependency path passes all 12 cases. No provider, CLI Agent,
paid credentials or GUI was used.
The adjacent run then passed 49 tests and failed one installed-entrypoint test
because ESM could not resolve @netcatty/plugin-cli from the new worktree. Standard
npm ci --ignore-scripts and build:plugin-runtime-deps repaired the setup. These
failures are setup evidence, not failed-before product regressions.
The core conversation repository stores the existing global AISession document
shape in a host-only directory, namespaced by the hash of source/private-owner.
Native session identity and compaction remain private. Commits serialize a cloned
snapshot, revalidate provenance before atomic rename, and retain previous history
when that check fails. Files use mode 0600 and no-follow reads. The repository
does not register a plugin storage API or change the source database schema.
The canonical schema and SDK now declare the proposed session interface and permissions. Runtime methods and the supported-feature advertisement are not yet registered. This stage must not be described as an installable working Agent bridge. Focused scope/history/wire and permission-copy tests pass 20 cases; contract/SDK/CLI tests pass 91. Focused lint and generated drift checks pass.
Independent stage-1 correction
The independent review of exact 056164157f34ea779ed6cf51199909082345eca4
confirmed two helper defects before any runtime acceptance claim: source failure
during the initial owner check rejected late work without aborting the active
native signal; Stop could acquire a replacement turn after awaiting identity.
Both reproduce against that exact helper using the real PluginAISourceBinding:
the focused before run is 13 passed / 2 failed. The correction revokes the captured
scope when its own host-authenticated identity fails, and captures the intended
turn before Stop's first await. A foreign runtime cannot use a failed lookup to
revoke another caller's scope. Focused after: 15 passed / 0 failed. The complete
foundation/permission group passes 23 on Node 24.19.0 and Node 22.23.3; focused lint
and diff checks pass. Logs: /tmp/netcatty-global-agent-review-before.log,
/tmp/netcatty-global-agent-review-after.log,
/tmp/netcatty-global-agent-review-node22.log.
The first CI run at 0561641, test 40459522087, Linux job 122040565759, failed
after an explicit runner shutdown and operation cancellation, with no assertion
failure in its log and no complete repository test total. Package workflow
40459521971 and both Windows jobs passed. The parent authorized one job rerun;
it was requested once, producing Linux job 122048349748, still running at this
checkpoint. Original runner failure remains historical evidence. Neither that
rerun nor the helper fix establishes runtime, native or independent-review
acceptance; the correction still needs reviewer recheck.
Follow-up: cancellation is not source revocation
The independent recheck confirmed the first two repairs and found a remaining
Stop race: an aborted Stop(A) RPC could enter the generic owner-failure cleanup
after B had started, revoking B's scope. The same failure was reproduced at both
owner-validation await paths using the actual source binding. Exact-18377 source
with the new 18-case scope suite yields 16 passed / 2 failed; evidence is retained
in /tmp/netcatty-global-agent-stop-rpc-exact183-before.log.
The minimal follow-up distinguishes this request's abort/deadline from verified
owner or resource failure, rethrows the access failure, and leaves the existing
turn-capture rule intact. Cancellation of Stop(A) cannot revoke B. A separate
regression confirms that a verified source mismatch still aborts native work
even when the RPC is concurrently cancelled. Foreign caller protections remain.
The full foundation/permission group passes 26 tests on Node 22.23.3 and Node
24.19.0; focused lint and diff checks pass. Logs:
/tmp/netcatty-global-agent-stop-rpc-final.log and
/tmp/netcatty-global-agent-stop-rpc-node22.log. Independent recheck is pending.
The authorized original-head Linux rerun 122048349748 ended cancelled, with an
operation-cancelled log and no assertion failure. No second rerun was requested.
At 18377, test workflow 40462595842, Linux job 122050816182, also received an
explicit runner shutdown; PluginLogSettings.test.tsx was SIGKILLed immediately
afterward. That interrupted stage reports 34 passed / 1 failed, not a complete
repository total or an assertion failure. Both Windows jobs passed. No blind
rerun of that job was made. Package workflow 40462595846 was still running when
checked. These records are not substituted for exact-head green CI.
Planned public contract and adapters
Independent transport correction
The exact ea619555 internal-handler reproductions fail all four targeted cases:
both no-session and empty-selection environment reads serialize global tool hints;
stale chat-wide cleanup cancels replacement B; and caller-supplied builtin chat
text can downgrade cancellation of a main-owned delegated request. The outer
sender gate still accepts only the current trusted main window. These are trusted
application lifecycle defects, not arbitrary plugin IPC exposure or installed
runtime exploit evidence.
Cancellation now resolves ownership from the main request map, rejects a conflicting caller chat, checks the recorded sender and current turn lease, and cancels only that native request. The legacy chat-wide cleanup IPC is unavailable for reserved delegated conversations; main-owned exact-turn release remains the cleanup authority. All delegated environment return paths omit global tool hints.
An additional Node 22 regression is independently reproduced: inline arrow
properties at the beginning of module.exports prevent namespace detection of
existing exports such as init, breaking the real Catty attachment harness.
Identifier exports preserve that existing interface. Correction tests pass 94 on
Node 22.23.3, including the actual Catty attachment consumer; focused lint passes.
Failed-before logs are /tmp/netcatty-global-agent-transport-review-four-failed-before.log
and /tmp/netcatty-global-agent-ea619-namespace-before.log. The transport PR's
review checkpoint remains ea619555 until the parent integrates/rechecks this
separate correction. No native/backend/full-CI acceptance is implied.
Stage 2A: trusted native dispatch boundary
The independent bounded recheck of foundation ba4d3fc passed all 20 reviewer
cases. This resolves its reported helper findings; it does not establish full CI,
runtime, backend or native acceptance.
The additive transport slice gives managed subprocesses a separate per-turn MCP credential, permanently binds their TCP connection to that turn, filters their tool list, and routes actual tool execution through the source-bound host policy adapter. Catty's trusted-app IPC enters the same dispatcher. Branded approval contexts skip the legacy Agent approval only after that host adapter grants the action; process-global permission mode is unchanged. Selected environment reads return the scoped session metadata without querying global tunnel inventory.
Managed Claude is restricted to its existing MCP mode with builtin tools disabled, strict MCP configuration and no inherited settings sources. The main native entry rejects unverified backends and Skills mode for reserved delegated conversations. Each model stream and native SDK request carries a main-owned turn tag; releasing that lease aborts its HTTP/native work. Old credentials, cancellation requests and disposers cannot acquire or cancel the next turn.
The focused boundary suite passes 116 cases, including an actual local TCP/main handler with synthetic workers, plus two new actual-HTTP/renderer-transport lease tests. These are deterministic transport tests, not real model inference or authenticated Claude service/CLI acceptance. Public runtime registration, core conversation integration and the custom chat sample are still separate work in progress; this transport slice alone is not a usable plugin Agent feature.
At exact ba4d3fc, package CI 40464058910 passed; test workflow 40464058908
is red. Linux job 122055141575 failed a real assertion in
PluginManagementDialog.interaction.test.tsx:71: the external view handoff had
not run when asserted. That stage reports 34 passed / 1 failed; earlier runtime
and contract groups passed 720 and 5. Both Windows jobs passed. No blind rerun was
requested. This unresolved assertion must not be classified as runner shutdown.
The wider initial local transport run reports 697 passed / 10 failed / 3 skipped.
All ten failures are Cursor discovery expectations after npm ci --ignore-scripts
left SQLite's native binding absent, making the bundled Cursor SDK import fail.
The standard rebuild first failed using unwritable default caches; rebuilding
with task-local npm/node-gyp cache paths succeeded. The failed totals are retained
in /tmp/netcatty-global-agent-transport-expanded.log; the after-setup run is
recorded separately. No GUI or provider credentials were used.
After the dependency repair, the expanded transport/native-handler/preload/SDK
suite passes 709 tests, 0 failures, 3 skips. Log:
/tmp/netcatty-global-agent-transport-expanded-after-setup.log. Focused lint passes.
The proposed feature is ai.agent-sessions, with ai.agent.use for conversation
operations and ai.agent.actions for actual Agent tool actions. Permission mode
comes from the existing source-bound Allow/Ask/Deny engine. These are additive
names, separate from the existing tools-disabled ai.invoke broker.
The API will provide backend listing, explicit target selection, owned chat listing/opening, sending, bounded event reads, history, Stop and close. Backend references are opaque host-issued configuration revisions. Conversation references identify only histories owned by the calling source/private-owner; runtime handles are separate and cannot substitute builtin chat IDs or native SDK resume IDs. Messages cannot supply permissionMode, CLI/env/MCP configuration or owner fields.
Core will reuse AISession, AgentRuntime, both existing turn drivers, event and
compaction handling, SDK resume identity validation, and stopAgentTurn. The first
eligible backends are Catty and configured Claude Code in MCP mode. Other backend
entries must return explicit unsupported/unconfigured status until their native
tool and approval boundaries are verified. Codex SDK's current unrestricted native
configuration must not be treated as eligible merely because it has a driver.
The terminal worker already exposes a suitable main-owned resource binding:
getPluginSessionBinding(sessionId, ownerWebContentsId) returns worker epoch and
session generation. Use this for dispatch-time targets; do not use menu IDs,
focused tab, display labels, or a renderer-provided session ID as authority.
The MCP dispatcher and Catty direct execution route need the same delegated session guard. A delegated call must not update process-global permission mode, or request both an Agent approval and a plugin approval for the same action. Policy changes, disable/restart/source replacement, lock and host disconnection must cancel scoped native work and invalidate outgoing event tickets. Existing Agent trace and plugin audit/log facilities will receive redacted correlation metadata, not credentials, provider diagnostics or full unreviewed tool payloads.
Remaining acceptance gates
Separate runtime/sample implementation checkpoint
The runtime continuation wires the nine context.agent methods through the
registered default host, dedicated trusted-app preload/IPC and PluginAgentHost
mounted in AppView. It reuses the existing AgentRuntime, Catty/external turn
drivers, core AISession documents, compaction, model/provider transport, native
cancellation, selected worker epoch/generation checks and permission/audit engine.
No source database, Vault history or builtin conversation ownership change is
included. Plugin input cannot supply internal session IDs, source/owner, CLI/env,
MCP configuration or permission mode.
The first eligible profiles are configured Catty and Claude MCP. Other known backends report unsupported/unavailable. Claude has builtin tools disabled, strict MCP, no inherited settings sources, at most 12 native turns and no native session persistence/resume; its existing driver rehydrates from core-owned history. This code path has handler/driver/MCP fixture coverage. Authenticated Claude service/native CLI acceptance has not run and must not be inferred from mocks.
Actions use one source-bound Allow / Ask / Deny decision path. Actions Deny permits model-only conversation with an empty tool profile; Agent-use Deny blocks host dispatch. Explicit target choice is independent of focus/workspace. Worker lifecycle changes cancel a pending chooser and revoke stale target leases; source/runtime/policy/lock invalidation aborts native work and rejects late events. Core history is source/private-owner namespaced and read/write protected through the plugin filesystem broker. A user-granted terminal command still has that terminal's native OS authority; this is not an OS filesystem sandbox.
Bounds include six sends/source/minute, eight scopes/runtime and 64 total, 256 retained turn handles, 32 tool actions and 32 Catty HTTP calls per turn, 12 Catty iterations, a 120-second turn lifetime, 60-second model HTTP/15-second streaming idle deadlines, 128 KiB HTTP responses, 256 KiB projected turn output and 4 KiB text events. Usage is projected; no hard total native-Claude token budget is claimed. Handles expire after five minutes without silent target reselection.
The installable examples/plugins/global-agent sample provides backend/owned
conversation choice, explicit targets, history, Send/Stop and existing host theme
tokens. Its deterministic local provider fixture performs no model inference,
paid API calls, real terminal execution or request/body/header logging. The
installed Node/JSDOM pipeline test uses actual Catty orchestration, configured
HTTP admission and main dispatch to synthetic workers. It proves one selected-B
tool cycle, streamed result, Stop and revoked-handle denial; it is not native
browser sandbox or real model acceptance. A failed-before JSON-snapshot regression
is retained at /tmp/netcatty-global-agent-snapshot-failed-before.log.
Recorded validation: plugin runtime 732 passed/0 failed/1 skipped; affected group 105 passed/0 failed/3 skipped; examples 6 passed/0 failed/1 skipped; repaired setup paths 284 passed. Build, codegen and lint passed before the final review corrections. Typecheck is still red: 774 diagnostics on both unchanged foundation and this continuation, with equal per-file/error-code counts; it is not a clean typecheck. The repaired Node 22 full run reports 15,354 passed/9 failed/46 skipped. Eight are missing xterm install patches, subsequently applied; the ninth is the transport CJS namespace regression fixed separately. Exact final-head validation is pending.
The earlier pre-setup full run remains pending after its timed-out unpatched FIDO
test worker kept a socket open. Reading /proc/319596/cwd to confirm that worker's
identity was denied (EACCES); no signal was sent and no alternate route attempted.
Its log is retained without invented final totals. pack:dir first failed using
the unwritable default npm cache; a standard task-local cache repaired that step,
then native rebuild failed because installed @electron/rebuild hardcodes
/home/agent/.electron-gyp outside writable roots. No home override or sandbox
bypass was attempted. Native screenshots/video and independent runtime review
remain parent-owned gates; nothing is merged or released.
Final focused Node 22 validation passes 205 cases, including all nine failure
paths from the broad run after the documented setup/correction changes. The
installed pipeline additionally proves disable/re-enable, owned history reopening
and a fresh model-only turn under Actions Deny. conversationRef is durable;
each open receives a fresh private runtime actor so revoked privacy/native/tool
state cannot be revived. A typed, host-only close control clears its owned
runtime caches after that actor settles. Build, lint (seven existing warnings)
and generated drift checks pass. Typecheck still has the same 774 per-file/code
diagnostic counts as the unchanged foundation. Logs:
/tmp/netcatty-global-agent-lifecycle-final-tests.log,
/tmp/netcatty-global-agent-lifecycle-final-build.log, and
/tmp/netcatty-global-agent-lifecycle-final-typecheck.log.
The native recipe and reproducible package hash are in
global-agent-qa.md. Remaining gates are independent
transport/runtime review, CI on the final integrated head, parent-scheduled native
screenshots/video, genuine Claude compatibility acceptance with separately
approved access, and native packaging on a machine with supported writable
rebuild caches. The initial full-run pending worker and previous red totals above
remain recorded. No GUI ownership, merge or release is granted to this executor.