ARCH - CODEX AGENTS: архитектура Agent Gateway и MCP-контракта
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,174 @@
|
||||
# Implementation Plan
|
||||
|
||||
Last updated: 2026-05-14.
|
||||
|
||||
## Phase 0. Architecture baseline
|
||||
|
||||
Status: current phase.
|
||||
|
||||
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
|
||||
|
||||
Create standalone service with:
|
||||
|
||||
- Dockerfile;
|
||||
- compose for local dev;
|
||||
- health endpoint;
|
||||
- env validation;
|
||||
- database migrations;
|
||||
- agent/token/grant/audit tables;
|
||||
- opaque token hashing;
|
||||
- idempotency-key storage.
|
||||
|
||||
No Tasker writes yet.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user