Files
Netcatty/docs/plugin-platform/global-agent-qa.md
T

4.3 KiB

Global Agent continuation: bounded QA recipe

This is a separate increment after the plugin platform foundation. The transport review checkpoint is #4012 at ea619555; its isolated correction is 63f0572e0. The runtime continuation carries the correction through an ordinary feature-branch merge. It is not merged to main or accepted for release.

Reproduce the installable sample

From the exact runtime head reported in the handoff:

npm ci
npm run build:plugin-runtime-deps
node examples/plugins/global-agent/build.mjs
node packages/plugin-cli/dist/cli.js pack examples/plugins/global-agent/.package --out /tmp/netcatty-global-agent.ncpkg
sha256sum /tmp/netcatty-global-agent.ncpkg

The reproducible sample SHA-256 is 0c13d89cb80965db978a42f1d6e84e9cf23d7289bfa432a14f04b7f3a2651b70. Two independent package builds matched. Build scripts and tests are excluded from the six-file installed package.

Native fixture acceptance (parent-scheduled GUI only)

  1. Use an isolated synthetic profile, no real Notes, hosts, histories or keys. Start node scripts/plugin-global-agent-provider-fixture.mjs --port 9218. It performs no inference or outbound request and logs no bodies/headers.
  2. Through normal host settings, configure an OpenAI-compatible Chat Completions provider at http://127.0.0.1:9218/v1, model global-agent-fixture, with the fixture-only literal FIXTURE_ONLY_API_MARKER. Do not use real credentials, paid services, allowlist edits, debugger injection or the builtin AI sidebar.
  3. Install the .ncpkg in Settings → Plugins and open its contributed Global Agent Chat view. Verify light/dark/accent updates using existing theme tokens.
  4. Choose Catty. Choose no targets, or only owned synthetic terminal fixtures, then Open conversation. The fixture's default tool is get_environment; it never requests a terminal command. Record Send → streamed result/usage and GET /fixture/status counters. This proves a deterministic pipeline, not real model inference.
  5. Send fixture:wait, wait for output, press Stop. Verify aborted count rises once and no late text appears. Capture screenshot/video with fixture labels.
  6. Exercise Actions Ask using the existing in-app policy dialog: approve and deny the scoped environment tool separately. Actions Deny permits model-only chat with no tools. Agent-use Deny prevents dispatch. A policy change revokes existing handles; reselect/reopen explicitly before another Send.
  7. Close/reopen and disable/re-enable only this synthetic plugin. Reselect its targets and reopen its owned conversation. History should survive, while the private per-open actor ID is fresh. At five-minute expiry, the sample asks for explicit reselection and keeps the draft, without resending or renewing scope.
  8. Revoke/disable or lock while streaming and verify cleanup/no late events. Disconnect/re-own a selected synthetic worker during selection and a turn; stale selections must fail instead of binding a replacement connection.

Do not activate a configured real Claude backend in this fixture recipe. Claude MCP's code/handler boundary is covered with synthetic tests; authenticated service and genuine CLI acceptance remain unverified and require separately approved access. Other backends are explicitly unsupported/unavailable. No background service, blanket OS/Vault access, merge or release is implied.

Evidence and limits

  • Installed Catty path uses actual AgentRuntime, driver, main provider admission, source policy and worker dispatcher, with JSDOM/in-process plugin transport and synthetic workers. It proves selected B dispatch, stream, Stop, revocation and history after runtime restart. This is not a native BrowserWindow sandbox test.
  • Main/core tests cover source/session/resource substitution, scope expiry, approval waits, worker lifecycle, cancellation, late completion, stable source budgets, source-isolated history and no key serialization. Filesystem API reads cannot access the core history root. Explicitly granted terminal commands still have that terminal's native OS authority.
  • No GUI ran in this executor. Native screenshots/video and independent runtime review remain parent-owned gates. The exact-head CI result must be reported separately from focused local evidence.