dispatch

type Answer ¶

type Answer struct {
	// Resolution is the text of the answer, or the note on a verdict.
	Resolution string
	// Allow is the verdict on a permission prompt. Ignored for a question.
	Allow bool
}

Answer is a caller's resolution of a park.

For a QUESTION, Resolution is the words. For a PERMISSION prompt, Allow is the verdict and Resolution is the person's own note, which reaches the model as the reason — never a stock phrase, because "Approved. Continue." is an instruction for a new turn and means nothing to a tool call that is waiting.

type AssistantObserver ¶

type AssistantObserver interface {
	Assistant(AssistantResult)
}

AssistantObserver is an optional Observer extension. It is called only when the receipt confirms successful completion; incomplete assistant output is already available through Text.

type AssistantResult ¶

type AssistantResult struct {
	Content  string
	Complete bool
	Duration time.Duration
}

AssistantResult is the completed assistant response and its active model time. It is an optional observer extension for consumers that bill or render model timing separately from tool timing.

type Noop ¶

type Noop struct{}

Noop satisfies Observer and does nothing. Embed it to implement a subset.

func (Noop) Aborted(context.Context) error

func (Noop) Assistant(AssistantResult)

func (Noop) Checkpoint(Snapshot)

func (Noop) Text(string)

func (Noop) ToolEnd(ToolResult)

func (Noop) ToolStart(string, string, string)

type Observer ¶

type Observer interface {
	// Text receives prose the harness produced, in order. A caller showing a
	// person the turn streams it; one that only records it concatenates it.
	// Summary.Text is the same prose, accumulated, so a caller need not.
	Text(delta string)
	// ToolStart announces a tool call the harness began. ID correlates it
	// with its ToolEnd. A call the harness reported in one piece produces
	// both at once.
	ToolStart(id, name, args string)
	// ToolEnd reports a tool call finishing. An attempt that ended with a call
	// still open produces a ToolEnd for it with Failed set and Result saying
	// so, so a transcript never holds a call open forever.
	ToolEnd(ToolResult)
	// Checkpoint offers a point the attempt can be re-joined at — nothing is
	// half-consumed when it fires. A caller that survives its own restart
	// persists it; one that does not ignores it.
	Checkpoint(Snapshot)
	// Aborted is consulted at every point the follow could stop cleanly: before
	// each reconnect and between quiet streams. A non-nil error stops the
	// follow with that error and Outcome.Receipt as last read. This is how a
	// caller's own durable cancel flag — one that outlives the context it
	// handed in — reaches the loop.
	Aborted(ctx context.Context) error
}

Observer receives what an attempt's stream says, as it says it.

Every method is optional in the sense that Noop satisfies all of them: a caller that only wants the Outcome passes Noop and gets exactly that. A caller with a transcript to keep, or a cancel flag of its own to honour, implements the methods it needs and embeds Noop for the rest.

Nothing here is a verdict. The stream is reported, not interpreted: whether a tool call should have been allowed, or whether a question is one the caller's users may answer, is the caller's business after Follow returns.

type Outcome ¶

type Outcome struct {
	Receipt  runner.Receipt
	Position Position
	Summary  Summary
	Parked   *Parked
	// Snapshot is the complete normalizer state at Position. It is useful when
	// the attempt parks before the next quiet-stream checkpoint.
	Snapshot Snapshot
}

Outcome is how a follow ended. Receipt is the authority; Position is where the attempt stands; Parked is set when the receipt is needs_input.

func Follow(ctx context.Context, r Runner, receipt runner.Receipt, from Position, obs Observer) (Outcome, error)

func FollowSnapshot(ctx context.Context, r Runner, receipt runner.Receipt, snap Snapshot, obs Observer) (Outcome, error)

func Rejoin(ctx context.Context, r Runner, pos Position, obs Observer) (Outcome, error)

func RejoinSnapshot(ctx context.Context, r Runner, snap Snapshot, obs Observer) (Outcome, error)

func Resume(ctx context.Context, r Runner, req runner.ResumeRequest, from Position, obs Observer) (Outcome, error)

func ResumeSnapshot(ctx context.Context, r Runner, req runner.ResumeRequest, snap Snapshot, obs Observer) (Outcome, error)

func Start(ctx context.Context, r Runner, req runner.StartRequest, obs Observer) (Outcome, error)

func (o Outcome) Completed() bool

func (o Outcome) Terminal() bool

type Parked ¶

type Parked struct {
	Question   *runner.Clarification
	Permission *runner.PermissionRequest
}

Parked describes a needs_input receipt. Exactly one field is set, and the two are answered differently: a Question with words, a Permission with a verdict on the named call. See Answer.

type Position ¶

type Position struct {
	TaskID    string
	AttemptID string
	Epoch     uint64
	SessionID string
	// Cursor is the last event consumed, so a re-join tails from there instead
	// of re-streaming what the caller has already recorded.
	Cursor uint64
	// ClarificationID is what a resume must echo to answer the QUESTION the
	// harness asked; PermissionID is what it must echo to answer a PERMISSION
	// prompt. They are different parks that resume differently, and at most
	// one is set.
	ClarificationID string
	PermissionID    string
}

Position is where an attempt can be re-joined: the coordinates of work in flight, not a snapshot of it. The harness holds the transcript; re-joining is addressing the same attempt at the same cursor.

Every field a receipt reports is taken from the receipt when it is set, and the session id in particular is AUTHORITATIVE: a harness may fork its session on a resume, and chaining onto what was sent would continue a conversation nobody is having.

func (p *Position) Observe(receipt runner.Receipt)

type Runner ¶

type Runner interface {
	Start(ctx context.Context, req runner.StartRequest) (runner.Receipt, error)
	Resume(ctx context.Context, req runner.ResumeRequest) (runner.Receipt, error)
	Cancel(ctx context.Context, req runner.CancelRequest) (runner.Receipt, error)
	Inspect(ctx context.Context, attemptID string) (runner.Receipt, error)
	Events(ctx context.Context, attemptID string, after uint64) (Stream, error)
}

Runner is the runner surface the lifecycle needs.

It is an interface for one reason: *client.Client reaches a real machine through kcp and an edges Service proxy, and a test that had to stand that up would be testing the plumbing instead of the rules. Every method is a method of *client.Client with the same name and signature, so this is a seam rather than an abstraction — Wrap is the only implementation that speaks to a runner.

func Wrap(c *client.Client) Runner

type Snapshot ¶

type Snapshot struct {
	Position Position
	Usage    Usage
	// State is the opaque, versioned state of the event normalizer. Callers that
	// only need to rejoin the runner may omit it; callers that must preserve a
	// transcript and dedupe state should persist the complete Snapshot.
	State json.RawMessage
}

Snapshot is a Position plus what the follow had accumulated when it was taken. It is what Observer.Checkpoint offers.

func RestoreSnapshot(ctx context.Context, r Runner, pos Position, obs Observer) (Snapshot, error)

type Stream ¶

type Stream interface {
	Next(ctx context.Context) (runner.Event, error)
	Close() error
}

Stream is one live read of an attempt's events. Next ends in io.EOF when the runner closes a quiet stream, which is ordinary: the runner does that after a silent interval so a caller resumes from its cursor instead of holding one connection open for the length of a coding turn.

type Summary ¶

type Summary struct {
	// Text is every piece of prose the harness produced, in order.
	Text string
	// Final is the harness's own answer record when it produced one, and
	// otherwise the text. It is the presentation answer.
	Final string
	// Usage is what THIS follow saw reported. A caller re-joining an attempt
	// adds what it had already recorded.
	Usage Usage
}

Summary is what the stream said, accumulated, so a caller need not.

type ToolResult ¶

type ToolResult struct {
	ID     string
	Name   string
	Args   string
	Result string
	Failed bool
	// Duration is the elapsed time reported by the harness, when available.
	Duration time.Duration
}

ToolResult is one finished tool call.

type Usage ¶

type Usage struct {
	InputTokens  int64
	OutputTokens int64
	CostMicros   int64
}

Usage is what an attempt reported spending. Where a harness reports tokens and no price the cost stays zero: a number invented from a token count and a guessed rate would be wrong in a billing column.