# Architecture: NODE.DC Tasker Codex API Last updated: 2026-05-14. ## Goal Give selected NODE.DC users a controlled way to connect their local Codex or another AI coding agent to Tasker so the agent can maintain project work items according to NODE.DC task-card rules. The agent can create and update cards, move them through states, write structured task documentation, update checkers, add comments, assign existing workspace users to project cards when permitted, and apply labels. It cannot delete cards, delete projects, manage workspace settings, bypass project grants, or call arbitrary Tasker endpoints. ## Product boundary This module is a standalone service: ```text Launcher / Hub owns platform entitlement: can this user/client use Codex agents? Tasker / Operational Core owns workspaces, projects, issues, labels, states, members, comments Agent Gateway owns agents, tokens, scopes, grants, MCP tools, audit, rate limits ``` The service is deployed as its own Docker container and has its own repository and database. It may call Launcher and Tasker through internal APIs, but it does not read or write either database directly. ## Runtime shape ```text Local Codex -> MCP over HTTPS / stdio connector -> Agent Gateway public endpoint -> scope and grant checks -> Tasker internal adapter -> Tasker domain models ``` ```text User UI -> Launcher entitlement -> Tasker workspace feature settings -> Agent Gateway agent/token management ``` ## Components ### Launcher integration Launcher decides whether a user can use the module at all. Required Launcher concepts: - service: `operational-core` - module entitlement: `codex_agents` - scope owner: client/user/access matrix - open contour support - enterprise contour support Launcher should not create low-level Tasker cards or tokens. It only projects entitlement and global lifecycle state. ### Tasker integration Tasker shows the feature in `Workspace settings -> Features` only when: - the current user has Tasker access; - Launcher access check says the user has `codex_agents`; - the workspace policy allows this workspace to host agents. Tasker remains the owner of issues, states, labels, project members, comments, and structured blocks. ### Agent Gateway Agent Gateway owns: - agent profiles; - pairing codes; - opaque access tokens; - token hashes; - grants; - scopes; - audit events; - idempotency keys; - rate limits; - MCP tools exposed to local Codex. It should not execute user code and should not run Codex itself. Agent lifecycle management is not public. Tasker/Launcher-facing management calls use `NODEDC_AGENT_GATEWAY_INTERNAL_TOKEN`, while external Codex calls use only the opaque agent token issued for one agent. The owner-scoped internal routes verify that the requested agent belongs to the requested `owner_user_id`. ### Tasker internal adapter The adapter is a narrow Tasker API layer for Agent Gateway. It exists because the current Plane REST API is broad and includes operations the agent must not receive directly. The adapter should expose intent-level operations: - list allowed workspaces/projects; - read project states, labels, members; - search/list issues; - create issue; - patch allowed issue fields; - append comment; - update NODE.DC structured blocks; - add existing workspace member to project when explicitly allowed; - publish audit/realtime events. It must reject delete, archive, workspace settings, project deletion, invite creation, arbitrary attachments, and arbitrary path proxying. ## Data model Initial Agent Gateway entities: ```text agent id owner_user_id owner_email display_name avatar_url status: active | disabled | revoked created_at updated_at agent_token id agent_id token_hash name status: active | revoked | expired expires_at last_used_at created_at agent_grant id agent_id workspace_slug project_id (empty string internally means workspace-level grant) scopes[] mode: voluntary | reporting created_by_user_id created_at updated_at pairing_code id agent_id code_hash status: active | used | expired | revoked expires_at created_at used_at agent_audit_event id agent_id event_type actor_user_id metadata created_at idempotency_key key agent_id request_hash response_body created_at expires_at ``` ## Actor model Writes should be visible as agent actions, not anonymous platform automation. Recommended Tasker-side identity: ```text display_name: Codex Agent: email: agent+@agents.nodedc.local is_bot: true owner_user_id: ``` For audit and UI, every write must preserve both: - `agent_id`; - `owner_user_id`. If Tasker cannot yet represent owned bot users cleanly, the adapter can initially use a system actor and store the agent metadata in audit payloads, but this should be treated as a migration step, not the final model. ## Capability model Allowed initial scopes: ```text workspace:read project:read project:member:add_existing issue:read issue:create issue:update issue:move issue:comment issue:label issue:assign issue:structured_blocks:write ``` Explicitly denied for MVP: ```text issue:delete issue:archive comment:delete label:delete state:create state:delete project:create project:delete workspace:settings workspace:member:invite workspace:member:remove raw_tasker_api ``` Deleting or archiving a card remains a human-only operation. ## Two operating modes ### Voluntary mode The user creates an agent and gives its token to their local Codex. Codex updates Tasker when the user asks it to. This mode is user-owned and best for personal development workflow. ### Reporting mode The enterprise/project admin requires agent reporting for a project. The developer still runs local Codex, but the expected workflow is: - start work session; - update active issue/checker; - append implementation notes; - finish work session. This mode is policy-visible but cannot be fully enforced if Codex runs entirely on the developer machine outside a managed wrapper. The system can enforce token scope and show stale/missing reports, but it cannot force an arbitrary local agent to report unless the organization distributes a managed Codex config or wrapper. ## Deployment Initial local target: ```text agents.local.nodedc -> Agent Gateway ``` Production-like domains should follow platform conventions: ```text agents.nodedc.ru or agents. ``` The service should support: - local `.env`; - staging `.env.staging`; - production secret store; - Docker image build; - health endpoint; - preflight script validating URLs/secrets.