Package com.tnsai.coordination.handoff

package com.tnsai.coordination.handoff
Narrow, bounded task delegation between agents (TNS-117).

This package's API is intentionally small: a one-shot Handoff strategy invoked once between a sender and receiver, plus HandoffChain for stringing a fixed list of those one-shots end-to-end. Both compress everything the receiver needs into a HandoffContext payload at dispatch time. Once the receiver picks up the task, the sender's reasoning is gone — the receiver works from the payload alone.

That compression is the point when handoff is the right tool. It is the wrong default for everything else.

When to use Handoff

  • Dispatching a bounded sub-task to a specialised executor — the receiver has everything it needs in the payload and no reason to consult the sender's history.
  • Crossing a trust boundary — e.g. a sandboxed tool invocation where the receiver must not see the sender's full reasoning chain for security / least-privilege reasons.
  • Short-lived delegation where the receiver completes the task in one shot and the conversation ends.

When NOT to use Handoff

  • Multi-session continuity — when the receiver needs to pick up days or weeks of accumulated state, use ContextManagerHandle and SnapshotStore. Snapshots accumulate incrementally and survive process restarts; handoff payloads die with the dispatch.
  • Primary inter-agent reasoning — when the receiver needs to negotiate, debate, or refine with the sender, prefer the ROMA orchestrator-worker pattern (com.tnsai.coordination.roma) which preserves the reasoning trace across rounds. Handoff one-shots are structurally unable to support a follow-up question.
  • State that must survive compaction — when work spans enough context that the LLM will compact, use durable external state (e.g. tasks/handoff-*.md task contracts, persisted memory entries). Handoff payloads live in process memory until the dispatch resolves, then vanish.
  • Quality gates on agent output — when the goal is "have a different agent verify this result," use com.tnsai.coordination.judge. Judges keep both the candidate and its rationale visible to the next step; handoff collapses the rationale.

Why this matters

The naming and structure of this package make Handoff look like the default coordination mechanism — pass a task from A to B and you're done. Used as the default it produces the "every node works, the whole drifts" failure mode: each individual handoff is correct, but accumulated context loss across a chain of handoffs leaves the system unable to reason about earlier decisions.

The framework's architectural stance favours incremental context accumulation (snapshots, decision traces, external task files) over compressed baton-passing. Handoff is the escape hatch for the specific cases above — keep it in your toolbox, but reach for snapshots first.

See also: the Context-Engineering vs Role-Based doctrine in this module's documentation.

Since:
0.0.2
See Also:
  • Class
    Description
    ConditionalHandoff
    Routes a handoff to the first agent whose predicate matches the context.
    DefaultHandoff
    Default handoff implementation that transfers a task from one agent to another via AgentMessage and invokes the receiving agent's chat method.
    Handoff
    Strategy interface for executing a one-shot handoff between two agents.
    HandoffChain
    Chains multiple handoff steps into an A -> B -> C pipeline.
    HandoffChain.Builder
     
    HandoffContext
    Immutable context passed through a handoff between agents.
    HandoffListener
    Observer for handoff lifecycle events.
    HandoffMessageType
    Message types used in the handoff protocol.
    HandoffResult
    Immutable result of a handoff operation.