NODEDC_TASKMANAGER_CODEXAPI/docs/TASKER_API_AUDIT.md

Tasker API Audit

Last updated: 2026-05-14.

Summary

Current Tasker / Plane fork is partially ready for the Codex Agent API use case through existing REST endpoints and NODE.DC structured blocks. It is not ready as a direct external API for agents because it has broad routes, session-oriented permissions, delete/archive endpoints, and no MCP layer.

The correct approach is to add a narrow internal Tasker adapter for Agent Gateway instead of exposing raw Plane API to local Codex.

Existing useful API surface

Issues

Routes exist for issue list/create/update/retrieve:

GET  /api/workspaces/:slug/projects/:project_id/issues/
POST /api/workspaces/:slug/projects/:project_id/issues/
GET  /api/workspaces/:slug/projects/:project_id/issues/:issue_id/
PATCH /api/workspaces/:slug/projects/:project_id/issues/:issue_id/

The same route also supports DELETE, but Agent Gateway must never expose it.

Existing serializers already support:

• name;
• state;
• priority;
• dates;
• labels;
• assignees;
• parent issue;
• description HTML;
• detail_layout.

Validation already checks:

• assignees are active project members with sufficient role;
• labels belong to project;
• state belongs to project;
• parent belongs to workspace/project;
• description HTML is sanitized.

Structured blocks

NODE.DC structured task content lives in:

Issue.detail_layout["nodedc_structured_blocks"]

Known block types:

text
checker

This is the right storage layer for:

• current architecture;
• planned architecture;
• stages;
• checkers;
• implementation notes.

Tasker already computes checker progress from this structure.

Comments

Routes exist:

GET  /api/workspaces/:slug/projects/:project_id/issues/:issue_id/comments/
POST /api/workspaces/:slug/projects/:project_id/issues/:issue_id/comments/
PATCH /api/workspaces/:slug/projects/:project_id/issues/:issue_id/comments/:comment_id/
DELETE /api/workspaces/:slug/projects/:project_id/issues/:issue_id/comments/:comment_id/

Agent Gateway should expose comment creation and possibly own-comment edit later, but not comment deletion.

Labels

Routes exist:

GET  /api/workspaces/:slug/projects/:project_id/issue-labels/
POST /api/workspaces/:slug/projects/:project_id/issue-labels/
PATCH /api/workspaces/:slug/projects/:project_id/issue-labels/:label_id/
DELETE /api/workspaces/:slug/projects/:project_id/issue-labels/:label_id/

MVP should let agents apply existing labels. Creating labels can be added later under an explicit admin scope.

States

Routes exist:

GET /api/workspaces/:slug/projects/:project_id/states/
PATCH /api/workspaces/:slug/projects/:project_id/states/:state_id/

Agent Gateway should allow moving issues to existing states. It should not allow state creation/deletion in MVP.

Project members

Routes exist:

GET  /api/workspaces/:slug/projects/:project_id/members/
POST /api/workspaces/:slug/projects/:project_id/members/
PATCH /api/workspaces/:slug/projects/:project_id/members/:member_id/
DELETE /api/workspaces/:slug/projects/:project_id/members/:member_id/

Current code checks workspace membership and blocks launcher-managed workspace self-management.

Agent Gateway may expose add_existing_project_member only with an explicit scope and only for existing workspace members.

Missing MCP layer

No dedicated MCP server exists in Tasker today. References to MCP are documentation/guideline-oriented, not an operational API server.

Required new layer:

Agent Gateway MCP tools -> Agent Gateway service -> Tasker internal adapter

Tasker should not become the MCP host. Keeping MCP in Agent Gateway preserves standalone Tasker and keeps the external agent surface outside Plane.

Required Tasker adapter additions

Add internal endpoints under a namespace such as:

/api/internal/nodedc/agent/...

These endpoints must use NODEDC_INTERNAL_ACCESS_TOKEN / PLANE_NODEDC_ACCESS_TOKEN style auth and must be callable only from Agent Gateway.

Suggested adapter endpoints:

POST /api/internal/nodedc/agent/context/
POST /api/internal/nodedc/agent/issues/search/
POST /api/internal/nodedc/agent/issues/
PATCH /api/internal/nodedc/agent/issues/:issue_id/
POST /api/internal/nodedc/agent/issues/:issue_id/comments/
POST /api/internal/nodedc/agent/issues/:issue_id/structured-blocks/
POST /api/internal/nodedc/agent/projects/:project_id/members/add-existing/

The adapter should receive normalized Agent Gateway metadata:

agent_id
owner_user_id
owner_email
workspace_slug
project_id
scopes
idempotency_key

The adapter should validate Tasker domain rules and return stable errors rather than leaking raw Plane serializer details.

Why raw Plane API is not enough

Raw Plane API is too broad for external agents:

• it includes delete/archive routes;
• it assumes a session user, not an external agent identity;
• it has more fields than agents should control;
• it does not know Launcher module entitlements;
• it does not have agent idempotency;
• it does not produce agent-specific audit by default;
• it is not MCP-native.

Compatibility note

Tasker must remain standalone-capable. All agent-specific behavior should be disabled when NODE.DC Agent Gateway env vars are absent.