How the WorkHub Coordination Session in Apache Maka Facilitates Agent Collaboration

The WorkHub coordination session in Apache Maka is a persistent, hidden conversational lane that reuses the existing Session infrastructure to mediate agent proposals, delegation, and decision-making without duplicating storage or blurring authority boundaries.

The apache/maka repository implements a specialized WorkHub coordination session that lives inside the normal Session substrate of a Runtime Host. This design gives agents a shared space to negotiate work assignments while maintaining strict separation between coordination chatter and actual execution state.

Single Persistent Session Architecture

Apache Maka provisions exactly one durable coordination session per Runtime Host, adhering to the Architectural Decision Record (ADR) defined in docs/architecture/workhub-coordination-session-adr.md.

Lazy Provisioning and Persistence

The WORKHUB_COORDINATION_SESSION_ID is instantiated lazily the first time WorkHub is accessed and survives host restarts. Unlike ordinary sessions, this coordination session remains hidden from standard session listings, preventing user interfaces from accidentally exposing internal agent negotiations. The session reuses the existing transcript, model, recovery, and event pipelines rather than creating a separate database or storage layer.

Core Coordination Components

The coordination workflow is orchestrated by two primary server-side components that enforce validation and routing.

HostWorkHubCoordinationCoordinator

Located in packages/runtime-host/src/server/workhub-coordination-coordinator.ts, the HostWorkHubCoordinationCoordinator manages the lifecycle of the coordination session. It creates or looks up the session, routes protocol operations, and interfaces with the Action Gate. Every coordination turn is stored as a workhub_coordination message type within the shared Session file, ensuring that recovery and audit trails remain unified.

WorkHubCoordinationActionGate

The WorkHubCoordinationActionGate (packages/runtime-host/src/server/workhub-coordination-action-gate.ts) serves as the admission layer for all agent proposals. It validates candidates, assignments, and replacements while ensuring that only opaque candidate references reach the model. This gate enforces deterministic routing, rejects self-route attempts, and performs permission checks before any write operation reaches the persistent session store.

Coordination Protocol and Dispositions

Agents interact with the coordination session through a strict protocol defined in packages/runtime-host/src/protocol/workhub-coordination.ts.

Protocol Operations

The protocol exposes five primary operations:

• resolve – Returns the existing coordination session ID or creates it if absent
• candidates – Retrieves the list of available Session candidates for delegation
• act – Submits a proposal with a specific disposition (delegate, create, clarify, etc.)
• answer – Provides direct responses within the coordination context
• record – Persists clarifications or conversational turns without triggering delegation

Delegation Links and Dispositions

Each coordination turn resolves to one of several dispositions: answer_here, delegate_existing, create_new, clarify, or replace. When agents delegate work, the session creates a typed delegation link (workhub_delegation_assigned) that records the action ID, target Session, and user text. This link acts as the sole persistent bridge between the coordination transcript and the target Session, which retains full ownership of its execution state while the coordination session projects read-only views.

Implementation Example

The following TypeScript demonstrates how to interact with the coordination session using the HostWorkHubCoordinationCoordinator API:

// Resolve (or create) the Coordination Session for the current host
const resolveResult = await hostCoordinationCoordinator.handlers['workhub.coordination.resolve']();
// => { sessionId: "workhub-coordination-session" }

// Get candidate Sessions available for delegation
const candidates = await hostCoordinationCoordinator.handlers['workhub.coordination.candidates']();
// candidates.candidates is an array of WorkHubCoordinationCandidate objects

// Propose an action to delegate to an existing Session
const actInput = {
  actionId: "whact_123",
  userText: "Please write a summary for the project",
  proposal: { disposition: "delegate_existing", candidateRef: "cand_abc" },
};
const actResult = await hostCoordinationCoordinator.handlers['workhub.coordination.act'](
  actInput,
  connectionContext,
);
// actResult returns targetSessionId, targetTurnId, and steered status

// Record a clarification without creating a new delegation
await hostCoordinationCoordinator.handlers['workhub.coordination.record']({
  turnId: "whturn_456",
  userText: "Can you clarify the deadline?",
  assistantText: "Sure, the deadline is next Friday."
});

All calls execute through the same event pipelines as regular Sessions, ensuring that the workhub_coordination message type persists alongside ordinary conversation turns.

Per-Host Isolation Boundaries

Because the WorkHub coordination session is scoped to a specific Runtime Host, agents operating on different hosts cannot interfere with each other’s coordination state. Switching hosts selects a different WORKHUB_COORDINATION_SESSION_ID, preserving isolation while allowing each host to coordinate its own pool of ordinary Sessions independently.

Summary

• The WorkHub coordination session is a special-role Session that reuses existing storage, transcript, and recovery infrastructure in apache/maka.
• One session per Runtime Host is provisioned lazily and persists across restarts while remaining hidden from standard session lists.
• The WorkHubCoordinationActionGate validates all proposals and enforces that only opaque references touch the model, preventing direct Session manipulation.
• Protocol operations (resolve, candidates, act, answer, record) provide a deterministic API for delegation and clarification.
• Delegation links (workhub_delegation_assigned) create typed, persistent bridges to target Sessions without transferring execution authority.

Frequently Asked Questions

What distinguishes the WorkHub coordination session from a regular Session?

The WorkHub coordination session is a specialized role of a normal Session rather than a distinct entity type. According to the ADR in docs/architecture/workhub-coordination-session-adr.md, it reuses the same storage file and event pipelines but stores messages with the workhub_coordination type. This design avoids database duplication while providing a dedicated conversational lane for agent negotiation that remains invisible to end users.

How does the coordination session prevent agents from directly manipulating target Sessions?

All proposals flow through the WorkHubCoordinationActionGate located in packages/runtime-host/src/server/workhub-coordination-action-gate.ts. This component validates proposals and ensures that only opaque candidate references reach the coordination model. It explicitly blocks direct writes to Sessions and enforces permission checks, deterministic routing, and self-route rejection before any delegation link is created.

What happens when an agent proposes a delegation?

When an agent invokes the act operation with a delegate_existing disposition, the HostWorkHubCoordinationCoordinator creates a typed delegation link (workhub_delegation_assigned) in the coordination transcript. This link records the action ID, target Session identifier, and user text. The target Session retains full ownership of execution state; the coordination session only maintains a read-only projection, ensuring clean authority boundaries between coordination and execution.

Can multiple Runtime Hosts share the same coordination session?

No. The ADR mandates exactly one WorkHub coordination session per Runtime Host, identified by the constant WORKHUB_COORDINATION_SESSION_ID. This per-host isolation ensures that agents operating on different hosts cannot see or interfere with each other’s coordination state. Switching hosts effectively selects a different coordination session namespace, maintaining strict isolation boundaries across the apache/maka deployment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}