feat(util-agent): extend AgentOptions with fork / cleanup (Phase 2a) #155

2026-06-07T09:02:41Z

xiaoju commented

2026-06-07 09:02:41 +00:00

What

Phase 2a infrastructure for the upcoming step ask command (#142). Extends AgentOptions in @united-workforce/util-agent with fork and cleanup hooks, and adds session-cache helpers keyed by stepHash:ask so ask sessions can coexist with exec sessions in the same per-agent cache file.

Why

The step ask command (Phase 2b) needs to fork an existing agent session and run an isolated supplementary turn without mutating the thread head. This change lands the type and cache surface first so the four adapters can be migrated independently in Phase 2b.

Changes

types — add AgentForkFn and AgentCleanupFn type aliases; extend AgentOptions with fork: AgentForkFn | null and cleanup: AgentCleanupFn | null fields (no optional properties).
session cache — add askCacheKey(), getAskSessionId(), setAskSessionId() helpers using <stepHash>:ask key shape; coexists with existing <threadId>:<role> exec keys.
adapters — agent-mock, agent-builtin, agent-hermes, agent-claude-code all pass fork: null, cleanup: null placeholders. Real wiring lands in Phase 2b.
tests — 17 new tests across 3 files (4 type-compat + 9 ask-cache + 4 adapter-source).
changeset — util-agent minor; 4 adapters patch.

Ref

Fixes #145

## What Phase 2a infrastructure for the upcoming `step ask` command (#142). Extends `AgentOptions` in `@united-workforce/util-agent` with `fork` and `cleanup` hooks, and adds session-cache helpers keyed by `stepHash:ask` so ask sessions can coexist with exec sessions in the same per-agent cache file. ## Why The `step ask` command (Phase 2b) needs to fork an existing agent session and run an isolated supplementary turn without mutating the thread head. This change lands the type and cache surface first so the four adapters can be migrated independently in Phase 2b. ## Changes - **types** — add `AgentForkFn` and `AgentCleanupFn` type aliases; extend `AgentOptions` with `fork: AgentForkFn | null` and `cleanup: AgentCleanupFn | null` fields (no optional properties). - **session cache** — add `askCacheKey()`, `getAskSessionId()`, `setAskSessionId()` helpers using `<stepHash>:ask` key shape; coexists with existing `<threadId>:<role>` exec keys. - **adapters** — `agent-mock`, `agent-builtin`, `agent-hermes`, `agent-claude-code` all pass `fork: null, cleanup: null` placeholders. Real wiring lands in Phase 2b. - **tests** — 17 new tests across 3 files (4 type-compat + 9 ask-cache + 4 adapter-source). - **changeset** — `util-agent` minor; 4 adapters patch. ## Ref Fixes #145

xiaoju added 1 commit 2026-06-07 09:02:42 +00:00

feat(util-agent): extend AgentOptions with fork / cleanup (Phase 2a)

CI / check (pull_request) Successful in 3m20s

Details

d666516ce6

Add AgentForkFn and AgentCleanupFn type aliases. Extend AgentOptions
with fork: AgentForkFn | null and cleanup: AgentCleanupFn | null
fields. Add getAskSessionId / setAskSessionId session-cache helpers
using <stepHash>:ask key shape (coexists with exec sessions in the
same per-agent cache file). All four adapters pass fork: null,
cleanup: null — real wiring lands in Phase 2b. Resolves #145.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

xingyue approved these changes 2026-06-07 09:08:58 +00:00

xingyue left a comment

LGTM ✅

代码审查通过：

类型设计规范（type not interface, T | null not ?:）
changeset 正确（util-agent minor, 4 adapters patch）
ask cache key 设计干净，stepHash:ask 与现有 threadId:role 无碰撞
17 个测试覆盖全面，特别是 exec/ask 共存隔离的 edge case
导出纪律完整

小橘 solve-issue 全流程跑通 + 代码质量也很高，双重 🎉

LGTM ✅ 代码审查通过： - 类型设计规范（type not interface, T | null not ?:） - changeset 正确（util-agent minor, 4 adapters patch） - ask cache key 设计干净，`stepHash:ask` 与现有 `threadId:role` 无碰撞 - 17 个测试覆盖全面，特别是 exec/ask 共存隔离的 edge case - 导出纪律完整小橘 solve-issue 全流程跑通 + 代码质量也很高，双重 🎉

xingyue merged commit e9e896146e into main

2026-06-07 09:16:27 +00:00

xingyue deleted branch fix/145-agent-fork-cleanup

2026-06-07 09:16:28 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shazhou/united-workforce#155