AEGIS DOCS

Model-Backed Coordinator Rebuild

This document defines the replacement target for the current coordinator conversation path.

The current coordinator is model-assisted, but it is still mostly a code-routed intent switch. It asks a model to classify a turn, then TypeScript routes the result through fixed branches such as chat, status, steer, or queue run. That is not the intended product.

The intended coordinator is an AI agent with durable context, known tools, known skills, bounded delegation authority, and policy-enforced side effects. The model should decide which coordinator tools to call, inspect relevant state, delegate specialist work when needed, and answer the user from observed facts. Code should validate and execute actions, enforce policy, record audit trails, and prevent unsafe or inconsistent mutations.

Target Behavior

The coordinator should be able to handle requests like:

For each turn, the coordinator should:

  1. Read the current conversation and relevant memory.
  2. Inspect active and recent runs when the message refers to prior work.
  3. Call tools to retrieve run state, task sessions, artifacts, approvals, and traces as needed.
  4. Decide whether to answer, ask a question, stop/pause/resume work, attach guidance, delegate work, request approval, or create a new run.
  5. Produce a structured action plan.
  6. Let the orchestrator validate and execute only allowed actions.
  7. Tell the user what happened and why, using facts from tool results.

Architectural Principle

Model reasoning owns interpretation. Deterministic code owns authority.

The coordinator model should handle:

The runtime should handle:

Hardcoded text matching is acceptable only as a fallback for offline tests, defensive safety gates, or compatibility shims. It should not be the primary coordinator intelligence path.

Validation and persistence must not recreate the old failure mode. The coordinator should not be boxed into a tiny set of hardcoded intent branches. The model must retain meaningful authority to inspect, reason, delegate, stop, guide, ask, answer, and queue work through known tools. Runtime checks should answer “is this action allowed and well formed?” rather than “did this message match a TypeScript phrase list?”

Coordinator Loop

The new coordinator loop should replace the current fixed intent path:

user message
  -> build coordinator context packet
  -> model chooses tool calls or final action plan
  -> execute read-only coordinator tools
  -> repeat until enough context is gathered
  -> model emits structured action plan
  -> orchestrator validates action plan
  -> execute approved actions
  -> append coordinator response

The loop is bounded by max tool calls, max model turns, timeout, and token budget. If the model cannot produce a valid action plan, the coordinator should ask for clarification or report the failure with the inspected state.

Coordinator Tools

Coordinator tools are not raw shell access. They are typed Aegis operations with scoped permissions and audit records.

Required read tools:

Required action tools:

High-risk action tools remain policy-gated. The coordinator can request or present approval checkpoints, but cannot silently bypass policy.

Delegation Authority

The coordinator should have explicit authority to delegate safe bounded work without a code path selecting a workflow from text matching.

Delegation should be model-planned and runtime-validated:

The coordinator should be able to choose between:

Structured Action Plan

The model should emit a validated action plan instead of only an intent label.

Minimum shape:

{
  "summary": "Short description of what the coordinator decided.",
  "rationale": "Why this action follows from the conversation and inspected state.",
  "actions": [
    {
      "type": "answer",
      "content": "User-facing response grounded in inspected state."
    }
  ],
  "references": {
    "conversationEventIds": [],
    "runIds": [],
    "taskSessionIds": [],
    "artifactPaths": []
  },
  "risk": {
    "requiresApproval": false,
    "policyClasses": []
  }
}

Action types should include:

The executor should reject invalid references, missing evidence, unsupported action types, disallowed profiles, and policy violations.

Context Packet

Every coordinator turn should receive a compact but useful packet:

The model can call tools to expand run, artifact, approval, and task-session details. Conversation context should not be reduced to a narrow recent window in the live coordinator path; otherwise pasted examples and follow-up corrections can be misread as the current task.

Testing Strategy

Tests should validate behavior rather than phrase matching.

Required scenario tests:

Unit tests should cover schema validation, tool permission checks, policy enforcement, and duplicate-action prevention. Integration tests should run the coordinator loop with a fake model gateway that selects tools based on inspected state.

Implementation Task List

Phase 1: Define Contracts

Phase 2: Build Coordinator Tool Runtime

Phase 3: Replace Intent Routing

Phase 4: Delegation Planner

Phase 5: Policy And Approval Integration

Phase 6: Dashboard Integration

Phase 7: Evaluation

First Refactor Slice

The first coding slice should be small enough to land safely but should follow the final architecture:

  1. Add the action-plan and tool-call schemas.
  2. Add a coordinator tool registry with read-only tools for conversation, runs, task sessions, artifacts, and approvals.
  3. Implement a model-tool loop behind a feature flag or runtime mode.
  4. Route coordinator live-model turns through the tool loop.
  5. Keep the existing intent path only as deterministic fallback.
  6. Add tests proving “implement the proposed patch” is solved by inspecting artifacts, not by text matching.

Once that slice works, remove the tactical patch-followup matcher from the live path.

Next Action Plan

Treat this section as the active task list for the next implementation pass. The goal is to harden the model-backed coordinator path without reducing it back to a brittle router.

Current Progress

Guardrails

Task List

  1. Persist coordinator turn transcripts. Status: completed for model-backed turns; follow-up links to context packets/trace events remain.
    • Add a durable coordinator_turns or equivalent table.
    • Store source conversation event ID, status, model prompt kind, tool calls, tool results, action plan, validation errors, executed actions, timestamps, and linked run/session/artifact/approval references.
    • Record failed model-tool turns instead of silently falling back with no explanation.
    • Add schema migration coverage.
    • Add contract/schema tests.
  2. Add coordinator transcript read APIs. Status: conversation-scoped list endpoint added; single-turn and compact summary APIs remain.
    • Add service methods to list turns for a conversation and retrieve one turn.
    • Add API endpoints for conversation-scoped coordinator turn history.
    • Include compact transcript summaries in conversation details or run workspace where useful.
    • Keep raw large tool-result content expandable rather than always embedded in main conversation payloads.
  3. Expose “why did the coordinator do that?” data.
    • Link coordinator response events to transcript IDs.
    • Link transcripts to context packets and trace events.
    • Add a derived explanation object with inspected tools, evidence, selected actions, validation checks, and execution result.
  4. Surface pending approvals in the new dashboard. Status: inline conversation approval controls added to the chat shell.
    • Load GET /approvals/queue into the new dashboard shell.
    • Render pending approvals in the conversation flow rather than a separate dashboard panel.
    • Keep human decisions to simple Approve/Reject controls under the relevant artifact links.
    • Show whether a checkpoint is coordinator-approvable, human-owned, or unknown.
  5. Add structured coordinator approval decisions. Status: bounded decide-approval action added.
    • Add a typed action-plan action for approval decisions.
    • Remove the live coordinator approval text-matching shortcut so the model-backed path can inspect state and decide.
    • Validate approval/run references and pending status before execution.
    • Allow coordinator approval only for executor-marked bounded start/internal checkpoints.
    • Include enough information to debug wrong coordinator behavior without reading raw logs.
  6. Strengthen action-plan validation. Status: started; reference checks and stale state checks are in place.
    • Validate referenced run IDs, task session IDs, approval IDs, artifact paths, memory IDs, profile IDs, and capability IDs before executing actions.
    • Reject present-approval unless the approval exists and is pending.
    • Reject stop-task-session, pause-run, resume-run, and cancel-run when the referenced state makes the action invalid or redundant.
    • Reject answer claims about applied patches or approvals unless tool results or references support the claim.
    • Return validation failures as coordinator-visible responses instead of silently routing through fallback.
  7. Add duplicate-action prevention. Status: started for stale approval presentation, redundant terminal run/task actions, duplicate active-run queueing, and implicit new workstreams during active-run follow-ups.
    • Prevent applying or presenting an already-decided approval as if it were pending.
    • Prevent queueing a new run when a model action plan references an already-running equivalent task and only needs guidance/status.
    • Prevent queueing or delegating new work from an active-run follow-up unless the user explicitly requests a separate workstream.
    • Prevent duplicate stop/cancel/resume actions from creating misleading conversation events.
    • Add tests for repeated “apply it”, “stop that”, and “run it again” follow-ups.
  8. Improve delegation semantics. Status: started; delegated roles must resolve to active specialist profiles, profile workflow/model hints are used when queueing delegated work, compatible multi-delegate plans are grouped into one coordinated run, and explicit delegate dependencies are supported.
    • Replace the temporary delegate-task -> inferred single-agent workflow mapping with a validated delegation planner.
    • Validate the requested specialist role against coordinator profile authority.
    • Validate specialist profile tool allowlist, skill IDs, policy classes, and model routing.
    • Support multiple delegated tasks with dependencies from one action plan.
    • Preserve workflow templates as reusable scaffolds, not the only delegation mechanism.
  9. Implement multi-agent task graph execution. Status: started for compatible profile-backed delegated tasks in one workflow-backed run with model-declared action dependencies.
    • Let an action plan create several specialist task sessions or a run-level delegation plan directly.
    • Support dependencies between researcher, coder, reviewer, verifier, and summarizer roles.
    • Ensure task sessions remain inspectable and steerable.
    • Keep repo writes on verified patch-bundle rails.
  10. Remove tactical live-path matchers.
    • Ensure model-backed planning errors never silently fall through to classifyCoordinatorIntent or handlePatchProposalFollowup.
    • Remove the live-path dependency on handlePatchProposalFollowup.
    • Keep only no-model fallback behavior for offline/local deterministic operation.
    • Add tests proving patch follow-ups, status follow-ups, steering, and approval presentation go through tool calls/action plans.
  11. Improve coordinator prompts. Status: started for active-run conversational behavior.
    • Add the persisted transcript schema and action validation rules to the coordinator prompt.
    • Include available tools and specialist profiles in a compact form.
    • Include full conversation event history so the model can distinguish the current request from quoted samples, old approval text, and follow-up corrections.
    • Add a schema-repair turn when the model returns malformed action-plan JSON.
    • Teach the model to inspect before acting on ambiguous references.
    • Teach the model to prefer inspecting, answering, continuing, stopping, or guiding existing active work over starting redundant runs.
  12. Add scenario coverage.
    • “What happened?” after a failed/stuck model call.
    • “Stop that one, use a smaller agent.”
    • “Apply it” with pending approval.
    • “Apply it” after already applied.
    • “Research this and have a reviewer check it.”
    • “Do not start work yet, just explain the plan.”
    • “Use the previous plan but change the UI behavior.”
    • “Continue the last run with this added constraint.”
  13. Dashboard transcript UI. Status: started; coordinator response messages now include compact expandable turn details for transcript status, tools, action plans, validation errors, and delegated tasks.
    • Show coordinator states: thinking, inspecting, reading artifacts, presenting approval, delegating, stopping, validating, executing.
    • Render tool calls and results as compact expandable rows.
    • Show action-plan summary and executed actions.
    • Link tool results to run/session/artifact/approval panels.
    • Preserve append-only updates so selection and scroll are not disrupted.
  14. Audit and replay integration.
    • Include coordinator transcripts in audit export.
    • Include coordinator turn failures in replay packets.
    • Add trace events for tool-call started/completed/failed, action-plan validated/rejected, and action executed.
    • Make transcript hashes available for integrity checks.
  15. Cleanup and simplification.
    • Delete obsolete intent-router branches once the tool loop covers the scenarios.
    • Move fallback logic into a clearly named no-model path.
    • Remove redundant text-matching helpers from live execution.
    • Update docs to mark completed slices and remaining gaps.