05-Agent-Providers

1. Provider interface

interface AgentProviderInterface {
	public function key(): string;                         // 'openai' | 'claude_api' | 'claude_code' | 'local_shell'
	public function capabilities(): array;                 // ['chat','tools','streaming','code_exec']

	public function prepareContext(AgentRun $run, RagResult $rag): ProviderContext;
	public function startRun(ProviderContext $ctx): ProviderStream;
	public function continueRun(AgentRun $run, string $userInput): ProviderStream;
	public function pauseRun(AgentRun $run): void;
	public function cancelRun(AgentRun $run): void;
	public function summarizeRun(AgentRun $run): RunSummary;
	public function extractFileChanges(ProviderEvent $e): array;   // FileChange[]
	public function streamEvents(ProviderStream $s): iterable;     // yields ProviderEvent
}

ProviderEvent is normalized:

final class ProviderEvent {
	public string $kind;          // 'message','tool_call','tool_result','file_change','command','done','error','pause'
	public array $payload;
	public ?string $rawProviderType = null;
}

The orchestrator maps ProviderEvent → agent_events rows via ConsoleEventService.

2. Provider implementations

All provider classes are constructor-injected and bound to the container in AgentProvidersServiceProvider. The AgentProviderResolver returns the right instance from selected_model / selected_agent.

3. Orchestrator

AgentRunOrchestrator is the single state machine. Responsibilities:

1. acquire workspace lock

2. snapshot pre_run

3. create Git branch agent/run-{id}-{slug}

4. retrieve RAG context (unless disabled)

5. call provider->prepareContext() and startRun()

6. iterate normalized events:
   • tool calls → CommandExecutionService / WorkspaceService / GitService
   • file changes → WorkspaceService::applyChange() + WorkspaceFile row + diff event
   • pause → set status waiting_for_user, persist, broadcast

7. on completion → run DocumentationAutoUpdateService, write final_summary, release lock

8. on failure → write failed_reason, still release lock, emit final_summary event with severity: error

State transitions match the diagram in the master page (§4).

4. Tool surface exposed to providers

Tools are advertised to each provider in its native schema. Provider-specific shaping lives in the provider class.

5. Specialized agents

Each specialized agent is a configuration object:

final class AgentDefinition {
	public string $key;                     // 'architect', 'backend', ...
	public string $displayName;
	public string $systemPrompt;            // role-specific
	public array $allowedTools;             // subset of the tool surface
	public array $defaultModel;             // ['provider' => 'openai', 'model' => 'gpt-4.1']
	public array $ragFilters;               // default source_types to bias retrieval
}

Roles

All agents share the same RAG, same event log, same workspace.

6. Prompt skeleton (shared system prompt header)

You are the {agent_display_name} for the AI Coding Agent Workspace.
Project: {project.name} ({framework}/{language}).
Branch: {run.branch_name} (an isolated branch for this run).
Safe mode: {safe_mode_on_off}.
RAG: {rag_on_off}. If ON, you must call rag_search before any plan or edit.
Never guess when context exists. If unsure, call ask_user.
Never push, never delete history, never run blocked commands.
Always finish() with a structured summary describing changes, risks, and tests.

Role-specific suffix appended per agent.

7. Failure handling

• Provider error → emit error event, transition to failed, do not auto-rollback (leave the user to choose).

• Tool error → propagate to provider as a tool_result with is_error: true; agent decides recovery.

• Timeout → kill subprocess, mark was_killed=true on the command row, transition to failed unless agent recovers gracefully.

8. Pause / resume

• paused_for_input event carries { question, options?, deadline? }.

• Orchestrator persists provider conversation state in agent_runs.metadata_json.provider_state.

• POST /api/runs/{run}/resume with { input: "…" } rehydrates and calls provider->continueRun().