Domain tool surface (shared registry for PWA agent + MCP)

james commented

2026-06-14 19:52:02 +00:00

Owner

Implement the tool registry that the built-in PWA agent and the MCP server both expose. Read tools for every domain entity. Write tools that return proposed changes (per the policy in the tool-granularity ADR). All scoped per-user at the repository layer.

Scope

Tool registry module that both the PWA agent loop and the MCP endpoint import — single source of truth, no duplication.
Read tools for every domain entity (Profile, Skills, Education, Jobs and their Positions and Contributions, Contracts, Projects, Organizations, People, Notes), shaped per the ADR.
Write tools for the same set, returning a proposed-change object rather than mutating. The proposal carries enough information for the PWA to render a diff and for an MCP client to display a confirmation prompt.
A single "commit" path that applies a previously-proposed change keyed by a server-issued proposal id, expiring after a short window. Both PWA and MCP route through this same commit path; the audit log is populated here.
Per-user scoping enforced at the repository layer. Tools must never accept a user_id parameter; the authenticated user is taken from the request context.
Tools are typed end-to-end with the same validation library used elsewhere in the codebase.
Cross-engine tests: each tool runs against both SQLite and Postgres.

Acceptance criteria

Tool registry exposes the full set per the ADR; every entity has at least its read tools shipped.
Write tools return proposals and never mutate directly; the commit path is the only mutator.
An attempted commit by user B against a proposal issued for user A returns 404 (not 403 — don't leak existence).
Tests run on both DB engines.

Part of epic #47. Depends on the tool-granularity ADR. Each entity's tools depend on that entity's repository layer (work in epics #4 and #5); tools land entity-by-entity as repositories land.

Implement the tool registry that the built-in PWA agent and the MCP server both expose. Read tools for every domain entity. Write tools that return proposed changes (per the policy in the tool-granularity ADR). All scoped per-user at the repository layer. ## Scope - Tool registry module that both the PWA agent loop and the MCP endpoint import — single source of truth, no duplication. - Read tools for every domain entity (Profile, Skills, Education, Jobs and their Positions and Contributions, Contracts, Projects, Organizations, People, Notes), shaped per the ADR. - Write tools for the same set, returning a proposed-change object rather than mutating. The proposal carries enough information for the PWA to render a diff and for an MCP client to display a confirmation prompt. - A single "commit" path that applies a previously-proposed change keyed by a server-issued proposal id, expiring after a short window. Both PWA and MCP route through this same commit path; the audit log is populated here. - Per-user scoping enforced at the repository layer. Tools must never accept a `user_id` parameter; the authenticated user is taken from the request context. - Tools are typed end-to-end with the same validation library used elsewhere in the codebase. - Cross-engine tests: each tool runs against both SQLite and Postgres. ## Acceptance criteria - [ ] Tool registry exposes the full set per the ADR; every entity has at least its read tools shipped. - [ ] Write tools return proposals and never mutate directly; the commit path is the only mutator. - [ ] An attempted commit by user B against a proposal issued for user A returns 404 (not 403 — don't leak existence). - [ ] Tests run on both DB engines. Part of epic #47. Depends on the tool-granularity ADR. Each entity's tools depend on that entity's repository layer (work in epics #4 and #5); tools land entity-by-entity as repositories land.

james added the

area:service

label

2026-06-14 19:52:52 +00:00

james referenced this issue from a commit

2026-06-28 21:06:40 +00:00

feat(api): shared agent domain tool registry, proposals, and commit path

james referenced this issue from a pull request that will close it,

2026-06-28 21:06:58 +00:00

feat(api): shared agent domain tool registry, proposals, and commit path #330

james closed this issue

2026-06-28 21:39:32 +00:00