feat(core): control-plane action registry for host-UI dispatch

[vreshch]

Summary

Adds @agentage/core/control — a transport-agnostic action registry so host UIs (desktop, web dashboard, future MCP clients) can dispatch control-plane actions into the local env. First three proof-of-shape actions: cli:update, project:addFromOrigin, agent:install.

Motivation: today there's no unified way for a UI to ask "what actions can I invoke on this machine?" and dispatch them with validation, auth, idempotency, and streaming progress. The CLI daemon, web backend, and desktop IPC each have ad-hoc route handlers. This module gives all of them one shape to wire up.

Design

• Transport-agnostic core. Registry yields InvokeEvent (accepted → progress* → result | error). REST, WS, Electron IPC, and MCP tools/call are thin adapters over this stream.
• Typed definitions. action<I, O, P>({ manifest, validateInput?, execute }) — execute is an AsyncGenerator<P, O> so progress events and final result share one control flow.
• Closed error union. ActionErrorCode = UNKNOWN_ACTION | UNKNOWN_VERSION | INVALID_INPUT | UNAUTHORIZED | DEPRECATED | DUPLICATE_INVOCATION | EXECUTION_FAILED | CANCELED, each with a retryable flag.
• Capabilities. Flat string set with * wildcard; transport layer maps session → caps.
• Idempotency. Keyed on action@version#idempotencyKey; replays emit DUPLICATE_INVOCATION.
• Versioning. Multiple versions of the same action can coexist; get(name) picks the highest, get(name, version) is explicit. deprecatedSince on the manifest short-circuits invoke.
• Cancellation. Callers pass an AbortSignal; the invoke loop checks before each yield and returns CANCELED.

Sample actions take an injected ShellExec so they're pure and testable — the host wires in core's shell adapter (or a stub).

Changes

• packages/core/src/control/
  • types.ts — ActionDefinition, ActionManifest, ActionContext, InvokeRequest/Event, ActionRegistry
  • action.ts — identity builder (matches the tool() / mcp() pattern)
  • registry.ts — createRegistry() with list/get/invoke + idempotency map
  • errors.ts — ActionError + isActionError
  • actions/{cli-update,project-add-from-origin,agent-install}.ts — three reference actions
  • actions/types.ts — ShellExec DI interface
  • Tests for registry (auth, validation, versioning, idempotency, cancel, deprecated) and each sample action with stubbed shell
• packages/core/src/index.ts — re-exports the control module from the top-level barrel

Next steps (not in this PR)

1. cli/daemon: instantiate registry, register actions, add POST /api/actions/:name route + WS handler forwarding the InvokeEvent stream.
2. desktop: IPC channel action:invoke that proxies to daemon (or runs its own registry for local-only actions).
3. MCP façade: tools/list ← registry.list(), tools/call ← registry.invoke().

Test plan

• npm run verify — type-check + lint + format + 145 tests + build, all green
• Wire cli/daemon route layer against the registry (follow-up PR)
• Dogfood cli:update end-to-end from desktop against a local daemon (follow-up)

[github-actions]

🎉 PR Validation ✅ PASSED

Commit: 6dc9f35b816421fd018ca73da7c22484f5dfa1e7
Branch: feature/control-plane

Checks:

• ✅ Release guard (no version/changelog changes)
• ✅ Dependencies installed
• ✅ Type check passed
• ✅ Linting passed
• ✅ Format check passed
• ✅ Tests + coverage passed
• ✅ Build successful

Ready to merge! ✨

---

🔗 View workflow run
⏰ Generated at: 2026-04-17T22:57:56.035Z