ARCH - CODEX AGENTS: архитектура Agent Gateway и MCP-контракта
This commit is contained in:
DCCONSTRUCTIONS
+177
@@ -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.
|
||||
Reference in New Issue
Block a user