Documentation
¶
Overview ¶
Package agent 提供 Agent Registry 与 Turn/Step 双循环执行器。
对齐上游:packages/core/agent + agent-loop
设计要点:
- Agent 通过 Inbox 双队列(turn 队列)接收 Run/Followup 输入;
- 后台 worker 串行处理 turn(单 Turn 串行保证):turn/start → claim → pre-step → 多 Step → turn-stopping → turn/end;
- 每个 Step:step/start → 派生 → agent/request → llm/stream → assistant/chunk* → 若含工具调用则经 M23 四级流水线执行 → step/end;
- step/tool 错误 → agent/error 写入日志,turn 以 interrupted 关闭;
- pending turn 超过队列容量 → ErrTurnQueueFull(reject)。
本文件对应任务 M18:Agent Cancel 原因分类(5 类)。
对齐上游:packages/core/agent/Agent.ts
Cancel 的取消原因通过 turn-stopping 事件记录为 "cancel:<cause>"; 上层读取日志时用 ExtractCancelCause 还原分类,turn/end 以 aborted 关闭。
本文件复刻官方 packages/core/agent/src/consumed-work.ts。
它回答 Turn/Step 词汇单独回答不了的问题:一份 agent 日志到底结算了哪些被消费的工作? 只看 turn/end 会把"在首个 step 前就中止的 turn"和"被拒绝/空 claim 产生的平衡 no-op turn" 混为一谈——要么把半途而废的工作误记为完成,要么冤枉每个 no-op。
缺失的事实来自收件箱自身的记录:Inbox 每次变更都带 removedCount,取消会标 outcome='canceled',据此区分"一个 claim 了输入的 turn"与"工作未运行即被丢弃"。
Package agent 的 Inbox 收件箱实现。
对齐官方 packages/core/agent/src/inbox.ts。
Inbox 是 Agent 拥有的两个有序待处理消息列表的增量投影:
- next-turn:等待各个 turn 的提示
- next-step:等待下一个 step 边界的输入
本文件对应任务 M33:Agent Initiator 上下文(安全归因)。
对齐上游:packages/core/agent initiator module
设计要点:
- withInitiator 在 context 中注入当前发起操作的 Agent 身份 + 操作名;
- requireInitiator 在无 withInitiator 包裹的调用点返回 Unauthorized 结构化错误 (不允许静默放行,阻断"匿名发起"的安全隐患);
- withoutInitiator 显式清除 initiator(进入不受控区域时隔离身份)。
本文件复刻官方 packages/core/agent/src/model-selection.ts 的核心语义。
官方用两个 waterfall(system-prompt/assemble、agent/request)把"可变的模型选择" 耦合到 prompt 装配与请求路由:prompt 装配前快照所选模型,请求时应用该快照, 从而一次并发切换只在后续 step 生效,不会把"装配面"与"请求面"撕裂成两个模型。
omnix 的 sysprompt 是同步 Assembler(非 Cordis 异步事件),因此这里不照搬事件 接线,而是把 current/assembled 双快照固化为一个并发安全的小状态机,由 Agent 在 同步装配/请求的对应位置显式调用 Capture / Apply。
Package agent 的配置与运行时类型。
对齐官方 packages/core/agent/src/runtime-types.ts 和 types.ts。
本文件对应任务 M34:agent/request-error 重试瀑布。
对齐上游:packages/core/agent-loop request-error waterfall
设计要点:
- RequestErrorAction{kind} 只有两种:'retry'(显式重试通道)与 'abort'(终止);
- request-error waterfall 复用 M02 waterfall 洋葱链:各中间件按序判定动作,可短路; 未命中任何中间件时落到 TerminalRetryDecision 兜底;
- 与 S15(LLM Retry)协同:S15 在 LLM 层做一次退避重试并写 llm/retry 事件;若仍失败 (达 max 上抛),进入本 request-error 瀑布决定 retry 或 abort;
- 超过 max 次重试 → abort,并以 error 关闭当前 turn(写 agent/error 事件)。
Index ¶
- Variables
- func RecordCancel(sl *session.SessionLog, cause CancelCause) error
- func RecordRequestError(log *session.SessionLog, err error)
- func ShouldRetryError(err error) bool
- func WithInitiator(ctx context.Context, agentID brand.SessionID, op string) context.Context
- func WithoutInitiator(ctx context.Context) context.Context
- type Agent
- func (a *Agent) Cancel(cause CancelCause)
- func (a *Agent) CancelWithOptions(cause CancelCause, opts CancelOptions)
- func (a *Agent) Dispose()
- func (a *Agent) Followup(input string) error
- func (a *Agent) Inbox() *Inbox
- func (a *Agent) Log() *session.SessionLog
- func (a *Agent) Options() AgentOptions
- func (a *Agent) Run(input string) error
- func (a *Agent) SetRunContext(parent context.Context, timeout time.Duration)
- func (a *Agent) SetToolProvider(fn func(name string) *tools.Tool)
- func (a *Agent) Status() AgentStatus
- func (a *Agent) WhenIdle(ctx context.Context) error
- type AgentOptions
- type AgentStatus
- type CancelCause
- type CancelOptions
- type ConsumedWork
- type Inbox
- func (inbox *Inbox) Claim(log *session.SessionLog, target session.InboxTarget, turn uint64) []UserMessage
- func (inbox *Inbox) Clear(log *session.SessionLog)
- func (inbox *Inbox) HasPending() bool
- func (inbox *Inbox) NextStep() []UserMessage
- func (inbox *Inbox) NextTurn() []UserMessage
- func (inbox *Inbox) Push(log *session.SessionLog, target session.InboxTarget, message UserMessage)
- type InboxNotifications
- type Initiator
- type ModelSelection
- type ModelSelectionRef
- type PreStepDecision
- type RequestConfig
- type RequestErrorAction
- type RequestErrorActionKind
- type RequestErrorPayload
- type RequestErrorWaterfall
- type SessionStartSource
- type UnauthorizedInitiatorError
- type UserMessage
Constants ¶
This section is empty.
Variables ¶
var ErrDisposed = errors.New("agent: disposed")
ErrTurnQueueFull 表示 pending turn 队列已满(拒绝新的 Run/Followup)。
var ErrTurnQueueFull = errors.New("agent: turn queue full, reject pending turn")
Functions ¶
func RecordCancel ¶
func RecordCancel(sl *session.SessionLog, cause CancelCause) error
RecordCancel 记录一次取消原因(写入 turn-stopping 事件)。
func RecordRequestError ¶
func RecordRequestError(log *session.SessionLog, err error)
RecordRequestError 把一次请求错误写入会话日志(agent/error 事件),供审计。 log 可为 nil(此时跳过)。
func ShouldRetryError ¶
ShouldRetryError 复用 llm 分类:仅 overload / rate-limit 可重试。
func WithInitiator ¶
WithInitiator 返回携带 initiator 的 context。
Types ¶
type Agent ¶
type Agent struct {
// ID 会话 ID(复用 SessionLog 的 ID)。
ID brand.SessionID
// contains filtered or unexported fields
}
Agent 是代理执行器。
func NewAgent ¶
func NewAgent(id brand.SessionID, log *session.SessionLog, sys *sysprompt.Assembler, pipeline *tools.Pipeline, adapter llm.LLMAdapter, options ...AgentOptions) *Agent
NewAgent 创建代理。 adapter 可为 nil(测试时由 Start 前的 mock 注入)。 options 可为 nil(使用默认配置)。
func (*Agent) Cancel ¶
func (a *Agent) Cancel(cause CancelCause)
Cancel aborts the active turn and discards queued work unless KeepInbox is set.
func (*Agent) CancelWithOptions ¶
func (a *Agent) CancelWithOptions(cause CancelCause, opts CancelOptions)
func (*Agent) Dispose ¶
func (a *Agent) Dispose()
Dispose permanently closes the agent and cancels active and pending work. Tool and adapter implementations must honor context cancellation.
func (*Agent) SetRunContext ¶
SetRunContext 绑定本次运行的上游 ctx(H01):可取消父 ctx + 可选超时预算。 timeout<=0 uses DefaultTimeout, or only parent cancellation when both are zero.
func (*Agent) SetToolProvider ¶
SetToolProvider 注入工具解析函数。
type AgentOptions ¶
type AgentOptions struct {
// Provider 路由名称(调用时必须有已注册的适配器)。
// 为空时使用适配器的默认 provider。
Provider string `json:"provider,omitempty"`
// Model 是由选定 provider 适配器解释的模型 ID。
// 为空时使用适配器的默认模型。
Model string `json:"model,omitempty"`
// ReasoningEffort 是适配器拥有的推理努力级别(provider/model 相关)。
// 为空时使用适配器的默认设置。
ReasoningEffort string `json:"reasoningEffort,omitempty"`
// MaxTokens 是每次对话模型请求的最大输出 token 数。
// 为 0 时使用适配器的默认限制。
MaxTokens int `json:"maxTokens,omitempty"`
// DefaultTimeout 是每次运行的默认超时(0 表示无超时)。
DefaultTimeout time.Duration `json:"defaultTimeout,omitempty"`
}
AgentOptions 是 Agent 的创建配置(对齐官方 AgentOptions)。
这些选项在 Agent 创建时固定,运行时不可变。Persona 属于 system-prompt 部分,不在此配置中。
type AgentStatus ¶
type AgentStatus string
AgentStatus 是 Agent 的生命周期状态(对齐官方 AgentStatus)。
在每次状态转换时通过 agent/status 事件发出:
- idle:没有驱动程序活动
- running:当唤醒输入开始可取消的 pre-step 处理时开始, 持续到驱动程序耗尽、关闭或检查点 turns
Disposal 将 Agent 从其注册表中移除;它不是第三个可观察状态。
const ( // StatusIdle 表示 Agent 当前空闲(没有活动的驱动程序)。 StatusIdle AgentStatus = "idle" // StatusRunning 表示 Agent 正在运行(有活动的驱动程序)。 StatusRunning AgentStatus = "running" )
type CancelCause ¶
type CancelCause string
CancelCause 是取消原因分类(M18:5 类)。
const ( // CancelUser 用户主动取消。 CancelUser CancelCause = "user" // CancelParent 父代理取消(subagent 场景)。 CancelParent CancelCause = "parent" // CancelHook hook 因拒绝触发取消。 CancelHook CancelCause = "hook" // CancelDisposed 代理被释放(dispose)导致的取消。 CancelDisposed CancelCause = "disposed" // CancelLegacy 历史/兼容性取消路径。 CancelLegacy CancelCause = "legacy" )
取消原因枚举(与上游 Agent.Cancel 的 5 类对齐)。
func ExtractCancelCause ¶
func ExtractCancelCause(events []session.SessionEvent) (CancelCause, bool)
ExtractCancelCause 从事件日志中提取最后一次取消原因分类。 返回 (cause, true) 表示存在取消记录;否则 (cause, false)。
type CancelOptions ¶
type CancelOptions struct {
// KeepInbox 保留排队和引导中的 inbox 项,而不是丢弃它们。
// 活动的 turn 仍然被中止,但未开始和待处理的工作会保留供后续 turn 使用,
// 并且不会记录 canceled inbox splice。
KeepInbox bool `json:"keepInbox,omitempty"`
}
CancelOptions 是取消选项(对齐官方 CancelOptions)。
type ConsumedWork ¶
type ConsumedWork struct {
// End 是最后一个结算了已消费工作的已关闭 turn:它进入过模型 step,
// 或 claim 了收件箱输入后失败/被中止/被拒绝。没有任何 turn 结算工作时为 nil。
End *session.SessionEvent
// DroppedUnrun 表示在上述 turn 之后,已被接受的工作在收件箱中被取消、从未运行。
// 这是"任何 turn 都来不及打开就被取消的输入"唯一的账目——没有 turn/end 描述它。
DroppedUnrun bool
}
ConsumedWork 是一份 agent 日志对其消费工作的结算。
func FoldConsumedWork ¶
func FoldConsumedWork(events []session.SessionEvent) ConsumedWork
FoldConsumedWork 单遍折叠一份 agent 日志(或其拥有的后缀),得到已消费工作的结算。 每个输入都是日志本身,调用方无需在取消前采样实时状态,因此任何人发起的取消 (持有者的 teardown、祖先的中断、卸载中的插件)都得到一致读法。
type Inbox ¶
type Inbox struct {
// contains filtered or unexported fields
}
Inbox 是持久化 Agent 收件箱事件的增量投影。
它维护两个列表:next-turn 和 next-step,并通过 splice 操作进行变更。
func NewInbox ¶
func NewInbox(log *session.SessionLog, notifications InboxNotifications) *Inbox
NewInbox 创建一个新的 Inbox,并从会话日志中重放所有 agent/inbox/spliced 事件。
func (*Inbox) Claim ¶
func (inbox *Inbox) Claim(log *session.SessionLog, target session.InboxTarget, turn uint64) []UserMessage
Claim 移除并返回为一个 step 提议的完整批次,并发布每条认领的消息。 持久化 splice 是纯删除。
target 表示此边界是否还消费一个排队的 turn。 turn 是将拥有该批次的 turn 编号。 返回 next-step 输入,后跟排队的 turn(如果请求)。
func (*Inbox) Clear ¶
func (inbox *Inbox) Clear(log *session.SessionLog)
Clear 持久化取消所有待处理输入,先清除 next-step 再清除 next-turn。
func (*Inbox) NextStep ¶
func (inbox *Inbox) NextStep() []UserMessage
NextStep 返回等待下一个 step 边界的输入(只读)。
func (*Inbox) NextTurn ¶
func (inbox *Inbox) NextTurn() []UserMessage
NextTurn 返回等待下一个 turn 的消息(只读)。
func (*Inbox) Push ¶
func (inbox *Inbox) Push(log *session.SessionLog, target session.InboxTarget, message UserMessage)
Push 追加一条消息到指定列表的末尾,并持久化。
type InboxNotifications ¶
type InboxNotifications struct {
// Inserted 发布一条插入的消息。
Inserted func(message UserMessage)
// Discarded 发布一条丢弃的消息。
Discarded func(message UserMessage)
// Claimed 在其拥有的 turn 内发布一条认领的消息。
Claimed func(message UserMessage, turn uint64)
}
InboxNotifications 是 Inbox 变更的实时通知。
type Initiator ¶
type Initiator struct {
// AgentID 发起操作的 Agent 会话 ID。
AgentID brand.SessionID
// Op 操作名(如 "Run" / "Followup" / "executeTool")。
Op string
}
Initiator 描述一次操作的发起者。
func MustInitiator ¶
MustInitiator 便捷版本:无 initiator 时 panic(用于内部已保证有 initiator 的调用点)。
type ModelSelection ¶
type ModelSelection struct {
// Provider 已注册的提供方路由。
Provider string
// Model 提供方拥有的模型 id。
Model string
// ReasoningEffort 适配器拥有的推理努力;为空表示采用提供方/默认行为。
ReasoningEffort string
}
ModelSelection 是为一次活跃 Agent 选定的完整 provider/model 及可选推理努力。
type ModelSelectionRef ¶
type ModelSelectionRef struct {
// contains filtered or unexported fields
}
ModelSelectionRef 是可变模型选择 + 为当前 step 捕获的快照。
func NewModelSelectionRef ¶
func NewModelSelectionRef() *ModelSelectionRef
NewModelSelectionRef 创建空选择器。
func (*ModelSelectionRef) Apply ¶
func (r *ModelSelectionRef) Apply(cfg RequestConfig) RequestConfig
Apply 用当前 step 捕获的快照改写请求配置,对齐官方 agent/request 语义:
- 没有捕获选择 → 原样返回(继承配置);
- 有捕获 → 先清除继承的 reasoningEffort,再应用 provider/model; 捕获自带 effort 则写入,为空则保持清除(恢复所选模型的提供方/默认行为)。
func (*ModelSelectionRef) Assembled ¶
func (r *ModelSelectionRef) Assembled() *ModelSelection
Assembled 返回当前 step 已捕获快照的拷贝。
func (*ModelSelectionRef) Capture ¶
func (r *ModelSelectionRef) Capture() *ModelSelection
Capture 在一次 step 的 prompt 装配边界调用:把当前 current 冻结为 assembled, 返回该快照(即便 current 为 nil 也返回 nil,表示本 step 不指定模型)。
func (*ModelSelectionRef) Current ¶
func (r *ModelSelectionRef) Current() *ModelSelection
Current 返回当前选择的拷贝。
func (*ModelSelectionRef) Select ¶
func (r *ModelSelectionRef) Select(sel *ModelSelection)
Select 更新"下一步"要用的选择(可在运行期并发切换;nil 表示清除选择、用默认)。
type PreStepDecision ¶
type PreStepDecision struct {
// Kind 是决策类型:"reject" 或 "enter"。
Kind string `json:"kind"`
// Messages 是进入 step 时携带的用户消息(Kind=enter 时有效)。
Messages []UserMessage `json:"messages,omitempty"`
// StartsRequestSeries 表示在此 step 的已接纳消息之前启动一个不同的
// model-message 系列(Kind=enter 时可选)。
StartsRequestSeries bool `json:"startsRequestSeries,omitempty"`
}
PreStepDecision 是循环是否以及携带哪些消息进入提议的 step (对齐官方 PreStepDecision)。
func EnterPreStep ¶
func EnterPreStep(messages ...UserMessage) PreStepDecision
EnterPreStep 创建一个 enter 决策(携带指定消息进入 step)。
type RequestConfig ¶
RequestConfig 是一次模型请求中与模型路由相关的可改字段。
type RequestErrorAction ¶
type RequestErrorAction struct {
// Kind 动作类型。
Kind RequestErrorActionKind `json:"kind"`
// Reason 决策原因(审计)。
Reason string `json:"reason,omitempty"`
}
RequestErrorAction 是一次 request-error 的决策结果。
func ResolveRequestError ¶
func ResolveRequestError(chain *RequestErrorWaterfall, p *RequestErrorPayload) RequestErrorAction
ResolveRequestError 运行 request-error 瀑布得到最终动作。
- 若某个中间件写入了 p.Action 则直接返回;
- 否则链放行到兜底:应用 TerminalRetryDecision。
func TerminalRetryDecision ¶
func TerminalRetryDecision(p *RequestErrorPayload) RequestErrorAction
TerminalRetryDecision 是兜底终端决策: 错误可重试且未超过最大次数 → retry;否则 abort(并以 error 关闭 turn)。
type RequestErrorActionKind ¶
type RequestErrorActionKind string
RequestErrorActionKind 是 request-error 处理动作类型。
const ( ActionRetry RequestErrorActionKind = "retry" ActionAbort RequestErrorActionKind = "abort" )
动作枚举:仅 retry 与 abort 两种。
type RequestErrorPayload ¶
type RequestErrorPayload struct {
// Err 触发请求错误的底层错误。
Err error
// RetryCount 已发生的重试次数。
RetryCount int
// MaxRetries 允许的最大重试次数。
MaxRetries int
// RetryableError 错误是否可重试(overload/rate-limit)。
RetryableError bool
// Action 由瀑布写入的最终动作。
Action *RequestErrorAction
}
RequestErrorPayload 是 request-error 瀑布的共享载荷。
func NewRequestErrorPayload ¶
func NewRequestErrorPayload(err error, retryCount, maxRetries int) *RequestErrorPayload
NewRequestErrorPayload 构造载荷并预计算可重试性。
type RequestErrorWaterfall ¶
type RequestErrorWaterfall = waterfall.Chain[RequestErrorPayload]
RequestErrorWaterfall 是 request-error 处理瀑布(复用 M02 waterfall.Chain)。 中间件可通过写入 p.Action 并短路(不调用 next)终止链。
func NewRequestErrorWaterfall ¶
func NewRequestErrorWaterfall(handlers ...waterfall.Handler[RequestErrorPayload]) *RequestErrorWaterfall
NewRequestErrorWaterfall 构建 request-error 瀑布链。
type SessionStartSource ¶
type SessionStartSource string
SessionStartSource 是会话生命周期开始的原因 (对齐官方 SessionStartSource)。
- startup:种子创建
- resume:持久化加载
- clear:清除后重新开始
- compact:压缩后重新开始
const ( // StartSourceStartup 表示种子创建。 StartSourceStartup SessionStartSource = "startup" // StartSourceResume 表示持久化加载。 StartSourceResume SessionStartSource = "resume" // StartSourceClear 表示清除后重新开始。 StartSourceClear SessionStartSource = "clear" // StartSourceCompact 表示压缩后重新开始。 StartSourceCompact SessionStartSource = "compact" )
type UnauthorizedInitiatorError ¶
type UnauthorizedInitiatorError struct {
}
UnauthorizedInitiatorError 表示在无 initiator 包裹时调用了 requireInitiator。
func (*UnauthorizedInitiatorError) Error ¶
func (e *UnauthorizedInitiatorError) Error() string
Error 实现 error 接口。
type UserMessage ¶
type UserMessage struct {
// ID 是消息 ID。
ID string `json:"id"`
// Content 是消息内容。
Content string `json:"content"`
// Source 是消息来源("run" / "followup" / "inbox" 等)。
Source string `json:"source,omitempty"`
// CreatedAt 是创建时间。
CreatedAt time.Time `json:"createdAt,omitempty"`
}
UserMessage 是用户消息(简化版,对齐官方 UserMessage)。