184 lines
5.5 KiB
Markdown
184 lines
5.5 KiB
Markdown
# Implementation Plan
|
|
|
|
Last updated: 2026-05-14.
|
|
|
|
## Phase 0. Architecture baseline
|
|
|
|
Status: done in `97d98a7`.
|
|
|
|
Deliverables:
|
|
|
|
- architecture document;
|
|
- UX flow;
|
|
- Tasker API audit;
|
|
- MCP tools contract;
|
|
- threat model;
|
|
- implementation plan.
|
|
|
|
Exit criteria:
|
|
|
|
- agreed capability model;
|
|
- agreed no-delete MVP boundary;
|
|
- agreed Launcher/Tasker/Gateway ownership split.
|
|
|
|
## Phase 1. Agent Gateway skeleton
|
|
|
|
Status: done in `e95cb3a`, `112522c`, `14c5f49`, `9f40207`, and the MCP transport slice. Initial service, migrations, persistence endpoints, token hashing, bearer-token session auth, product tool endpoints, local Postgres compose, product-like Gateway container startup, and Gateway smoke checks are implemented.
|
|
|
|
Create standalone service with:
|
|
|
|
- Dockerfile;
|
|
- compose for local dev;
|
|
- container entrypoint that runs migrations before service startup;
|
|
- health endpoint;
|
|
- env validation;
|
|
- database migrations;
|
|
- agent/token/grant/audit tables;
|
|
- opaque token hashing;
|
|
- idempotency-key storage.
|
|
|
|
Tasker writes are available through the narrow internal adapter; Gateway still must not call raw Plane routes.
|
|
|
|
## Phase 2. Launcher entitlement projection
|
|
|
|
Launcher changes:
|
|
|
|
- add Operational Core module entitlement `codex_agents`;
|
|
- open contour Operational Core dropdown becomes modal;
|
|
- enterprise access modal gets `Operational Core modules`;
|
|
- access check exposes whether user can use Codex agents.
|
|
|
|
Acceptance:
|
|
|
|
- root/admin can enable/disable Codex agents per user/client;
|
|
- blocked user loses entitlement;
|
|
- audit records entitlement changes.
|
|
|
|
## Phase 3. Tasker feature UI
|
|
|
|
Tasker changes:
|
|
|
|
- `Workspace settings -> Features` shows Codex agents when entitlement exists;
|
|
- reusable NODE.DC round toggle/checker component is extracted if needed;
|
|
- feature card opens agent management UI;
|
|
- create/revoke agent calls Agent Gateway;
|
|
- setup instruction panel displays pairing flow.
|
|
|
|
Acceptance:
|
|
|
|
- no entitlement means no feature card;
|
|
- entitlement means feature card appears;
|
|
- revoked agent disappears or becomes disabled;
|
|
- design follows NODE.DC glass/checker canon.
|
|
|
|
## Phase 4. Tasker internal adapter
|
|
|
|
Tasker changes:
|
|
|
|
- internal `/api/internal/nodedc/agent/...` namespace;
|
|
- token auth using NODE.DC internal token;
|
|
- project/state/label/member context endpoint;
|
|
- issue create/update/move/comment endpoints;
|
|
- structured block update endpoint;
|
|
- existing workspace member add-to-project endpoint;
|
|
- delete/archive rejection.
|
|
|
|
Acceptance:
|
|
|
|
- adapter works without exposing raw Plane API;
|
|
- adapter rejects ungranted project;
|
|
- adapter rejects delete/archive;
|
|
- adapter validates labels/states/assignees.
|
|
|
|
Status: initial product slice done in Tasker commit `2ae353c`. Implemented project resolution/context, issue search/create/update/move/comment/label/assign, agent bot actor metadata, and internal token auth. `add_existing_project_member` remains planned behind the explicit `project:member:add_existing` scope.
|
|
|
|
## Phase 5. MCP server
|
|
|
|
Agent Gateway changes:
|
|
|
|
- MCP endpoint;
|
|
- tool schemas from `docs/MCP_TOOLS_CONTRACT.md`;
|
|
- token auth;
|
|
- scope checks per tool;
|
|
- idempotency per write;
|
|
- audit per call;
|
|
- generated instruction pack.
|
|
|
|
Acceptance:
|
|
|
|
- local Codex can list projects;
|
|
- local Codex can create a card;
|
|
- local Codex can update structured blocks;
|
|
- local Codex can move card state;
|
|
- local Codex cannot delete/archive.
|
|
|
|
Status: initial product slice implemented. `/mcp` supports JSON-RPC `initialize`, `ping`, `tools/list`, and `tools/call`. REST product endpoints and MCP tools share the same runtime, scope checks, grant checks, idempotency handling, audit events, and Tasker adapter calls. `/api/v1/agent-session/setup` returns the MCP config template and generated AGENTS.md instruction pack. `npm run smoke:mcp:e2e` verifies real local Tasker writes and idempotent replay.
|
|
|
|
Owner lifecycle API is now split from public agent traffic. Management routes require `NODEDC_AGENT_GATEWAY_INTERNAL_TOKEN`, and Tasker UI should use `/api/internal/v1/owners/:ownerUserId/agents...` through a backend proxy. The owner routes verify that the requested agent belongs to the owner before returning grants, tokens, setup packets, profile updates, or revoke actions.
|
|
|
|
## Phase 6. Agent identity
|
|
|
|
Tasker/Gateway integration:
|
|
|
|
- create or map dedicated agent bot identity;
|
|
- display owner user and agent name;
|
|
- write audit metadata;
|
|
- preserve standalone Tasker behavior when gateway is disabled.
|
|
|
|
Acceptance:
|
|
|
|
- Tasker history shows agent-originated writes;
|
|
- owner can revoke agent;
|
|
- blocked owner disables agent.
|
|
|
|
## Phase 7. Reporting mode
|
|
|
|
Add enterprise-oriented work-session tools:
|
|
|
|
- start work session;
|
|
- update active card;
|
|
- finish work session;
|
|
- stale report indicators;
|
|
- last activity panel.
|
|
|
|
Acceptance:
|
|
|
|
- admin can see connected/stale agents;
|
|
- voluntary mode still works;
|
|
- reporting mode does not pretend to enforce unmanaged local Codex.
|
|
|
|
## Phase 8. Security acceptance
|
|
|
|
Checklist:
|
|
|
|
- token revoke immediate;
|
|
- blocked/annulled owner disables token;
|
|
- project scope escape denied;
|
|
- raw Tasker API inaccessible;
|
|
- delete/archive denied;
|
|
- duplicate idempotency key returns same result;
|
|
- audit written for every write;
|
|
- rate limit enforced;
|
|
- secrets absent from generated files.
|
|
|
|
## MVP cut
|
|
|
|
MVP includes:
|
|
|
|
- Launcher entitlement;
|
|
- Tasker feature UI;
|
|
- Agent Gateway token/grant/audit;
|
|
- MCP tools for read/create/update/move/comment/label/assign/structured blocks;
|
|
- no deletion;
|
|
- no arbitrary proxy;
|
|
- no hosted Codex execution.
|
|
|
|
MVP excludes:
|
|
|
|
- hosted agent runner;
|
|
- workspace invites;
|
|
- project creation;
|
|
- deletion/archive;
|
|
- billing;
|
|
- mandatory reporting enforcement for unmanaged local Codex.
|