Files
Assistant/architecture/adrs/ADR-0017-general-agent-delegation-codex-bridge.md
m b3491520bd
CI / test (push) Successful in 20s
CI / test (pull_request) Successful in 20s
DEV-000069 general agent delegation codex bridge foundation
2026-08-17 20:07:14 +03:00

4.7 KiB

ADR-0017 — General Agent Delegation and Codex Bridge V1

Status: Accepted

Task: DEV-000069

Context

Domovoy already has Human Interaction, Situation/context, optional durable Work/Plan, Capability registry/resolution, Continuity/Attention, HumanResponse, Experience/Reflection, Skill evolution, Secret Resolver and Cognitive Gateway/Router. The next step is not "make Codex the center", but to let Domovoy delegate suitable work to a general external intelligent agent while preserving canonical human intent, work semantics, authority boundaries and future portability to non-Codex agents.

The first real implementation is Codex for software-engineering work. However, a model is not an external agent. Cognitive models provide advice/candidates, while an external agent may inspect state, use tools, modify files, run tests, maintain a long-running task, checkpoint, resume and return evidence-bearing results.

Decision

  1. Do not create a new canonical owner for DEV-000069.
  2. capability remains the canonical owner for agent implementation registration by reusing CapabilityImplementation with Kind=AGENT. A Codex bridge is one concrete implementation, not a new canonical capability identity.
  3. work remains the canonical owner for durable delegation lifecycle. DEV-000069 extends Work semantics from planning-only DelegationCandidate to real delegation execution state such as Delegation, AgentRun, AgentCheckpoint and AgentResult.
  4. continuity remains the canonical owner for human waiting/attention semantics. Human-dependent blockers or completed long-running delegations surface through Attention rather than a Codex-specific notification path.
  5. epistemics remains the canonical owner for delegation outcome evidence through ExperienceRecord and later reflection, using typed refs to Work, Capability, Artifact and Interaction state.
  6. artifact remains the place for durable artifact metadata/refs when an agent run produces file, diff, test, log, PR or deployment evidence. Work stores typed refs, not payload copies.
  7. OriginalHumanIntent, Goal, Work, CapabilityRequirement and Delegation must remain canonical semantic records. Agent-specific instruction or prompt text is only a derived adapter artifact with provenance that distinguishes:
    • what the human asked;
    • what Domovoy inferred;
    • what project/runtime context was added;
    • how completion will be verified.
  8. Execution-window exhaustion is a run lifecycle state, not automatic task failure. The same higher-level delegation may continue through later runs while preserving checkpoint/history.
  9. Codex transport/UI wording is adapter-local. Canonical state must stay valid if the coding agent is replaced by another future agent.

Ownership

  • interaction owns the append-only human request/correction history and original intent traceability.
  • situation resolves project/repository context and active focus used for delegation context compilation.
  • work owns durable delegation requests, selected implementation refs, run lifecycle, checkpoint/result refs and verification gating before Work completion.
  • capability owns executor-neutral capability identity and concrete eligible implementations, including AGENT implementations such as Codex.
  • continuity owns waiting/attention/human-response continuation for delegation progress and genuine human blockers.
  • epistemics owns experience/reflection evidence derived from delegation outcomes.
  • artifact owns durable metadata for diffs/logs/checkpoints/results when they must survive outside a transient adapter response.

Boundaries

  • SOFTWARE_ENGINEERING, MODIFY_CODE, INSPECT_REPOSITORY and RUN_TESTS remain executor-neutral capability semantics.
  • MODIFY_CODE != CODEX.
  • Canonical Work/Delegation does not become a Codex prompt.
  • Secret access remains least-privilege through CredentialRef/Secret Resolver. Agent capability availability does not imply credential access or authority.
  • A completed agent run does not automatically mark higher-level Work complete. Verification must inspect available evidence.
  • Technical failures, execution-window exhaustion and human-dependent blockers are distinct lifecycle states.
  • LLM-free startup must continue to pass when Codex is unavailable.

Consequences

  • Domovoy can delegate suitable software-engineering work without forcing the human to author a giant Codex prompt.
  • The first production bridge can target Codex while leaving canonical semantics portable to future scientific, accounting, research or alternate coding agents.
  • Long-running agent work can checkpoint and continue across bounded execution windows.
  • Human chat remains simple, while operator/debug tooling can inspect the durable delegation/run/checkpoint/result state.