NODEDC_TASKMANAGER_CODEXAPI/README.md

NODE.DC Tasker Codex API

Отдельный модуль NODE.DC для безопасного подключения локальных Codex/AI-агентов к Tasker / Operational Core.

Модуль не является частью Plane fork и не должен становиться backend-расширением Tasker. Его роль — agent gateway: выдача ограниченных agent credentials, проверка прав, MCP/REST-контракт для внешних агентов, аудит и маршрутизация разрешённых операций в Tasker через узкий internal adapter.

Documents

• Architecture
• UX flow
• MCP tools contract
• Tasker API audit
• Threat model
• Implementation plan

Core rule

External Codex instances never receive Plane session cookies, raw Tasker API tokens, database access, or a generic HTTP proxy into Tasker.

All writes go through NODE.DC Agent Gateway, are scoped by agent grants, and are recorded as actions of a dedicated agent identity owned by a human platform user.

Current implementation

• Fastify service with /healthz, /readyz, and capability metadata.
• Postgres migrations for agents, grants, token hashes, pairing codes, audit events, and idempotency keys.
• Internal REST endpoints for agent profile, grant, and token lifecycle.
• Opaque agent tokens are generated once and stored only as SHA-256 hashes.
• Authenticated agent-session endpoint returns effective grants/scopes for future MCP calls.
• Product tool endpoints validate agent token, scopes, and project grants before calling Tasker internal adapter.
• MCP and Tasker write execution are documented but not implemented yet.

Local development

cp .env.example .env
docker compose --env-file .env -f docker-compose.local.yml up -d postgres
npm install
npm run migrate
npm run dev

Useful checks:

npm run check
npm run build
npm run smoke:gateway
curl http://127.0.0.1:4100/readyz
curl http://127.0.0.1:4100/api/v1/meta/capabilities

Create a local test agent:

curl -X POST http://127.0.0.1:4100/api/v1/agents \
  -H 'Content-Type: application/json' \
  -d '{"owner_user_id":"local-user","owner_email":"local@example.test","display_name":"Local Codex"}'

Create a token and inspect effective agent session:

TOKEN=$(curl -sS -X POST http://127.0.0.1:4100/api/v1/agents/<agent-id>/tokens \
  -H 'Content-Type: application/json' \
  -d '{"name":"Local Codex token"}' | jq -r .token)

curl http://127.0.0.1:4100/api/v1/agent-session \
  -H "Authorization: Bearer $TOKEN"

Do not expose these lifecycle endpoints publicly before the Launcher/internal auth layer is added.

Local testing strategy

No fake Tasker storage is embedded into Agent Gateway.

Local verification is split into product layers:

1. npm run smoke:gateway verifies real Agent Gateway persistence, bearer token auth, scope checks, grant checks, and the boundary before Tasker calls.
2. Full localhost e2e starts after Tasker implements /api/internal/nodedc/agent/... adapter. Then the same Gateway tool endpoints call the real local Tasker runtime.
3. External-machine testing uses the same token and endpoint shape against staging HTTPS; no extra protocol or fake environment should be introduced.

Current Tasker internal adapter contract expected by Gateway:

• POST /api/internal/nodedc/agent/projects/resolve
• GET /api/internal/nodedc/agent/projects/:projectId/context
• GET /api/internal/nodedc/agent/issues?project_id=...
• POST /api/internal/nodedc/agent/issues
• PATCH /api/internal/nodedc/agent/issues/:issueId
• POST /api/internal/nodedc/agent/issues/:issueId/move
• POST /api/internal/nodedc/agent/issues/:issueId/comments
• PUT /api/internal/nodedc/agent/issues/:issueId/labels
• PUT /api/internal/nodedc/agent/issues/:issueId/assignees