interject

package
v0.52.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package interject answers a message that arrives while a conversation's main turn is still running, without stopping it.

The relay forks the main session (session/fork), asks the fork the new message, posts the fork's short answer at once, and lets the fork's own verdict decide what happens to the main turn:

None   — the answer was enough; main never sees the exchange.
Inform — the side Q&A (plus an optional note from the fork) is
         injected into the running main turn, which keeps going.
Abort  — the relay cancels the main turn.

When the agent advertises the fir steer extension (SteerCap), Ask delivers natively: None and Abort are logged with _fir/session/steer mode "record" (a side_query transcript entry the LLM never sees) and Inform is sent with mode "steer". Reply.Delivered reports it.

Without the extension — or when steer finds no running turn — the exchange is kept and Take hands it back once as a prefix for the next main prompt; the relay handles an undelivered Inform as before (cancel main, re-prompt). Every interrupt forks afresh; earlier side Q&A of the same turn is carried into the fork as text until Take.

Index

Constants

View Source
const (
	SteerCap    = "dev.fir.steer/v1"
	SteerMethod = "_fir/session/steer"
)

SteerCap is the agentCapabilities._meta key of the fir steer extension; SteerMethod is its method.

View Source
const DefaultMinConf = 7

DefaultMinConf is the confidence below which a verdict becomes None.

View Source
const Instruction = `` /* 853-byte string literal not displayed */

Instruction is the rule appended to every fork prompt.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action

type Action int

Action is the fork's verdict on the main turn.

const (
	None Action = iota + 1
	Inform
	Abort
)

Actions, numbered as the fork reports them.

func (Action) String

func (a Action) String() string

String returns the action's tag word.

type Agent

type Agent interface {
	ForkSession(ctx context.Context, cwd string, parent acp.SessionId, at string, sink client.SessionUpdateSink) (acp.SessionId, error)
	Prompt(ctx context.Context, sid acp.SessionId, prompt []acp.ContentBlock) (acp.StopReason, error)
	CloseSession(ctx context.Context, sid acp.SessionId) error
	Caps() client.Caps
	ExtMethod(ctx context.Context, sid acp.SessionId, method string, params map[string]any) (json.RawMessage, error)
}

Agent is the agent surface used. *client.AgentProc satisfies it.

type Config

type Config struct {
	Enabled bool `json:"enabled" yaml:"enabled"`
	// MinConf (0-9) is the confidence a verdict needs to act; 0 means
	// DefaultMinConf.
	MinConf int `json:"min_conf" yaml:"min_conf"`
	// Logf, when set, receives a line for each exchange the agent
	// refused, so a fallback to cancel-and-reprompt is never silent.
	Logf func(format string, args ...any) `json:"-" yaml:"-"`
}

Config is the relay's opt-in. The zero value is disabled.

type Interjector

type Interjector struct {
	// contains filtered or unexported fields
}

Interjector keeps the per-conversation side state. Safe for concurrent use.

func New

func New(agent Agent, cfg Config) *Interjector

New returns an Interjector, or nil when cfg is disabled — so a relay can test `ij != nil`.

func (*Interjector) Ask

func (i *Interjector) Ask(ctx context.Context, conv, cwd string, parent acp.SessionId, text string) (Reply, error)

Ask forks parent, asks it text, delivers the verdict to parent when the agent supports it, and returns the answer. On a fork error (including client.ErrForkUnsupported) the caller falls back to its old behaviour. The fork is closed before Ask returns. Bound ctx: the fork prompt has no timeout of its own. Text may be empty when the fork gave only a verdict.

func (*Interjector) Take

func (i *Interjector) Take(conv string) string

Take returns the prefix for conv's next main prompt — the side Q&A the agent did not take natively — and resets conv's side state. "" when there is none. Call it when building every main prompt: it is what resets the side state for the next turn.

type Reply

type Reply struct {
	Text   string // the answer, verdict and NOTE lines stripped
	Note   string // optional note from the fork for the main agent; Inform only
	Action Action // after the confidence gate
	Conf   int    // -1 when the verdict line did not parse
	// Delivered: the agent took the exchange natively (record or
	// steer), so it is not in Take. An undelivered Inform is the
	// relay's to handle (cancel main and re-prompt).
	Delivered bool
}

Reply is the fork's answer.

func Parse

func Parse(out string) Reply

Parse splits the fork's output into the answer, an optional "NOTE:" line just before the verdict, and the verdict line "ACTION CONF". An unparseable last line yields the whole text, None and conf -1.

func (Reply) Tag

func (r Reply) Tag() string

Tag is the marker a relay puts on the posted answer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL