ARCH - CODEX AGENTS: архитектура Agent Gateway и MCP-контракта
This commit is contained in:
DCCONSTRUCTIONS
commit
97d98a7bcb
|
|
@ -0,0 +1,20 @@
|
|||
# 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](docs/ARCHITECTURE.md)
|
||||
- [UX flow](docs/UX_FLOW.md)
|
||||
- [MCP tools contract](docs/MCP_TOOLS_CONTRACT.md)
|
||||
- [Tasker API audit](docs/TASKER_API_AUDIT.md)
|
||||
- [Threat model](docs/THREAT_MODEL.md)
|
||||
- [Implementation plan](docs/IMPLEMENTATION_PLAN.md)
|
||||
|
||||
## 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.
|
||||
|
|
@ -0,0 +1,259 @@
|
|||
# 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.
|
||||
|
||||
### 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
|
||||
scopes[]
|
||||
mode: voluntary | reporting
|
||||
created_by_user_id
|
||||
created_at
|
||||
|
||||
pairing_code
|
||||
id
|
||||
agent_id
|
||||
code_hash
|
||||
expires_at
|
||||
consumed_at
|
||||
|
||||
agent_audit_event
|
||||
id
|
||||
agent_id
|
||||
owner_user_id
|
||||
operation
|
||||
workspace_slug
|
||||
project_id
|
||||
issue_id
|
||||
idempotency_key
|
||||
result
|
||||
created_at
|
||||
```
|
||||
|
||||
## Actor model
|
||||
|
||||
Writes should be visible as agent actions, not anonymous platform automation.
|
||||
|
||||
Recommended Tasker-side identity:
|
||||
|
||||
```text
|
||||
display_name: Codex Agent: <name>
|
||||
email: agent+<agent_id>@agents.nodedc.local
|
||||
is_bot: true
|
||||
owner_user_id: <human 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.<deployment-domain>
|
||||
```
|
||||
|
||||
The service should support:
|
||||
|
||||
- local `.env`;
|
||||
- staging `.env.staging`;
|
||||
- production secret store;
|
||||
- Docker image build;
|
||||
- health endpoint;
|
||||
- preflight script validating URLs/secrets.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,317 @@
|
|||
# MCP Tools Contract
|
||||
|
||||
Last updated: 2026-05-14.
|
||||
|
||||
## Position
|
||||
|
||||
The current Tasker / Plane fork does not expose a dedicated MCP server. It exposes REST endpoints and NODE.DC internal endpoints. The new module should expose MCP tools externally and translate those tool calls into validated Tasker adapter calls.
|
||||
|
||||
Codex should not call generic Tasker REST directly.
|
||||
|
||||
## Authentication
|
||||
|
||||
MCP clients authenticate to Agent Gateway with an opaque agent token.
|
||||
|
||||
Recommended transport options:
|
||||
|
||||
- HTTPS MCP endpoint for general clients;
|
||||
- local stdio connector later if useful;
|
||||
- REST fallback for non-MCP clients.
|
||||
|
||||
Token rules:
|
||||
|
||||
- token is opaque;
|
||||
- server stores only token hash;
|
||||
- token is scoped to one agent;
|
||||
- token can be revoked immediately;
|
||||
- token expires;
|
||||
- owner blocked/annulled disables tokens.
|
||||
|
||||
## Tool list
|
||||
|
||||
### `tasker_get_agent_instructions`
|
||||
|
||||
Returns operating rules, allowed projects, card guide, and reporting expectations.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
workspace:read
|
||||
```
|
||||
|
||||
### `tasker_list_projects`
|
||||
|
||||
Lists projects granted to the agent.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
project:read
|
||||
```
|
||||
|
||||
### `tasker_get_project_context`
|
||||
|
||||
Returns project states, labels, members, and card-writing rules.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
project:read
|
||||
```
|
||||
|
||||
### `tasker_search_issues`
|
||||
|
||||
Searches existing work items within granted projects.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:read
|
||||
```
|
||||
|
||||
### `tasker_get_issue`
|
||||
|
||||
Returns one issue with description, structured blocks, labels, state, assignees, and comments summary.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:read
|
||||
```
|
||||
|
||||
### `tasker_create_issue`
|
||||
|
||||
Creates a work item.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:create
|
||||
```
|
||||
|
||||
Allowed fields:
|
||||
|
||||
```text
|
||||
project_id
|
||||
name
|
||||
description_html
|
||||
detail_layout
|
||||
state_id
|
||||
priority
|
||||
label_ids
|
||||
assignee_ids
|
||||
start_date
|
||||
target_date
|
||||
parent_id
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- project must be granted;
|
||||
- state must belong to project;
|
||||
- labels must belong to project;
|
||||
- assignees must be active project members;
|
||||
- detail layout must match NODE.DC structured block schema.
|
||||
|
||||
### `tasker_update_issue`
|
||||
|
||||
Patches allowed issue fields.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:update
|
||||
```
|
||||
|
||||
Allowed fields:
|
||||
|
||||
```text
|
||||
name
|
||||
description_html
|
||||
detail_layout
|
||||
priority
|
||||
start_date
|
||||
target_date
|
||||
parent_id
|
||||
```
|
||||
|
||||
Deletion, archive, and project transfer are not allowed.
|
||||
|
||||
### `tasker_move_issue`
|
||||
|
||||
Changes issue state and optional sort order.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:move
|
||||
```
|
||||
|
||||
Allowed fields:
|
||||
|
||||
```text
|
||||
state_id
|
||||
sort_order
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- target state must belong to the same project;
|
||||
- cancelled/completed moves are allowed only if the grant permits them.
|
||||
|
||||
### `tasker_set_issue_labels`
|
||||
|
||||
Sets or merges labels.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:label
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- labels must already exist in project for MVP;
|
||||
- creating new labels can be added later under `label:create`.
|
||||
|
||||
### `tasker_assign_issue`
|
||||
|
||||
Sets assignees.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:assign
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- assignees must be active project members;
|
||||
- if the user asks to add a workspace member to the project, use `tasker_add_existing_project_member` first.
|
||||
|
||||
### `tasker_add_existing_project_member`
|
||||
|
||||
Adds an existing workspace member to a granted project.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
project:member:add_existing
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- target user must already be an active workspace member;
|
||||
- target user role cannot exceed workspace role;
|
||||
- launcher-managed workspace rules must be respected;
|
||||
- the request should be traceable to an explicit human instruction or reporting policy.
|
||||
|
||||
### `tasker_append_comment`
|
||||
|
||||
Adds a comment to an issue.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:comment
|
||||
```
|
||||
|
||||
Allowed fields:
|
||||
|
||||
```text
|
||||
comment_html
|
||||
```
|
||||
|
||||
### `tasker_update_structured_blocks`
|
||||
|
||||
Replaces or patches NODE.DC structured blocks in `detail_layout`.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:structured_blocks:write
|
||||
```
|
||||
|
||||
Supported blocks:
|
||||
|
||||
```text
|
||||
text
|
||||
checker
|
||||
```
|
||||
|
||||
Canonical key:
|
||||
|
||||
```text
|
||||
nodedc_structured_blocks
|
||||
```
|
||||
|
||||
The tool should support high-level patch actions:
|
||||
|
||||
```text
|
||||
append_text_block
|
||||
append_checker
|
||||
update_checker_item
|
||||
replace_blocks
|
||||
append_implementation_note
|
||||
```
|
||||
|
||||
### `tasker_start_work_session`
|
||||
|
||||
Starts a reporting session for a project or issue.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:comment
|
||||
```
|
||||
|
||||
This is mainly for enterprise reporting mode.
|
||||
|
||||
### `tasker_finish_work_session`
|
||||
|
||||
Finishes a reporting session and appends summary/validation notes.
|
||||
|
||||
Required scope:
|
||||
|
||||
```text
|
||||
issue:comment
|
||||
issue:structured_blocks:write
|
||||
```
|
||||
|
||||
## Idempotency
|
||||
|
||||
All write tools must accept:
|
||||
|
||||
```text
|
||||
idempotency_key
|
||||
```
|
||||
|
||||
Agent Gateway stores result mapping and returns the prior result for duplicate keys.
|
||||
|
||||
## Denied tools
|
||||
|
||||
These should not exist in MVP:
|
||||
|
||||
```text
|
||||
tasker_delete_issue
|
||||
tasker_archive_issue
|
||||
tasker_delete_comment
|
||||
tasker_delete_label
|
||||
tasker_delete_project
|
||||
tasker_invite_workspace_member
|
||||
tasker_raw_api_request
|
||||
```
|
||||
|
||||
## Instruction pack
|
||||
|
||||
`tasker_get_agent_instructions` should include the effective card guide. The local Codex setup file should instruct the agent to call this tool before planning Tasker changes.
|
||||
|
||||
Minimum instruction:
|
||||
|
||||
```text
|
||||
Before creating or updating Tasker cards, call tasker_get_agent_instructions.
|
||||
Use Tasker for durable project planning, current architecture, planned architecture, stage checkers, implementation notes, and validation results.
|
||||
Do not create multiple top-level cards for substeps of one product topic.
|
||||
Do not delete or archive cards.
|
||||
Do not operate outside granted projects.
|
||||
```
|
||||
|
|
@ -0,0 +1,185 @@
|
|||
# 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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
Issue.detail_layout["nodedc_structured_blocks"]
|
||||
```
|
||||
|
||||
Known block types:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
/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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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.
|
||||
|
|
@ -0,0 +1,115 @@
|
|||
# Threat Model
|
||||
|
||||
Last updated: 2026-05-14.
|
||||
|
||||
## Security objective
|
||||
|
||||
Let external local Codex agents maintain Tasker cards without turning Tasker into an open automation surface.
|
||||
|
||||
## Main threats
|
||||
|
||||
### Raw Tasker access leakage
|
||||
|
||||
Risk: a user copies a broad Tasker token or cookie into local Codex, allowing arbitrary API calls.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- never issue Plane session cookies to agents;
|
||||
- never expose raw Tasker API tokens;
|
||||
- use opaque Agent Gateway tokens;
|
||||
- only expose allowlisted MCP tools.
|
||||
|
||||
### Project scope escape
|
||||
|
||||
Risk: an agent writes to another project or workspace.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- Agent Gateway grants are project-scoped;
|
||||
- Tasker adapter revalidates workspace/project membership;
|
||||
- every tool requires explicit `project_id`;
|
||||
- gateway rejects projects outside grant set.
|
||||
|
||||
### Destructive action
|
||||
|
||||
Risk: an agent deletes or archives cards, labels, comments, projects, or members.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- no delete/archive MCP tools in MVP;
|
||||
- adapter rejects delete/archive intents;
|
||||
- raw API proxy is forbidden.
|
||||
|
||||
### Privilege confusion
|
||||
|
||||
Risk: an agent acts as the human user and hides automation history.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- create dedicated agent identity;
|
||||
- store owner user separately;
|
||||
- every audit event includes both `agent_id` and `owner_user_id`;
|
||||
- UI displays agent-originated changes.
|
||||
|
||||
### Prompt injection
|
||||
|
||||
Risk: text inside a card tells Codex to exfiltrate token or call forbidden tools.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- MCP tools enforce server-side scopes;
|
||||
- instruction pack says Tasker content is untrusted;
|
||||
- Gateway never exposes secrets through read tools;
|
||||
- deny arbitrary HTTP fetch/proxy tools.
|
||||
|
||||
### Token theft
|
||||
|
||||
Risk: local token leaks from developer machine.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- token hash storage;
|
||||
- expiry;
|
||||
- immediate revoke;
|
||||
- last used metadata;
|
||||
- rate limits;
|
||||
- optional IP/device binding later.
|
||||
|
||||
### Owner lifecycle bypass
|
||||
|
||||
Risk: blocked/annulled user keeps active agent token.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- Gateway checks Launcher owner status;
|
||||
- blocked/annulled owner disables agent tokens;
|
||||
- periodic sync plus request-time access check.
|
||||
|
||||
### Replay and duplicate writes
|
||||
|
||||
Risk: network retry creates duplicate cards/comments.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- required idempotency keys for write tools;
|
||||
- store operation result by token and idempotency key.
|
||||
|
||||
### Reporting mode false confidence
|
||||
|
||||
Risk: enterprise admin assumes local Codex must report, but the developer bypasses the managed config.
|
||||
|
||||
Mitigation:
|
||||
|
||||
- UI distinguishes `connected`, `stale`, `never connected`;
|
||||
- reporting mode is visibility and policy, not hard enforcement, unless a managed wrapper is used;
|
||||
- CI/workflow checks can require Tasker session updates later.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- No database access from Agent Gateway to Tasker DB.
|
||||
- No arbitrary Tasker HTTP proxy.
|
||||
- No user session cookie reuse.
|
||||
- No delete/archive tools in MVP.
|
||||
- No secrets in generated markdown instruction files.
|
||||
- No token logging.
|
||||
- No frontend access to service secrets.
|
||||
|
|
@ -0,0 +1,177 @@
|
|||
# UX Flow: Codex Agents
|
||||
|
||||
Last updated: 2026-05-14.
|
||||
|
||||
## Launcher entitlement UX
|
||||
|
||||
Launcher grants access to the module. It does not configure individual agents.
|
||||
|
||||
### Open contour
|
||||
|
||||
Current open-contour Operational Core access is a dropdown with:
|
||||
|
||||
- workspace member;
|
||||
- service admin;
|
||||
- blocked.
|
||||
|
||||
Target UX: replace this dropdown with a modal aligned with enterprise access modals.
|
||||
|
||||
Modal structure:
|
||||
|
||||
```text
|
||||
Operational Core access
|
||||
Role:
|
||||
- Workspace member
|
||||
- Service admin
|
||||
- Blocked
|
||||
|
||||
Operational Core modules
|
||||
Codex agents: on/off
|
||||
```
|
||||
|
||||
This keeps the existing role decision but makes room for module-level entitlements.
|
||||
|
||||
### Enterprise contour
|
||||
|
||||
The existing enterprise Operational Core access modal should gain a bottom section:
|
||||
|
||||
```text
|
||||
Operational Core modules
|
||||
Codex agents: on/off
|
||||
```
|
||||
|
||||
It must coexist with current controls:
|
||||
|
||||
- client;
|
||||
- service;
|
||||
- NODE.DC user;
|
||||
- global status;
|
||||
- workspace/project assignment;
|
||||
- role assignment.
|
||||
|
||||
The module toggle is independent from project assignment. A user may have Tasker access without Codex-agent access.
|
||||
|
||||
## Tasker workspace settings UX
|
||||
|
||||
Location:
|
||||
|
||||
```text
|
||||
Workspace settings -> Features
|
||||
```
|
||||
|
||||
The `Codex agents` feature appears only when Launcher entitlement is present.
|
||||
|
||||
Feature card:
|
||||
|
||||
```text
|
||||
Codex agents
|
||||
Connect local Codex or compatible AI agents to maintain work items in this workspace.
|
||||
```
|
||||
|
||||
Controls:
|
||||
|
||||
- enable/disable feature for workspace;
|
||||
- create agent;
|
||||
- list agents;
|
||||
- revoke agent;
|
||||
- show last activity;
|
||||
- open agent setup instructions.
|
||||
|
||||
The toggle/checker should use the NODE.DC round checker style, not a browser checkbox. If an existing reusable switch from `AI Voice Tasker` is suitable, extract it into a shared component instead of duplicating local styling.
|
||||
|
||||
## Agent create flow
|
||||
|
||||
Steps:
|
||||
|
||||
1. User opens `Codex agents`.
|
||||
2. User clicks `Create agent`.
|
||||
3. User enters agent name.
|
||||
4. User optionally chooses avatar.
|
||||
5. User chooses allowed projects.
|
||||
6. User chooses capability preset.
|
||||
7. System creates agent and one-time pairing code.
|
||||
8. UI shows setup instructions for local Codex.
|
||||
|
||||
Recommended capability presets:
|
||||
|
||||
```text
|
||||
Task author
|
||||
create/update/move/comment/label/assign/structured blocks
|
||||
|
||||
Reporter
|
||||
read/update/comment/structured blocks/work sessions
|
||||
|
||||
Read-only reviewer
|
||||
read only
|
||||
```
|
||||
|
||||
MVP should focus on `Task author`.
|
||||
|
||||
## Agent setup UX
|
||||
|
||||
The UI should provide:
|
||||
|
||||
- copy MCP endpoint;
|
||||
- copy environment variable name;
|
||||
- generate one-time pairing code;
|
||||
- download instruction file;
|
||||
- show allowed workspace/project list;
|
||||
- show revoke button.
|
||||
|
||||
The token itself should be shown once and never stored in frontend state longer than needed.
|
||||
|
||||
Recommended user-facing artifact:
|
||||
|
||||
```text
|
||||
TASKER_AGENT.md
|
||||
```
|
||||
|
||||
This file contains instructions, not the raw secret. Secrets should be passed through environment variables or Codex secret storage.
|
||||
|
||||
## Card management UX expectations
|
||||
|
||||
Codex agents should follow NODE.DC task-card structure:
|
||||
|
||||
- concise card title;
|
||||
- conceptual description;
|
||||
- `Current architecture` text block when relevant;
|
||||
- stage text blocks;
|
||||
- checker blocks;
|
||||
- implementation notes after real work;
|
||||
- validation notes;
|
||||
- no top-level card spam for substeps of one product topic.
|
||||
|
||||
For cards created by agents, UI should make the author clear:
|
||||
|
||||
```text
|
||||
Created by Codex Agent: <name>
|
||||
Owner: <human user>
|
||||
```
|
||||
|
||||
## Voluntary scenario
|
||||
|
||||
The user explicitly asks local Codex to maintain Tasker.
|
||||
|
||||
Example flow:
|
||||
|
||||
```text
|
||||
User: We agreed on the architecture. Go create Tasker cards for this in project X.
|
||||
Codex: calls tasker_create_issue and tasker_update_structured_blocks.
|
||||
User: Implement stage 1.
|
||||
Codex: updates checker and appends implementation note.
|
||||
```
|
||||
|
||||
## Reporting scenario
|
||||
|
||||
The organization expects developers to report through Tasker while working with Codex.
|
||||
|
||||
UX should expose:
|
||||
|
||||
- connected/not connected agent status;
|
||||
- last activity;
|
||||
- stale report indicator;
|
||||
- active work session;
|
||||
- last updated card;
|
||||
- missing report warning.
|
||||
|
||||
Important limitation: local Codex cannot be forced to report unless it is launched with a managed config/wrapper. The system can show missing reports and enforce API scope, but it cannot control an arbitrary external agent process.
|
||||
Loading…
Reference in New Issue