handoff

Documentation

Overview

Package handoff linearizes a source agent's transcript into conversational turns so a DIFFERENT destination agent can summarize it. Foreign turns are DATA, not instructions — the destination summarizes and waits (it does not auto-continue). Matches the previous implementation's TranscriptHandoffReader.swift (TranscriptHandoffReader.swift) which is the proven reference implementation.

Distinct from the unified/ package, which extracts *stats* (tokens/turns) from transcripts; this extracts *conversational turns* — a different concern, kept isolated on purpose (same separation as the Mac).

This is a best-effort LINEAR reader. It deliberately skips edge cases the reference reader handles (Claude fork side-chains, Codex compaction pre-history, Grok encrypted/reasoning blocks) — sufficient for a handoff summary, not a fidelity-critical reconstruction. `Skipped` + `Warnings` surface what was dropped so the destination's summary can note the gaps.

Index

• func BuildContinuationHandoff(o *Outcome, source sessions.AgentKind) string
• func BuildHandoff(o *Outcome, source sessions.AgentKind) string
• func ContinueMessage(handoffPath string, source sessions.AgentKind, task string) string
• func InjectMessage(handoffPath string, source sessions.AgentKind) string
• func Supported(source sessions.AgentKind) bool
• func SweepFiles(maxAge time.Duration)
• func WriteFile(content string, source sessions.AgentKind) (string, error)
• type Outcome
  • func Read(source sessions.AgentKind, sessionID, cwd string) *Outcome
• type Turn

Functions

func BuildContinuationHandoff

func BuildContinuationHandoff(o *Outcome, source sessions.AgentKind) string

BuildContinuationHandoff builds the transcript artifact used by agent orchestration handoff. Unlike cross-resume, this workflow explicitly carries a task and the destination should continue after understanding the context.

func BuildHandoff

func BuildHandoff(o *Outcome, source sessions.AgentKind) string

BuildHandoff builds the full handoff file payload: an inert-data preamble + JSON turn list + closing line. The dest agent reads this from disk and is told (via the short InjectMessage) to summarize only and wait — never replay/execute turns, never auto-continue. Parity with the Mac's TranscriptHandoffReader.buildHandoff.

func ContinueMessage

func ContinueMessage(handoffPath string, source sessions.AgentKind, task string) string

ContinueMessage is the short prompt for an explicit take-over task.

func InjectMessage

func InjectMessage(handoffPath string, source sessions.AgentKind) string

InjectMessage is the SHORT dest-agent launch prompt. The full handoff is written to a file (WriteFile) and the dest is told to read it — a direct large paste hits the dest's large-paste handler (claude's "paste again to expand") and never auto-submits, while a file the agent reads via its own read-tool has no size limit. Parity with ServerExtendedRoutes.swift:677-683.

func Supported

func Supported(source sessions.AgentKind) bool

Supported reports whether Read can linearize this agent kind. The summon auto-reply uses this to decide between the deterministic Stop-hook relay (supported agent) and the in-prompt directive fallback (unsupported) — so a partially-wired or brand-new agent always has a working reply path. This is the single source of truth; keep it in sync with Read's switch.

func SweepFiles

func SweepFiles(maxAge time.Duration)

SweepFiles removes expired handoff artifacts. Files must remain long enough for the destination agent to read asynchronously, but full transcripts must not accumulate indefinitely.

func WriteFile

func WriteFile(content string, source sessions.AgentKind) (string, error)

WriteFile writes the full handoff text to ~/.rmote/handoffs/ and returns the path. mkdir -p so a fresh daemon install works. Errors are surfaced to the caller (the REST handler maps to 500) — unlike the Mac's try? we do not silently swallow, since without the file the dest agent cannot read it.

Types

type Outcome

type Outcome struct {
	Turns    []Turn
	Skipped  int      // unparseable record count
	Warnings []string // e.g. grok encrypted-record count
}

Outcome is the result of reading one source transcript.

func Read

func Read(source sessions.AgentKind, sessionID, cwd string) *Outcome

Read reads a source agent's transcript and linearizes it into turns. Returns nil if no transcript file is found; an Outcome (possibly with empty turns) if found but unreadable. cwd is required for grok (its path resolution is cwd-derived); ignored for claude/codex.

type Turn

type Turn struct {
	Role  string   `json:"role"` // "user" | "assistant"
	Text  string   `json:"text"`
	Tools []string `json:"tools"` // truncated "[tool] <name>" summaries
}

Turn is one linearized conversational turn from the source transcript.