Zhin.js

Appearance

ADR 0023: CollaborationScene multi-endpoint agent collaboration ​

Status ​

Accepted, revised by ADR 0027 and ADR 0028.

Context ​

Zhin needs a first-class experience where multiple real bots in the same IM group can collaborate visibly. Earlier designs stored pipeline state on the collaboration unit and used group chat as the orchestration plane. That coupled IM projection, task state, and five-agent workflow too tightly.

Decision ​

CollaborationScene (formerly CollaborationCell) is not the orchestration state machine. It is the collaboration plane over one or more IM scenes:

ConceptOwnerResponsibility
Transport ActorEndpointPlatform identity used for outbound messages
Cognitive Profileai.agents / .agent.mdModel, prompt, tools, and policy
RuntimeZhinAgent per endpointExecutes local turns and local tasks
Collaboration SceneCollaborationSceneLogical unit, member directory, endpoint/profile mapping, group projection context
IM SceneIMSceneRefPlatform group/channel/private identity (ADR 0028)
Run StateOrchestrationKernelRuns, tasks, assignments, events, state transitions

Run-to-scene linkage:

ts
run.source = {
  kind: 'im_scene',
  scene: { platform, endpointId, sceneId, kind },
  collaborationSceneId, // optional CollaborationScene.id
}

Invariants ​

  1. Identity follows outbound: when a peer endpoint should speak, the scene executor sends an actual IM mention instead of making the planner impersonate that peer.
  2. Cognition follows profile: agent configuration does not imply transport identity.
  3. Coordination follows the kernel: runs, tasks, assignments, handback, progress, and result recovery are kernel events.
  4. Platform remains a projection bus: group messages are a visible projection of assignments and results, not the source of truth for task state.

Scene Mention Executor ​

Group collaboration uses scene_mention (group_mention is a read-time alias only).

  • Assignment emits a group/channel mention containing #taskId.
  • Handback first matches an explicit #taskId.
  • If no #taskId exists and the (collaborationSceneId, endpoint) pair has exactly one active assignment, the reply is attributed to that task.
  • Private scenes cannot use scene_mention.

Persistence ​

Tables (new installs, ADR 0028):

  • collaboration_scenes — id, adapter, scene_id (IM), goal, optional legacy pipeline fields
  • collaboration_scene_members — collaboration_scene_id, endpoint_id, roles
  • collaboration_scene_aliases — logical_scene_id ↔ adapter/scene_id
  • collaboration_scene_member_channels — cross-adapter identity edges

Host REST: /api/collaboration/scenes* (members, pipeline, artifacts sub-resources).

User commands ​

/collab init, bind, status, etc. remain the in-chat management surface. Master endpoint gate unchanged.

Consequences ​

  • Console collaboration REST manages scenes and members; run snapshots and event streams come from the kernel.
  • Existing group-chat collaboration remains visible to users; implementation evolves independently of the core run state machine.
  • Five-agent collaboration is a workflow strategy over kernel tasks, not a scene-level state machine.