The OrchestratorAPI extends QuarryAPI with orchestration-specific functionality for managing AI coding agents, their sessions, and task assignments. It provides methods for agent registration, session tracking, and task metadata management.
Overview The OrchestratorAPI is implemented in packages/smithy/src/api/orchestrator-api.ts and provides:
Agent registration (Director, Worker, Steward roles)
Agent lifecycle management
Session status tracking
Orchestrator-specific task metadata
Agent channel communication setup
Installation import { createOrchestratorAPI } from '@stoneforge/smithy' ; import { createStorageBackend } from '@stoneforge/storage' ; const backend = await createStorageBackend ({ dbPath: '.stoneforge/stoneforge.db' }); const api = createOrchestratorAPI ( backend );
Agent Registration registerDirector() Registers a Director agent (task backlog owner, strategic decisions).
input
RegisterDirectorInput
required
Agent registration configuration Entity creating the agent
Maximum concurrent tasks (defaults to 3)
Reference to role definition file
AI provider (e.g., ‘anthropic’, ‘openai’)
Model identifier (e.g., ‘claude-4.5-sonnet’)
Path to executable for spawning
Optional tags for the agent
The created agent with metadata including channelId
const director = await api . registerDirector ({ name: 'director-main' , createdBy: operatorId , maxConcurrentTasks: 5 , provider: 'anthropic' , model: 'claude-4.5-sonnet' , executablePath: '/usr/local/bin/opencode' , });
registerWorker() Registers a Worker agent (executes assigned tasks).
input
RegisterWorkerInput
required
Worker registration configuration workerMode
'ephemeral' | 'persistent'
required
Worker lifecycle mode
Entity creating the agent
Director this worker reports to
Maximum concurrent tasks (defaults to 1 for workers)
Reference to role definition file
Path to executable for spawning
Optional tags for the agent
const worker = await api . registerWorker ({ name: 'worker-001' , workerMode: 'ephemeral' , createdBy: directorId , reportsTo: directorId , provider: 'anthropic' , model: 'claude-4.5-sonnet' , });
registerSteward() Registers a Steward agent (handles merges, documentation fixes).
input
RegisterStewardInput
required
Steward registration configuration stewardFocus
'merge' | 'docs' | 'general'
required
Area of responsibility
Entity creating the agent
Director this steward reports to
Event triggers that activate this steward
Steward’s operational playbook
Reference to playbook document
Reference to role definition file
Path to executable for spawning
Optional tags for the agent
The created steward agent
const steward = await api . registerSteward ({ name: 'merge-steward' , stewardFocus: 'merge' , createdBy: directorId , reportsTo: directorId , triggers: [ 'task_completed' , 'tests_passed' ], });
Agent Queries getAgent() Retrieves an agent by ID.
The agent entity or undefined if not found
const agent = await api . getAgent ( agentId ); if ( agent ) { console . log ( `Agent: ${ agent . name } , Role: ${ agent . metadata . agent . agentRole } ` ); }
getAgentByName() Retrieves an agent by name.
The agent entity or undefined if not found
const worker = await api . getAgentByName ( 'worker-001' );
listAgents() Lists agents matching filter criteria.
role
'director' | 'worker' | 'steward'
Filter by agent role
workerMode
'ephemeral' | 'persistent'
Filter workers by mode
stewardFocus
'merge' | 'docs' | 'general'
Filter stewards by focus area
sessionStatus
'idle' | 'running' | 'suspended' | 'terminated'
Filter by session status
Filter by reporting relationship
Filter by session presence
// Get all idle workers const idleWorkers = await api . listAgents ({ role: 'worker' , sessionStatus: 'idle' }); // Get all agents reporting to director const team = await api . listAgents ({ reportsTo: directorId });
getAgentsByRole() Shorthand for listing agents by role.
role
'director' | 'worker' | 'steward'
required
Agent role
Array of agents with specified role
const allWorkers = await api . getAgentsByRole ( 'worker' );
getAvailableWorkers() Returns workers that are currently available (idle or accepting tasks).
Array of available worker agents
const availableWorkers = await api . getAvailableWorkers (); if ( availableWorkers . length > 0 ) { // Dispatch task to first available worker }
getStewards() Returns all steward agents.
const stewards = await api . getStewards ();
getDirector() Returns the Director agent (there should be only one per workspace).
The director agent or undefined if none exists
const director = await api . getDirector ();
Session Management updateAgentSession() Updates an agent’s session status and ID.
sessionId
string | undefined
required
Session ID (undefined to clear)
status
'idle' | 'running' | 'suspended' | 'terminated'
required
New session status
// Start session await api . updateAgentSession ( workerId , 'session-123' , 'running' ); // Mark idle after task completion await api . updateAgentSession ( workerId , undefined , 'idle' );
getAgentChannel() Retrieves the communication channel for an agent.
Channel ID or undefined if not found
const channelId = await api . getAgentChannel ( workerId ); if ( channelId ) { // Send message to agent's channel }
Sets orchestrator-specific metadata on a task.
meta
OrchestratorTaskMeta
required
Agent assigned to the task
mergeStatus
'pending' | 'testing' | 'merging' | 'merged' | 'conflict' | 'failed'
Merge workflow status
Last test execution result
await api . setTaskOrchestratorMeta ( taskId , { assignedAgent: workerId , branch: 'task/feature-123' , worktree: '/worktrees/worker-001/feature-123' , sessionId: 'session-456' , startedAt: createTimestamp (), mergeStatus: 'pending' , });
Partially updates orchestrator metadata on a task.
updates
Partial<OrchestratorTaskMeta>
required
Metadata updates (partial)
// Update just the merge status await api . updateTaskOrchestratorMeta ( taskId , { mergeStatus: 'merged' , mergedAt: createTimestamp (), });
Retrieves orchestrator metadata from a task.
meta
OrchestratorTaskMeta | undefined
Orchestrator metadata or undefined if not set
const meta = await api . getTaskOrchestratorMeta ( taskId ); if ( meta ?. branch ) { console . log ( `Task is on branch: ${ meta . branch } ` ); }
assignTaskToAgent() Assigns a task to an agent and sets up orchestrator metadata.
Git branch (auto-generated if not provided)
Worktree path (auto-generated if not provided)
Whether to immediately mark as in_progress
Updated task with orchestrator metadata
const task = await api . assignTaskToAgent ( taskId , workerId , { markAsStarted: true , sessionId: 'session-789' , }); // Branch and worktree are auto-generated based on task title and agent name console . log ( task . metadata . orchestrator . branch ); // e.g., "worker-001/task-el12345-feature-name"
Type Definitions AgentEntity interface AgentEntity extends Entity { metadata : { agent : AgentMetadata ; [ key : string ] : unknown ; }; }
Base metadata for all agents:
interface AgentMetadata { agentRole : 'director' | 'worker' | 'steward' ; sessionStatus : 'idle' | 'running' | 'suspended' | 'terminated' ; sessionId ?: string ; channelId ?: ChannelId ; maxConcurrentTasks ?: number ; roleDefinitionRef ?: string ; provider ?: string ; model ?: string ; executablePath ?: string ; lastActivityAt ?: Timestamp ; }
Extends AgentMetadata for workers:
interface WorkerMetadata extends AgentMetadata { agentRole : 'worker' ; workerMode : 'ephemeral' | 'persistent' ; }
Extends AgentMetadata for stewards:
interface StewardMetadata extends AgentMetadata { agentRole : 'steward' ; stewardFocus : 'merge' | 'docs' | 'general' ; triggers ?: string []; playbook ?: string ; playbookId ?: ElementId ; }
Orchestration metadata stored in task.metadata.orchestrator:
interface OrchestratorTaskMeta { assignedAgent ?: EntityId ; branch ?: string ; worktree ?: string ; sessionId ?: string ; startedAt ?: Timestamp ; completedAt ?: Timestamp ; mergeStatus ?: 'pending' | 'testing' | 'merging' | 'merged' | 'conflict' | 'failed' | 'not_applicable' ; mergedAt ?: Timestamp ; mergeFailureReason ?: string ; lastTestResult ?: TestResult ; testRunCount ?: number ; }
QuarryAPI - Base API for CRUD operationsServices - DispatchService, WorkerTaskService, MergeStewardService