session

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package session 是会话域（自产品 internal/agent/session.go 迁入）：内存 注册表 + users/<op>/sessions/<sid>/session.json 落盘（用户隔离）。会话记录 = 发起人/状态/模式/模型快照/任务摘要 + 事件流（回看端点原样输出，应用层走 自有传输管线渲染）。存储经 Store 接口注入——数据面（唯一文件写入器）在应用。

状态：running | pending_approval | ended | error。

Index

Constants

View Source 
const (
	StateRunning         = contract.StateRunning
	StatePendingApproval = contract.StatePendingApproval
	StateEnded           = contract.StateEnded
	StateError           = contract.StateError
)

会话状态常量（契约形态）。

Variables

View Source 
var SessionTTLVar = 7 * 24 * time.Hour

SessionTTLVar 会话保留期（测试可缩短）。

Functions

func EventAs added in v0.5.0 

func EventAs[T any](ev Event) (T, bool)

EventAs 事件载荷的双形态统一取值器（Record 落 typed 原样、Reattach 盘面 回读是 map——data any 的固有双形态）。typed 直断言，map 经 JSON 往返还原， 失败 false。消费面统一走此取值器：此前各消费者自做归一（ui 手写往返、 sessionEndAt 手写双分支、feishu 仅断言 typed——盘面回放消费即静默空白， 审查 P2-8 收口）。

func ListPersistedRecent added in v0.2.0 

func ListPersistedRecent(st Store, owner string, n int) []string

ListPersistedRecent 最近的 n 个持久会话 sid（按 session.json 修改时间降序； 无记录文件或不可读的目录跳过）。n ≤0 返回空。

func ValidOwner added in v0.5.0 

func ValidOwner(op string) bool

ValidOwner operator（用户标识符）的结构围栏：非空、非 "." / ".."、不含 路径分隔符与 NUL——可含任意 Unicode（owner 是「张三」这类标识不是文件名 白名单）。operator 进 Store 前的入口面（ui 查询参数、渠道 InboundMsg） 应先过此栏：拦截的是「标识符携带路径形态穿越 users 树」的注入面。

Types

type ApprovalDecision 

type ApprovalDecision = contract.ApprovalDecision

ApprovalDecision 审批决议（approve 端点 → 包装工具消费；契约形态）。

type AskDecision 

type AskDecision = contract.AskDecision

AskDecision ask_user 作答（answer 端点 → askuser 工具消费；契约形态）。

type Attachment 

type Attachment = contract.Attachment

Attachment 用户消息附件（契约形态）。

type Event 

type Event = contract.Event

Event 已发事件（回放端点原样输出；契约形态）。

type PersistedDigest added in v0.2.0 

type PersistedDigest struct {
	SID       string
	Title     string
	Task      string
	Summary   string
	State     string
	UpdatedAt time.Time
	Messages  []*schema.Message
}

PersistedDigest 持久会话检索视图（轻字段 + 续聊历史——多模态在落盘时已 拍平为文本）。

func ReadPersisted added in v0.2.0 

func ReadPersisted(st Store, owner, sid string) (PersistedDigest, bool)

ReadPersisted 读单个持久会话的检索视图（不存在/损坏 = ok=false 不报错—— 检索面容忍缺页，调用方跳过即可）。

type QueuedMsg 

type QueuedMsg = contract.QueuedMsg

QueuedMsg 排队消息（契约形态；steering 入队，可编辑/删除）。

type Registry 

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

Registry 会话注册表（内存 + 磁盘合并读）。

func NewRegistry 

func NewRegistry(st Store) *Registry

NewRegistry 构造。

func (*Registry) Create 

func (r *Registry) Create(owner, task, mode string, model contract.UserPrefs) *Session

Create 新会话（默认态 running 由 Run 侧设置；此处先 ended 占位防并发窗）。 顺带触发一轮过期清理（2026-08-23 定：新建即触检，替代小时级后台任务—— 会话只在有人用时累积，新建时机天然自限；全量扫盘轻量）。

func (*Registry) Delete 

func (r *Registry) Delete(owner, sid string)

Delete 删除契约：停执行 → 内存摘除 → users/<op>/sessions/<sid>/ 与会话 工作区（用户域 workspaces/<sid>，含持久子区）整目录移除（停执行在 前——运行中的 Run 步间检查即中止；磁盘零残留）。返回 owner 供 api 层发起人校验（校验失败时调用方不得触达本方法——先 Detail 校验再删）。

func (*Registry) Detail 

func (r *Registry) Detail(sid string, since int) (SessionDetail, bool)

Detail 单会话详情（内存优先，缺则读盘；owner 不符由 api 层先校验）。since>0 时 events 只含 id>since 的增量（按标签缓存切回的增量追赶——缩 wire 载荷， 2026-08-26 会话切换提速）。

func (*Registry) DetailDisk 

func (r *Registry) DetailDisk(owner, sid string, since int) (SessionDetail, bool)

DetailDisk 磁盘历史会话详情（软恢复/回看：进程重启后；since 语义同 Detail）。

func (*Registry) Drain added in v0.3.0 

func (r *Registry) Drain(deadline time.Duration) []string

Drain 优雅停机收尾（A6）：对全部 running 态会话发取消 → 有界等执行体收尾 （取消走引擎 interruptUnlessStopped 既有链：终态事件 + 检查点 + 中断注记 全落）。到点仍未收尾的会话 SID 如实返回（调用方记日志，不阻塞停机—— 与强制退出同，但多数场景已收干净）。挂起态（pending_approval）无执行体 不在列——跨重启由 RearmPendingTimer 续表；执行体必在内存（Get 语义）。

func (*Registry) Fork added in v0.3.0 

func (r *Registry) Fork(owner, sid string) *Session

Fork 全量快照分叉（B8）：从既有会话复制当前完整态（事件流+历史+摘要+外置 域），生成新 SID 的新会话（= ForkAt 锚 0）。V1 限定源非 running（源 running 即返回 nil——升级位须先给 spill 写入与复制立同步点）。分叉体 State=ended 占位（Create 同款），Run 由应用发起。寻址同 Reattach 语义：内存优先，不在 内存则磁盘重建后再克隆（历史会话分叉是主场景）。挂起域/taskGrant/planSeq/ 排队消息不带（分叉体无执行体残留，与 Reattach 的不可续降级同裁决；任务期 写授权回审批流是安全侧）；spill 外置域整目录复制（history 含外置指针，不 复制即 read_file 取回落空）。

func (*Registry) ForkAt added in v0.5.0 

func (r *Registry) ForkAt(owner, sid string, anchor int) *Session

ForkAt 锚定分叉（ZCode「从已完成消息岔出」对位）：anchor = 源会话某条 session_end 事件 ID（载荷 HistLen>0 才可锚——旧存量零值事件不可锚）； anchor=0 即全量快照（Fork 同义）；负数一律 nil（fail-closed——非 0 即 要求合法锚）。截断语义：事件截至锚（含）、历史截至锚 HistLen、 fileChanges/summary 取锚事件载荷重建（锚后账目不随行）、事件 seq 接锚 ID。锚后 spill 余量照旧整目录复制（无害——callID 寻址不冲突）。 side 会话不可分叉；源 running/未知锚/数据不一致（HistLen 越界）一律 nil。

func (*Registry) Get 

func (r *Registry) Get(sid string) (*Session, bool)

Get 取会话（仅内存——运行态必在内存；历史会话经 Detail 读盘）。

func (*Registry) List 

func (r *Registry) List(owner string) []SessionListItem

List 我的会话（mine：内存 + 磁盘合并，内存覆盖同 sid；活动时间倒序）。

func (*Registry) ListAll 

func (r *Registry) ListAll() []SessionListItem

ListAll 全部用户全部会话（admin 视图）：内存全量 + 各用户磁盘合并（内存覆盖 同 sid；含已移除成员的历史目录——ListUsers 直扫语义），活动时间倒序截断。

func (*Registry) LoadHistory 

func (r *Registry) LoadHistory(s *Session)

LoadHistory 磁盘恢复续聊历史（进程重启后 Run 前调用；无历史 no-op）。

func (*Registry) Persist 

func (r *Registry) Persist(s *Session)

Persist 导出落盘口（Run 状态迁移调用）。

func (*Registry) Reattach 

func (r *Registry) Reattach(owner, sid string) *Session

Reattach 磁盘会话续接（进程重启后带 sid 再 POST：注册表重建会话 + 装载 历史；内存已有同 sid 直接回）。挂起审批态一并恢复（checkpoint 在盘，approve 端点可续流）——running 残留/旧格式挂起（无 pending_app_id，RecoverInterrupted 启动已翻，防御分支）落 ended。归属不符返回 nil。

func (*Registry) RecoverInterrupted 

func (r *Registry) RecoverInterrupted() int

RecoverInterrupted 进程启动孤儿清理：落盘仍处 running 的会话已无执行体 （进程重启丢内存态，watch/续聊皆死胡同），统一翻 error 终态并补一条中断 error 事件——列表显示「出错」，回放可见中断原因，点击可正常回看/接续。 挂起审批（pending_approval）例外——checkpoint 在盘、决议可续流（2026-08-24 定案：重启前挂起的审批卡跨重启可批准）：带 pending_app_id 且未到截止的保留 挂起（等 owner 决议）；停机期间已到截止的镜像超时器动作（approval_timeout/ ask_timeout 事件 + ended）；旧格式（无 pending_app_id）按 running 同样翻 error。 返回修复数（serve 启动调用一次）。

func (*Registry) Search 

func (r *Registry) Search(owner, q string) []SessionListItem

Search 我的会话关键词过滤（标题或任一用户消息文本包含 q，不区分大小写； 活动时间倒序——q 由 api 层 TrimSpace，空串 = 同 List）。

func (*Registry) SearchAll 

func (r *Registry) SearchAll(q string) []SessionListItem

SearchAll admin 全量关键词过滤（语义同 Search，跨全部用户）。

func (*Registry) Side added in v0.5.0 

func (r *Registry) Side(owner, sid string) *Session

Side 辅助对话：继承主会话当前历史快照的轻量派生会话（ZCode side chat 对位）。快照语义——创建后各自演化，父后续轮不流入；Model/Effort/Mode/ lastUsedModel 继承；事件流置空（界面从空白开始）+ 血缘 note（Kind: side） ；Summary/FileChanges/挂起域/排队消息不带。允许父 running（历史快照持锁 安全——主任务执行中问快速问题是核心场景）；spill/工作区由引擎侧父感知 共享（engine.wsSID）。side of side/归属不符/未知 sid 返回 nil。

func (*Registry) SidesOf added in v0.5.0 

func (r *Registry) SidesOf(owner, sid string) []string

SidesOf 主会话的辅助对话清单（内存 + 盘面扫——UI 寻址与级联删除共用； Store 无子树枚举面，os 直扫是 copySpill/Sweep 同先例）。

func (*Registry) Store 

func (r *Registry) Store() Store

Store 会话域存储出口（引擎会话域件装配用——计划文档写入走用户域文件面）。

func (*Registry) SweepTmpWorkspaces 

func (r *Registry) SweepTmpWorkspaces() int

SweepTmpWorkspaces 启动清扫会话工作区（用户域 workspaces/<sid>）：对照 磁盘会话（.agent/users/<op>/sessions/<sid>/），无对应会话**或会话已正常 结束**（任务收尾即清的主锚点漏网的兜底——崩溃前未及清的 ended 残留） 整删；挂起/异常态保留待续（跨重启可恢复）。顺带两代旧布局清场： DATA_DIR/workspaces 活会话 rename 搬入用户域（迁移后旧根移除，下次自然 空跑）；.tmp/workspaces 整树移除（旧位已弃用，树里全是孤儿）。返回清 理/迁移的目录数（serve 启动日志观测用）。

type Session 

type Session struct {
	SID   string             `json:"sid"`
	Owner string             `json:"owner"`
	Task  string             `json:"task"` // 会话列表任务摘要（首条用户消息截断）
	State string             `json:"state"`
	Mode  string             `json:"mode"`
	Title string             `json:"title"` // LLM 总结标题（首轮收尾异步生成；空 = 回退 Task 截断）
	Model contract.UserPrefs `json:"model"` // {model 复合键, effort} 快照（会话粘住）

	StartedAt time.Time `json:"started_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Events    []Event   `json:"events"`
	// contains filtered or unexported fields
}

Session 会话（Events 即消息流真源；mu 保护并发 emit/删除竞态）。

func (*Session) AppendHistory 

func (s *Session) AppendHistory(msgs ...*schema.Message)

AppendHistory 追加消息（user 输入与每轮 assistant 终态）。

func (*Session) BeginResume added in v0.3.0 

func (s *Session) BeginResume() bool

BeginResume 决议续流执行体抢占（单锁原子：查挂起 + 清挂起域 + 翻 running + 挂 runDone——BeginRun 同型三步）。判据用 curAppID 而非 State：挂起后 State 仍为 pending_approval，态检查挡不住并发双 Resume；curAppID 的查清在同一 锁段完成即闭合 check→Resume 的 TOCTOU 窗口。翻 running 同时修复续流执行 期的可见性（此前恒显 pending：FlushQueue 误报不可打断、Drain 枚举漏执行 体）。返回 false = 无挂起（重复/迟到 Resume 在此即拒——checkpoint 不随 Resume 消费，迟到调用放行是脏重放）。

func (*Session) BeginRun 

func (s *Session) BeginRun(mode string) bool

BeginRun 执行抢占（原子：态检查 + 翻 running + 模式置换一步完成）—— 任务后台化后同一会话防并发双执行体的闸门（api 层 POST /api/chat 启动前 调用；false = 活跃中，调用方走 steering 入队）。顺带挂 runDone（本轮执行体 结束信号——FlushQueue 打断当前执行后等其收尾再接管，防双执行体竞态）。

func (*Session) CancelRun 

func (s *Session) CancelRun()

CancelRun 取消运行中的执行体（停止按钮端点；无运行则 no-op）。执行体收 到取消后由 pump 中断收尾（中断事件 + error 终态落盘）。

func (*Session) ClearPendingIf added in v0.4.0 

func (s *Session) ClearPendingIf(appID string) ([]string, bool)

ClearPendingIf 条件原子清挂起（超时路径专用）：锁内校验「仍挂起该 appID 且 无决议到达」才清并返回项清单——闭合守卫检查与清挂起之间的 TOCTOU（用户 approve 与超时并发时抢到锁者赢，另一方让位）。项清单随清返回（清域后不可 再取——合并卡逐项落拒用）。askDecision 归提问路径（kind=ask 超时同样经此）。

func (*Session) ClearTaskGrant 

func (s *Session) ClearTaskGrant()

func (*Session) ClearTurnGrant 

func (s *Session) ClearTurnGrant()

func (*Session) CloneHistory 

func (s *Session) CloneHistory() []*schema.Message

CloneHistory 取历史快照（Run 组装输入用）。

func (*Session) ContinueOrNotify 

func (s *Session) ContinueOrNotify(msg string, wake bool) (began bool, q QueuedMsg)

ContinueOrNotify 后台完成通知的单锁原子注入原语（W-3）： 锁内一步裁定——running/pending/error → 通知入队（began=false，当前/ 下一轮 TakePending 消费）；ended（自然收口）+ wake → 翻 running + 挂 runDone + 通知入队（began=true，调用方锁外 Record notify_queued 后以 Run("") 起自续轮——通知经队列注入，输入路径与 steering 唯一）；ended + !wake → 只入队（自激护栏预算耗尽：不自动开轮，下轮用户交互消费）。 **error 终态绝不自续**（对照审查 A-3：用户停止把中断洗成模型请求是被 明确拒绝的形态；运行错误同理保守——通知只入队，下轮用户交互消费）。 竞态封闭依据：与 BeginRun/Steer 同锁互斥，TOCTOU 丢通知/丢启动窗口不 存在（单锁原语义，对照审查定案）。返回的 q 供锁外 Record（Record 自持 锁，锁内不可调）。

func (*Session) EditQueued 

func (s *Session) EditQueued(id, text string) bool

EditQueued 编辑排队消息（false = 不存在或系统通知只读）；落 steer_updated 回执。

func (*Session) EventsSince added in v0.5.0 

func (s *Session) EventsSince(from int) []Event

EventsSince 快照中 ID 大于 from 的事件（订阅通道满即弃的补投源——渠道 消费泵的间隙补投/节拍追赶与 ui SSE 慢消费兜底同源共用，见 engine/channel.go）。

func (*Session) FileChangesSnapshot 

func (s *Session) FileChangesSnapshot() []contract.FileChange

FileChangesSnapshot 会话累计变更清单（path 排序稳定输出）。

func (*Session) GrantTask 

func (s *Session) GrantTask()

GrantTask plan 档任务期写授权置位 / 查询 / 清零（计划批准置位；任务成功 收尾、档位变更、新计划提交时清零。不在轮末无条件清——轮次预算耗尽后 「继续」仍在授权期内，兑现「批准计划后一口气完成」）。

func (*Session) GrantTurn 

func (s *Session) GrantTurn()

GrantTurn plan 档本轮写授权置位 / 查询 / 清零。

func (*Session) HasPendingDecision added in v0.2.0 

func (s *Session) HasPendingDecision() bool

HasPendingDecision 挂起决议/作答是否已登记。决议到达（SetDecision/ SetDecisionFor/SetAskDecision）先于超时到点或 Resume 停表时，超时兜底 须让位——覆盖已到达的决议等于把用户的 approve 改写成超时拒绝。审批看 "" 槽与挂起项槽（批量决议逐项写入的非原子窗口：任一到达即让位，未决项 由 Resume 重放 fail-closed 兜底）；提问看 askDecision。

func (*Session) HasQueuedImages 

func (s *Session) HasQueuedImages() bool

HasQueuedImages 排队消息是否含图片附件（设置通道切模型的守卫：落回轮 无图片门禁兜底，纯文本模型 + 含图排队消息会在执行时炸——写入时拒）。

func (*Session) HistoryLen added in v0.5.0 

func (s *Session) HistoryLen() int

HistoryLen 历史长度（settleTurn 记 SessionEnd.HistLen 的取值面）。

func (*Session) MarkFlush 

func (s *Session) MarkFlush()

MarkFlush / TakeFlushMark 立即处理排队标记（FlushQueue 打断前置位； pump 中断收尾消费分叉事件形态）。

func (*Session) MarkTitleFlight 

func (s *Session) MarkTitleFlight() func()

MarkTitleFlight 标记标题异步生成在途（返回收尾闭包；引擎 settleTurn 起 genTitle goroutine 前调用）。genTitle 是唯一逃逸 Run 生命周期的写者—— Run 返回 ≠ 写完，此信号让测试收尾/删除方可确定性等待在途写落地。

func (*Session) ModePublic 

func (s *Session) ModePublic() string

ModePublic 模式读取（包装器组装用）。

func (*Session) ModelSnapshot added in v0.4.0 

func (s *Session) ModelSnapshot() contract.UserPrefs

ModelSnapshot 模型复合键持锁快照（PUT settings 类随时写路径与引擎读并发， 裸读 s.Model.Model 构成 data race）。

func (*Session) NextPlanSeq 

func (s *Session) NextPlanSeq() int

NextPlanSeq 计划文档序号自增取号（提交即定号——文档先落盘再挂起，跨重启 由 sessionRecord.PlanSeq 接续）。

func (*Session) NoteModelCall added in v0.4.0 

func (s *Session) NoteModelCall(model string)

NoteModelCall 模型调用边界登记（engine.assemble 每次模型调用前调）：本次 将用模型与上次实际调用不同 → 落 model_change 注记（UI 切换标志）。首调/ 跨重启无前序只登记不落。lastUsedModel 随记录持久化（跨重启比对不断）。

func (*Session) NotifyBudget 

func (s *Session) NotifyBudget(budget int) bool

NotifyBudget 自激护栏预算（W-3）：budget = 连续自续上限。true = 还有预算 （消费一格）；false = 已耗尽（调用方降级仅记事件）。用户消息消费恢复预算 （RestoreNotifyBudget——通知自身不恢复，dsh spentWakes 同款）。

func (*Session) ParentOf added in v0.5.0 

func (s *Session) ParentOf() string

ParentOf 父会话 SID（辅助对话；空 = 普通会话）。构造后不变，无锁直读。

func (*Session) ParticipantsOf added in v0.5.0 

func (s *Session) ParticipantsOf() []contract.Participant

ParticipantsOf 名册快照。

func (*Session) PendingAppID 

func (s *Session) PendingAppID() string

PendingAppID 当前挂起审批 ID。

func (*Session) PendingDueOf 

func (s *Session) PendingDueOf() (string, time.Time)

PendingDueOf 挂起计时元数据读取（RearmPendingTimer 续表用）。

func (*Session) PendingItems 

func (s *Session) PendingItems() []string

PendingItems 项标识清单快照（超时批量拒 / approve 端点覆盖校验）。

func (*Session) PendingTarget added in v0.5.0 

func (s *Session) PendingTarget() string

PendingTarget 挂起审批的路由目标（空 = 无目标不校验）。

func (*Session) QueueLen 

func (s *Session) QueueLen() int

QueueLen 排队消息数（flush 端点空队列守卫）。

func (*Session) Record 

func (s *Session) Record(name string, data any) Event

Record 追加事件（seq 自增；已停止会话不再记录——删除后磁盘零残留）。 记录即扇出到旁观订阅（M5-2）。

func (*Session) RecordAskDecision 

func (s *Session) RecordAskDecision(askID string, d AskDecision)

RecordAskDecision 作答回执落流（answer 端点在 SetAskDecision 后调用—— 切回/回放重建提问卡终态的真源）。

func (*Session) RecordDecision 

func (s *Session) RecordDecision(appID string, d ApprovalDecision, items ...contract.ItemDecisionOut)

RecordDecision 决议回执落流（approve 端点在 SetDecision 后调用）。事件流是 切回/回放重建审批卡终态的真源——决议只 Set 不落流，卡片永远停在待审批态。 items = 合并决议卡的逐项回执（分歧态以 Items 为准——契约声明的真源面， 审查 P2-16 落码：此前从不填充，批一拒一的回放无法重建逐项终态）；单卡 决议空参零变化。

func (*Session) RecordFileChange 

func (s *Session) RecordFileChange(path, action string)

RecordFileChange 工具层报备入口（ctx 记录器直连；并发安全）。

func (*Session) RecordPlanDecision 

func (s *Session) RecordPlanDecision(planID string, d ApprovalDecision)

RecordPlanDecision 计划决议回执落流（approve 端点按 pending_kind=plan 分叉 调用；切回/回放重建计划卡终态的真源）。

func (*Session) RemoveQueued 

func (s *Session) RemoveQueued(id string) bool

RemoveQueued 移除排队消息（false = 不存在或系统通知不可删）；落 steer_removed 回执。

func (*Session) ReorderQueued 

func (s *Session) ReorderQueued(ids []string) bool

ReorderQueued 排队消息重排（UI-B3 拖拽排序——ids = 期望顺序的完整清单； 集合与现存不一致整体拒（多/少/未知 id，防并发丢消息）；成功落 steer_reordered 回执——回放重建顺序的真源）。

func (*Session) RestoreNotifyBudget 

func (s *Session) RestoreNotifyBudget()

RestoreNotifyBudget 用户输入到达本轮输入（Run/Resume 头部消费到非 notify 条目）时恢复全部自续预算。

func (*Session) RunDone 

func (s *Session) RunDone() <-chan struct{}

RunDone 执行体结束信号快照（nil = 无执行体）。

func (*Session) RunFinished 

func (s *Session) RunFinished()

RunFinished 执行体收尾（Run/Resume defer 调用；摘下并关闭 runDone—— 等待者以 close 为同步点，此后 BeginRun 才可能创建新通道，无别名竞态）。

func (*Session) SetAskDecision 

func (s *Session) SetAskDecision(d AskDecision)

SetAskDecision 登记作答（answer 端点调用）。

func (*Session) SetCancel 

func (s *Session) SetCancel(c context.CancelFunc)

SetCancel 挂运行取消口（Stop 时取消）。

func (*Session) SetDecision 

func (s *Session) SetDecision(d ApprovalDecision)

SetDecision 登记决议（approve 端点调用；幂等覆盖前值无意义——单审批通道）。 旧单决议路径（plan 决议/超时兜底/升级前重放）：落 "" 槽。

func (*Session) SetDecisionFor 

func (s *Session) SetDecisionFor(itemID string, d ApprovalDecision)

SetDecisionFor 按项登记决议（合并决议多槽——approve 端点批量形态逐项写入）。

func (*Session) SetMode 

func (s *Session) SetMode(mode string)

SetMode 模式设置（设置通道与随轮次写入共用，docs/05；换档收口见 setModeLocked——同步快照字段 s.Model.Mode，detail/设置回执回显用）。

func (*Session) SetPendingApproval 

func (s *Session) SetPendingApproval(appID string)

SetPendingApproval 挂起登记（approval_request 已发；空 id = 清挂起态）。

func (*Session) SetPendingDue 

func (s *Session) SetPendingDue(kind string, due time.Time)

SetPendingDue 挂起计时元数据登记（startApprovalTimer 挂表时同步调用—— 挂起态落盘在 finishOf 其后，元数据随之持久；跨重启续表依据）。

func (*Session) SetPendingItems 

func (s *Session) SetPendingItems(ids []string)

SetPendingItems 合并决议卡项标识清单登记（pump 聚合发卡后调用；与 SetPendingApproval 同生命周期——清挂起态时一并清空）。

func (*Session) SetPendingTarget added in v0.5.0 

func (s *Session) SetPendingTarget(id string)

SetPendingTarget 挂起审批的路由目标（T6：Options.ApprovalRouter 裁决后 泵面写入；空 = 不路由）。

func (*Session) SetRunModel 

func (s *Session) SetRunModel(model, effort string)

SetRunModel 会话内切换模型/effort（BeginRun 抢占成功后由 API 层调用—— 运行边界生效：当前执行体不被打断，新值从本轮起用；空值保持现值。 换模型不作废任务期授权——授权跟任务不跟模型）。切换只记录不落事件—— 切换标志注记在调用边界（NoteModelCall：本次调用与上次实际调用比对， 2026-09-03 用户定调——选择器切换与显示标志是两回事）。

func (*Session) SetState 

func (s *Session) SetState(state string)

SetState 状态迁移 + 更新时间。

func (*Session) SetTitle 

func (s *Session) SetTitle(title string)

SetTitle / TitleOf 标题读写（genTitle 异步写）。

func (*Session) SetTurnActor added in v0.5.0 

func (s *Session) SetTurnActor(p *contract.Participant)

SetTurnActor 当轮说话人（T6：渠道/应用在 Run 前设置）。

func (*Session) SetTurnFirst added in v0.5.1 

func (s *Session) SetTurnFirst(first bool)

SetTurnFirst 轮次首轮标记（Run 入口判定：本轮开始前历史无 assistant； 跨审批中断保留——挂起段 flushAcc 入史不污染判定，Resume 收尾消费）。

func (*Session) SetTurnUserMsg 

func (s *Session) SetTurnUserMsg(msg string)

SetTurnUserMsg / TakeTurnUserMsg 轮次用户消息（跨审批中断保留——Resume 完成 时随 assistant 终态一并入历史）。

func (*Session) SnapshotEvents 

func (s *Session) SnapshotEvents() []Event

SnapshotEvents 事件快照（追赶回放源）。

func (*Session) StateOf 

func (s *Session) StateOf() string

StateOf 当前状态读取（与 State 字段区分）。

func (*Session) Steer 

func (s *Session) Steer(msg string, atts []Attachment, mode string) bool

Steer running/pending 中再输入：入队 + 模式即时切换（docs/05）。 返回 false = 会话空闲（走正常 Run 而非 steering）。入队落 steer_queued 事件——排队态可回放重建（切回/刷新不丢，对齐审批决议回执定案）。

func (*Session) SteerBy added in v0.5.0 

func (s *Session) SteerBy(actor *contract.Participant, msg string, atts []Attachment, mode string) bool

SteerBy 带说话人入队（T6 多参与者：群聊中他人消息排队不丢身份—— 排队消息与 steer_queued 事件携带 Speaker，运行中注入/下轮前置均署名）。

func (*Session) Stop 

func (s *Session) Stop()

Stop 删除会话的停止语义：置位 + close 通道 + 取消运行上下文（幂等）。

func (*Session) Stopped 

func (s *Session) Stopped() bool

Stopped 删除置位检查。

func (*Session) Subscribe 

func (s *Session) Subscribe() (chan Event, int)

Subscribe 旁观订阅（返回通道与订阅时最新事件 ID——追赶回放去重基准）。 慢消费者不阻塞运行：通道满即丢弃（旁观是尽力而为视图，回看端点兜底完整流）。

func (*Session) SummaryOf 

func (s *Session) SummaryOf() string

SummaryOf 取列表摘要（公开读取——引擎 session_end 载荷用）。

func (*Session) TakeAskDecision 

func (s *Session) TakeAskDecision() *AskDecision

TakeAskDecision 取走作答（Resume 消费；取后清空防复用）。

func (*Session) TakeDecision 

func (s *Session) TakeDecision() *ApprovalDecision

TakeDecision 取走决议（Resume 消费；取后清空防复用）。

func (*Session) TakeDecisionFor 

func (s *Session) TakeDecisionFor(itemID string) *ApprovalDecision

TakeDecisionFor 按项取走决议（Resume 重放时各审批工具按保存态 item_id 领各自的；取后清空防复用；无决议 = nil → fail-closed 拒绝）。

func (*Session) TakeFlushMark 

func (s *Session) TakeFlushMark() bool

func (*Session) TakePending 

func (s *Session) TakePending() []QueuedMsg

TakePending 取走排队消息（Run 前置带回——排队兜底路径）。

func (*Session) TakeTurnUserMsg 

func (s *Session) TakeTurnUserMsg() string

func (*Session) TaskGranted 

func (s *Session) TaskGranted() bool

func (*Session) TaskOf added in v0.2.0 

func (s *Session) TaskOf() string

TaskOf 会话任务摘要读（首条用户消息截断——与落盘 sessionRecord.Task 同源； recall 检索与 TurnEpilogue 交接载荷用）。

func (*Session) TitleFlight 

func (s *Session) TitleFlight() <-chan struct{}

TitleFlight 标题生成在途信号：nil = 无在途；关闭 = 写收尾完成。

func (*Session) TitleOf 

func (s *Session) TitleOf() string

func (*Session) TurnActorOf added in v0.5.0 

func (s *Session) TurnActorOf() *contract.Participant

TurnActorOf 当轮说话人（nil = 单用户零变化——引擎回退 Owner 语义）。

func (*Session) TurnFirstOf added in v0.5.1 

func (s *Session) TurnFirstOf() bool

TurnFirstOf 轮次首轮标记读取（settleTurn 标题触发依据）。

func (*Session) TurnGranted 

func (s *Session) TurnGranted() bool

func (*Session) TurnUserMsgOf 

func (s *Session) TurnUserMsgOf() string

TurnUserMsgOf 轮次用户消息读取（标题生成输入）。

func (*Session) Unsubscribe 

func (s *Session) Unsubscribe(ch chan Event)

Unsubscribe 摘除订阅（断连/收尾）。

func (*Session) UpsertParticipant added in v0.5.0 

func (s *Session) UpsertParticipant(p contract.Participant) string

UpsertParticipant 名册登记（T6）：首见落 joined、在册变更落 updated （participant_update 事件——回放重建 roster 的真源，不依赖 session.json 快照）。Name/Role 空值不覆盖在册值（部分更新）。返回变更 Kind（无变更 空串）；Kind 封闭集含 left（移除面待第一个消费者，本批不开）。

type SessionDetail 

type SessionDetail struct {
	SID       string             `json:"sid"`
	Owner     string             `json:"owner"`
	State     string             `json:"state"`
	Title     string             `json:"title"`
	Mode      string             `json:"mode"`  // 会话当前档位（前端切回恢复 composer 显示）
	Model     contract.UserPrefs `json:"model"` // 会话模型快照（创建时粘住——前端恢复显示用）
	StartedAt string             `json:"started_at"`
	UpdatedAt string             `json:"updated_at"` // 最新活动时间（头部展示）
	Events    []Event            `json:"events"`
}

SessionDetail 回看/软恢复载荷（字段契约 = M3-2 桩 detail）。

type SessionListItem 

type SessionListItem struct {
	SID       string `json:"sid"`
	Owner     string `json:"owner"`
	State     string `json:"state"`
	Title     string `json:"title"` // Title || Task（存量兼容回退）
	StartedAt string `json:"started_at"`
	UpdatedAt string `json:"updated_at"` // 最新活动时间（列表展示与排序键）
	Summary   string `json:"summary"`
}

SessionListItem 列表条目（活动时间倒序；字段契约 = M3-2 桩 + 2026-08-23 增 updated_at）。

type Store 

type Store interface {
	ReadUserTreeFile(operator, rel string) ([]byte, bool)
	WriteUserTreeFile(operator, rel string, data []byte) error
	RemoveUserTree(operator, rel string) error
	// UserTreeDir 用户域根绝对路径（.agent/users/<op>；会话工作区
	// workspaces/<sid> 在其下——Delete/Sweep 清理链用）。契约：须为本地
	// 文件系统路径——Sweeper 与 recall 检索（persist_read.go）直用 os 操作，
	// 文件保存会话是本基座唯一支持的存储形态（无 DB 型实现需求）。
	UserTreeDir(operator string) string
	ListUserTreeSessions(operator string) []string
	ListUsers() []string
	TmpDir() string
	Dir() string
}

Store 会话域存储面（应用注入——产品 FileStore 结构性满足）。 契约：operator 是用户标识符——实现方构造用户域路径时必须圈禁（结构规则 见 ValidOwner：无路径分隔符、非 ./.. ——否则 operator 可携带 ../ 穿越 users/<op>/ 树读写区外，安全审查 2026-09-06）。

type Sweeper 

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

Sweeper 过期清理器（触发 = Registry.Create 新建会话顺带全量扫一轮， 2026-08-23 定——无后台定时任务）。

func NewSweeper 

func NewSweeper(st Store, reg *Registry) *Sweeper

NewSweeper 构造。

func (*Sweeper) RunOnce 

func (s *Sweeper) RunOnce(now time.Time) int

RunOnce 扫一轮：各用户 sessions/ 下超期（按活动时间 UpdatedAt，7 天无活动） 目录整删 + 内存幽灵摘除（内存活跃会话跳过——7 天 TTL 不可能与运行中会话 相交，防御性判断）。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.