Zhin.js

Appearance

ADR 0027: Agent Run Orchestration Kernel ​

Status ​

Accepted.

Context ​

Zhin had several competing orchestration paths: subagent spawning, remote mesh delegation, group-cell pipeline state, and five-agent AOP. They all needed the same capabilities: create a run, split work into tasks, assign tasks to executors, listen for progress, recover results, and expose status to Console.

Decision ​

Introduce OrchestrationKernel as the only state transition authority for agent work.

ConceptMeaning
RunA user-visible unit of work, often sourced from an IM session or IM cell
TaskA stateful work item inside a run
AssignmentThe chosen executor and target for a task
ExecutorA local agent, group mention peer, or remote mesh worker
RunEventAppend-only event describing run/task progress
ProjectionConsole, REST, IM group messages, or logs derived from kernel state

State Model ​

ts
type RunStatus = 'open' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled'
type TaskStatus = 'pending' | 'assigned' | 'running' | 'waiting_result' | 'completed' | 'failed' | 'cancelled'

Events ​

The event log includes at least:

  • run.started
  • run.status_changed
  • task.created
  • task.assigned
  • task.started
  • task.thinking
  • task.progress
  • task.completed
  • task.failed
  • result.returned

task.thinking stores only displayable summaries or progress notes. It must not store raw chain-of-thought.

Executors ​

The kernel supports multiple executor kinds:

KindPurpose
localExecute a local ZhinAgent or subagent
scene_mentionSend a task into an IM group/channel as an @ assignment and wait for handback (ADR 0028; legacy name group_mention)
remote_meshDelegate to a remote agent over MCP/HTTP

Executors emit execution events. They do not directly mutate task status.

Workflow Strategies ​

WorkflowStrategy is optional planning logic that returns task specs. The kernel owns task creation, dependency resolution, execution, and snapshots.

Five-agent is implemented as one built-in strategy, not the default architecture.

Consequences ​

  • spawn_task creates or uses kernel tasks.
  • Inbound group routing creates scene_mention tasks instead of directly advancing collaboration scene pipeline state.
  • Console and REST should read kernel snapshots/event streams for run status.
  • CollaborationScene remains valuable as member context and IM projection, but no longer owns orchestration state.