From cbf28caef1ba52aef45a8cd83b30841800167dba Mon Sep 17 00:00:00 2001 From: NoHarry Date: Fri, 6 Nov 2026 23:01:57 -0800 Subject: [PATCH 01/40] docs: record API review and approved repair decisions Preserve the review handoff before grouped repairs; keep Bothy phone and location filtering disabled as explicitly requested. Co-Authored-By: Codex --- AGENTS.md | 2 +- docs/design/public-api-redesign-handoff.md | 2 + docs/design/public-api-redesign-review.md | 295 +++++++++++++++++++++ docs/design/public-api-redesign.md | 4 +- 4 files changed, 300 insertions(+), 3 deletions(-) create mode 100644 docs/design/public-api-redesign-review.md diff --git a/AGENTS.md b/AGENTS.md index 90ca9f4..a573605 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ An embeddable agent runtime for Android and the JVM. Gradle project at the repos | `samples/` | `quickstart-jvm`, `quickstart-android`, `minimal`, `extensions` (offline; its test runs in CI) (not published) | | `buildSrc/` | `SourceRulesTask` | | `tools/` | Python helpers and fixtures; `agent-runtime` tests read `tools/fixtures` | -| `docs/design/` | Designs for upcoming work; read the one that matches your task before changing the public API (`public-api-redesign.md`: the Thread / Turn / Item API replacing the current one in 0.5.0; section 9.3 approved on 2026-11-06; start from `public-api-redesign-handoff.md`) | +| `docs/design/` | Designs for upcoming work; read the one that matches your task before changing the public API (`public-api-redesign.md`: the Thread / Turn / Item API replacing the current one in 0.5.0; section 9.3 approved on 2026-11-06; start from `public-api-redesign-handoff.md`, then `public-api-redesign-review.md` (fixes required before releasing 0.5.0)) | ## Rules diff --git a/docs/design/public-api-redesign-handoff.md b/docs/design/public-api-redesign-handoff.md index cd2cf56..0ba1ab6 100644 --- a/docs/design/public-api-redesign-handoff.md +++ b/docs/design/public-api-redesign-handoff.md @@ -5,6 +5,8 @@ > 接手更新(2026-11-06):owner 已在接手会话确认「全部按 9.3 推荐实施」。下文关于 9.2 / 9.3 等确认的记录是交接时的状态,不再是开工阻塞;Maven Central 发布仍需单独授权。实现使用 `codex/api-redesign` 分支和独立 worktree。 +> **2026-11-07 评审:先读 `public-api-redesign-review.md`。** 实现(SDK `dc90409`、Bothy `6713dd08`)经独立评审,发现一批发布前必须修的问题;0.5.0 不发,Bothy 不推,下一步是按那份文档修复。下面第 2 节是实现者自己记录的状态,评审结论以那份文档为准。 + ## 1. 一句话 0.5.0 把运行时(`android-agent-runtime`)的对外 API 换成 Codex 那样的 Thread / Turn / Item,同时把 Bothy 一次迁完,之后两边都不再做结构性迁移。 diff --git a/docs/design/public-api-redesign-review.md b/docs/design/public-api-redesign-review.md new file mode 100644 index 0000000..3cd3646 --- /dev/null +++ b/docs/design/public-api-redesign-review.md @@ -0,0 +1,295 @@ +# 0.5.0 实现评审与修复交接 + +> 写于 2026-11-07,给接手修复的模型。先读完这份,再按需查 `public-api-redesign.md`(设计稿)和 `public-api-redesign-handoff.md`(仓库、规矩、命令)。 +> 评审对象:SDK `dc90409`「feat!: replace the public runtime API with threads and turns」;Bothy 分支 `codex/api-redesign`(`724125f0`、`6713dd08`,基于 `c6502c86`)。 +> 评审方法:四路只读评审(公开 API、会话运行逻辑、持久化和隐私、Bothy 迁移),每条都按代码路径追过,没有运行。标了 ✔ 的几条又由我亲自读代码核对过。行号以 `dc90409` 和 `6713dd08` 为准,动手前请自己再看一遍。 +> 和 owner 交流用中文。 + +## 1. 结论 + +- 方向和主体结构是对的,设计稿的大部分内容都做出来了,CI 也是绿的。第 9 节列了确认没问题的部分,不要动。 +- **0.5.0 先不发。** 0.5.0 一发,主线 API 和扩展接口就要承诺稳定,现在还有一批公开 API 的问题和行为 bug,发布后再改就是破坏兼容。 +- **Bothy 分支先不推。** 有几处用户看得见的倒退,提交也要整理。 +- 修复的范围和顺序见第 4 到第 8 节。第 2 节的几件事要先问 owner。 + +## 2. 动手前先问 owner 的事 + +每项都附了我的推荐。owner 没回答之前,不要实现这几项。 + +1. **拒绝之后,这一轮是结束还是接着跑?** + - 现在:拒绝会让整轮以 `TurnFailed(CONFIRMATION_DENIED)` 结束,测试也锁定了这个行为。 + - 设计稿 4.6 写的是拒绝之后同一个流接着跑。 + - 后果:在「全部拒绝」下,每个要批准的轮次都会直接失败,模型连解释的机会都没有。 + - **推荐:接着跑。** 把「用户拒绝」作为工具结果交给模型,让模型告诉用户这件事做不了。 +2. **存盘时,最终答案和用户的话要不要遮?** + - 现在:会话快照里的最终答案和用户输入都过了电话号码规则,重启后显示的和当时不一样。这和 owner 之前定的「答案不过滤」矛盾。 + - **推荐:不遮。** 工具的参数和结果按 JSON 结构过滤(见 4.3 第 5 条),过滤规则和事件日志一致。 +3. **Bothy 关掉电话号码和位置过滤,同不同意?** + - 现在:`SharedRuntimeAssembly.kt:21` 用 `phones = false, locations = false`。后果是 trace 和会话存储会把电话号码和位置明文写到磁盘,超出了设计稿「落盘照旧过滤」的说法。 + - **推荐:落盘照旧过滤。** 界面拿到的条目本来就是原文,Bothy 没必要为了显示关掉落盘过滤。 +4. **0.4.0 留下的旧会话怎么处理?**(影响小,可以和上面几项一起问) + - 现在:`listThreads` 看不到旧会话,`items()` 是空的(4.3 第 2 条)。 + - **推荐:只在 CHANGELOG 里写清楚,不做导入。** 0.4.0 的模型历史本来就只在内存里;Bothy 自己有转录存储,用户感觉不到。 + +### Owner 已确认的处理方式(本轮修复) + +1. 拒绝批准后继续运行,把拒绝作为工具结果交给模型。 +2. 最终答案和用户输入持久化时保留原文;工具参数/结果按 JSON 结构过滤。 +3. Bothy 保持关闭电话号码和位置过滤。这是 owner 的明确选择,覆盖上面的推荐;密钥仍过滤。 +4. 不导入 0.4.0 旧历史,只在 CHANGELOG 说明。 + +以上四项已确认,不再作为修复阻塞。Maven 发布仍未授权。 + +## 3. 现状和注意事项 + +- **SDK**:`dc90409` 已经推到 `origin/main` 和 `origin/codex/api-redesign`,两个工作区都在这个提交上: + - 主工作区 `~/project/android-agent-runtime`(main); + - `~/project/android-agent-runtime-api`(`codex/api-redesign`)。 +- **0.5.0 没发**,`VERSION_NAME` 还是 `0.5.0-SNAPSHOT`。发布要 owner 点头。 +- **本机 Bothy 编不过了。** 停在 main 的几个 Bothy 目录(`~/project/bothy-server`、`~/project/bothy`、`~/project/bothy-pr5`)默认编旁边的 SDK 源码;SDK main 已经换成新 API,这些目录现在都编不过。要编的话加 `-PagentRuntimeDir=`,改用 Maven 上的 0.4.0。Bothy 在 GitHub 上的发布流程本来就用 Maven,不受影响。 +- **Bothy 的迁移**在 `~/project/bothy-api`(分支 `codex/api-redesign`),没推送。它编的是 `~/project/android-agent-runtime`(也就是 SDK main)。 +- **修复怎么提交**: + - 在 `codex/api-redesign` 上按组提交:公开 API、行为、持久化、文档,各一组。 + - 每组做一次独立评审再推送。 + - 全部做完再把 main 快进过去。 + - 不要再把几十个文件塞进一个提交。 +- 规矩照 `public-api-redesign-handoff.md` 第 4 节。尤其注意两条: + - 用 NoHarry 身份提交; + - 新 API 发布到 Maven 之前,Bothy 不能推送用到它的代码。 + +## 4. SDK 必须修的 + +### 4.1 公开 API(发布后再改就是破坏兼容) + +1. **✔ `resumeThread` 只要带了任何选项,就会把存下来的批准策略改回 `ASK`。** + - 位置:`agent-api/.../TurnInput.kt:31-38`(`approvalPolicy` 不能为空,默认 `ASK`);`agent-runtime/.../thread/DefaultThreadRuntime.kt:52-56`(只有选项完全等于默认值时才保留存下来的策略)。 + - 例子:`resumeThread(id, ThreadOptions(scene = "x"))` 会把存下来的 `APPROVE_ALL` / `REMEMBER` / `DENY_ALL` 改成 `ASK`。model、workspace、scene、instructions 也没法在恢复时清空。 + - 修法:`approvalPolicy` 改成可空(null 表示沿用),逐字段合并。KDoc 写明 null 就是沿用。 + - 测试:恢复会话时只改 scene,批准策略保持不变。 +2. **✔ `settings()` 会冲掉前面 `limits()` 设好的预算。** + - 位置:`AgentRuntimeBuilder.kt:420-424` 无条件调用 `limits(settings.limits)`。 + - 例子:`.limits(LoopLimits(maxModelRounds = 50)).settings(LoopSettings(narration = c))` 会把轮数、工具调用数、时间和重试预算都恢复成默认值。 + - 修法:从 `LoopSettings` 里去掉 `limits`(它有自己的 builder 方法),或者改成可空、只在非空时应用。 +3. **稳定和实验标记反了。** + - `NarrationCheck`(`spi/NarrationCheck.kt:12`)、`ServiceAnswerCheck`(`:14`)和 `LoopSettings` 里的细项类型(`RuntimeMemoryRetriever`、`MemoryTopic`、`RuntimeMemoryPolicy`、`RuntimeConcurrency`、`BackendTools`、`NetworkToolConfirmationPolicy`)现在是稳定的。按设计稿第 5 节,它们应该标 experimental。 + - 反过来,`LoopLimits`(`LoopSettings.kt:53`)标了 experimental,宿主设个轮数都要 opt-in。它应该是稳定的。 + - `NarrationCheck` 的文档第 5 行还说默认认中文说法,实际已经只认英文了。 +4. **没人能用的公开接口,冻结前要收进内部。** + - `WorkspacePort` 一族(`spi/WorkspacePort.kt:9`,约 77 行 dump)没有任何公开方法接收或返回它,文档还写着 Plugin-facing。 + - `RuntimeHookRegistration`(`spi/RuntimeHooks.kt:69`)也一样。 +5. **漏成公开的内部名字。** + - `RuntimeCompletionGate.kt:20`:给 internal 的 `decideFinish` 加了 `@JvmOverloads`,结果生成了一个公开的重载,进了 dump。去掉这个注解。 + - `openFileBackedSessionEventLog`(`runtime/eventlog/DurableSessionEventLogPlugin.kt:58`)应该公开(agent-runtime-android 要用),但 Java 看到的类名是 `DurableSessionEventLogPluginKt`,文档还提到已删除的插件。加 `@file:JvmName` 或者把它挪到别的文件。 +6. **`AgentRuntime` 接口在 agent-runtime 模块里(`agent-runtime/.../AgentRuntime.kt:8`),不在 agent-api 里。** + - 后果:`cc.noharry.agent` 包被拆在两个构件里;一个只想接收 `AgentRuntime` 的库,也得依赖整个实现。 + - 修法:接口挪到 agent-api。`AgentRuntime.builder()` 改成 agent-runtime 里对 `Companion` 的扩展函数,Java 入口用 `AgentRuntimes.builder()` 或保留 `AgentRuntimeBuilder.create()`。 +7. **错误码是没有公开列表的字符串。** + - `TurnError.code`(`TurnInput.kt:74`)和 `ThreadItem.Error.code`(`ThreadItem.kt:82`)都是 `String`。`IMAGE_INPUT_UNSUPPORTED`、`INTERRUPTED`、`TURN_FAILED`、`MISSING_TURN_RESULT`、`THREAD_BUSY`、`QUESTION_NOT_FOUND`(`DefaultAgentThread.kt:122-133`)都不在 `RuntimeErrorCode` 里,也没有文档。 + - 修法:保留字符串,加一个公开的常量对象(比如 `TurnErrorCodes`),每个码写一句说明。 +8. **扩展接口里还用旧的 id 名字。** + - `HookContext`、`ToolCallContext`、`RuntimeContextRequest`、`SessionEvent` 里还是 `sessionId` / `runId` / `requestId`,冻结后再改名就是破坏兼容。 + - 推荐:趁现在改成 `threadId` / `turnId`。至少也要在 KDoc 里写明它们分别等于哪个。 +9. **公开面还是太大。** 主线约 671 行(目标 600 行),稳定的主线加扩展接口约 3,600 行(目标 2,000 行)。 + - 收进内部:上面第 4、5 条的东西;其他模块都不用的 VFS 内部类(`VfsSnapshot*`、`VfsMountTable`、`VfsPathResolver`、`VfsManifestLoader`、`VfsResolvedMount`,约 130 行)。 + - 改成 experimental:`SessionEventPayload` 和 `SessionJson`(约 320 行,只有自己写事件日志的宿主才需要)。 + - 改完重新量,在 CHANGELOG 里写实际数字。 +10. **CHANGELOG 的 0.5.0 一节不完整,还自相矛盾。** + - 迁移表(第 35-53 行)只有 3 行。要补齐设计稿 7.1、7.2 的完整对照,加上 `cancelPendingConfirmation`、`KernelRuntimeBuilder` / `CoreAgentRuntime`(改用 `AgentRuntime.builder()`)、`sessionStore`。 + - 删掉或改写描述已删 API 的旧条目:第 57-62、66-69、77-79、88-99 行;第 213 行说 `traceRedactor` 是 experimental,实际已经是稳定的。 + +### 4.2 行为 bug + +1. **幂等的轮次 id 是坏的。** + - 位置:`thread/ThreadInput.kt:22` 把 `turnId` 直接当成引擎的全局 run id;`RunStateController.kt:104-106`、`DefaultAgentRuntime.kt:306`;会话层只在本会话里查重放(`DefaultAgentThread.kt:62,76`)。 + - 后果: + - 开了 `storage(dir)` 以后,进程在一轮中途崩掉,再用同一个 `turnId` 重试,会得到 `DUPLICATE_RUN_ID`。这个失败还会被存下来,之后每次重试都重放这个失败。 + - 两个会话用了同一个 `turnId` 也会冲突。 + - 修法: + - 引擎的 run id 和 `turnId` 脱钩(比如随机 id),会话存储里记下 `turnId` 到 run id 的对应。 + - 崩溃后重试时,如果找到了旧 run 但这个会话没有存下结果,把旧 run 记为中断,重新开一轮。 + - 测试:崩溃后重试;两个会话用相同的 `turnId`。 +2. **✔ 普通插话会被绑成最新那个异步提问的回答。** + - 位置:`thread/DefaultAgentThread.kt:170-176`:`answering == null` 时取 `questions.lastOrNull()`。而接口 KDoc(`AgentThread.kt:16-19`)说不指定就是普通插话。 + - 后果: + - 模型同时问了目的地、预算、日期三个问题,用户插话说「苏州」,模型收到的是「日期问题的回答:苏州」。 + - 某个问题已经收到回答、还没被消费时,普通插话会被拒,返回 `QUESTION_NOT_FOUND`,插话的内容就丢了。 + - 修法:只有显式传了 `answering` 才绑定;普通插话一律当普通用户消息。设计稿 4.6 原来写得含糊,已经改正。 + - 测试:开着多个异步提问时普通插话;指定问题插话。 +3. **模型重复用同一个工具调用 id 时,整轮失败。** + - 位置:`thread/ThreadToolProjection.kt:34-42`、`ThreadEventProjection.kt:208`:一次调用结束就把记录删掉;同一个 id 再来时,`start()` 会撞上「Duplicate item id」的检查而抛异常。 + - 诱因:服务商不给 id 时,OpenAI 客户端统一用 `"openai-tool-call"` 兜底(`OpenAiProviderJson.kt:245,286`);有些本地或兼容服务器也会在每次回复里复用 id。 + - 修法:条目 id 用这一轮里的序号,不直接用服务商给的 id;OpenAI 的兜底 id 加上序号。 + - 测试:同一轮里两次调用用同一个 id;回复里没有 id。 +4. **拒绝后是否接着跑,按第 2 节第 1 问的决定改。** 如果改成接着跑,要同步更新 `ThreadApprovalFlowTest` 等锁定了现有行为的测试,并验证 `DENY_ALL` 下模型能正常回复。 +5. **等批准时被取消或中断,模型历史里会一直留着「等待确认」。** + - 位置:只有拒绝和过期才调用 `recordUnconfirmed`(`DefaultAgentRuntime.kt:657`);取消时,`NativeToolMessages.kt:72` 写的 "awaiting_confirmation … has not run" 留在了历史里。 + - 修法:取消和中断的路径也记成 `CONFIRMATION_CANCELLED`。 + - 测试:取消一次批准,看下一轮的模型输入。 +6. **旧的暂停/恢复路径还编在代码里。** `resumeConfirmation`、`resumeUserInput`、确认存储、`emitToolConfirmation` 都已经是 internal,公开 API 也调不到了,但代码还在。确认没人用之后删掉。 + +次要的(这一轮顺手修): + +- **刚开始就中断,可能什么事件都没有。**(`DefaultAgentThread.kt:99-102`)任务是 LAZY 启动的,正文还没跑就被取消的话,既没有 `TurnStarted` 也没有结束事件,`run()` 会抛「Turn did not produce a result」。要保证一定发出结束事件。 +- **一轮还在跑时删除会话,流直接断,没有结束事件**(`DefaultThreadRuntime.kt:84`、`DefaultAgentThread.kt:96`)。应该以 `TurnFailed(THREAD_DELETED)` 结束。 +- **`TurnCompleted` 发出时,这一轮还没释放运行权**(`DefaultAgentThread.kt:89-96` 对比 `:102-107`)。收到完成事件的代码马上发起下一轮,会碰到 `THREAD_BUSY`。要先释放再发事件。 +- **等批准时 `steer` 返回 `NOT_RUNNING`**,而 `status()` 显示的是 `WAITING_FOR_APPROVAL`。改成先排队,或者返回一个能说明情况的结果。 +- **REMEMBER 记的区域和网络策略对不上。**(`thread/ThreadApproval.kt:71-78`)这里用 `java.net.URI` 取域名,网络策略用的是 OkHttp 的解析。主机名带下划线,或者 URL 前面有空格时,取到的是空值,于是退回到 `"web_fetch"`,批准一次就放行所有这类网址。另外,MCP 服务 id 和主机名共用一个命名空间。修法:统一用 `NetworkToolBackend` 的解析,并给不同来源的区域加前缀区分。 +- **`approvedBy` 分不清是人批准过记住的,还是策略自动批准的**,两者都记成 REMEMBER。 + +### 4.3 持久化和隐私 + +1. **✔ Android 升级以后,事件日志换了位置。** + - 位置:`agent-runtime-android/.../AndroidAgentRuntime.kt:35-36` 先设了 `sessionEventLogRoot(.../event-log)`,紧接着调用 `.storage(.../conversations)`,而 `AgentRuntimeBuilder.kt:181` 在 `storage()` 里把它覆盖成了 `conversations/events`。 + - 后果:0.4.0 的日志成了孤儿,诊断接口看不到;公开的辅助函数 `appPrivateSessionEventLog`(`AndroidRuntime.kt:22`)和 CHANGELOG 还指着旧路径。 + - 修法:`storage()` 不覆盖已经设过的事件日志位置。Android 继续用原来的 `event-log` 路径。 + - 测试:先设事件日志位置再调 `storage()`,位置不变。 +2. **0.4.0 的旧会话:`listThreads` 看不到,`items()` 是空的。**(`DefaultThreadRuntime.kt:51`、`ThreadStore.kt:58-63`)按第 2 节第 4 问处理,推荐只在 CHANGELOG 里写清楚。会话 id 和旧的 sessionId 一致,新轮次会接着写进同一个 SQLite 会话。 +3. **`deleteThread` 删不干净。** + - 位置:`DefaultThreadRuntime.kt:86-90`、`DefaultAgentRuntime.kt:293-296` 只清了内存和两个 json 文件。 + - 还留着的:事件日志及其图片附件、Android SQLite 里的消息和工具参数、运行记录和 `runs//loop-history.json`(`storage()` 默认会开运行记录,`AgentRuntimeBuilder.kt:182`)。 + - 后果:删除后诊断接口还能查到旧事件;同一个 id 重建会话,新旧事件会混在一起。 + - 修法: + - 给 `SessionEventLog` 加一个带默认实现的删除方法,再加上 SQLite 和运行记录的删除,都在 `deleteThread` 里调用。 + - 正在跑的轮次照现有测试的做法先停掉。 + - 测试:删除后各处都查不到这个会话的数据。 +4. **一个坏文件就能让整个功能报错。** + - `list()` 解析每个文件时都不处理错误(`ThreadStore.kt:59-60`),一个坏文件或者版本号不认识,`listThreads` 就整个抛异常。 + - `.history.json` 坏了(`ModelHistoryCodec.kt:24`、`ThreadStore.kt:122-126`),这个会话每一轮都失败,连删除都会失败,因为删除前要先读一遍(`SessionHistoryStore.kt:121-131,138-142`)。 + - 存盘失败(比如磁盘满)会以异常形式从 `runStreamed` 抛出,而不是 `TurnFailed`(`DefaultAgentThread.kt:91,132-136`)。 + - 修法: + - 列表时跳过读不了的文件。 + - 历史文件坏了就改名成 `.corrupt`,当作空历史继续。 + - 删除时不需要先解析文件。 + - 存盘失败时以 `TurnFailed(STORAGE_FAILED)` 结束这一轮。 + - 测试:坏文件、版本号不认识、磁盘写失败。 +5. **✔ 存盘的过滤方式不对。** + - 位置:`thread/ThreadItemCodec.kt:74-76` 对工具参数和结果整串套用文本规则(`runtime/TraceSecurity.kt` 里的那几条)。 + - 漏掉的:`Bearer` 令牌,以及 `"access_token":"…"`、`"api_key":"…"` 这种 JSON 字段里的密钥,会明文写进 `.thread.json`;而同样的内容事件日志是拒收的。 + - 改坏的:10 位以上的数字会被换成不带引号的 `[REDACTED_PHONE]`。比如 `{"ts":1730900000000}` 会变成 `{"ts":[REDACTED_PHONE]}`,重启后读回来的工具结果就不是合法 JSON 了,Bothy 画卡片要解析它。 + - 最终答案和用户的话(`ThreadItemCodec.kt:29,106`,还有 `finalResponse`)重启后也会被遮。 + - 修法: + - 按 JSON 结构过滤:遍历 JSON,只过滤字符串值;按字段名整个替换敏感字段;补上 `Bearer`。替换完的结果必须仍是合法 JSON。 + - 最终答案和用户的话按第 2 节第 2 问处理(推荐不遮)。 + - `.history.json` 按设计就是原文(包括推理内容和图片),要在 CHANGELOG 里写明。 + - 测试:带密钥形状的工具结果、长数字,重启后 JSON 仍然合法、密钥不在文件里。 +6. **存储无限增长。** + - `.thread.json` 永久保存每一轮,图片用 base64 存在里面(`ThreadItemCodec.kt:107-108`),每一轮还要整个重写两次(`DefaultAgentThread.kt:91,136`)。 + - `list()` 要把每个文件完整解析一遍,而且全程只用一把锁。 + - 历史的 4 MB 上限没算图片、推理内容和签名(`SessionHistoryStore.kt:174-175`)。 + - `liveTurns`(`ThreadStore.kt:30,77`)在进程活着期间一直留着每一轮的完整结果,图片也在里面。 + - 修法: + - 图片存成附件文件,用哈希引用。 + - 改成按轮追加写,或者每轮一个文件;每轮只存一次。 + - 列表的元数据单独存一份。 + - `liveTurns` 存盘后就释放。 + - 上限把图片和推理内容也算进去。 + - 测试:几十轮带图片的会话,文件大小和内存都有上限。 +7. **`resumeThread` 不是挂起函数,却在调用线程上读写磁盘。**(`DefaultThreadRuntime.kt:51,57`、`DefaultAgentThread.kt:29-31`)在 Android 主线程上可能读写几 MB。 + - 推荐:`startThread` / `resumeThread` 保持非挂起,等第一次挂起调用(`run`、`items`、`status`)时再从磁盘加载。 + - 测试:主线程调用 `resumeThread` 不做 I/O(StrictMode 或计时)。 +8. **等批准时进程被杀,历史和条目会对不上。** + - 位置:等批准之前,历史已经存了「等待确认」的占位(`NativeToolLoop.kt:462-463`、`DefaultAgentRuntime.kt:651`),但 `.thread.json` 里没有这一轮。 + - 修法:恢复时发现这种占位,就记成已取消,再补一条 `Notice`。 + - 测试:等批准时杀进程,然后恢复。 +9. **没有确认的一点:两个进程同时用同一个存储目录,可能丢数据。** 没有文件锁。至少在 KDoc 里写明一个存储目录只能由一个进程使用。 + +## 5. Bothy 必须修的 + +以下路径都在 `~/project/bothy-api/workspace/apps/android/` 下。文件名在仓库里是唯一的,可以直接搜。 + +1. **✔ 插话变成了一条新的用户消息。** + - 位置:`session/TranscriptStore.kt:268-269` 只丢掉了「不是插话」的用户消息,所以 SDK 回显的每一条插话都被 `ThreadItemProjection.kt:12` 画成了一个 `TurnHeader`,显示的还是发给模型的原文。 + - 后果: + - 计划提醒(`RuntimeSession.kt:645`)显示成用户说了「【计划提醒】…在这一轮的回复里把它原样告诉用户…」;委托和子 agent 的报告(`:582`、`:617`、`:702`)、语音插话(`:550`)也一样。 + - 和原来那条「Runtime steering input」行(`RuntimeSteering.kt:24`)重复。 + - 手机上这一轮会从这里被劈成两半(`PhoneTimeline.kt:91`)。 + - 修法:Bothy 发插话时按请求 id 记下这是哪一类、要显示什么文字。投影时,内部插话不画用户气泡,用户自己的插话画显示用的文字。 +2. **✔ 最终答案里又出现了「TTS:」开头的语音进度行。** + - 位置:`ThreadItemProjection.kt:10` 显示的是原文,没有经过 `shownReply()`(`runtime/ShownReply.kt:7`);A2A 那条路(`A2aEvents.kt:24`)倒是经过了。 + - 后果:控制台原样显示这些行;悬浮窗会跳过以「TTS:」开头的回复(`OverlayHud.kt:232`、`OverlayParts.kt:161`),可能显示一条旧回复、丢掉选项。 + - 修法:最终答案(`phase == FINAL`)先经过 `shownReply()` 再显示。 +3. **agent 看不到陪聊和空闲时的计划提醒了。** + - 位置:`recordCompanionTurn` 只写进 Bothy 自己的会话存储;这份存储现在只给 Jev 用,主提示词拿到的是空的(`RuntimeBuilder.kt:179-180`、`RuntimePrompt.kt:44`);SDK 恢复的历史里也没有这些轮。 + - 后果:计划提醒问「要导航去加油站吗?」,用户回一个「好」,模型不知道在答什么;而 `ActionGate` 还在读 Bothy 的存储,两边对「上一个问题是什么」的理解不一致。 + - 修法:只在最近一次对话不是 SDK 的轮次时(陪聊或提醒),把它作为这一轮的上下文带给模型,相当于只针对这两类恢复原来的回顾。`ActionGate` 和模型用同一个来源。如果想让 SDK 提供「往历史里补外部消息」的接口,那是公开 API 的改动,要先问 owner。 +4. **A2A 加了令牌,但界面上看不到令牌。**(`A2aServerManager.kt:15,33-51`)令牌只存在 `noBackupFilesDir` 里,现有调用方只会收到 401。修法:在设置里显示令牌并能复制,README 里写一句怎么用。 +5. **批准的行为变了。** + - 位置:`RuntimeConfirmation.kt:15,24-29`。 + - 用户在「批准过的不再问」模式下点批准,传的是 `ONCE`,所以不会被记住。修法:这种情况传 `THREAD`。 + - SDK 拿 MCP 服务 id 或工具名当区域,一次批准会放行整个服务。区域要细到工具区域,这部分在 SDK 侧,和 4.2 的 REMEMBER 那条一起改。 + - 卡片文字变成了「要访问 web_fetch:example.com」。修法:Bothy 显示时把区域的前缀去掉。 +6. **子 agent 遇到批准时没人能回应,白等 60 秒。** + - 位置:子 agent 用默认的 `ASK`(`RuntimeTurnRequest.kt:18`、`AppSubagents.kt:215`);在「全部允许」之外的模式下,子 agent 的 `web_fetch` 要等满 60 秒,连「全部拒绝」也一样。 + - 修法:SDK 侧让子 agent 沿用父会话的批准策略;没法问人的批准立刻拒绝。Bothy 侧传入当前的模式。 +7. **丢了几样东西,要补回来。** + - 工具失败的提示条:`appendRuntimeResult` 现在没人调用,而手机靠它判断这一轮失败(`PhoneTimeline.kt:102`)。改成从 `TurnResult` 或 `FAILED` 状态的工具条目推出来。 + - 看板上的执行输出、工作区、搜索和网络状态。 + - A2A 的进度更新(搜索、网络、重试、压缩、预算)。另外,转发出去的提示是 SDK 的英文原文,比如「Retry 1 in 500 ms」,要换成 Bothy 自己的说法。 + - 子 agent 失败或被取消时,token 用量没被计入(`AppSubagents.kt:221`)。 + - 工具卡片的编号显示成 `turn:tool:call_x`。 +8. **调试页的回放核对失效了。**(`RunEvidence.kt:45-53`)「公开」和「原始」两份记录来自同一个工具调用事件,`RunReplayVerifier` 永远不会报不一致。修法:改成拿条目和诊断接口里的事件日志比,或者干脆删掉这个核对。 +9. **`traceRedactor` 关掉了电话号码和位置过滤。** 按第 2 节第 3 问的决定改。 + +## 6. Bothy 清理和提交 + +- **删掉没用的代码。** + - 空文件 `ConfirmationDomains.kt`。 + - `RuntimeRunScope.kt:154-181` 里没用的 `confirmationDomain` / `confirmedDomains` 参数。 + - `RuntimeSessionRunner.kt`:第 586 行的 `activateSelectedRun = Unit`;第 176 行没用的 `requestId`;第 499 行注释里提到的 `ThreadEvent.TokenUsageDelta`,这个类型并不存在。 + - `RuntimePrompt.kt:29,44` 的 `previousExchange` 和 `replyContext`;`RuntimeBuilder.kt:159` 那句「the recap」的注释。 + - `TranscriptStore` 里的 `appendRuntimeResult`、`appendThinkingDelta`、`appendAssistantDelta`、`appendConfirmationRequired`、`toolIssuesForCurrentTurn`。 + - `Transcript.kt` 的 `parseToolResultStatus`、`parseRawToolCallId`,`RuntimeTimeline.kt:45` 的 `parseRawToolName`。 + - `SessionTurnRecorder.kt:12,174-182`、`RunEvidence.kt:5,84-95`、`McpProgressiveEvidence.kt:52,128-134`,以及 `RunReplayVerifier.kt:62` 里提到 `NativeToolCallStarted` 的地方。 + - `RawToolTranscriptHookTest.kt` 现在只测 `redactToolPayload`,改个名字。 +- **整理提交。** + - 两个 `chore(checkpoint)` 提交合成一个,按 Bothy 的格式写完整的说明和正文。提交者用 NoHarry;Co-Authored-By 行按你自己的模型写。 + - `harness/trace/2026-11-06-sdk-thread-api-migration.md` 会是这个公开仓库里第一个按日期命名的 trace 文件,里面还写着「不推送」。推荐不提交它。 +- **依赖版本。** `gradle.properties:11` 还是 `agentRuntimeVersion=0.4.0`,0.5.0 发布后再改成 0.5.0,这是计划里的最后一步。 + +## 7. 修完以后怎么验证 + +1. **SDK**: + - `./gradlew -q apiDump`,然后 `./gradlew -q --continue ciCheck`,全过。 + - 记录 dump 的实际行数,对照 4.1 第 9 条。 + - 4.2、4.3 里写了「测试」的每一条,都要有对应的测试。 +2. **Bothy**:在 `~/project/bothy-api` 里从零编(`--rerun-tasks`),再跑一遍 validate。 +3. **平板**(装包前先告诉 owner,装完恢复无障碍服务和录音权限,命令在交接文档第 5 节)。设计稿第 10 节的 8 项都要走一遍,另外**必须在 Bothy 界面上**看这几项,上次都没覆盖到: + - 批准卡片在每种模式下的表现,包括跑到一半切换模式;拒绝以后的表现。 + - 回答 `ask`;回答 `ask_async`,开着多个问题时也试。 + - 跑着的时候插话:用户自己的插话显示正常,计划提醒和委托报告不再显示成用户气泡。 + - 控制台、悬浮窗、手机上的最终答案里都没有「TTS:」开头的行。 + - 陪聊或计划提醒之后,回答「好」,agent 能接上。 + - 杀掉进程再打开:会话列表和历史都在,工具卡片里的 JSON 正常。 + - A2A:不带令牌返回 401;从设置里复制令牌后请求返回 completed。 +4. **CHANGELOG** 按 4.1 第 10 条补全。 +5. **收尾**: + 1. SDK 分支快进到 main,推送。 + 2. owner 点头后发布 0.5.0。 + 3. Bothy 换成 Maven 上的 0.5.0,合成一个提交,评审后推送,平板再验一遍。 + 4. 最后更新知识体系文章(交接文档第 10 节)。 + +## 8. 修复的建议顺序 + +1. 问 owner 第 2 节的四件事。 +2. SDK 公开 API(4.1)。这一组决定冻结的样子,最先做。 +3. SDK 行为(4.2)。 +4. SDK 持久化和隐私(4.3)。 +5. SDK 文档:CHANGELOG 和 KDoc。 +6. Bothy(第 5、6 节)。从第 2 步起,每做完一组 SDK 改动,就拿 Bothy 编一遍。 +7. 第 7 节的验证。 + +## 9. 确认没问题的(不要动) + +- 正好 8 种 `ThreadEvent`,顺序规则写进了文档注释;条目有完整的结束事件,结束之后不会再有事件。 +- 条目种类都有:`AgentMessage.phase`;`ToolCall` 带 `server`、`network`、`approvedBy`;`Approval`;`Question(async)`。 +- `AgentThread` 的方法齐全,加了 `steer(text, answering)`,这是个改进;`RespondResult` 是枚举,Java 也好用。 +- 旧方法、`AgentRequest`、`AgentEvent`、`OpenConfusion`、`RuntimeBlocker`、插件系统都收进了内部,协议请求删了。 +- `agent-api` 模块和 `cc.noharry.agent` / `.spi(.model/.mcp)` 的包结构到位了;kernel-core 没了,可选模块只依赖 `agent-api`。 +- 四项破坏性改动都做了:`ServerSideSearchCapability` 挪到了 `cc.noharry.agent.model`;`ModelMessage.reasoningContent` 在 OpenAI 和 Anthropic 客户端以及存盘历史里都接通了;不给模型 `build()` 会报错;默认值是中性的(没有内置话题,结束语检查只认英文,没有必应 RSS 那行)。 +- MCP 区域规则认得带 `_` 的服务 id。hook 用的是 `onTurnStarted` / `onTurnFinished(TurnResult)`。 +- 在「全部允许」下,hook 的拒绝仍然优先:批准之后执行前还会再跑一遍 hook。 +- 回应、过期、取消三者之间没有竞争:重复回应得到 `ALREADY_ANSWERED`;一轮结束后再回应得到 `NOT_FOUND` 或 `ALREADY_ANSWERED`;在收集事件的代码里回应不会死锁。 +- `ask_async` 的回答不会漏到下一轮;子 agent 不能提问。 +- 图片能送到 `ModelMessage.images`,模型不收图时以 `IMAGE_INPUT_UNSUPPORTED` 结束这一轮。 +- SQLite 的结构还是 v5,0.5.0 打开 0.4.0 的数据库不会崩,也不会清空。 +- Bothy 的前端协议(agent-app-protocol、bothy-protocol)没有改动;没有代码调用已删除的 SDK API;旧默认值都显式写上了;A2A 加了鉴权;通知渠道有了名字。 diff --git a/docs/design/public-api-redesign.md b/docs/design/public-api-redesign.md index e3d7b13..be3d8a6 100644 --- a/docs/design/public-api-redesign.md +++ b/docs/design/public-api-redesign.md @@ -303,7 +303,7 @@ sealed interface RespondResult { **提问。** 运行时现在给模型两个提问工具,对应两种 `Question`。这是推荐做法,见第 9 节第 1 问。 - `ask`(缺了信息就什么都做不了时用):流里出现 `ItemCompleted(Question(async = false))`,这一轮以 `TurnCompleted(status = WAITING_FOR_ANSWER, pending = 那个提问)` 结束。下一轮 `run(...)` 的输入就是回答。运行时在内部照现在 `resumeUserInput` 的做法接着同一个 run 跑:模型看到的历史里,`ask` 的工具结果后面紧跟着用户的回答。现在 Bothy 在 `FollowUpReply.kt` 里自己给回答套的框,也挪进 SDK。宿主想明确绑定,就传 `TurnInput(answering = questionId)`。如果下一轮输入其实是新请求(用户不理提问、说了别的),按现有回答框的规则当作新请求处理。 -- `ask_async`(一边问一边继续干活,最多 3 题):流里出现 `Question(async = true)`,这一轮照常继续跑。回答用 `thread.steer(text)` 插进来;这一轮结束时还没回答的问题作废。 +- `ask_async`(一边问一边继续干活,最多 3 题):流里出现 `Question(async = true)`,这一轮照常继续跑。回答用 `thread.steer(text, answering = questionId)` 插进来;不带 `answering` 的普通插话不绑定任何问题,由模型自己理解。这一轮结束时还没回答的问题作废。 这么分的理由:批准是工具执行前的一道闸,时间短,宿主或策略能马上回应;提问要等人,可能很久,甚至永远不回答。让一个轮次一直开着,会长期占住会话的运行权(session lease)。 @@ -513,7 +513,7 @@ Codex 的做法(看的是本地 codex-rs 源码,2026-10-17 的版本): 选项: -- **A(推荐)**:`ask` 结束当轮,下一轮的输入就是回答;`ask_async` 在当轮里给出问题条目,回答用 `steer`(4.6)。理由有三条:跟 Codex 的默认模式一致;车上的人常常不回答;现在的实现本来就是这样,改动最小。 +- **A(推荐)**:`ask` 结束当轮,下一轮的输入就是回答;`ask_async` 在当轮里给出问题条目,回答用带 `answering` 的 `steer`(4.6)。理由有三条:跟 Codex 的默认模式一致;车上的人常常不回答;现在的实现本来就是这样,改动最小。 - B:`ask` 也像 Codex 的 Plan 模式那样,当轮一直挂着等回答。这只适合有人盯着屏幕的场景,以后需要可以加成选项。 **2. 工具调用条目给不给原文。** From d30a22748b5c3629ddf0e9e754bd03d4baecdcc5 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Fri, 6 Nov 2026 23:18:46 -0800 Subject: [PATCH 02/40] fix(api): correct stability markers and the Java event log factory Keep basic loop budgets stable and advanced tuning and event payloads experimental. Expose durable log creation through SessionEventLogs instead of a plugin-named JVM facade. Validated with apiDump, ciCheck, Bothy compilation and independent review. Co-Authored-By: Codex --- CHANGELOG.md | 5 +++++ .../cc/noharry/agent/spi/NarrationCheck.kt | 3 ++- .../noharry/agent/spi/ServiceAnswerCheck.kt | 1 + .../cc/noharry/agent/spi/SessionEvent.kt | 2 ++ .../noharry/agent/spi/SessionEventAppend.kt | 2 ++ .../noharry/agent/spi/SessionEventPayload.kt | 1 + .../cc/noharry/agent/spi/SessionJson.kt | 1 + agent-runtime/api/agent-runtime.api | 3 ++- .../cc/noharry/agent/runtime/LoopSettings.kt | 3 ++- .../agent/runtime/NetworkToolBackend.kt | 3 +++ .../agent/runtime/RuntimeMemoryPolicy.kt | 3 +++ .../agent/runtime/RuntimeMemoryRetriever.kt | 4 ++++ .../eventlog/DurableSessionEventLogPlugin.kt | 14 +------------- .../runtime/eventlog/SessionEventLogs.kt | 19 +++++++++++++++++++ 14 files changed, 48 insertions(+), 16 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventLogs.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a26693..a6a9518 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Stable budgets, experimental advanced tuning.** `LoopLimits` is stable. Narration and service-answer checks, + memory/concurrency/tool-exposure tuning, and structured event-log payloads remain experimental. +- **Java event-log factory.** Open a durable log with `SessionEventLogs.openFileBackedSessionEventLog(File)`. + The Kotlin top-level function keeps its name; the old plugin-named JVM facade is removed. + - **Breaking: Thread / Turn / Item replaces the run API.** Import the stable conversation contracts from `cc.noharry.agent`: start or resume an `AgentThread`, call `run` for a `TurnResult` or collect `runStreamed`. Eight event types replace the old event union. Items have stable ids and complete final snapshots; diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/NarrationCheck.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/NarrationCheck.kt index 04426b1..19a16a8 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/NarrationCheck.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/NarrationCheck.kt @@ -3,12 +3,13 @@ package cc.noharry.agent.spi /** * Whether a final answer only says what the agent is about to do ("I'll now look that up") instead of answering. Such an * answer goes back to the model once for a real one, and fails the run if the next is no better. The runtime's own - * check knows English and Chinese phrasings; a host whose users write another language, or whose answers are short + * check recognizes English phrasings; a host whose users write another language, or whose answers are short * confirmations the check would mistake, supplies its own, also to the runtimes it builds for subagents. * * It is called on the run's thread, possibly several times for one answer and for runs at once: keep it quick, without * side effects and safe to call concurrently. One that throws fails the run. */ +@ExperimentalAgentRuntimeApi fun interface NarrationCheck { fun isNarration(answer: String): Boolean diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/ServiceAnswerCheck.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/ServiceAnswerCheck.kt index e4dc617..b1c337e 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/ServiceAnswerCheck.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/ServiceAnswerCheck.kt @@ -11,6 +11,7 @@ package cc.noharry.agent.spi * It is called for every failed tool result, on several threads at once when tools run in parallel: keep it quick, * without side effects and safe to call concurrently. One that throws is taken as no. */ +@ExperimentalAgentRuntimeApi fun interface ServiceAnswerCheck { fun isServiceAnswer(resultJson: String): Boolean diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEvent.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEvent.kt index 20c8198..f86c3cb 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEvent.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEvent.kt @@ -1,3 +1,5 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + package cc.noharry.agent.spi /** diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventAppend.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventAppend.kt index a5ac8ff..91e975d 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventAppend.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventAppend.kt @@ -1,3 +1,5 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + package cc.noharry.agent.spi /** diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventPayload.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventPayload.kt index 29d32f2..d44b2fa 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventPayload.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventPayload.kt @@ -7,6 +7,7 @@ package cc.noharry.agent.spi * headers, bearer tokens, cookies and transport credentials must be removed before the * writer accepts the event. */ +@ExperimentalAgentRuntimeApi sealed class SessionEventPayload { data object Empty : SessionEventPayload() diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionJson.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionJson.kt index 27e6a01..5844521 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionJson.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionJson.kt @@ -5,6 +5,7 @@ package cc.noharry.agent.spi * * Number literals keep their original text so integers and decimals round-trip. */ +@ExperimentalAgentRuntimeApi sealed class SessionJson { data object Null : SessionJson() diff --git a/agent-runtime/api/agent-runtime.api b/agent-runtime/api/agent-runtime.api index 41d5a55..75be9d0 100644 --- a/agent-runtime/api/agent-runtime.api +++ b/agent-runtime/api/agent-runtime.api @@ -894,7 +894,8 @@ public final class cc/noharry/agent/runtime/WebSearchResult { public fun toString ()Ljava/lang/String; } -public final class cc/noharry/agent/runtime/eventlog/DurableSessionEventLogPluginKt { +public final class cc/noharry/agent/runtime/eventlog/SessionEventLogs { + public static final fun openFileBackedSessionEventLog (Ljava/io/File;)Lcc/noharry/agent/spi/SessionEventLog; public static final fun openFileBackedSessionEventLog (Ljava/io/File;Lkotlin/jvm/functions/Function0;)Lcc/noharry/agent/spi/SessionEventLog; public static synthetic fun openFileBackedSessionEventLog$default (Ljava/io/File;Lkotlin/jvm/functions/Function0;ILjava/lang/Object;)Lcc/noharry/agent/spi/SessionEventLog; } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/LoopSettings.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/LoopSettings.kt index 0911005..b077281 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/LoopSettings.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/LoopSettings.kt @@ -50,7 +50,6 @@ const val MAX_CONTEXT_TIMEOUT_MILLIS = 60_000L * in the conversation sent to the model ([newestImages]; older ones fold to a note three at a time, so up to two more * may stay). */ -@ExperimentalAgentRuntimeApi class LoopLimits @JvmOverloads constructor( val failuresPerCall: Int = DEFAULT_MAX_CONSECUTIVE_TOOL_CALL_FAILURES, val failuresPerTool: Int = DEFAULT_MAX_CONSECUTIVE_TOOL_FAILURES_PER_TOOL, @@ -80,12 +79,14 @@ class LoopLimits @JvmOverloads constructor( internal fun LoopSettings.withLimits(limits: LoopLimits): LoopSettings = copy(limits = limits) /** How provider tools become visible to the model. */ +@ExperimentalAgentRuntimeApi enum class BackendTools { DIRECT, SEARCH, NATIVE_DEFERRED } /** * Process-local caps; provider-specific concurrency declarations remain in force. Runtimes sharing a storage * directory share one turn admission queue and use the most restrictive caps among its open runtime instances. */ +@ExperimentalAgentRuntimeApi data class RuntimeConcurrency( val tools: Int = 4, val models: Int = 4, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt index 55e7de8..8677318 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt @@ -1,4 +1,6 @@ package cc.noharry.agent.runtime + +import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi import cc.noharry.agent.spi.reliability.RuntimeErrorCode import cc.noharry.agent.kernel.core.loop.failed import cc.noharry.agent.kernel.core.tools.NetworkToolActivityResult @@ -252,6 +254,7 @@ internal class NetworkToolBackend( } /** Controls whether [NetworkToolBackend] gates web_fetch per host. */ +@ExperimentalAgentRuntimeApi enum class NetworkToolConfirmationPolicy { /** Default: each new host in a run requires explicit confirmation before transport. */ REQUIRE_PER_HOST, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeMemoryPolicy.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeMemoryPolicy.kt index 27059bb..930d69e 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeMemoryPolicy.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeMemoryPolicy.kt @@ -1,7 +1,10 @@ package cc.noharry.agent.runtime +import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi + import cc.noharry.agent.kernel.core.memory.* /** Runtime-owned guardrails for memory retrieval and candidate promotion. */ +@ExperimentalAgentRuntimeApi data class RuntimeMemoryPolicy( val maxRetrievedLessons: Int = 2, val maxPreactivatedTools: Int = 2, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeMemoryRetriever.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeMemoryRetriever.kt index e518ce6..cc409dc 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeMemoryRetriever.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeMemoryRetriever.kt @@ -1,5 +1,7 @@ package cc.noharry.agent.runtime +import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi + import cc.noharry.agent.kernel.core.memory.* import cc.noharry.agent.kernel.core.loop.RuntimeMemoryMatchSummary @@ -26,6 +28,7 @@ internal data class RuntimeMemorySelection( * Selects only explicitly prewarm-eligible lessons that are relevant to the * current request. Legacy and query-only lessons deliberately return no match. */ +@ExperimentalAgentRuntimeApi class RuntimeMemoryRetriever @JvmOverloads constructor( /** How many lessons reach a run and which count, also for learning them ([RuntimeMemoryPolicy]). */ val policy: RuntimeMemoryPolicy = RuntimeMemoryPolicy(), @@ -146,6 +149,7 @@ private data class RetrievalProfile( * the text is (lower case, punctuation as spaces: "Wi-Fi" is "wi fi"); a term of ASCII letters and digits matches a whole * word, any other term anywhere in the text. [name] is how matches name the topic, in lower case. */ +@ExperimentalAgentRuntimeApi class MemoryTopic( name: String, strongTerms: Set, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/DurableSessionEventLogPlugin.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/DurableSessionEventLogPlugin.kt index d505ef0..35c9c98 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/DurableSessionEventLogPlugin.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/DurableSessionEventLogPlugin.kt @@ -10,10 +10,8 @@ import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi import cc.noharry.agent.spi.KernelApiRange import cc.noharry.agent.spi.KernelApiVersions import cc.noharry.agent.spi.PluginVersion -import cc.noharry.agent.spi.SessionEventLog import cc.noharry.agent.spi.ProviderConcurrencyDeclaration import java.io.File -import java.util.UUID /** * Packaged SINGLE [AgentCapabilities.SESSION_EVENT_LOG] using a host-owned app-private @@ -44,19 +42,9 @@ internal class DurableSessionEventLogPlugin private constructor( companion object { const val PLUGIN_ID: String = "durable-session-event-log" - /** The root's directory name under an app's no-backup storage (`agent-runtime-android`'s `appPrivate`). */ + /** Directory name for the internal packaged log's default root. */ const val ROOT_DIRECTORY: String = "agent-runtime" fun forRoot(root: File): DurableSessionEventLogPlugin = DurableSessionEventLogPlugin(root) } } - -/** - * Opens the durable file-backed session event log under [root] directly, the same log [DurableSessionEventLogPlugin] - * installs. - */ -@ExperimentalAgentRuntimeApi -fun openFileBackedSessionEventLog( - root: File, - eventIdFactory: () -> String = { UUID.randomUUID().toString() }, -): SessionEventLog = FileBackedSessionEventLog(root, eventIdFactory = eventIdFactory) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventLogs.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventLogs.kt new file mode 100644 index 0000000..2dd5506 --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventLogs.kt @@ -0,0 +1,19 @@ +@file:JvmName("SessionEventLogs") + +package cc.noharry.agent.runtime.eventlog + +import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi +import cc.noharry.agent.spi.SessionEventLog +import java.io.File +import java.util.UUID + +/** + * Opens a durable session event log under a host-owned private [root]. It can be supplied with + * `AgentRuntimeBuilder.sessionEventLog`; Android hosts normally use `appPrivateSessionEventLog(context)`. + */ +@ExperimentalAgentRuntimeApi +@JvmOverloads +fun openFileBackedSessionEventLog( + root: File, + eventIdFactory: () -> String = { UUID.randomUUID().toString() }, +): SessionEventLog = FileBackedSessionEventLog(root, eventIdFactory = eventIdFactory) From 51d69613c676f3b1bf781b15e409d61277e2b208 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Fri, 6 Nov 2026 23:32:38 -0800 Subject: [PATCH 03/40] fix(api): preserve saved thread options and independent budgets Treat null resume options as unchanged, allow explicit override resets, and retain limits when settings only change advanced behavior. Cover saved approval policy and model request behavior across runtime recreation. Validated with apiDump, ciCheck, Bothy compilation and independent review. Co-Authored-By: Codex --- CHANGELOG.md | 5 ++ agent-api/api/agent-api.api | 20 ++++-- .../main/kotlin/cc/noharry/agent/TurnInput.kt | 11 +++- .../agent/kernel/core/loop/NativeToolLoop.kt | 8 +-- .../agent/runtime/AgentRuntimeBuilder.kt | 4 +- .../cc/noharry/agent/runtime/LoopSettings.kt | 5 +- .../runtime/thread/DefaultAgentThread.kt | 2 +- .../runtime/thread/DefaultThreadRuntime.kt | 10 +-- .../runtime/thread/ThreadOptionsMerge.kt | 15 +++++ .../agent/runtime/thread/ThreadRecordCodec.kt | 2 +- .../agent/runtime/IndependentLimitsTest.kt | 38 +++++++++++ .../agent/runtime/ThreadOptionPatchTest.kt | 65 +++++++++++++++++++ 12 files changed, 163 insertions(+), 22 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadOptionsMerge.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/IndependentLimitsTest.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadOptionPatchTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index a6a9518..14953de 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Thread option patches preserve saved approval policy.** Null values on resume retain saved defaults; + `ThreadOptions.reset` clears selected model, workspace, scene or instruction overrides. New threads still use ASK. +- **Independent budgets survive settings changes.** `LoopSettings.limits` defaults to null, so a settings call does + not reset limits configured through `limits(...)`. An explicit settings budget still replaces them. + - **Stable budgets, experimental advanced tuning.** `LoopLimits` is stable. Narration and service-answer checks, memory/concurrency/tool-exposure tuning, and structured event-log payloads remain experimental. - **Java event-log factory.** Open a durable log with `SessionEventLogs.openFileBackedSessionEventLog(File)`. diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index 5d42809..1143018 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -500,22 +500,34 @@ public final class cc/noharry/agent/ThreadItem$WebSearch : cc/noharry/agent/Thre public fun toString ()Ljava/lang/String; } +public final class cc/noharry/agent/ThreadOption : java/lang/Enum { + public static final field INSTRUCTIONS Lcc/noharry/agent/ThreadOption; + public static final field MODEL Lcc/noharry/agent/ThreadOption; + public static final field SCENE Lcc/noharry/agent/ThreadOption; + public static final field WORKSPACE Lcc/noharry/agent/ThreadOption; + public static fun getEntries ()Lkotlin/enums/EnumEntries; + public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/ThreadOption; + public static fun values ()[Lcc/noharry/agent/ThreadOption; +} + public final class cc/noharry/agent/ThreadOptions { public fun ()V - public fun (Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ApprovalPolicy;)V - public synthetic fun (Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ApprovalPolicy;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ApprovalPolicy;Ljava/util/Set;)V + public synthetic fun (Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ApprovalPolicy;Ljava/util/Set;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun component1 ()Ljava/lang/String; public final fun component2 ()Lcc/noharry/agent/spi/model/ModelRef; public final fun component3 ()Ljava/lang/String; public final fun component4 ()Ljava/lang/String; public final fun component5 ()Ljava/lang/String; public final fun component6 ()Lcc/noharry/agent/ApprovalPolicy; - public final fun copy (Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ApprovalPolicy;)Lcc/noharry/agent/ThreadOptions; - public static synthetic fun copy$default (Lcc/noharry/agent/ThreadOptions;Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ApprovalPolicy;ILjava/lang/Object;)Lcc/noharry/agent/ThreadOptions; + public final fun component7 ()Ljava/util/Set; + public final fun copy (Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ApprovalPolicy;Ljava/util/Set;)Lcc/noharry/agent/ThreadOptions; + public static synthetic fun copy$default (Lcc/noharry/agent/ThreadOptions;Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ApprovalPolicy;Ljava/util/Set;ILjava/lang/Object;)Lcc/noharry/agent/ThreadOptions; public fun equals (Ljava/lang/Object;)Z public final fun getApprovalPolicy ()Lcc/noharry/agent/ApprovalPolicy; public final fun getInstructions ()Ljava/lang/String; public final fun getModel ()Lcc/noharry/agent/spi/model/ModelRef; + public final fun getReset ()Ljava/util/Set; public final fun getScene ()Ljava/lang/String; public final fun getThreadId ()Ljava/lang/String; public final fun getWorkspace ()Ljava/lang/String; diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/TurnInput.kt b/agent-api/src/main/kotlin/cc/noharry/agent/TurnInput.kt index c1144c2..6baaf9b 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/TurnInput.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/TurnInput.kt @@ -28,16 +28,23 @@ sealed interface InputPart { data class Attachment(val ref: SessionAttachmentRef) : InputPart } -/** Defaults for a thread. A null model uses the runtime's configured model. */ +/** + * Defaults for a new thread, or a patch when resuming one. Null fields retain saved values on resume; for a new + * thread they use runtime defaults (ASK for approvals). Use [reset] to clear individual saved overrides explicitly. + */ data class ThreadOptions( val threadId: String? = null, val model: ModelRef? = null, val workspace: String? = null, val scene: String? = null, val instructions: String? = null, - val approvalPolicy: ApprovalPolicy = ApprovalPolicy.ASK, + val approvalPolicy: ApprovalPolicy? = null, + val reset: Set = emptySet(), ) +/** Saved overrides that can be cleared independently while resuming a thread. Explicit values take precedence. */ +enum class ThreadOption { MODEL, WORKSPACE, SCENE, INSTRUCTIONS } + /** Overrides for one turn. A caller-supplied turn id is the idempotency key. */ data class TurnOptions( val turnId: String? = null, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt index 8f903d8..f6bfcd4 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt @@ -92,8 +92,8 @@ internal class NativeToolLoop( sessionRecorder, toolExecutionLimiter = toolExecutionLimiter, failureBreaker = ToolCallFailureBreaker( - loopSettings.limits.failuresPerCall, - loopSettings.limits.failuresPerTool, + loopSettings.resolvedLimits.failuresPerCall, + loopSettings.resolvedLimits.failuresPerTool, loopSettings.serviceAnswer, ), obligationLedger = obligationLedger, @@ -108,7 +108,7 @@ internal class NativeToolLoop( nowEpochMillis, sessionRecorder, steeringQueue, - ModelImageRequestView(imageInputEnabled = loopBudget.imageInputEnabled, keepNewest = loopSettings.limits.newestImages), + ModelImageRequestView(imageInputEnabled = loopBudget.imageInputEnabled, keepNewest = loopSettings.resolvedLimits.newestImages), textNeedsFinish = textNeedsFinish, userReachable = userReachable, narrationCheck = loopSettings.narration, @@ -337,7 +337,7 @@ internal class NativeToolLoop( steeringQueue.open(toolContext, sessionRecorder) var activeModelRef = modelRef var probeRoundIndex = 0 - val repeatedCalls = RepeatToolCallReminder(loopSettings.limits.repeatReminders) + val repeatedCalls = RepeatToolCallReminder(loopSettings.resolvedLimits.repeatReminders) // A finish accepted while user input was pending; it is the fallback if the continuation cannot run. var withheldFinish: RoundOutcome.Finished? = null try { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilder.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilder.kt index 29cb8b9..1257700 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilder.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilder.kt @@ -418,8 +418,8 @@ class AgentRuntimeBuilder { internal fun loopSettings(settings: LoopSettings): AgentRuntimeBuilder = settings(settings) fun settings(settings: LoopSettings): AgentRuntimeBuilder = apply { - limits(settings.limits) - loopSettings = settings + settings.limits?.let(::limits) + loopSettings = settings.withLimits(settings.limits ?: loopSettings.resolvedLimits) imageInput(settings.imageInputEnabled) deferredBackendTools(settings.backendTools == BackendTools.SEARCH) nativeDeferredTools(settings.backendTools == BackendTools.NATIVE_DEFERRED) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/LoopSettings.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/LoopSettings.kt index b077281..9c1dff2 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/LoopSettings.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/LoopSettings.kt @@ -24,7 +24,8 @@ data class LoopSettings @JvmOverloads constructor( val memory: RuntimeMemoryRetriever = RuntimeMemoryRetriever(), val serviceAnswer: ServiceAnswerCheck = RuntimeServiceAnswerCheck, val contextTimeoutMillis: Long = RuntimeContextHooks.CONTEXT_AGGREGATE_TIMEOUT_MS, - val limits: LoopLimits = LoopLimits(), + /** Optional budget override. Null keeps the builder's independently configured limits. */ + val limits: LoopLimits? = null, val imageInputEnabled: Boolean = true, val backendTools: BackendTools = BackendTools.DIRECT, val runContextAsSystem: Boolean = false, @@ -35,6 +36,8 @@ data class LoopSettings @JvmOverloads constructor( val hookTimeoutMillis: Long = 5_000, val concurrency: RuntimeConcurrency = RuntimeConcurrency(), ) { + internal val resolvedLimits: LoopLimits = limits ?: LoopLimits() + init { require(contextTimeoutMillis in 1..MAX_CONTEXT_TIMEOUT_MILLIS) { "contextTimeoutMillis must be 1 to $MAX_CONTEXT_TIMEOUT_MILLIS." } } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 4b1e702..28a101a 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -139,7 +139,7 @@ internal class DefaultAgentThread( private suspend fun approve(turn: ActiveThreadTurn, pending: PendingConfirmation, options: TurnOptions): ApprovalState { val projection = checkNotNull(turn.projection) - val policy = options.approvalPolicy ?: turn.options.approvalPolicy + val policy = options.approvalPolicy ?: turn.options.approvalPolicy ?: ApprovalPolicy.ASK val domain = approvalDomain(pending.toolName.orEmpty(), pending.argumentsJson.orEmpty()) val automatic = when (policy) { ApprovalPolicy.APPROVE_ALL -> ApprovalState.APPROVED diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt index 39e4d80..994d37b 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt @@ -40,7 +40,7 @@ internal class DefaultThreadRuntime( override fun startThread(options: ThreadOptions): AgentThread { checkOpen() val id = options.threadId ?: UUID.randomUUID().toString() - val record = store.create(id, options) + val record = store.create(id, mergeThreadOptions(ThreadOptions(), options)) return handle(record) } @@ -48,12 +48,8 @@ internal class DefaultThreadRuntime( checkOpen() require(threadId.isNotBlank()) { "Thread id must not be blank" } require(options.threadId == null || options.threadId == threadId) { "Thread id does not match options" } - val saved = store.load(threadId) ?: store.create(threadId, options) - val merged = saved.options.copy( - model = options.model ?: saved.options.model, workspace = options.workspace ?: saved.options.workspace, - scene = options.scene ?: saved.options.scene, instructions = options.instructions ?: saved.options.instructions, - approvalPolicy = if (options == ThreadOptions()) saved.options.approvalPolicy else options.approvalPolicy, - ) + val saved = store.load(threadId) ?: store.create(threadId, mergeThreadOptions(ThreadOptions(), options)) + val merged = mergeThreadOptions(saved.options, options) return handle(saved.copy(options = merged)).also { it.configure(merged) } } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadOptionsMerge.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadOptionsMerge.kt new file mode 100644 index 0000000..8fc0c04 --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadOptionsMerge.kt @@ -0,0 +1,15 @@ +package cc.noharry.agent.runtime.thread + +import cc.noharry.agent.ApprovalPolicy +import cc.noharry.agent.ThreadOption +import cc.noharry.agent.ThreadOptions + +internal fun mergeThreadOptions(saved: ThreadOptions, patch: ThreadOptions): ThreadOptions = saved.copy( + threadId = patch.threadId ?: saved.threadId, + model = patch.model ?: saved.model.takeUnless { ThreadOption.MODEL in patch.reset }, + workspace = patch.workspace ?: saved.workspace.takeUnless { ThreadOption.WORKSPACE in patch.reset }, + scene = patch.scene ?: saved.scene.takeUnless { ThreadOption.SCENE in patch.reset }, + instructions = patch.instructions ?: saved.instructions.takeUnless { ThreadOption.INSTRUCTIONS in patch.reset }, + approvalPolicy = patch.approvalPolicy ?: saved.approvalPolicy ?: ApprovalPolicy.ASK, + reset = emptySet(), +) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt index f6062be..1c81317 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt @@ -60,7 +60,7 @@ internal class ThreadRecordCodec( options.scene?.let { put("scene", it) } options.workspace?.let { put("workspace", it) } options.instructions?.let { put("instructions", it) } - put("approvalPolicy", options.approvalPolicy.name) + put("approvalPolicy", (options.approvalPolicy ?: ApprovalPolicy.ASK).name) options.model?.let { model -> put("model", buildJsonObject { put("providerId", model.providerId); put("modelId", model.modelId) model.variant?.let { put("variant", it) } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/IndependentLimitsTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/IndependentLimitsTest.kt new file mode 100644 index 0000000..b25d6e0 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/IndependentLimitsTest.kt @@ -0,0 +1,38 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.ThreadEvent +import cc.noharry.agent.spi.NarrationCheck +import cc.noharry.agent.spi.model.ModelEvent +import kotlinx.coroutines.flow.toList +import kotlinx.coroutines.runBlocking +import org.junit.Assert.* +import org.junit.Test + +class IndependentLimitsTest { + @Test fun changingNarrationDoesNotResetAnExistingRoundBudget() = runBlocking { + val model = ThreadScriptModel(listOf( + listOf(ModelEvent.ToolCall("todo", "update_todo", """{"items":[]}"""), ModelEvent.Completed), + finishEvents("would need another round"), + )) + threadBuilder(model).limits(LoopLimits(maxModelRounds = 1)) + .settings(LoopSettings(narration = NarrationCheck { false })).build().use { runtime -> + val events = runtime.startThread().runStreamed("continue").toList() + assertEquals("MODEL_LOOP_BUDGET_EXCEEDED", (events.last() as ThreadEvent.TurnFailed).error.code) + assertEquals(1, model.requests.size) + } + } + + @Test fun anExplicitSettingsBudgetStillReplacesThePreviousOne() = runBlocking { + val model = ThreadScriptModel(listOf( + listOf(ModelEvent.ToolCall("todo", "update_todo", """{"items":[]}"""), ModelEvent.Completed), + finishEvents("done"), + )) + threadBuilder(model).limits(LoopLimits(maxModelRounds = 1)) + .settings(LoopSettings(limits = LoopLimits(maxModelRounds = 2))).build().use { runtime -> + assertEquals("done", runtime.startThread().run("continue").finalResponse) + assertEquals(2, model.requests.size) + } + } +} diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadOptionPatchTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadOptionPatchTest.kt new file mode 100644 index 0000000..2d717d1 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadOptionPatchTest.kt @@ -0,0 +1,65 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.runtime.thread.DefaultThreadRuntime +import cc.noharry.agent.spi.model.ModelRef +import kotlinx.coroutines.flow.toList +import kotlinx.coroutines.runBlocking +import org.junit.Assert.* +import org.junit.Test + +class ThreadOptionPatchTest { + @Test fun resumingOnlySceneRetainsEverySavedApprovalPolicy() = runBlocking { + for (policy in listOf(ApprovalPolicy.APPROVE_ALL, ApprovalPolicy.DENY_ALL, ApprovalPolicy.REMEMBER)) { + val root = threadRoot() + approvalBuilder(root).build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "saved", approvalPolicy = policy)) + if (policy == ApprovalPolicy.REMEMBER) thread.runStreamed("set temperature").collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) (event.item as Approval).approve() + } + } + approvalBuilder(root).build().use { runtime -> + val thread = runtime.resumeThread("saved", ThreadOptions(scene = "new-scene")) + var requested = 0 + thread.runStreamed("set temperature").collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + requested++ + (event.item as Approval).deny() + } + } + assertEquals("Policy $policy must survive an unrelated option patch", 0, requested) + } + } + } + + @Test fun individualOverridesCanBeClearedWithoutResettingOtherDefaults() = runBlocking { + val model = ThreadScriptModel(listOf(finishEvents("done"))) + threadBuilder(model).build().use { runtime -> + runtime.startThread(ThreadOptions(threadId = "reset", model = ModelRef("custom", "custom-model"), + scene = "keep-scene", workspace = "default", instructions = "SAVED_THREAD_INSTRUCTIONS", + approvalPolicy = ApprovalPolicy.DENY_ALL)) + val thread = runtime.resumeThread("reset", ThreadOptions(reset = setOf(ThreadOption.MODEL, ThreadOption.INSTRUCTIONS))) + assertEquals(TurnStatus.COMPLETED, thread.run("hello").status) + assertNull(model.requests.single().modelRef) + assertFalse(model.requests.single().system.orEmpty().contains("SAVED_THREAD_INSTRUCTIONS")) + val saved = (runtime as DefaultThreadRuntime).store.load("reset")!!.options + assertEquals("keep-scene", saved.scene) + assertEquals("default", saved.workspace) + assertEquals(ApprovalPolicy.DENY_ALL, saved.approvalPolicy) + assertTrue(saved.reset.isEmpty()) + } + } + + @Test fun settingNewValuesWinsOverResetAndExplicitAskReplacesPolicy() = runBlocking { + val model = ThreadScriptModel(listOf(finishEvents("done"))) + threadBuilder(model).build().use { runtime -> + runtime.startThread(ThreadOptions(threadId = "replace", instructions = "OLD", approvalPolicy = ApprovalPolicy.DENY_ALL)) + runtime.resumeThread("replace", ThreadOptions(instructions = "NEW_INSTRUCTIONS", + approvalPolicy = ApprovalPolicy.ASK, reset = setOf(ThreadOption.INSTRUCTIONS))).run("hello") + assertTrue(model.requests.single().system.orEmpty().contains("NEW_INSTRUCTIONS")) + assertEquals(ApprovalPolicy.ASK, (runtime as DefaultThreadRuntime).store.load("replace")!!.options.approvalPolicy) + } + } +} From a021bffb0554fe1edf9fb20ec515862fce6726fa Mon Sep 17 00:00:00 2001 From: NoHarry Date: Fri, 6 Nov 2026 23:26:57 -0800 Subject: [PATCH 04/40] refactor(api): separate runtime contracts from their implementation Move AgentRuntime and its diagnostic contracts to agent-api. Keep construction and runtime inspection in agent-runtime, with Kotlin companion extensions and the existing Java create factory. Verified API-only consumers, Kotlin/Java factories, module boundaries and API dumps; independently reviewed. Co-Authored-By: Codex --- CHANGELOG.md | 4 + agent-api/api/agent-api.api | 229 +++++++++++++++ .../kotlin/cc/noharry/agent/AgentRuntime.kt | 12 +- .../cc/noharry/agent/RuntimeDiagnostics.kt | 20 ++ .../agent/spi/reliability/RuntimeRecords.kt | 119 ++++++++ .../agent/RuntimeContractClasspathTest.java | 16 ++ .../agent/spi/ApiPackageImportBoundaryTest.kt | 4 +- .../SessionRunSchedulerDeviceSmokeTest.kt | 1 + agent-runtime/api/agent-runtime.api | 269 ++---------------- .../cc/noharry/agent/AgentRuntimeFactories.kt | 8 + .../cc/noharry/agent/RuntimeDiagnostics.kt | 40 --- .../agent/runtime/RuntimeInspection.kt | 28 ++ .../agent/spi/reliability/RuntimeRecords.kt | 114 -------- .../META-INF/proguard/agent-runtime.pro | 1 + .../agent/spi/JavaHostDefaultsTest.java | 10 + ...xperimentalAgentRuntimeApiInventoryTest.kt | 2 +- .../agent/release/ReleaseHardeningTest.kt | 2 + .../agent/runtime/PublicBuilderTest.kt | 1 + .../cc/noharry/agent/minimal/MinimalAgent.kt | 1 + 19 files changed, 465 insertions(+), 416 deletions(-) rename {agent-runtime => agent-api}/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt (75%) create mode 100644 agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt create mode 100644 agent-api/src/main/kotlin/cc/noharry/agent/spi/reliability/RuntimeRecords.kt create mode 100644 agent-api/src/test/java/cc/noharry/agent/RuntimeContractClasspathTest.java create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/AgentRuntimeFactories.kt delete mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeInspection.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 14953de..37ead75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ called out; a patch release does not break it. memory/concurrency/tool-exposure tuning, and structured event-log payloads remain experimental. - **Java event-log factory.** Open a durable log with `SessionEventLogs.openFileBackedSessionEventLog(File)`. The Kotlin top-level function keeps its name; the old plugin-named JVM facade is removed. +- **Runtime contracts belong to `agent-api`.** Libraries that accept `AgentRuntime` or its experimental diagnostics + no longer need the runtime implementation. Kotlin construction imports `cc.noharry.agent.builder` from + `agent-runtime`; Java uses `AgentRuntimeBuilder.create()`. Implementation-specific prompt and tool catalog + helpers move from `RuntimeDiagnostics.Companion` to `cc.noharry.agent.runtime.RuntimeInspection`. - **Breaking: Thread / Turn / Item replaces the run API.** Import the stable conversation contracts from `cc.noharry.agent`: start or resume an `AgentThread`, call `run` for a `TurnResult` or collect `runStreamed`. diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index 1143018..1bd5eb9 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -1,3 +1,23 @@ +public abstract interface class cc/noharry/agent/AgentRuntime : java/lang/AutoCloseable { + public static final field Companion Lcc/noharry/agent/AgentRuntime$Companion; + public abstract fun close ()V + public abstract fun deleteThread (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getDiagnostics ()Lcc/noharry/agent/RuntimeDiagnostics; + public abstract fun listThreads (Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun resumeThread (Ljava/lang/String;Lcc/noharry/agent/ThreadOptions;)Lcc/noharry/agent/AgentThread; + public static synthetic fun resumeThread$default (Lcc/noharry/agent/AgentRuntime;Ljava/lang/String;Lcc/noharry/agent/ThreadOptions;ILjava/lang/Object;)Lcc/noharry/agent/AgentThread; + public abstract fun startThread (Lcc/noharry/agent/ThreadOptions;)Lcc/noharry/agent/AgentThread; + public static synthetic fun startThread$default (Lcc/noharry/agent/AgentRuntime;Lcc/noharry/agent/ThreadOptions;ILjava/lang/Object;)Lcc/noharry/agent/AgentThread; +} + +public final class cc/noharry/agent/AgentRuntime$Companion { +} + +public final class cc/noharry/agent/AgentRuntime$DefaultImpls { + public static synthetic fun resumeThread$default (Lcc/noharry/agent/AgentRuntime;Ljava/lang/String;Lcc/noharry/agent/ThreadOptions;ILjava/lang/Object;)Lcc/noharry/agent/AgentThread; + public static synthetic fun startThread$default (Lcc/noharry/agent/AgentRuntime;Lcc/noharry/agent/ThreadOptions;ILjava/lang/Object;)Lcc/noharry/agent/AgentThread; +} + public abstract interface class cc/noharry/agent/AgentThread { public abstract fun getId ()Ljava/lang/String; public abstract fun interrupt (Lkotlin/coroutines/Continuation;)Ljava/lang/Object; @@ -191,6 +211,18 @@ public final class cc/noharry/agent/RespondResult : java/lang/Enum { public static fun values ()[Lcc/noharry/agent/RespondResult; } +public abstract interface class cc/noharry/agent/RuntimeDiagnostics { + public abstract fun getRunState (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getRuntimeEvidence (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getRuntimeHandoff (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getRuntimeResult (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getRuntimeTraceEvents (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getSessionEventLogHealth (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun querySessionEvents (Lcc/noharry/agent/spi/SessionEventQuery;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun replaySessionEvents (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun subscribeSessionEvents (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Ljava/lang/AutoCloseable; +} + public final class cc/noharry/agent/SteerResult : java/lang/Enum { public static final field ACCEPTED Lcc/noharry/agent/SteerResult; public static final field EMPTY_INPUT Lcc/noharry/agent/SteerResult; @@ -2382,6 +2414,46 @@ public final class cc/noharry/agent/spi/model/ModelVariant { public fun toString ()Ljava/lang/String; } +public final class cc/noharry/agent/spi/reliability/RuntimeCompletionOutcome : java/lang/Enum { + public static final field BLOCKED Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; + public static final field FAILED Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; + public static final field PARTIAL Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; + public static final field SUCCEEDED Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; + public static final field UNKNOWN Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; + public static fun getEntries ()Lkotlin/enums/EnumEntries; + public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; + public static fun values ()[Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; +} + +public final class cc/noharry/agent/spi/reliability/RuntimeCompletionSummary { + public static final field Companion Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary$Companion; + public fun ()V + public fun (Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome;IIILjava/util/List;Ljava/lang/String;)V + public synthetic fun (Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome;IIILjava/util/List;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; + public final fun component2 ()I + public final fun component3 ()I + public final fun component4 ()I + public final fun component5 ()Ljava/util/List; + public final fun component6 ()Ljava/lang/String; + public final fun copy (Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome;IIILjava/util/List;Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; + public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome;IIILjava/util/List;Ljava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; + public fun equals (Ljava/lang/Object;)Z + public final fun getOutcome ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; + public final fun getProjectionDigest ()Ljava/lang/String; + public final fun getRequiredSucceeded ()I + public final fun getRequiredTotal ()I + public final fun getRequiredUnresolved ()I + public final fun getUnresolvedCodes ()Ljava/util/List; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + +public final class cc/noharry/agent/spi/reliability/RuntimeCompletionSummary$Companion { + public final fun firstPartyPass (Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;)Z + public final fun unknown ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; +} + public final class cc/noharry/agent/spi/reliability/RuntimeErrorCode : java/lang/Enum { public static final field ADMISSION_POLICY_REQUIRED Lcc/noharry/agent/spi/reliability/RuntimeErrorCode; public static final field BACKEND_CALL_FAILED Lcc/noharry/agent/spi/reliability/RuntimeErrorCode; @@ -2447,3 +2519,160 @@ public final class cc/noharry/agent/spi/reliability/RuntimeErrorCode : java/lang public static fun values ()[Lcc/noharry/agent/spi/reliability/RuntimeErrorCode; } +public final class cc/noharry/agent/spi/reliability/RuntimeEvidence { + public fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType;Ljava/lang/String;JLjava/lang/String;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType;Ljava/lang/String;JLjava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Ljava/lang/String; + public final fun component2 ()Ljava/lang/String; + public final fun component3 ()Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public final fun component4 ()Ljava/lang/String; + public final fun component5 ()J + public final fun component6 ()Ljava/lang/String; + public final fun copy (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType;Ljava/lang/String;JLjava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeEvidence; + public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeEvidence;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType;Ljava/lang/String;JLjava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeEvidence; + public fun equals (Ljava/lang/Object;)Z + public final fun getCreatedAtEpochMillis ()J + public final fun getEvidenceId ()Ljava/lang/String; + public final fun getRunId ()Ljava/lang/String; + public final fun getSummary ()Ljava/lang/String; + public final fun getTraceEventName ()Ljava/lang/String; + public final fun getType ()Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + +public final class cc/noharry/agent/spi/reliability/RuntimeEvidenceType : java/lang/Enum { + public static final field BLOCKER_RECORDED Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public static final field HANDOFF_WRITTEN Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public static final field MCP_DEBUG_CALL Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public static final field RESULT_WRITTEN Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public static final field RUN_CREATED Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public static final field WORKPAD_UPDATED Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public static fun getEntries ()Lkotlin/enums/EnumEntries; + public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; + public static fun values ()[Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; +} + +public final class cc/noharry/agent/spi/reliability/RuntimeHandoff { + public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;JLjava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;JLjava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Ljava/lang/String; + public final fun component10 ()Ljava/util/List; + public final fun component11 ()Ljava/util/List; + public final fun component2 ()Ljava/lang/String; + public final fun component3 ()Ljava/lang/String; + public final fun component4 ()Ljava/util/List; + public final fun component5 ()Ljava/util/List; + public final fun component6 ()Ljava/util/List; + public final fun component7 ()J + public final fun component8 ()Ljava/lang/String; + public final fun component9 ()Ljava/util/List; + public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;JLjava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;)Lcc/noharry/agent/spi/reliability/RuntimeHandoff; + public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeHandoff;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;JLjava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeHandoff; + public fun equals (Ljava/lang/Object;)Z + public final fun getDecisions ()Ljava/util/List; + public final fun getDoNotRepeat ()Ljava/util/List; + public final fun getDone ()Ljava/util/List; + public final fun getEvidenceRefs ()Ljava/util/List; + public final fun getNextActions ()Ljava/util/List; + public final fun getRunId ()Ljava/lang/String; + public final fun getSessionId ()Ljava/lang/String; + public final fun getSummary ()Ljava/lang/String; + public final fun getTask ()Ljava/lang/String; + public final fun getTriedAndAbandoned ()Ljava/util/List; + public final fun getUpdatedAtEpochMillis ()J + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + +public final class cc/noharry/agent/spi/reliability/RuntimeResult { + public fun (Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Ljava/lang/String;Ljava/util/List;Ljava/lang/String;ZLcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;)V + public synthetic fun (Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Ljava/lang/String;Ljava/util/List;Ljava/lang/String;ZLcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Ljava/lang/String; + public final fun component2 ()Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public final fun component3 ()Ljava/lang/String; + public final fun component4 ()Ljava/util/List; + public final fun component5 ()Ljava/lang/String; + public final fun component6 ()Z + public final fun component7 ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; + public final fun copy (Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Ljava/lang/String;Ljava/util/List;Ljava/lang/String;ZLcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;)Lcc/noharry/agent/spi/reliability/RuntimeResult; + public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeResult;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Ljava/lang/String;Ljava/util/List;Ljava/lang/String;ZLcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeResult; + public fun equals (Ljava/lang/Object;)Z + public final fun getCompletion ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; + public final fun getErrorCode ()Ljava/lang/String; + public final fun getEvidenceIds ()Ljava/util/List; + public final fun getRecoverable ()Z + public final fun getResponse ()Ljava/lang/String; + public final fun getRunId ()Ljava/lang/String; + public final fun getStatus ()Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + +public final class cc/noharry/agent/spi/reliability/RuntimeRunSnapshot { + public fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;JLcc/noharry/agent/spi/reliability/SuggestedNextAction;Ljava/lang/String;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;JLcc/noharry/agent/spi/reliability/SuggestedNextAction;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Ljava/lang/String; + public final fun component2 ()Ljava/lang/String; + public final fun component3 ()Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public final fun component4 ()J + public final fun component5 ()Lcc/noharry/agent/spi/reliability/SuggestedNextAction; + public final fun component6 ()Ljava/lang/String; + public final fun copy (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;JLcc/noharry/agent/spi/reliability/SuggestedNextAction;Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeRunSnapshot; + public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeRunSnapshot;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;JLcc/noharry/agent/spi/reliability/SuggestedNextAction;Ljava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeRunSnapshot; + public fun equals (Ljava/lang/Object;)Z + public final fun getPendingConfirmationId ()Ljava/lang/String; + public final fun getRunId ()Ljava/lang/String; + public final fun getSessionId ()Ljava/lang/String; + public final fun getStatus ()Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public final fun getSuggestedNextAction ()Lcc/noharry/agent/spi/reliability/SuggestedNextAction; + public final fun getUpdatedAtEpochMillis ()J + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + +public final class cc/noharry/agent/spi/reliability/RuntimeRunStatus : java/lang/Enum { + public static final field BLOCKED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static final field CANCELLED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static final field COMPLETED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static final field CREATED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static final field FAILED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static final field QUEUED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static final field RUNNING Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static final field WAITING_CONFIRMATION Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static final field WAITING_USER_INPUT Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static fun getEntries ()Lkotlin/enums/EnumEntries; + public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; + public static fun values ()[Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; +} + +public final class cc/noharry/agent/spi/reliability/RuntimeTraceEvent { + public fun (Ljava/lang/String;Ljava/lang/String;JLjava/lang/String;Ljava/util/Map;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;JLjava/lang/String;Ljava/util/Map;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Ljava/lang/String; + public final fun component2 ()Ljava/lang/String; + public final fun component3 ()J + public final fun component4 ()Ljava/lang/String; + public final fun component5 ()Ljava/util/Map; + public final fun copy (Ljava/lang/String;Ljava/lang/String;JLjava/lang/String;Ljava/util/Map;)Lcc/noharry/agent/spi/reliability/RuntimeTraceEvent; + public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeTraceEvent;Ljava/lang/String;Ljava/lang/String;JLjava/lang/String;Ljava/util/Map;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeTraceEvent; + public fun equals (Ljava/lang/Object;)Z + public final fun getCreatedAtEpochMillis ()J + public final fun getDetails ()Ljava/util/Map; + public final fun getEventName ()Ljava/lang/String; + public final fun getEvidenceId ()Ljava/lang/String; + public final fun getRunId ()Ljava/lang/String; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + +public final class cc/noharry/agent/spi/reliability/SuggestedNextAction : java/lang/Enum { + public static final field ASK_USER Lcc/noharry/agent/spi/reliability/SuggestedNextAction; + public static final field INSPECT_BLOCKER Lcc/noharry/agent/spi/reliability/SuggestedNextAction; + public static final field RESUME_CONFIRMATION Lcc/noharry/agent/spi/reliability/SuggestedNextAction; + public static final field START_NEW_AGENT_REQUEST Lcc/noharry/agent/spi/reliability/SuggestedNextAction; + public static fun getEntries ()Lkotlin/enums/EnumEntries; + public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/SuggestedNextAction; + public static fun values ()[Lcc/noharry/agent/spi/reliability/SuggestedNextAction; +} + diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt b/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt similarity index 75% rename from agent-runtime/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt rename to agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt index 20f121e..8ee3352 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt @@ -2,9 +2,11 @@ package cc.noharry.agent -import cc.noharry.agent.runtime.AgentRuntimeBuilder - -/** An embeddable agent. Configure a model, then start or resume a conversation. */ +/** + * An embeddable agent contract available from the `agent-api` artifact. + * The `agent-runtime` artifact supplies the `builder` companion extension for Kotlin hosts (import + * `cc.noharry.agent.builder`); Java hosts use `AgentRuntimeBuilder.create()` from that artifact. + */ interface AgentRuntime : AutoCloseable { fun startThread(options: ThreadOptions = ThreadOptions()): AgentThread /** @@ -21,7 +23,5 @@ interface AgentRuntime : AutoCloseable { val diagnostics: RuntimeDiagnostics override fun close() - companion object { - @JvmStatic fun builder(): AgentRuntimeBuilder = AgentRuntimeBuilder.create() - } + companion object } diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt b/agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt new file mode 100644 index 0000000..7ae497f --- /dev/null +++ b/agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt @@ -0,0 +1,20 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent + +import cc.noharry.agent.spi.* +import cc.noharry.agent.spi.reliability.* + +/** Advanced diagnostic records, separate from the stable conversation API. */ +@ExperimentalAgentRuntimeApi +interface RuntimeDiagnostics { + suspend fun getRunState(turnId: String): RuntimeRunSnapshot? + suspend fun getRuntimeResult(turnId: String): RuntimeResult? + suspend fun getRuntimeHandoff(turnId: String): RuntimeHandoff? + suspend fun getRuntimeEvidence(evidenceId: String): RuntimeEvidence? + suspend fun getRuntimeTraceEvents(turnId: String): List + suspend fun querySessionEvents(query: SessionEventQuery): List + suspend fun replaySessionEvents(threadId: String, turnId: String): List + suspend fun getSessionEventLogHealth(threadId: String, turnId: String): SessionEventLogHealth + fun subscribeSessionEvents(threadId: String, listener: (SessionEvent) -> Unit): AutoCloseable +} diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/reliability/RuntimeRecords.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/reliability/RuntimeRecords.kt new file mode 100644 index 0000000..918271d --- /dev/null +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/reliability/RuntimeRecords.kt @@ -0,0 +1,119 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.spi.reliability + +import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi + +@ExperimentalAgentRuntimeApi +enum class RuntimeRunStatus { + CREATED, + QUEUED, + RUNNING, + WAITING_CONFIRMATION, + WAITING_USER_INPUT, + BLOCKED, + COMPLETED, + FAILED, + CANCELLED, +} + +@ExperimentalAgentRuntimeApi +data class RuntimeRunSnapshot( + val runId: String, + val sessionId: String, + val status: RuntimeRunStatus, + val updatedAtEpochMillis: Long, + val suggestedNextAction: SuggestedNextAction? = null, + val pendingConfirmationId: String? = null, +) + +/** Redacted waiting-state handoff. */ +@ExperimentalAgentRuntimeApi +data class RuntimeHandoff( + val runId: String, + val sessionId: String, + val summary: String, + val done: List = emptyList(), + val nextActions: List = emptyList(), + val evidenceRefs: List = emptyList(), + val updatedAtEpochMillis: Long = 0, + val task: String? = null, + val decisions: List = emptyList(), + val triedAndAbandoned: List = emptyList(), + val doNotRepeat: List = emptyList(), +) + +@ExperimentalAgentRuntimeApi +enum class RuntimeCompletionOutcome { + SUCCEEDED, + PARTIAL, + BLOCKED, + FAILED, + UNKNOWN, +} + +/** Bounded, metadata-only completion projection. Missing persisted fields decode as UNKNOWN. */ +@ExperimentalAgentRuntimeApi +data class RuntimeCompletionSummary( + val outcome: RuntimeCompletionOutcome = RuntimeCompletionOutcome.UNKNOWN, + val requiredTotal: Int = 0, + val requiredSucceeded: Int = 0, + val requiredUnresolved: Int = 0, + val unresolvedCodes: List = emptyList(), + val projectionDigest: String = "", +) { + companion object { + fun unknown(): RuntimeCompletionSummary = RuntimeCompletionSummary() + + fun firstPartyPass(status: RuntimeRunStatus, completion: RuntimeCompletionSummary): Boolean = + status == RuntimeRunStatus.COMPLETED && completion.outcome == RuntimeCompletionOutcome.SUCCEEDED + } +} + +@ExperimentalAgentRuntimeApi +data class RuntimeResult( + val runId: String, + val status: RuntimeRunStatus, + val response: String, + val evidenceIds: List = emptyList(), + val errorCode: String? = null, + val recoverable: Boolean = true, + val completion: RuntimeCompletionSummary = RuntimeCompletionSummary.unknown(), +) + +@ExperimentalAgentRuntimeApi +data class RuntimeEvidence( + val evidenceId: String, + val runId: String, + val type: RuntimeEvidenceType, + val summary: String, + val createdAtEpochMillis: Long, + val traceEventName: String? = null, +) + +@ExperimentalAgentRuntimeApi +enum class RuntimeEvidenceType { + RUN_CREATED, + WORKPAD_UPDATED, + HANDOFF_WRITTEN, + BLOCKER_RECORDED, + RESULT_WRITTEN, + MCP_DEBUG_CALL, +} + +@ExperimentalAgentRuntimeApi +data class RuntimeTraceEvent( + val runId: String, + val eventName: String, + val createdAtEpochMillis: Long, + val evidenceId: String? = null, + val details: Map = emptyMap(), +) + +@ExperimentalAgentRuntimeApi +enum class SuggestedNextAction { + ASK_USER, + RESUME_CONFIRMATION, + START_NEW_AGENT_REQUEST, + INSPECT_BLOCKER, +} diff --git a/agent-api/src/test/java/cc/noharry/agent/RuntimeContractClasspathTest.java b/agent-api/src/test/java/cc/noharry/agent/RuntimeContractClasspathTest.java new file mode 100644 index 0000000..171ae2e --- /dev/null +++ b/agent-api/src/test/java/cc/noharry/agent/RuntimeContractClasspathTest.java @@ -0,0 +1,16 @@ +package cc.noharry.agent; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertThrows; +import org.junit.Test; + +/** This module's test classpath contains agent-api and its dependencies, without agent-runtime. */ +public class RuntimeContractClasspathTest { + @Test + public void runtimeAndDiagnosticsLinkWithoutTheImplementation() throws Exception { + assertEquals(RuntimeDiagnostics.class, AgentRuntime.class.getMethod("getDiagnostics").getReturnType()); + assertEquals(AgentThread.class, AgentRuntime.class.getMethod("startThread", ThreadOptions.class).getReturnType()); + assertThrows(ClassNotFoundException.class, + () -> Class.forName("cc.noharry.agent.runtime.AgentRuntimeBuilder")); + } +} diff --git a/agent-api/src/test/kotlin/cc/noharry/agent/spi/ApiPackageImportBoundaryTest.kt b/agent-api/src/test/kotlin/cc/noharry/agent/spi/ApiPackageImportBoundaryTest.kt index 9aaafd8..5fc99fd 100644 --- a/agent-api/src/test/kotlin/cc/noharry/agent/spi/ApiPackageImportBoundaryTest.kt +++ b/agent-api/src/test/kotlin/cc/noharry/agent/spi/ApiPackageImportBoundaryTest.kt @@ -9,7 +9,7 @@ import java.io.File class ApiPackageImportBoundaryTest { @Test fun apiProductionSourcesHaveZeroForbiddenImports() { - val root = File("src/main/kotlin/cc/noharry/agent/spi") + val root = File("src/main/kotlin/cc/noharry/agent") assertTrue("api production root must exist: ${root.absolutePath}", root.isDirectory) val forbidden = listOf( @@ -33,7 +33,7 @@ class ApiPackageImportBoundaryTest { } @Test - fun kernelApiModuleHasZeroProjectDependencies() { + fun contractsModuleHasZeroProjectDependencies() { val buildFile = File("build.gradle.kts") assertTrue(buildFile.isFile) val text = buildFile.readText() diff --git a/agent-runtime-android/src/androidTest/kotlin/cc/noharry/agent/runtime/android/SessionRunSchedulerDeviceSmokeTest.kt b/agent-runtime-android/src/androidTest/kotlin/cc/noharry/agent/runtime/android/SessionRunSchedulerDeviceSmokeTest.kt index 75258ca..a16473c 100644 --- a/agent-runtime-android/src/androidTest/kotlin/cc/noharry/agent/runtime/android/SessionRunSchedulerDeviceSmokeTest.kt +++ b/agent-runtime-android/src/androidTest/kotlin/cc/noharry/agent/runtime/android/SessionRunSchedulerDeviceSmokeTest.kt @@ -4,6 +4,7 @@ package cc.noharry.agent.runtime.android import androidx.test.runner.AndroidJUnit4 import cc.noharry.agent.AgentRuntime +import cc.noharry.agent.builder import cc.noharry.agent.AgentThread import cc.noharry.agent.ThreadStatus import cc.noharry.agent.TurnStatus diff --git a/agent-runtime/api/agent-runtime.api b/agent-runtime/api/agent-runtime.api index 75be9d0..ac25054 100644 --- a/agent-runtime/api/agent-runtime.api +++ b/agent-runtime/api/agent-runtime.api @@ -1,59 +1,5 @@ -public abstract interface class cc/noharry/agent/AgentRuntime : java/lang/AutoCloseable { - public static final field Companion Lcc/noharry/agent/AgentRuntime$Companion; - public static fun builder ()Lcc/noharry/agent/runtime/AgentRuntimeBuilder; - public abstract fun close ()V - public abstract fun deleteThread (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getDiagnostics ()Lcc/noharry/agent/RuntimeDiagnostics; - public abstract fun listThreads (Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun resumeThread (Ljava/lang/String;Lcc/noharry/agent/ThreadOptions;)Lcc/noharry/agent/AgentThread; - public static synthetic fun resumeThread$default (Lcc/noharry/agent/AgentRuntime;Ljava/lang/String;Lcc/noharry/agent/ThreadOptions;ILjava/lang/Object;)Lcc/noharry/agent/AgentThread; - public abstract fun startThread (Lcc/noharry/agent/ThreadOptions;)Lcc/noharry/agent/AgentThread; - public static synthetic fun startThread$default (Lcc/noharry/agent/AgentRuntime;Lcc/noharry/agent/ThreadOptions;ILjava/lang/Object;)Lcc/noharry/agent/AgentThread; -} - -public final class cc/noharry/agent/AgentRuntime$Companion { - public final fun builder ()Lcc/noharry/agent/runtime/AgentRuntimeBuilder; -} - -public final class cc/noharry/agent/AgentRuntime$DefaultImpls { - public static synthetic fun resumeThread$default (Lcc/noharry/agent/AgentRuntime;Ljava/lang/String;Lcc/noharry/agent/ThreadOptions;ILjava/lang/Object;)Lcc/noharry/agent/AgentThread; - public static synthetic fun startThread$default (Lcc/noharry/agent/AgentRuntime;Lcc/noharry/agent/ThreadOptions;ILjava/lang/Object;)Lcc/noharry/agent/AgentThread; -} - -public abstract interface class cc/noharry/agent/RuntimeDiagnostics { - public static final field Companion Lcc/noharry/agent/RuntimeDiagnostics$Companion; - public static final field DEFERRED_TOOLS_HEADER Ljava/lang/String; - public static final field MAX_HOST_SYSTEM_PROMPT_BYTES I - public static final field RUN_CONTEXT_HEADER Ljava/lang/String; - public static final field SESSION_MODEL_CALL_SOURCE_COMPACTION Ljava/lang/String; - public static final field SESSION_MODEL_CALL_SOURCE_ROUND Ljava/lang/String; - public static final field STATIC_PROMPT_SOFT_BUDGET_BYTES I - public abstract fun getRunState (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getRuntimeEvidence (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getRuntimeHandoff (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getRuntimeResult (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getRuntimeTraceEvents (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getSessionEventLogHealth (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public static fun nativeToolNames ()Ljava/util/Set; - public static fun qualifiedToolName (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String; - public abstract fun querySessionEvents (Lcc/noharry/agent/spi/SessionEventQuery;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun replaySessionEvents (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun subscribeSessionEvents (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Ljava/lang/AutoCloseable; - public static fun toolCatalog (Ljava/util/List;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public static fun validateHostSystemPrompt (Ljava/lang/String;)V -} - -public final class cc/noharry/agent/RuntimeDiagnostics$Companion { - public static final field DEFERRED_TOOLS_HEADER Ljava/lang/String; - public static final field MAX_HOST_SYSTEM_PROMPT_BYTES I - public static final field RUN_CONTEXT_HEADER Ljava/lang/String; - public static final field SESSION_MODEL_CALL_SOURCE_COMPACTION Ljava/lang/String; - public static final field SESSION_MODEL_CALL_SOURCE_ROUND Ljava/lang/String; - public static final field STATIC_PROMPT_SOFT_BUDGET_BYTES I - public final fun nativeToolNames ()Ljava/util/Set; - public final fun qualifiedToolName (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String; - public final fun toolCatalog (Ljava/util/List;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public final fun validateHostSystemPrompt (Ljava/lang/String;)V +public final class cc/noharry/agent/AgentRuntimeFactories { + public static final fun builder (Lcc/noharry/agent/AgentRuntime$Companion;)Lcc/noharry/agent/runtime/AgentRuntimeBuilder; } public final class cc/noharry/agent/ToolCatalogDomain { @@ -593,6 +539,20 @@ public final class cc/noharry/agent/runtime/RuntimeConcurrency { public fun toString ()Ljava/lang/String; } +public final class cc/noharry/agent/runtime/RuntimeInspection { + public static final field DEFERRED_TOOLS_HEADER Ljava/lang/String; + public static final field INSTANCE Lcc/noharry/agent/runtime/RuntimeInspection; + public static final field MAX_HOST_SYSTEM_PROMPT_BYTES I + public static final field RUN_CONTEXT_HEADER Ljava/lang/String; + public static final field SESSION_MODEL_CALL_SOURCE_COMPACTION Ljava/lang/String; + public static final field SESSION_MODEL_CALL_SOURCE_ROUND Ljava/lang/String; + public static final field STATIC_PROMPT_SOFT_BUDGET_BYTES I + public static final fun nativeToolNames ()Ljava/util/Set; + public static final fun qualifiedToolName (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String; + public static final fun toolCatalog (Ljava/util/List;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public static final fun validateHostSystemPrompt (Ljava/lang/String;)V +} + public final class cc/noharry/agent/runtime/RuntimeMemoryPolicy { public fun ()V public fun (IIFFIII)V @@ -900,203 +860,6 @@ public final class cc/noharry/agent/runtime/eventlog/SessionEventLogs { public static synthetic fun openFileBackedSessionEventLog$default (Ljava/io/File;Lkotlin/jvm/functions/Function0;ILjava/lang/Object;)Lcc/noharry/agent/spi/SessionEventLog; } -public final class cc/noharry/agent/spi/reliability/RuntimeCompletionOutcome : java/lang/Enum { - public static final field BLOCKED Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; - public static final field FAILED Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; - public static final field PARTIAL Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; - public static final field SUCCEEDED Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; - public static final field UNKNOWN Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; - public static fun values ()[Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeCompletionSummary { - public static final field Companion Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary$Companion; - public fun ()V - public fun (Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome;IIILjava/util/List;Ljava/lang/String;)V - public synthetic fun (Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome;IIILjava/util/List;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; - public final fun component2 ()I - public final fun component3 ()I - public final fun component4 ()I - public final fun component5 ()Ljava/util/List; - public final fun component6 ()Ljava/lang/String; - public final fun copy (Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome;IIILjava/util/List;Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome;IIILjava/util/List;Ljava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; - public fun equals (Ljava/lang/Object;)Z - public final fun getOutcome ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionOutcome; - public final fun getProjectionDigest ()Ljava/lang/String; - public final fun getRequiredSucceeded ()I - public final fun getRequiredTotal ()I - public final fun getRequiredUnresolved ()I - public final fun getUnresolvedCodes ()Ljava/util/List; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeCompletionSummary$Companion { - public final fun firstPartyPass (Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;)Z - public final fun unknown ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeEvidence { - public fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType;Ljava/lang/String;JLjava/lang/String;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType;Ljava/lang/String;JLjava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public final fun component4 ()Ljava/lang/String; - public final fun component5 ()J - public final fun component6 ()Ljava/lang/String; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType;Ljava/lang/String;JLjava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeEvidence; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeEvidence;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType;Ljava/lang/String;JLjava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeEvidence; - public fun equals (Ljava/lang/Object;)Z - public final fun getCreatedAtEpochMillis ()J - public final fun getEvidenceId ()Ljava/lang/String; - public final fun getRunId ()Ljava/lang/String; - public final fun getSummary ()Ljava/lang/String; - public final fun getTraceEventName ()Ljava/lang/String; - public final fun getType ()Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeEvidenceType : java/lang/Enum { - public static final field BLOCKER_RECORDED Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public static final field HANDOFF_WRITTEN Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public static final field MCP_DEBUG_CALL Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public static final field RESULT_WRITTEN Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public static final field RUN_CREATED Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public static final field WORKPAD_UPDATED Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; - public static fun values ()[Lcc/noharry/agent/spi/reliability/RuntimeEvidenceType; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeHandoff { - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;JLjava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;JLjava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component10 ()Ljava/util/List; - public final fun component11 ()Ljava/util/List; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()Ljava/lang/String; - public final fun component4 ()Ljava/util/List; - public final fun component5 ()Ljava/util/List; - public final fun component6 ()Ljava/util/List; - public final fun component7 ()J - public final fun component8 ()Ljava/lang/String; - public final fun component9 ()Ljava/util/List; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;JLjava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;)Lcc/noharry/agent/spi/reliability/RuntimeHandoff; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeHandoff;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;JLjava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeHandoff; - public fun equals (Ljava/lang/Object;)Z - public final fun getDecisions ()Ljava/util/List; - public final fun getDoNotRepeat ()Ljava/util/List; - public final fun getDone ()Ljava/util/List; - public final fun getEvidenceRefs ()Ljava/util/List; - public final fun getNextActions ()Ljava/util/List; - public final fun getRunId ()Ljava/lang/String; - public final fun getSessionId ()Ljava/lang/String; - public final fun getSummary ()Ljava/lang/String; - public final fun getTask ()Ljava/lang/String; - public final fun getTriedAndAbandoned ()Ljava/util/List; - public final fun getUpdatedAtEpochMillis ()J - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeResult { - public fun (Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Ljava/lang/String;Ljava/util/List;Ljava/lang/String;ZLcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;)V - public synthetic fun (Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Ljava/lang/String;Ljava/util/List;Ljava/lang/String;ZLcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public final fun component3 ()Ljava/lang/String; - public final fun component4 ()Ljava/util/List; - public final fun component5 ()Ljava/lang/String; - public final fun component6 ()Z - public final fun component7 ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; - public final fun copy (Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Ljava/lang/String;Ljava/util/List;Ljava/lang/String;ZLcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;)Lcc/noharry/agent/spi/reliability/RuntimeResult; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeResult;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;Ljava/lang/String;Ljava/util/List;Ljava/lang/String;ZLcc/noharry/agent/spi/reliability/RuntimeCompletionSummary;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeResult; - public fun equals (Ljava/lang/Object;)Z - public final fun getCompletion ()Lcc/noharry/agent/spi/reliability/RuntimeCompletionSummary; - public final fun getErrorCode ()Ljava/lang/String; - public final fun getEvidenceIds ()Ljava/util/List; - public final fun getRecoverable ()Z - public final fun getResponse ()Ljava/lang/String; - public final fun getRunId ()Ljava/lang/String; - public final fun getStatus ()Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeRunSnapshot { - public fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;JLcc/noharry/agent/spi/reliability/SuggestedNextAction;Ljava/lang/String;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;JLcc/noharry/agent/spi/reliability/SuggestedNextAction;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public final fun component4 ()J - public final fun component5 ()Lcc/noharry/agent/spi/reliability/SuggestedNextAction; - public final fun component6 ()Ljava/lang/String; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;JLcc/noharry/agent/spi/reliability/SuggestedNextAction;Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeRunSnapshot; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeRunSnapshot;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/reliability/RuntimeRunStatus;JLcc/noharry/agent/spi/reliability/SuggestedNextAction;Ljava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeRunSnapshot; - public fun equals (Ljava/lang/Object;)Z - public final fun getPendingConfirmationId ()Ljava/lang/String; - public final fun getRunId ()Ljava/lang/String; - public final fun getSessionId ()Ljava/lang/String; - public final fun getStatus ()Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public final fun getSuggestedNextAction ()Lcc/noharry/agent/spi/reliability/SuggestedNextAction; - public final fun getUpdatedAtEpochMillis ()J - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeRunStatus : java/lang/Enum { - public static final field BLOCKED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static final field CANCELLED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static final field COMPLETED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static final field CREATED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static final field FAILED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static final field QUEUED Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static final field RUNNING Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static final field WAITING_CONFIRMATION Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static final field WAITING_USER_INPUT Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; - public static fun values ()[Lcc/noharry/agent/spi/reliability/RuntimeRunStatus; -} - -public final class cc/noharry/agent/spi/reliability/RuntimeTraceEvent { - public fun (Ljava/lang/String;Ljava/lang/String;JLjava/lang/String;Ljava/util/Map;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;JLjava/lang/String;Ljava/util/Map;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()J - public final fun component4 ()Ljava/lang/String; - public final fun component5 ()Ljava/util/Map; - public final fun copy (Ljava/lang/String;Ljava/lang/String;JLjava/lang/String;Ljava/util/Map;)Lcc/noharry/agent/spi/reliability/RuntimeTraceEvent; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/reliability/RuntimeTraceEvent;Ljava/lang/String;Ljava/lang/String;JLjava/lang/String;Ljava/util/Map;ILjava/lang/Object;)Lcc/noharry/agent/spi/reliability/RuntimeTraceEvent; - public fun equals (Ljava/lang/Object;)Z - public final fun getCreatedAtEpochMillis ()J - public final fun getDetails ()Ljava/util/Map; - public final fun getEventName ()Ljava/lang/String; - public final fun getEvidenceId ()Ljava/lang/String; - public final fun getRunId ()Ljava/lang/String; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/reliability/SuggestedNextAction : java/lang/Enum { - public static final field ASK_USER Lcc/noharry/agent/spi/reliability/SuggestedNextAction; - public static final field INSPECT_BLOCKER Lcc/noharry/agent/spi/reliability/SuggestedNextAction; - public static final field RESUME_CONFIRMATION Lcc/noharry/agent/spi/reliability/SuggestedNextAction; - public static final field START_NEW_AGENT_REQUEST Lcc/noharry/agent/spi/reliability/SuggestedNextAction; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/spi/reliability/SuggestedNextAction; - public static fun values ()[Lcc/noharry/agent/spi/reliability/SuggestedNextAction; -} - public abstract interface class cc/noharry/agent/transport/HttpEvent { } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/AgentRuntimeFactories.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/AgentRuntimeFactories.kt new file mode 100644 index 0000000..5d8291e --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/AgentRuntimeFactories.kt @@ -0,0 +1,8 @@ +@file:JvmName("AgentRuntimeFactories") + +package cc.noharry.agent + +import cc.noharry.agent.runtime.AgentRuntimeBuilder + +/** Creates the runtime implementation builder. Java hosts use [AgentRuntimeBuilder.create]. */ +fun AgentRuntime.Companion.builder(): AgentRuntimeBuilder = AgentRuntimeBuilder.create() diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt deleted file mode 100644 index d7647bc..0000000 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt +++ /dev/null @@ -1,40 +0,0 @@ -@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) - -package cc.noharry.agent - -import cc.noharry.agent.spi.* -import cc.noharry.agent.spi.reliability.* - -/** Advanced diagnostic records, separate from the stable conversation API. */ -@ExperimentalAgentRuntimeApi -interface RuntimeDiagnostics { - suspend fun getRunState(turnId: String): RuntimeRunSnapshot? - suspend fun getRuntimeResult(turnId: String): RuntimeResult? - suspend fun getRuntimeHandoff(turnId: String): RuntimeHandoff? - suspend fun getRuntimeEvidence(evidenceId: String): RuntimeEvidence? - suspend fun getRuntimeTraceEvents(turnId: String): List - suspend fun querySessionEvents(query: SessionEventQuery): List - suspend fun replaySessionEvents(threadId: String, turnId: String): List - suspend fun getSessionEventLogHealth(threadId: String, turnId: String): SessionEventLogHealth - fun subscribeSessionEvents(threadId: String, listener: (SessionEvent) -> Unit): AutoCloseable - - companion object { - const val MAX_HOST_SYSTEM_PROMPT_BYTES = cc.noharry.agent.kernel.core.context.MAX_HOST_SYSTEM_PROMPT_BYTES - const val STATIC_PROMPT_SOFT_BUDGET_BYTES = cc.noharry.agent.kernel.core.context.STATIC_PROMPT_SOFT_BUDGET_BYTES - const val RUN_CONTEXT_HEADER = cc.noharry.agent.kernel.core.context.RUN_CONTEXT_HEADER - const val DEFERRED_TOOLS_HEADER = cc.noharry.agent.kernel.core.tools.DEFERRED_TOOLS_HEADER - const val SESSION_MODEL_CALL_SOURCE_ROUND = "round" - const val SESSION_MODEL_CALL_SOURCE_COMPACTION = "compaction" - - @JvmStatic fun validateHostSystemPrompt(text: String) = cc.noharry.agent.kernel.core.context.validateHostSystemPrompt(text) - @JvmStatic fun qualifiedToolName(serverId: String, name: String): String = - cc.noharry.agent.kernel.core.tools.mcpQualifiedName(serverId, name) - - /** Names of the runtime's native tools, including optional tools a host may disable. */ - @JvmStatic fun nativeToolNames(): Set = - cc.noharry.agent.kernel.core.tools.NATIVE_TOOLS.mapTo(linkedSetOf()) { it.name } - - @JvmStatic suspend fun toolCatalog(providers: List): ToolCatalogSnapshot = - inspectToolCatalog(providers) - } -} diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeInspection.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeInspection.kt new file mode 100644 index 0000000..975e2fc --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeInspection.kt @@ -0,0 +1,28 @@ +package cc.noharry.agent.runtime + +import cc.noharry.agent.ToolCatalogSnapshot +import cc.noharry.agent.inspectToolCatalog +import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi +import cc.noharry.agent.spi.ToolProvider + +/** Implementation-specific prompt limits and tool catalog inspection, separate from the conversation contracts. */ +@ExperimentalAgentRuntimeApi +object RuntimeInspection { + const val MAX_HOST_SYSTEM_PROMPT_BYTES = cc.noharry.agent.kernel.core.context.MAX_HOST_SYSTEM_PROMPT_BYTES + const val STATIC_PROMPT_SOFT_BUDGET_BYTES = cc.noharry.agent.kernel.core.context.STATIC_PROMPT_SOFT_BUDGET_BYTES + const val RUN_CONTEXT_HEADER = cc.noharry.agent.kernel.core.context.RUN_CONTEXT_HEADER + const val DEFERRED_TOOLS_HEADER = cc.noharry.agent.kernel.core.tools.DEFERRED_TOOLS_HEADER + const val SESSION_MODEL_CALL_SOURCE_ROUND = "round" + const val SESSION_MODEL_CALL_SOURCE_COMPACTION = "compaction" + + @JvmStatic fun validateHostSystemPrompt(text: String) = cc.noharry.agent.kernel.core.context.validateHostSystemPrompt(text) + @JvmStatic fun qualifiedToolName(serverId: String, name: String): String = + cc.noharry.agent.kernel.core.tools.mcpQualifiedName(serverId, name) + + /** Names of the runtime's native tools, including optional tools a host may disable. */ + @JvmStatic fun nativeToolNames(): Set = + cc.noharry.agent.kernel.core.tools.NATIVE_TOOLS.mapTo(linkedSetOf()) { it.name } + + @JvmStatic suspend fun toolCatalog(providers: List): ToolCatalogSnapshot = + inspectToolCatalog(providers) +} diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/reliability/RuntimeRecords.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/reliability/RuntimeRecords.kt index 188b678..ac4b151 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/reliability/RuntimeRecords.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/reliability/RuntimeRecords.kt @@ -4,29 +4,6 @@ package cc.noharry.agent.spi.reliability import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi -@ExperimentalAgentRuntimeApi -enum class RuntimeRunStatus { - CREATED, - QUEUED, - RUNNING, - WAITING_CONFIRMATION, - WAITING_USER_INPUT, - BLOCKED, - COMPLETED, - FAILED, - CANCELLED, -} - -@ExperimentalAgentRuntimeApi -data class RuntimeRunSnapshot( - val runId: String, - val sessionId: String, - val status: RuntimeRunStatus, - val updatedAtEpochMillis: Long, - val suggestedNextAction: SuggestedNextAction? = null, - val pendingConfirmationId: String? = null, -) - internal data class RuntimeRunEnvelope( val runId: String, val requestId: String, @@ -64,60 +41,6 @@ internal data class CompletionItem( val done: Boolean, ) -/** Redacted waiting-state handoff. */ -@ExperimentalAgentRuntimeApi -data class RuntimeHandoff( - val runId: String, - val sessionId: String, - val summary: String, - val done: List = emptyList(), - val nextActions: List = emptyList(), - val evidenceRefs: List = emptyList(), - val updatedAtEpochMillis: Long = 0, - val task: String? = null, - val decisions: List = emptyList(), - val triedAndAbandoned: List = emptyList(), - val doNotRepeat: List = emptyList(), -) - -@ExperimentalAgentRuntimeApi -enum class RuntimeCompletionOutcome { - SUCCEEDED, - PARTIAL, - BLOCKED, - FAILED, - UNKNOWN, -} - -/** Bounded, metadata-only completion projection. Missing persisted fields decode as UNKNOWN. */ -@ExperimentalAgentRuntimeApi -data class RuntimeCompletionSummary( - val outcome: RuntimeCompletionOutcome = RuntimeCompletionOutcome.UNKNOWN, - val requiredTotal: Int = 0, - val requiredSucceeded: Int = 0, - val requiredUnresolved: Int = 0, - val unresolvedCodes: List = emptyList(), - val projectionDigest: String = "", -) { - companion object { - fun unknown(): RuntimeCompletionSummary = RuntimeCompletionSummary() - - fun firstPartyPass(status: RuntimeRunStatus, completion: RuntimeCompletionSummary): Boolean = - status == RuntimeRunStatus.COMPLETED && completion.outcome == RuntimeCompletionOutcome.SUCCEEDED - } -} - -@ExperimentalAgentRuntimeApi -data class RuntimeResult( - val runId: String, - val status: RuntimeRunStatus, - val response: String, - val evidenceIds: List = emptyList(), - val errorCode: String? = null, - val recoverable: Boolean = true, - val completion: RuntimeCompletionSummary = RuntimeCompletionSummary.unknown(), -) - internal data class RuntimeBlocker( val runId: String, val code: String, @@ -135,43 +58,6 @@ internal data class OpenConfusion( val createdAtEpochMillis: Long = 0, ) -@ExperimentalAgentRuntimeApi -data class RuntimeEvidence( - val evidenceId: String, - val runId: String, - val type: RuntimeEvidenceType, - val summary: String, - val createdAtEpochMillis: Long, - val traceEventName: String? = null, -) - -@ExperimentalAgentRuntimeApi -enum class RuntimeEvidenceType { - RUN_CREATED, - WORKPAD_UPDATED, - HANDOFF_WRITTEN, - BLOCKER_RECORDED, - RESULT_WRITTEN, - MCP_DEBUG_CALL, -} - -@ExperimentalAgentRuntimeApi -data class RuntimeTraceEvent( - val runId: String, - val eventName: String, - val createdAtEpochMillis: Long, - val evidenceId: String? = null, - val details: Map = emptyMap(), -) - -@ExperimentalAgentRuntimeApi -enum class SuggestedNextAction { - ASK_USER, - RESUME_CONFIRMATION, - START_NEW_AGENT_REQUEST, - INSPECT_BLOCKER, -} - /** Candidate-only runtime finding. Promotion requires trusted review outside runtime. */ internal data class RuntimeCandidate( val candidateId: String, diff --git a/agent-runtime/src/main/resources/META-INF/proguard/agent-runtime.pro b/agent-runtime/src/main/resources/META-INF/proguard/agent-runtime.pro index 7e90f56..f7d1144 100644 --- a/agent-runtime/src/main/resources/META-INF/proguard/agent-runtime.pro +++ b/agent-runtime/src/main/resources/META-INF/proguard/agent-runtime.pro @@ -1,6 +1,7 @@ -keep class cc.noharry.agent.* { *; } -keep class cc.noharry.agent.spi.** { *; } -keep class cc.noharry.agent.runtime.AgentRuntimeBuilder { *; } +-keep class cc.noharry.agent.runtime.RuntimeInspection { *; } -keep class cc.noharry.agent.runtime.RuntimeWorkspaceRef { *; } -keep class cc.noharry.agent.runtime.HostSkill { *; } -keep class cc.noharry.agent.runtime.NetworkToolConfirmationPolicy { *; } diff --git a/agent-runtime/src/test/java/cc/noharry/agent/spi/JavaHostDefaultsTest.java b/agent-runtime/src/test/java/cc/noharry/agent/spi/JavaHostDefaultsTest.java index 84f92f0..0c53709 100644 --- a/agent-runtime/src/test/java/cc/noharry/agent/spi/JavaHostDefaultsTest.java +++ b/agent-runtime/src/test/java/cc/noharry/agent/spi/JavaHostDefaultsTest.java @@ -3,6 +3,8 @@ import static org.junit.Assert.assertEquals; import static org.junit.Assert.assertNotNull; +import cc.noharry.agent.AgentRuntime; +import cc.noharry.agent.runtime.AgentRuntimeBuilder; import cc.noharry.agent.spi.model.ModelClient; import cc.noharry.agent.spi.model.ModelEvent; import cc.noharry.agent.spi.model.ModelRequest; @@ -19,6 +21,14 @@ public void aJavaHookWritesNothingItDoesNotChange() { assertNotNull(hook); } + @Test + public void aJavaHostBuildsThroughTheImplementationFactory() { + ModelClient model = request -> FlowKt.emptyFlow(); + try (AgentRuntime runtime = AgentRuntimeBuilder.create().model(model).build()) { + assertNotNull(runtime.startThread(new cc.noharry.agent.ThreadOptions())); + } + } + @Test public void aJavaModelClientWritesOnlyComplete() { ModelClient client = new ModelClient() { diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ExperimentalAgentRuntimeApiInventoryTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ExperimentalAgentRuntimeApiInventoryTest.kt index 7f99978..250a27d 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ExperimentalAgentRuntimeApiInventoryTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ExperimentalAgentRuntimeApiInventoryTest.kt @@ -33,7 +33,7 @@ class ExperimentalAgentRuntimeApiInventoryTest { @Test fun diagnosticsRemainExperimental() { - val diagnostics = File("src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt").readText() + val diagnostics = File("../agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt").readText() assertTrue(diagnostics.contains("@ExperimentalAgentRuntimeApi")) assertTrue(apiSource("RuntimeContextSpi.kt").readText().contains("@ExperimentalAgentRuntimeApi")) } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ReleaseHardeningTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ReleaseHardeningTest.kt index 7bf7428..baae18a 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ReleaseHardeningTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ReleaseHardeningTest.kt @@ -24,6 +24,7 @@ class ReleaseHardeningTest { assertTrue(rules.contains("-keep class cc.noharry.agent.spi.** { *; }")) assertTrue(rules.contains("-keep class cc.noharry.agent.runtime.AgentRuntimeBuilder { *; }")) + assertTrue(rules.contains("-keep class cc.noharry.agent.runtime.RuntimeInspection { *; }")) assertTrue(rules.contains("-keep class cc.noharry.agent.runtime.RuntimeWorkspaceRef { *; }")) assertTrue(rules.contains("-keep class cc.noharry.agent.runtime.HostSkill { *; }")) assertTrue(rules.contains("-keep class cc.noharry.agent.runtime.NetworkToolConfirmationPolicy { *; }")) @@ -265,6 +266,7 @@ private val CANDIDATE_PUBLIC_API_CLASS_NAMES = listOf( "cc.noharry.agent.runtime.NetworkToolConfirmationPolicy", "cc.noharry.agent.runtime.ProtocolRules", "cc.noharry.agent.runtime.RuntimeConcurrency", + "cc.noharry.agent.runtime.RuntimeInspection", "cc.noharry.agent.runtime.RuntimeMemoryPolicy", "cc.noharry.agent.runtime.RuntimeMemoryRetriever", "cc.noharry.agent.runtime.RuntimeWorkspaceRef", diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/PublicBuilderTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/PublicBuilderTest.kt index 7e1a982..9c76774 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/PublicBuilderTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/PublicBuilderTest.kt @@ -3,6 +3,7 @@ package cc.noharry.agent.runtime import cc.noharry.agent.AgentRuntime +import cc.noharry.agent.builder import cc.noharry.agent.ThreadEvent import cc.noharry.agent.spi.ProviderConcurrencyDeclaration import cc.noharry.agent.spi.model.ModelClient diff --git a/samples/minimal/src/main/kotlin/cc/noharry/agent/minimal/MinimalAgent.kt b/samples/minimal/src/main/kotlin/cc/noharry/agent/minimal/MinimalAgent.kt index 879378d..21b0e2e 100644 --- a/samples/minimal/src/main/kotlin/cc/noharry/agent/minimal/MinimalAgent.kt +++ b/samples/minimal/src/main/kotlin/cc/noharry/agent/minimal/MinimalAgent.kt @@ -1,6 +1,7 @@ package cc.noharry.agent.minimal import cc.noharry.agent.AgentRuntime +import cc.noharry.agent.builder import cc.noharry.agent.spi.model.ModelClient import cc.noharry.agent.runtime.AgentRuntimeBuilder From 1c69921515918a7581de0253677061ba6e471e4b Mon Sep 17 00:00:00 2001 From: NoHarry Date: Fri, 6 Nov 2026 23:53:09 -0800 Subject: [PATCH 05/40] refactor(api): internalize unused assembly and VFS helpers Remove workspace ports, hook registration records, VFS implementation helpers and the generated completion-gate overload from host API. Retain the public builder and VFS entry points. Validated API boundaries and affected runtime tests; independent review caught and corrected the stale public inventory. Co-Authored-By: Codex --- CHANGELOG.md | 4 + agent-api/api/agent-api.api | 99 ------------------- .../cc/noharry/agent/spi/RuntimeHooks.kt | 15 --- agent-runtime/api/agent-runtime.api | 81 --------------- .../kernel/core/loop/RuntimeCompletionGate.kt | 1 - .../agent/spi/RuntimeHookRegistration.kt | 15 +++ .../cc/noharry/agent/spi/WorkspacePort.kt | 13 ++- .../cc/noharry/agent/vfs/VfsManifest.kt | 2 +- .../cc/noharry/agent/vfs/VfsMountTable.kt | 4 +- .../cc/noharry/agent/vfs/VfsPathResolver.kt | 2 +- .../cc/noharry/agent/vfs/VfsSnapshot.kt | 6 +- .../agent/release/ReleaseHardeningTest.kt | 5 - 12 files changed, 32 insertions(+), 215 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/spi/RuntimeHookRegistration.kt rename {agent-api => agent-runtime}/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt (76%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 37ead75..a889d2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Internal assembly and VFS helpers are not host API.** Workspace ports, hook registrations, VFS snapshot/mount + resolution helpers, and an accidentally generated completion-gate overload are excluded from the public surface. + Hosts continue to supply `VfsFileSystem` workspaces and register hooks through the builder. + - **Thread option patches preserve saved approval policy.** Null values on resume retain saved defaults; `ThreadOptions.reset` clears selected model, workspace, scene or instruction overrides. New threads still use ASK. - **Independent budgets survive settings changes.** `LoopSettings.limits` defaults to null, so a settings call does diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index 1bd5eb9..b8bedc3 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -1141,28 +1141,6 @@ public final class cc/noharry/agent/spi/RuntimeHook$DefaultImpls { public static fun onTurnStarted (Lcc/noharry/agent/spi/RuntimeHook;Lcc/noharry/agent/spi/HookContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; } -public final class cc/noharry/agent/spi/RuntimeHookRegistration { - public fun (Lcc/noharry/agent/spi/RuntimeHook;Lcc/noharry/agent/spi/ToolMatcher;JLcc/noharry/agent/spi/HookFailurePolicy;)V - public synthetic fun (Lcc/noharry/agent/spi/RuntimeHook;Lcc/noharry/agent/spi/ToolMatcher;JLcc/noharry/agent/spi/HookFailurePolicy;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Lcc/noharry/agent/spi/RuntimeHook; - public final fun component2 ()Lcc/noharry/agent/spi/ToolMatcher; - public final fun component3 ()J - public final fun component4 ()Lcc/noharry/agent/spi/HookFailurePolicy; - public final fun copy (Lcc/noharry/agent/spi/RuntimeHook;Lcc/noharry/agent/spi/ToolMatcher;JLcc/noharry/agent/spi/HookFailurePolicy;)Lcc/noharry/agent/spi/RuntimeHookRegistration; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/RuntimeHookRegistration;Lcc/noharry/agent/spi/RuntimeHook;Lcc/noharry/agent/spi/ToolMatcher;JLcc/noharry/agent/spi/HookFailurePolicy;ILjava/lang/Object;)Lcc/noharry/agent/spi/RuntimeHookRegistration; - public fun equals (Ljava/lang/Object;)Z - public final fun getFailurePolicy ()Lcc/noharry/agent/spi/HookFailurePolicy; - public final fun getHook ()Lcc/noharry/agent/spi/RuntimeHook; - public final fun getMatcher ()Lcc/noharry/agent/spi/ToolMatcher; - public final fun getTimeoutMillis ()J - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/RuntimeHooksKt { - public static final field DEFAULT_HOOK_TIMEOUT_MILLIS J -} - public final class cc/noharry/agent/spi/RuntimeObserverActionPreflight { public fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/RuntimeEffectKind;Lcc/noharry/agent/spi/CompletionImpact;Ljava/lang/String;Ljava/lang/String;)V public synthetic fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/RuntimeEffectKind;Lcc/noharry/agent/spi/CompletionImpact;Ljava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V @@ -2080,83 +2058,6 @@ public final class cc/noharry/agent/spi/TurnObservationReceipt { public fun toString ()Ljava/lang/String; } -public final class cc/noharry/agent/spi/WorkspaceCallContext { - public fun ()V - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()Ljava/lang/String; - public final fun component4 ()Ljava/lang/String; - public final fun component5 ()Lcc/noharry/agent/spi/model/ModelRef; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;)Lcc/noharry/agent/spi/WorkspaceCallContext; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/WorkspaceCallContext;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/model/ModelRef;ILjava/lang/Object;)Lcc/noharry/agent/spi/WorkspaceCallContext; - public fun equals (Ljava/lang/Object;)Z - public final fun getModelRef ()Lcc/noharry/agent/spi/model/ModelRef; - public final fun getRequestId ()Ljava/lang/String; - public final fun getRunId ()Ljava/lang/String; - public final fun getScene ()Ljava/lang/String; - public final fun getSessionId ()Ljava/lang/String; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/WorkspaceExecutionResult { - public fun (Ljava/lang/String;Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry;)V - public synthetic fun (Ljava/lang/String;Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry; - public final fun copy (Ljava/lang/String;Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry;)Lcc/noharry/agent/spi/WorkspaceExecutionResult; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/WorkspaceExecutionResult;Ljava/lang/String;Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry;ILjava/lang/Object;)Lcc/noharry/agent/spi/WorkspaceExecutionResult; - public fun equals (Ljava/lang/Object;)Z - public final fun getResultJson ()Ljava/lang/String; - public final fun getTelemetry ()Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/spi/WorkspaceExecutionTelemetry { - public fun ()V - public fun (JJJJJJJJJJLjava/lang/Boolean;)V - public synthetic fun (JJJJJJJJJJLjava/lang/Boolean;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()J - public final fun component10 ()J - public final fun component11 ()Ljava/lang/Boolean; - public final fun component2 ()J - public final fun component3 ()J - public final fun component4 ()J - public final fun component5 ()J - public final fun component6 ()J - public final fun component7 ()J - public final fun component8 ()J - public final fun component9 ()J - public final fun copy (JJJJJJJJJJLjava/lang/Boolean;)Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry; - public static synthetic fun copy$default (Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry;JJJJJJJJJJLjava/lang/Boolean;ILjava/lang/Object;)Lcc/noharry/agent/spi/WorkspaceExecutionTelemetry; - public fun equals (Ljava/lang/Object;)Z - public final fun getBatchResultWaitDurationMs ()J - public final fun getBatchWaitDurationMs ()J - public final fun getExecuteDurationMs ()J - public final fun getMaterializeDurationMs ()J - public final fun getPrepareDurationMs ()J - public final fun getPublicFinishDurationMs ()J - public final fun getResolveDurationMs ()J - public final fun getScanDurationMs ()J - public final fun getSchemaCacheHit ()Ljava/lang/Boolean; - public final fun getSerializeDurationMs ()J - public final fun getSummaryDurationMs ()J - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public abstract interface class cc/noharry/agent/spi/WorkspacePort { - public abstract fun execute (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/WorkspaceCallContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public static synthetic fun execute$default (Lcc/noharry/agent/spi/WorkspacePort;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/WorkspaceCallContext;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object; -} - -public final class cc/noharry/agent/spi/WorkspacePort$DefaultImpls { - public static synthetic fun execute$default (Lcc/noharry/agent/spi/WorkspacePort;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/WorkspaceCallContext;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object; -} - public abstract interface class cc/noharry/agent/spi/mcp/McpClientProvider : cc/noharry/agent/spi/ToolProvider { public fun getProviderId ()Ljava/lang/String; public abstract fun getServerId ()Ljava/lang/String; diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeHooks.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeHooks.kt index 6686d99..472fec7 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeHooks.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeHooks.kt @@ -3,9 +3,6 @@ package cc.noharry.agent.spi import cc.noharry.agent.spi.reliability.RuntimeErrorCode import cc.noharry.agent.TurnResult -/** Default per-hook timeout used by hook registrations. */ -const val DEFAULT_HOOK_TIMEOUT_MILLIS: Long = 5_000L - /** * Host hook API for observing and controlling runtime tool use. */ @@ -65,18 +62,6 @@ enum class HookFailurePolicy { FAIL_OPEN, } -/** Host hook registration with a matcher, per-hook timeout, and failure policy. */ -data class RuntimeHookRegistration( - val hook: RuntimeHook, - val matcher: ToolMatcher = ToolMatcher.All, - val timeoutMillis: Long = DEFAULT_HOOK_TIMEOUT_MILLIS, - val failurePolicy: HookFailurePolicy = HookFailurePolicy.FAIL_CLOSED, -) { - init { - require(timeoutMillis > 0) { "timeoutMillis must be positive." } - } -} - /** Matcher used to decide whether a hook registration observes a tool call. */ fun interface ToolMatcher { fun matches(call: ToolUse): Boolean diff --git a/agent-runtime/api/agent-runtime.api b/agent-runtime/api/agent-runtime.api index ac25054..ad2937e 100644 --- a/agent-runtime/api/agent-runtime.api +++ b/agent-runtime/api/agent-runtime.api @@ -49,10 +49,6 @@ public final class cc/noharry/agent/ToolCatalogSnapshot { public fun toString ()Ljava/lang/String; } -public final class cc/noharry/agent/kernel/core/loop/RuntimeCompletionGateKt { - public static final fun decideFinish (Ljava/lang/String;Lcc/noharry/agent/kernel/core/loop/RuntimeObligationLedger;Z)Lcc/noharry/agent/kernel/core/loop/FinishDecision; -} - public abstract interface class cc/noharry/agent/mcp/McpClientMessages { public static final field Default Lcc/noharry/agent/mcp/McpClientMessages$Default; public fun httpProblem (I)Ljava/lang/String; @@ -1037,11 +1033,6 @@ public final class cc/noharry/agent/vfs/VfsListResult$NotFound : cc/noharry/agen public fun toString ()Ljava/lang/String; } -public final class cc/noharry/agent/vfs/VfsManifestLoader { - public fun ()V - public final fun parse (Ljava/lang/String;)Lcc/noharry/agent/vfs/VfsWorkspaceManifest; -} - public final class cc/noharry/agent/vfs/VfsMemorySource : cc/noharry/agent/vfs/VfsSource { public fun ()V public fun (Ljava/util/Map;J)V @@ -1088,16 +1079,6 @@ public final class cc/noharry/agent/vfs/VfsMountMode$Companion { public final fun fromWire (Ljava/lang/String;)Lcc/noharry/agent/vfs/VfsMountMode; } -public final class cc/noharry/agent/vfs/VfsMountTable { - public fun (Ljava/util/List;)V - public final fun mounts ()Ljava/util/List; - public final fun resolve (Ljava/lang/String;Z)Lcc/noharry/agent/vfs/VfsResolvedMount; - public static synthetic fun resolve$default (Lcc/noharry/agent/vfs/VfsMountTable;Ljava/lang/String;ZILjava/lang/Object;)Lcc/noharry/agent/vfs/VfsResolvedMount; - public final fun resolveAll (Ljava/lang/String;Z)Ljava/util/List; - public static synthetic fun resolveAll$default (Lcc/noharry/agent/vfs/VfsMountTable;Ljava/lang/String;ZILjava/lang/Object;)Ljava/util/List; - public final fun resolveVisible (Ljava/lang/String;)Ljava/util/List; -} - public final class cc/noharry/agent/vfs/VfsPath { public fun (Ljava/lang/String;)V public final fun component1 ()Ljava/lang/String; @@ -1110,12 +1091,6 @@ public final class cc/noharry/agent/vfs/VfsPath { public fun toString ()Ljava/lang/String; } -public final class cc/noharry/agent/vfs/VfsPathResolver { - public static final field INSTANCE Lcc/noharry/agent/vfs/VfsPathResolver; - public final fun normalize (Ljava/lang/String;)Lcc/noharry/agent/vfs/VfsPath; - public final fun resolveInside (Ljava/io/File;Ljava/lang/String;)Ljava/io/File; -} - public final class cc/noharry/agent/vfs/VfsReadAttributes { public fun ()V public fun (Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V @@ -1209,21 +1184,6 @@ public final class cc/noharry/agent/vfs/VfsRecordsKt { public static final field VFS_ENTRY_FILE Ljava/lang/String; } -public final class cc/noharry/agent/vfs/VfsResolvedMount { - public fun (Lcc/noharry/agent/vfs/VfsMount;Lcc/noharry/agent/vfs/VfsPath;Ljava/lang/String;)V - public final fun component1 ()Lcc/noharry/agent/vfs/VfsMount; - public final fun component2 ()Lcc/noharry/agent/vfs/VfsPath; - public final fun component3 ()Ljava/lang/String; - public final fun copy (Lcc/noharry/agent/vfs/VfsMount;Lcc/noharry/agent/vfs/VfsPath;Ljava/lang/String;)Lcc/noharry/agent/vfs/VfsResolvedMount; - public static synthetic fun copy$default (Lcc/noharry/agent/vfs/VfsResolvedMount;Lcc/noharry/agent/vfs/VfsMount;Lcc/noharry/agent/vfs/VfsPath;Ljava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/vfs/VfsResolvedMount; - public fun equals (Ljava/lang/Object;)Z - public final fun getMount ()Lcc/noharry/agent/vfs/VfsMount; - public final fun getPath ()Lcc/noharry/agent/vfs/VfsPath; - public final fun getRelativePath ()Ljava/lang/String; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - public final class cc/noharry/agent/vfs/VfsRoomResource { public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V @@ -1359,47 +1319,6 @@ public final class cc/noharry/agent/vfs/VfsSearchResult$NotFound : cc/noharry/ag public fun toString ()Ljava/lang/String; } -public final class cc/noharry/agent/vfs/VfsSnapshot { - public fun (Ljava/lang/String;Ljava/lang/String;JLjava/util/List;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()J - public final fun component4 ()Ljava/util/List; - public final fun copy (Ljava/lang/String;Ljava/lang/String;JLjava/util/List;)Lcc/noharry/agent/vfs/VfsSnapshot; - public static synthetic fun copy$default (Lcc/noharry/agent/vfs/VfsSnapshot;Ljava/lang/String;Ljava/lang/String;JLjava/util/List;ILjava/lang/Object;)Lcc/noharry/agent/vfs/VfsSnapshot; - public fun equals (Ljava/lang/Object;)Z - public final fun getCapturedAtEpochMillis ()J - public final fun getManifestHash ()Ljava/lang/String; - public final fun getMounts ()Ljava/util/List; - public final fun getVfsContractVersion ()Ljava/lang/String; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class cc/noharry/agent/vfs/VfsSnapshotFactory { - public static final field INSTANCE Lcc/noharry/agent/vfs/VfsSnapshotFactory; - public final fun snapshot (Lcc/noharry/agent/vfs/VfsWorkspaceManifest;Ljava/lang/String;J)Lcc/noharry/agent/vfs/VfsSnapshot; -} - -public final class cc/noharry/agent/vfs/VfsSnapshotMount { - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;I)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()Ljava/lang/String; - public final fun component4 ()Ljava/lang/String; - public final fun component5 ()I - public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;I)Lcc/noharry/agent/vfs/VfsSnapshotMount; - public static synthetic fun copy$default (Lcc/noharry/agent/vfs/VfsSnapshotMount;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;IILjava/lang/Object;)Lcc/noharry/agent/vfs/VfsSnapshotMount; - public fun equals (Ljava/lang/Object;)Z - public final fun getId ()Ljava/lang/String; - public final fun getMode ()Ljava/lang/String; - public final fun getPriority ()I - public final fun getSource ()Ljava/lang/String; - public final fun getTarget ()Ljava/lang/String; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - public abstract interface class cc/noharry/agent/vfs/VfsSource { public fun deleteTree (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; public abstract fun list (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeCompletionGate.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeCompletionGate.kt index 558d174..e864583 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeCompletionGate.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeCompletionGate.kt @@ -17,7 +17,6 @@ internal data class FinishDecision( val safeCode: String? = null, ) -@JvmOverloads internal fun decideFinish( argumentsJson: String, ledger: RuntimeObligationLedger, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/RuntimeHookRegistration.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/RuntimeHookRegistration.kt new file mode 100644 index 0000000..9f3a917 --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/RuntimeHookRegistration.kt @@ -0,0 +1,15 @@ +package cc.noharry.agent.spi + +import cc.noharry.agent.runtime.run.DEFAULT_HOOK_TIMEOUT_MILLIS + +/** Internal hook registration with a matcher, per-hook timeout, and failure policy. */ +internal data class RuntimeHookRegistration( + val hook: RuntimeHook, + val matcher: ToolMatcher = ToolMatcher.All, + val timeoutMillis: Long = DEFAULT_HOOK_TIMEOUT_MILLIS, + val failurePolicy: HookFailurePolicy = HookFailurePolicy.FAIL_CLOSED, +) { + init { + require(timeoutMillis > 0) { "timeoutMillis must be positive." } + } +} diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt similarity index 76% rename from agent-api/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt rename to agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt index 17c0b29..93c7339 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt @@ -3,10 +3,9 @@ package cc.noharry.agent.spi import cc.noharry.agent.spi.model.ModelRef /** - * Plugin-facing workspace capability. Concrete VFS adapters live in runtime; - * Kernel core and plugins depend only on this contract and its string/API DTOs. + * Internal workspace capability used by the loop and its VFS adapters. */ -interface WorkspacePort { +internal interface WorkspacePort { /** Executes a native workspace tool and returns JSON plus optional telemetry. */ suspend fun execute( toolName: String, @@ -15,8 +14,8 @@ interface WorkspacePort { ): WorkspaceExecutionResult } -/** API-owned call context for [WorkspacePort]. Independent of core/VFS types. */ -data class WorkspaceCallContext( +/** Runtime-owned call context for [WorkspacePort]. Independent of core/VFS types. */ +internal data class WorkspaceCallContext( val sessionId: String = "", val runId: String = "", val requestId: String = "", @@ -25,13 +24,13 @@ data class WorkspaceCallContext( ) /** Workspace tool execution result. [resultJson] is the model-visible payload. */ -data class WorkspaceExecutionResult( +internal data class WorkspaceExecutionResult( val resultJson: String, val telemetry: WorkspaceExecutionTelemetry = WorkspaceExecutionTelemetry(), ) /** Timing and cache telemetry for a workspace tool execution. */ -data class WorkspaceExecutionTelemetry( +internal data class WorkspaceExecutionTelemetry( val resolveDurationMs: Long = 0, val materializeDurationMs: Long = 0, val scanDurationMs: Long = 0, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsManifest.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsManifest.kt index 0d32ba0..d57c6c6 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsManifest.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsManifest.kt @@ -47,7 +47,7 @@ enum class VfsMountMode(val wireName: String) { } /** Parser and validator for workspace.json manifests. */ -class VfsManifestLoader { +internal class VfsManifestLoader { /** Parses workspace.json text into a validated manifest. */ fun parse(jsonText: String): VfsWorkspaceManifest { val root = Json.parseToJsonElement(jsonText).jsonObject diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsMountTable.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsMountTable.kt index 9e3887e..680f592 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsMountTable.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsMountTable.kt @@ -5,7 +5,7 @@ package cc.noharry.agent.vfs * * Higher priority wins. For equal priority, the most specific target path wins. */ -class VfsMountTable(mounts: List) { +internal class VfsMountTable(mounts: List) { private val orderedMounts = mounts.sortedWith( compareByDescending { it.priority } .thenByDescending { it.target.value.length } @@ -64,7 +64,7 @@ private fun relativePath(target: VfsPath, path: VfsPath): String = } /** Result of resolving a VFS path to a mount. */ -data class VfsResolvedMount( +internal data class VfsResolvedMount( val mount: VfsMount, val path: VfsPath, val relativePath: String, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsPathResolver.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsPathResolver.kt index 98532ff..dcfa52e 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsPathResolver.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsPathResolver.kt @@ -20,7 +20,7 @@ data class VfsPath(val value: String) { * The resolver only enforces Linux-like absolute path shape and canonical host * containment. Runtime-specific policy remains in the caller. */ -object VfsPathResolver { +internal object VfsPathResolver { /** Returns a normalized absolute VFS path, or null when the path is invalid. */ fun normalize(path: String): VfsPath? { if (!isShapeAllowed(path)) return null diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsSnapshot.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsSnapshot.kt index c927eb0..516c440 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsSnapshot.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/vfs/VfsSnapshot.kt @@ -3,7 +3,7 @@ package cc.noharry.agent.vfs import java.security.MessageDigest /** Replayable snapshot of a VFS manifest installation. */ -data class VfsSnapshot( +internal data class VfsSnapshot( val vfsContractVersion: String, val manifestHash: String, val capturedAtEpochMillis: Long, @@ -11,7 +11,7 @@ data class VfsSnapshot( ) /** Replayable snapshot entry for one mount. */ -data class VfsSnapshotMount( +internal data class VfsSnapshotMount( val id: String, val source: String, val target: String, @@ -20,7 +20,7 @@ data class VfsSnapshotMount( ) /** Creates VFS snapshots for replay and diagnostics. */ -object VfsSnapshotFactory { +internal object VfsSnapshotFactory { /** Creates a snapshot from the manifest and the exact workspace.json text. */ fun snapshot( manifest: VfsWorkspaceManifest, diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ReleaseHardeningTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ReleaseHardeningTest.kt index baae18a..276b118 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ReleaseHardeningTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/release/ReleaseHardeningTest.kt @@ -316,7 +316,6 @@ private val CANDIDATE_PUBLIC_API_CLASS_NAMES = listOf( "cc.noharry.agent.spi.RuntimeEffectKind", "cc.noharry.agent.spi.RuntimeEvidenceConfig", "cc.noharry.agent.spi.RuntimeHook", - "cc.noharry.agent.spi.RuntimeHookRegistration", "cc.noharry.agent.spi.RuntimeObserverActionPreflight", "cc.noharry.agent.spi.RuntimeTurnInput", "cc.noharry.agent.spi.RuntimeTurnObserver", @@ -353,10 +352,6 @@ private val CANDIDATE_PUBLIC_API_CLASS_NAMES = listOf( "cc.noharry.agent.spi.ToolUseResult", "cc.noharry.agent.spi.TurnInputObservation", "cc.noharry.agent.spi.TurnObservationReceipt", - "cc.noharry.agent.spi.WorkspaceCallContext", - "cc.noharry.agent.spi.WorkspaceExecutionResult", - "cc.noharry.agent.spi.WorkspaceExecutionTelemetry", - "cc.noharry.agent.spi.WorkspacePort", "cc.noharry.agent.spi.mcp.McpClientProvider", "cc.noharry.agent.spi.model.ModelClient", "cc.noharry.agent.spi.model.ModelClientException", From 002ef07ac5082fb5f11000f0ff921fc4a9888d16 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:10:23 -0800 Subject: [PATCH 06/40] docs(api): expose named conversation error codes Co-Authored-By: Codex --- CHANGELOG.md | 3 ++ agent-api/api/agent-api.api | 21 ++++++++++ .../kotlin/cc/noharry/agent/ThreadItem.kt | 1 + .../kotlin/cc/noharry/agent/TurnErrorCodes.kt | 42 +++++++++++++++++++ .../main/kotlin/cc/noharry/agent/TurnInput.kt | 5 ++- .../runtime/ThreadAttachmentInputTest.kt | 4 +- .../agent/runtime/ThreadImageInputTest.kt | 4 +- 7 files changed, 75 insertions(+), 5 deletions(-) create mode 100644 agent-api/src/main/kotlin/cc/noharry/agent/TurnErrorCodes.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index a889d2e..7b179ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,9 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Named conversation error codes.** `TurnErrorCodes` documents the codes used by thread admission, interruption, + storage, questions, attachments and approvals. Provider/tool codes remain available through `RuntimeErrorCode`. + - **Internal assembly and VFS helpers are not host API.** Workspace ports, hook registrations, VFS snapshot/mount resolution helpers, and an accidentally generated completion-gate overload are excluded from the public surface. Hosts continue to supply `VfsFileSystem` workspaces and register hooks through the builder. diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index b8bedc3..2f82c84 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -593,6 +593,27 @@ public final class cc/noharry/agent/TurnError { public fun toString ()Ljava/lang/String; } +public final class cc/noharry/agent/TurnErrorCodes { + public static final field ATTACHMENT_INVALID_TEXT Ljava/lang/String; + public static final field ATTACHMENT_MEDIA_UNSUPPORTED Ljava/lang/String; + public static final field ATTACHMENT_NOT_FOUND Ljava/lang/String; + public static final field CONFIRMATION_CANCELLED Ljava/lang/String; + public static final field CONFIRMATION_DENIED Ljava/lang/String; + public static final field CONFIRMATION_EXPIRED Ljava/lang/String; + public static final field IMAGE_INPUT_UNSUPPORTED Ljava/lang/String; + public static final field INSTANCE Lcc/noharry/agent/TurnErrorCodes; + public static final field INTERRUPTED Ljava/lang/String; + public static final field MISSING_TURN_RESULT Ljava/lang/String; + public static final field QUESTION_NOT_FOUND Ljava/lang/String; + public static final field RUNTIME_BUSY Ljava/lang/String; + public static final field RUNTIME_CLOSED Ljava/lang/String; + public static final field SESSION_QUEUE_FULL Ljava/lang/String; + public static final field STORAGE_FAILED Ljava/lang/String; + public static final field THREAD_BUSY Ljava/lang/String; + public static final field THREAD_DELETED Ljava/lang/String; + public static final field TURN_FAILED Ljava/lang/String; +} + public final class cc/noharry/agent/TurnInput { public static final field Companion Lcc/noharry/agent/TurnInput$Companion; public fun (Ljava/util/List;Ljava/lang/String;)V diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt b/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt index b7fbfb6..b64f04c 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt @@ -79,6 +79,7 @@ sealed interface ThreadItem { data class Error( override val id: String, override val turnId: String, + /** A [TurnErrorCodes] or provider/tool failure code. */ val code: String, val message: String, val recoverable: Boolean, diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/TurnErrorCodes.kt b/agent-api/src/main/kotlin/cc/noharry/agent/TurnErrorCodes.kt new file mode 100644 index 0000000..d0686f0 --- /dev/null +++ b/agent-api/src/main/kotlin/cc/noharry/agent/TurnErrorCodes.kt @@ -0,0 +1,42 @@ +package cc.noharry.agent + +/** + * Conversation-level codes returned in [TurnError] and [ThreadItem.Error]. Provider and tool failures may also use + * the codes in [cc.noharry.agent.spi.reliability.RuntimeErrorCode]. Hosts should retain a fallback for unknown codes. + */ +object TurnErrorCodes { + /** The selected model or runtime configuration does not accept image input. */ + const val IMAGE_INPUT_UNSUPPORTED = "IMAGE_INPUT_UNSUPPORTED" + /** The caller interrupted an admitted turn. */ + const val INTERRUPTED = "INTERRUPTED" + /** An unexpected execution failure prevented the turn from completing. */ + const val TURN_FAILED = "TURN_FAILED" + /** Execution ended without producing a terminal result. */ + const val MISSING_TURN_RESULT = "MISSING_TURN_RESULT" + /** A non-queuing request encountered another active turn in the same thread. */ + const val THREAD_BUSY = "THREAD_BUSY" + /** The conversation was deleted while this turn was queued or executing. */ + const val THREAD_DELETED = "THREAD_DELETED" + /** The selected question is not an unanswered question in the current conversation or turn. */ + const val QUESTION_NOT_FOUND = "QUESTION_NOT_FOUND" + /** Conversation data could not be loaded or saved; a result may be unavailable after restarting. */ + const val STORAGE_FAILED = "STORAGE_FAILED" + /** The referenced attachment is absent or failed integrity verification. */ + const val ATTACHMENT_NOT_FOUND = "ATTACHMENT_NOT_FOUND" + /** The referenced attachment has an unsupported media type. */ + const val ATTACHMENT_MEDIA_UNSUPPORTED = "ATTACHMENT_MEDIA_UNSUPPORTED" + /** A text attachment is not valid UTF-8. */ + const val ATTACHMENT_INVALID_TEXT = "ATTACHMENT_INVALID_TEXT" + /** The per-thread queue has reached its configured limit. */ + const val SESSION_QUEUE_FULL = "SESSION_QUEUE_FULL" + /** The shared queue has reached its configured limit. */ + const val RUNTIME_BUSY = "RUNTIME_BUSY" + /** The runtime was closed before the queued turn could execute. */ + const val RUNTIME_CLOSED = "RUNTIME_CLOSED" + /** A required approval was not received before its deadline. */ + const val CONFIRMATION_EXPIRED = "CONFIRMATION_EXPIRED" + /** A tool's approval was denied; a tool result can carry this code while the turn continues. */ + const val CONFIRMATION_DENIED = "CONFIRMATION_DENIED" + /** A pending tool approval was canceled without executing the tool. */ + const val CONFIRMATION_CANCELLED = "CONFIRMATION_CANCELLED" +} diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/TurnInput.kt b/agent-api/src/main/kotlin/cc/noharry/agent/TurnInput.kt index 6baaf9b..ddde09c 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/TurnInput.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/TurnInput.kt @@ -77,7 +77,10 @@ data class Usage( val cacheWriteTokens: Int = 0, ) -/** Stable machine-readable code with a human-readable explanation. */ +/** + * Machine-readable [code] with a human-readable explanation. See [TurnErrorCodes] for conversation failures and + * [cc.noharry.agent.spi.reliability.RuntimeErrorCode] for provider/tool codes; custom providers may add their own. + */ data class TurnError(val code: String, val message: String, val recoverable: Boolean = false) /** Complete snapshot of one turn. A waiting turn has a [pending] question. */ diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadAttachmentInputTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadAttachmentInputTest.kt index c9df789..2a40d0f 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadAttachmentInputTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadAttachmentInputTest.kt @@ -44,7 +44,7 @@ class ThreadAttachmentInputTest { threadBuilder(model).build().use { runtime -> val ref = attachmentRef("missing".toByteArray(), "text/plain") val result = runtime.startThread().run(TurnInput.of(InputPart.Attachment(ref))) - assertEquals("ATTACHMENT_NOT_FOUND", result.error?.code) + assertEquals(cc.noharry.agent.TurnErrorCodes.ATTACHMENT_NOT_FOUND, result.error?.code) assertTrue(model.requests.isEmpty()) } } @@ -57,7 +57,7 @@ class ThreadAttachmentInputTest { val model = ThreadScriptModel(emptyList()) threadBuilder(model, root).sessionEventLog(log).build().use { runtime -> val result = runtime.startThread(ThreadOptions(threadId = "attached")).run(TurnInput.of(InputPart.Attachment(ref))) - assertEquals("ATTACHMENT_MEDIA_UNSUPPORTED", result.error?.code) + assertEquals(cc.noharry.agent.TurnErrorCodes.ATTACHMENT_MEDIA_UNSUPPORTED, result.error?.code) assertTrue(model.requests.isEmpty()) } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadImageInputTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadImageInputTest.kt index b266458..28d30a2 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadImageInputTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadImageInputTest.kt @@ -29,7 +29,7 @@ class ThreadImageInputTest { threadBuilder(model).build().use { runtime -> val events = runtime.startThread().runStreamed(TurnInput.of(InputPart.Image(byteArrayOf(1), "image/png"))).toList() assertTurnEvents(events) - assertEquals("IMAGE_INPUT_UNSUPPORTED", (events.last() as ThreadEvent.TurnFailed).error.code) + assertEquals(cc.noharry.agent.TurnErrorCodes.IMAGE_INPUT_UNSUPPORTED, (events.last() as ThreadEvent.TurnFailed).error.code) assertTrue(model.requests.isEmpty()) } } @@ -38,7 +38,7 @@ class ThreadImageInputTest { val model = ThreadScriptModel(emptyList()) threadBuilder(model).imageInput(false).build().use { runtime -> val result = runtime.startThread().run(TurnInput.of(InputPart.Image(byteArrayOf(1), "image/png"))) - assertEquals("IMAGE_INPUT_UNSUPPORTED", result.error?.code) + assertEquals(cc.noharry.agent.TurnErrorCodes.IMAGE_INPUT_UNSUPPORTED, result.error?.code) assertTrue(model.requests.isEmpty()) } } From b058b06957444774f653a48f282716764103e4a8 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:10:24 -0800 Subject: [PATCH 07/40] fix(runtime): finalize turns after execution cleanup Co-Authored-By: Codex --- CHANGELOG.md | 4 + .../kotlin/cc/noharry/agent/AgentRuntime.kt | 2 +- .../runtime/thread/DefaultAgentThread.kt | 105 ++++++++--- .../runtime/thread/DefaultThreadRuntime.kt | 5 +- .../runtime/thread/ThreadEventMailbox.kt | 36 ++++ .../agent/runtime/thread/ThreadExecution.kt | 13 +- .../agent/runtime/thread/ThreadStore.kt | 3 + .../agent/runtime/ThreadAdmissionTest.kt | 12 +- .../agent/runtime/ThreadDeletionTest.kt | 17 +- .../agent/runtime/ThreadFinalizationTest.kt | 164 ++++++++++++++++++ 10 files changed, 314 insertions(+), 47 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventMailbox.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadFinalizationTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b179ee..0658929 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,10 @@ called out; a patch release does not break it. resolution helpers, and an accidentally generated completion-gate overload are excluded from the public surface. Hosts continue to supply `VfsFileSystem` workspaces and register hooks through the builder. +- **Turns finish after releasing execution.** Completion hooks and terminal events may immediately start another + turn or delete the thread. Interrupted and deleted turns emit one complete failure sequence; storage failures + report `STORAGE_FAILED`, and successful turn snapshots are written once. + - **Thread option patches preserve saved approval policy.** Null values on resume retain saved defaults; `ThreadOptions.reset` clears selected model, workspace, scene or instruction overrides. New threads still use ASK. - **Independent budgets survive settings changes.** `LoopSettings.limits` defaults to null, so a settings call does diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt b/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt index 8ee3352..712fe75 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt @@ -17,7 +17,7 @@ interface AgentRuntime : AutoCloseable { suspend fun listThreads(): List /** * Deletes saved history and invalidates all existing handles to this conversation, even if its id is reused. - * @throws IllegalStateException if called from that thread's active turn, including its completion hook. + * @throws IllegalStateException if called from that thread's active execution. Completion hooks run after execution is released. */ suspend fun deleteThread(threadId: String) val diagnostics: RuntimeDiagnostics diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 28a101a..391c769 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -40,7 +40,7 @@ internal class DefaultAgentThread( is ThreadEvent.TurnCompleted -> result = event.result is ThreadEvent.ItemCompleted -> items[event.item.id] = event.item is ThreadEvent.UsageUpdated -> usage = event.usage - is ThreadEvent.TurnFailed -> result = (if (isCurrent()) runtime.store.turn(id, event.turnId, generation) else null) ?: TurnResult( + is ThreadEvent.TurnFailed -> result = TurnResult( event.turnId, TurnStatus.FAILED, "", items.values.toList(), usage, error = event.error, ) else -> Unit @@ -63,18 +63,44 @@ internal class DefaultAgentThread( if (options.onConflict == SessionRunConflictPolicy.CANCEL_AND_REPLACE) interrupt() val busyPolicy = options.onConflict == SessionRunConflictPolicy.RESUME_CURRENT && active?.id != turnId when (val admitted = runtime.admission.enter(runtime, id, generation, busyPolicy)) { - is ThreadAdmissionResult.Granted -> try { collectTurn(input, options, turnId) } - finally { runtime.admission.release(admitted.ticket) } + is ThreadAdmissionResult.Granted -> collectAdmitted(input, options, turnId, admitted.ticket) is ThreadAdmissionResult.Rejected -> reject(input.snapshot(), turnId, admitted) } } } - private suspend fun ProducerScope.collectTurn(input: TurnInput, options: TurnOptions, turnId: String) { - runtime.checkOpen() - checkCurrent() - val previous = runtime.store.turn(id, turnId, generation) - if (previous != null) replay(previous) else execute(input.snapshot(), options, turnId) + private suspend fun ProducerScope.collectAdmitted( + input: TurnInput, options: TurnOptions, turnId: String, ticket: ThreadTicket, + ) { + val completed = try { collectTurn(input, options, turnId) } finally { runtime.admission.release(ticket) } + if (completed.mailbox == null) replay(completed.result) + else try { + withContext(NonCancellable) { + try { runtime.engine.notifyTurnFinished(completed.result, id) } catch (_: CancellationException) { } + } + completed.mailbox.emit(completed.result.terminalEvent(), awaitDelivery = false) + } finally { completed.mailbox.close() } + currentCoroutineContext().ensureActive() + } + + private suspend fun ProducerScope.collectTurn(input: TurnInput, options: TurnOptions, turnId: String): FinishedThreadTurn { + stoppedBeforeExecution(input, turnId)?.let { return it } + val previous = try { runtime.store.turn(id, turnId, generation) } catch (error: IllegalStateException) { + stoppedBeforeExecution(input, turnId)?.let { return it } + throw error + } + return if (previous != null) FinishedThreadTurn(previous) else execute(input.snapshot(), options, turnId) + } + + /** A granted ticket can be invalidated before its continuation installs the active execution. */ + private fun stoppedBeforeExecution(input: TurnInput, turnId: String): FinishedThreadTurn? { + val error = when { + !runtime.isOpen() -> TurnError("RUNTIME_CLOSED", "Runtime is closed.") + !isCurrent() -> TurnError("THREAD_DELETED", "The thread was deleted.") + else -> return null + } + val item = ThreadItem.UserMessage("$turnId:item:1", turnId, input.snapshot().parts) + return FinishedThreadTurn(TurnResult(turnId, TurnStatus.FAILED, "", listOf(item), error = error)) } private suspend fun ProducerScope.reject(input: TurnInput, turnId: String, rejection: ThreadAdmissionResult.Rejected) { @@ -82,32 +108,51 @@ internal class DefaultAgentThread( projection.fail(TurnError(rejection.code, rejection.message, true)) } - private suspend fun ProducerScope.execute(input: TurnInput, options: TurnOptions, turnId: String) { - val scope = this + private suspend fun ProducerScope.execute(input: TurnInput, options: TurnOptions, turnId: String): FinishedThreadTurn { + val mailbox = ThreadEventMailbox(this) val turn = ActiveThreadTurn(turnId, defaults, runtime, generation) val projection = ThreadEventProjection(id, turnId, input, { error("Approval must be handled in the active turn") }) { event -> - if (event is ThreadEvent.TurnCompleted || event is ThreadEvent.TurnFailed) { - turn.projection?.result?.let { - withContext(Dispatchers.IO) { runtime.store.saveTurn(id, it, generation) } - runtime.engine.notifyTurnFinished(it, id) - } - } turn.items = turn.projection?.items().orEmpty() - if (scope.isActive && isCurrent() && !turn.suppressDelivery) send(event) + if (event !is ThreadEvent.TurnCompleted && event !is ThreadEvent.TurnFailed) { + mailbox.emit(event, awaitDelivery = !turn.finalizing) + } } turn.projection = projection val job = launch(ThreadExecutionContext(runtime.store.coordination, id, turn), start = CoroutineStart.LAZY) { executeTurn(turn, input, options) } turn.job = job active = turn - try { job.start(); job.join() } finally { - withContext(NonCancellable) { - if (!scope.isActive) job.cancel() + try { + try { job.start(); job.join() } catch (_: CancellationException) { turn.cancel() } + return withContext(NonCancellable) { job.join() + FinishedThreadTurn(finalizeTurn(turn), mailbox) } + } catch (failure: Throwable) { + mailbox.close() + throw failure + } finally { + withContext(NonCancellable) { if (!job.isCompleted) turn.cancel(); job.join() } active = null } } + private suspend fun finalizeTurn(turn: ActiveThreadTurn): TurnResult { + val projection = checkNotNull(turn.projection) + turn.finalizing = true + if (projection.result == null) { + val error = turn.cancellation ?: TurnError("MISSING_TURN_RESULT", "The model stopped without completing the turn.") + projection.fail(error, interrupted = error.code == "INTERRUPTED") + } + val result = checkNotNull(projection.result) + if (!isCurrent()) return result.failed(TurnError("THREAD_DELETED", "The thread was deleted.")) + return try { + withContext(Dispatchers.IO) { runtime.store.saveTurn(id, result, generation) } + if (isCurrent()) result else result.failed(TurnError("THREAD_DELETED", "The thread was deleted.")) + } catch (_: Exception) { + result.failed(TurnError("STORAGE_FAILED", "The turn could not be saved.")) + } + } + private suspend fun executeTurn(turn: ActiveThreadTurn, input: TurnInput, options: TurnOptions) { val projection = checkNotNull(turn.projection) try { @@ -124,17 +169,16 @@ internal class DefaultAgentThread( } runtime.engine.runThread(request) { pending -> approve(turn, pending, options) }.collect(projection::accept) if (projection.result == null) projection.fail(TurnError("MISSING_TURN_RESULT", "The model stopped without completing the turn.")) - } catch (cancelled: CancellationException) { + } catch (_: CancellationException) { turn.approval?.cancel() - withContext(NonCancellable) { projection.fail(TurnError("INTERRUPTED", "The turn was interrupted."), interrupted = true) } + turn.finalizing = true + val error = turn.cancellation ?: TurnError("INTERRUPTED", "The turn was interrupted.") + withContext(NonCancellable) { projection.fail(error, interrupted = error.code == "INTERRUPTED") } } catch (error: ThreadInputException) { projection.fail(TurnError(error.code, error.message ?: "Invalid turn input.")) } catch (error: Exception) { projection.fail(TurnError("TURN_FAILED", error.message ?: "The turn failed.")) - } finally { - turn.approval?.cancel() - withContext(NonCancellable + Dispatchers.IO) { projection.result?.let { runtime.store.saveTurn(id, it, generation) } } - } + } finally { turn.approval?.cancel() } } private suspend fun approve(turn: ActiveThreadTurn, pending: PendingConfirmation, options: TurnOptions): ApprovalState { @@ -220,3 +264,12 @@ internal class DefaultAgentThread( else send(ThreadEvent.TurnCompleted(result)) } } + +private data class FinishedThreadTurn(val result: TurnResult, val mailbox: ThreadEventMailbox? = null) + +private fun TurnResult.failed(error: TurnError): TurnResult = copy( + status = TurnStatus.FAILED, finalResponse = "", pending = null, error = error, +) + +private fun TurnResult.terminalEvent(): ThreadEvent = + if (status == TurnStatus.FAILED) ThreadEvent.TurnFailed(turnId, checkNotNull(error)) else ThreadEvent.TurnCompleted(this) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt index 994d37b..8eb3ae8 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt @@ -77,7 +77,7 @@ internal class DefaultThreadRuntime( slot.generation += 1 admission.invalidate(threadId) } - slot.active?.let { turn -> turn.suppressDelivery = true; turn.cancel() } + slot.active?.cancel(TurnError("THREAD_DELETED", "The thread was deleted.")) try { drain.await() withContext(Dispatchers.IO) { @@ -88,7 +88,8 @@ internal class DefaultThreadRuntime( } finally { synchronized(store.coordination.lock) { slot.deleting = false } } } - internal fun checkOpen() { check(!closed.get()) { "Runtime is closed" } } + internal fun isOpen(): Boolean = !closed.get() + internal fun checkOpen() { check(isOpen()) { "Runtime is closed" } } override fun close() { if (!closed.compareAndSet(false, true)) return diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventMailbox.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventMailbox.kt new file mode 100644 index 0000000..a6699fd --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventMailbox.kt @@ -0,0 +1,36 @@ +package cc.noharry.agent.runtime.thread + +import cc.noharry.agent.ThreadEvent +import kotlinx.coroutines.CompletableDeferred +import kotlinx.coroutines.channels.Channel +import kotlinx.coroutines.channels.ProducerScope +import kotlinx.coroutines.isActive +import kotlinx.coroutines.launch + +/** + * Acknowledged delivery bounds ordinary production by the collector's buffer. Cleanup may enqueue the remaining + * item completions without awaiting that collector: it may itself be waiting for interrupt/delete to finish. + */ +internal class ThreadEventMailbox(private val output: ProducerScope) { + private val events = Channel(Channel.UNLIMITED) + + init { + output.launch { + for (delivery in events) { + try { output.send(delivery.event) } finally { delivery.accepted.complete(Unit) } + } + } + } + + suspend fun emit(event: ThreadEvent, awaitDelivery: Boolean = true) { + if (!output.isActive) return + val delivery = Delivery(event) + if (events.trySend(delivery).isSuccess && awaitDelivery) delivery.accepted.await() + } + + fun close() { events.close() } + + private class Delivery(val event: ThreadEvent) { + val accepted = CompletableDeferred() + } +} diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt index b51f6f3..cd27bc1 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt @@ -1,5 +1,6 @@ package cc.noharry.agent.runtime.thread +import cc.noharry.agent.TurnError import cc.noharry.agent.ThreadItem import cc.noharry.agent.ThreadOptions import java.util.Collections @@ -30,9 +31,17 @@ internal class ActiveThreadTurn(val id: String, val options: ThreadOptions, val var projection: ThreadEventProjection? = null @Volatile var approval: ThreadApproval? = null @Volatile var items: List = emptyList() - @Volatile var suppressDelivery = false + @Volatile var finalizing = false + @Volatile var cancellation: TurnError? = null + private set - fun cancel() { approval?.cancel(); job?.cancel() } + fun cancel(error: TurnError = TurnError("INTERRUPTED", "The turn was interrupted.")) { + synchronized(this) { + if (cancellation == null || error.code == "THREAD_DELETED") cancellation = error + } + approval?.cancel() + job?.cancel() + } } /** Preserved across hook dispatch and timeout scopes to reject deletion that would await its own admission ticket. */ diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt index a255772..e871d0c 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt @@ -62,8 +62,11 @@ internal class ThreadStore( threads.filterNot { executionSlot(it.record.id).deleting }.map { it.record.info() }.sortedByDescending { it.updatedAt } } + @Volatile internal var beforeSaveTurnForTest: ((TurnResult) -> Unit)? = null + fun saveTurn(threadId: String, result: TurnResult, generation: Long? = null) = synchronized(lock) { if (generation != null && !isCurrent(threadId, generation)) return@synchronized + beforeSaveTurnForTest?.invoke(result) val current = requireNotNull(read(threadId)) { "Thread does not exist: $threadId" } val turns = current.turns.filterNot { it.turnId == result.turnId } + result val pending = when { diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadAdmissionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadAdmissionTest.kt index a4b0c9a..c0c5a1d 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadAdmissionTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadAdmissionTest.kt @@ -61,15 +61,11 @@ class ThreadAdmissionTest { val model = GatedThreadModel() val cleanupEntered = CompletableDeferred() val releaseCleanup = CompletableDeferred() - val hook = object : RuntimeHook { - override suspend fun onTurnFinished(result: TurnResult, context: HookContext) { - if (result.status == TurnStatus.INTERRUPTED) { - cleanupEntered.complete(Unit) - releaseCleanup.await() - } + limitedThreadBuilder(model).build().use { runtime -> + (runtime as DefaultThreadRuntime).engine.beforeCleanupForTest = { + cleanupEntered.complete(Unit) + runBlocking { releaseCleanup.await() } } - } - limitedThreadBuilder(model).hook(hook, timeoutMillis = 5000).build().use { runtime -> val first = launch { runtime.startThread().run("cancel me") } model.entered.receive() first.cancel() diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDeletionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDeletionTest.kt index e88f6d7..7538ab6 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDeletionTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDeletionTest.kt @@ -17,15 +17,15 @@ import org.junit.Assert.* import org.junit.Test class ThreadDeletionTest { - @Test(timeout = 10_000) fun completionHookCannotWaitForItsOwnThreadDeletion() = runBlocking { + @Test(timeout = 10_000) fun completionHookCanDeleteTheReleasedThread() = runBlocking { for (throughAnotherRuntime in listOf(false, true)) { val root = threadRoot() - val rejected = CompletableDeferred() + val deleted = CompletableDeferred() lateinit var deletionTarget: AgentRuntime val hook = object : RuntimeHook { override suspend fun onTurnFinished(result: TurnResult, context: HookContext) { - try { deletionTarget.deleteThread(context.sessionId) } - catch (error: IllegalStateException) { rejected.complete(error) } + deletionTarget.deleteThread(context.sessionId) + deleted.complete(Unit) } } threadBuilder(ThreadScriptModel(emptyList()), root).hook(hook).build().use { runtime -> @@ -33,10 +33,9 @@ class ThreadDeletionTest { deletionTarget = if (throughAnotherRuntime) other else runtime val thread = runtime.startThread() assertEquals(TurnStatus.COMPLETED, withTimeout(2000) { thread.run("finish") }.status) - assertTrue(withTimeout(1000) { rejected.await() }.message.orEmpty().contains("own active turn")) - assertEquals(1, runtime.listThreads().size) - withTimeout(1000) { deletionTarget.deleteThread(thread.id) } + withTimeout(1000) { deleted.await() } assertTrue(runtime.listThreads().isEmpty()) + assertDeleted { thread.run("deleted") } } } } @@ -81,7 +80,9 @@ class ThreadDeletionTest { a.awaitQueued(1) withTimeout(5000) { b.deleteThread("delete-active") } assertEquals("THREAD_DELETED", queued.await().error?.code) - active.await() + val events = active.await() + assertTurnEvents(events) + assertEquals("THREAD_DELETED", (events.last() as ThreadEvent.TurnFailed).error.code) assertTrue(a.listThreads().isEmpty()) assertEquals(1, model.requests.size) assertDeleted { oldA.pendingRequests() } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadFinalizationTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadFinalizationTest.kt new file mode 100644 index 0000000..d61ed60 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadFinalizationTest.kt @@ -0,0 +1,164 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.runtime.thread.DefaultThreadRuntime +import cc.noharry.agent.spi.HookContext +import cc.noharry.agent.spi.RuntimeHook +import cc.noharry.agent.spi.SessionRunConflictPolicy +import java.io.IOException +import java.util.concurrent.ConcurrentLinkedQueue +import java.util.concurrent.atomic.AtomicInteger +import kotlin.coroutines.CoroutineContext +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.toList +import org.junit.Assert.* +import org.junit.Test + +class ThreadFinalizationTest { + @Test fun completionHookDeletionTerminatesTheGrantedButNotStartedTurn() = runBlocking { + assertGrantedTurnStopsNormally(closeRuntime = false) + } + + @Test fun completionHookCloseTerminatesTheGrantedButNotStartedTurn() = runBlocking { + assertGrantedTurnStopsNormally(closeRuntime = true) + } + + @Test fun completedEventCollectorCanImmediatelyRunTheNextTurn() = runBlocking { + threadBuilder(ThreadScriptModel(emptyList())).build().use { runtime -> + val thread = runtime.startThread() + val events = mutableListOf() + withTimeout(5000) { + thread.runStreamed("first").collect { event -> + events += event + if (event is ThreadEvent.TurnCompleted) { + assertEquals(ThreadStatus.IDLE, thread.status()) + val next = thread.run("next", TurnOptions(onConflict = SessionRunConflictPolicy.RESUME_CURRENT)) + assertEquals(TurnStatus.COMPLETED, next.status) + } + } + } + assertTurnEvents(events) + } + } + + @Test fun completionHookCanImmediatelyRunTheNextTurn() = runBlocking { + lateinit var thread: AgentThread + val next = CompletableDeferred() + val hook = object : RuntimeHook { + override suspend fun onTurnFinished(result: TurnResult, context: HookContext) { + if (result.turnId == "first") next.complete(thread.run("next", TurnOptions(turnId = "next"))) + } + } + threadBuilder(ThreadScriptModel(emptyList())).hook(hook).build().use { runtime -> + thread = runtime.startThread() + assertEquals(TurnStatus.COMPLETED, withTimeout(5000) { thread.run("first", TurnOptions(turnId = "first")) }.status) + assertEquals(TurnStatus.COMPLETED, next.await().status) + assertEquals(listOf("first", "next"), thread.items().filterIsInstance().map { it.turnId }) + } + } + + @Test fun earlyInterruptStillEmitsStartedAndExactlyOneTerminal() = runBlocking { + val dispatcher = QueuedTurnDispatcher() + val model = ThreadScriptModel(emptyList()) + AgentRuntime.builder().model(model).build().use { runtime -> + val thread = runtime.startThread() + val result = async(dispatcher) { thread.runStreamed("interrupt before execution").toList() } + dispatcher.until { thread.status() == ThreadStatus.RUNNING } + thread.interrupt() + dispatcher.until { result.isCompleted } + val events = result.await() + assertTurnEvents(events) + assertEquals(TurnStatus.INTERRUPTED, (events.last() as ThreadEvent.TurnCompleted).result.status) + assertTrue(model.requests.isEmpty()) + } + } + + @Test fun collectorCanDeleteTheActiveThreadAndStillReceiveItsTerminal() = runBlocking { + threadBuilder(ThreadScriptModel(emptyList())).build().use { runtime -> + val thread = runtime.startThread() + val events = mutableListOf() + withTimeout(5000) { + thread.runStreamed("delete at first item").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is ThreadItem.UserMessage) runtime.deleteThread(thread.id) + } + } + assertTurnEvents(events) + assertEquals("THREAD_DELETED", (events.last() as ThreadEvent.TurnFailed).error.code) + assertTrue(runtime.listThreads().isEmpty()) + } + } + + @Test fun resultIsSavedExactlyOnceAndSaveFailureBecomesOneTerminal() = runBlocking { + threadBuilder(ThreadScriptModel(emptyList())).build().use { runtime -> + val store = (runtime as DefaultThreadRuntime).store + val saves = AtomicInteger() + store.beforeSaveTurnForTest = { saves.incrementAndGet() } + val thread = runtime.startThread() + thread.run("save once") + assertEquals(1, saves.get()) + store.beforeSaveTurnForTest = { saves.incrementAndGet(); throw IOException("simulated full storage") } + val events = thread.runStreamed("cannot save").toList() + assertTurnEvents(events) + assertEquals("STORAGE_FAILED", (events.last() as ThreadEvent.TurnFailed).error.code) + assertEquals(2, saves.get()) + assertEquals("STORAGE_FAILED", thread.run("still cannot save").error?.code) + assertEquals(3, saves.get()) + store.beforeSaveTurnForTest = null + assertEquals(TurnStatus.COMPLETED, thread.run("storage available again").status) + } + } + + @Test fun cancellationFromCompletionHookCannotRemoveTheTerminalResult() = runBlocking { + val hook = object : RuntimeHook { + override suspend fun onTurnFinished(result: TurnResult, context: HookContext) { + throw CancellationException("host observation stopped") + } + } + threadBuilder(ThreadScriptModel(emptyList())).hook(hook).build().use { runtime -> + val events = runtime.startThread().runStreamed("finish").toList() + assertTurnEvents(events) + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) + } + } +} + +private class QueuedTurnDispatcher : CoroutineDispatcher() { + private val tasks = ConcurrentLinkedQueue() + override fun dispatch(context: CoroutineContext, block: Runnable) { tasks.add(block) } + suspend fun until(done: suspend () -> Boolean) = withTimeout(5000) { + while (!done()) tasks.poll()?.run() ?: delay(1) + } +} + +/** runBlocking's single-thread event loop leaves the granted continuation queued while the first hook runs. */ +private suspend fun CoroutineScope.assertGrantedTurnStopsNormally(closeRuntime: Boolean) { + val model = GatedThreadModel() + val grantedBeforeExecution = CompletableDeferred() + lateinit var activeRuntime: AgentRuntime + val hook = object : RuntimeHook { + override suspend fun onTurnFinished(result: TurnResult, context: HookContext) { + if (result.turnId != "first") return + val runtime = activeRuntime as DefaultThreadRuntime + grantedBeforeExecution.complete(runtime.admission.queuedCount() == 0 && runtime.store.executionSlot(context.sessionId).active == null) + if (closeRuntime) runtime.close() else runtime.deleteThread(context.sessionId) + } + } + limitedThreadBuilder(model).hook(hook).build().use { runtime -> + activeRuntime = runtime + val thread = runtime.startThread() + val first = async { thread.run("first", TurnOptions(turnId = "first")) } + model.entered.receive() + val next = async { thread.runStreamed("next", TurnOptions(turnId = "next")).toList() } + runtime.awaitQueued(1) + model.release.send(Unit) + assertEquals(TurnStatus.COMPLETED, withTimeout(5000) { first.await() }.status) + val events = withTimeout(5000) { next.await() } + assertTrue(grantedBeforeExecution.await()) + assertTurnEvents(events) + assertEquals(if (closeRuntime) "RUNTIME_CLOSED" else "THREAD_DELETED", (events.last() as ThreadEvent.TurnFailed).error.code) + assertEquals(1, model.requests.size) + } +} From 8a4a7e013a149f19d95b14b1d4bc56d7bcad6a8d Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:20:11 -0800 Subject: [PATCH 08/40] fix(storage): redact tool JSON without altering conversation text Co-Authored-By: Codex --- CHANGELOG.md | 7 ++ .../agent/runtime/AgentRuntimeBuilder.kt | 8 +- .../agent/runtime/ToolPayloadRedaction.kt | 30 ++++++++ .../cc/noharry/agent/runtime/TraceSecurity.kt | 6 +- .../agent/runtime/thread/ThreadItemCodec.kt | 12 +-- .../agent/runtime/thread/ThreadRecordCodec.kt | 2 +- .../agent/runtime/AgentRuntimeBuilderTest.kt | 13 ++++ .../agent/runtime/ThreadStoragePrivacyTest.kt | 76 +++++++++++++++++++ 8 files changed, 144 insertions(+), 10 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 0658929..d336122 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,13 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Conversation storage preserves display text and valid tool JSON.** User input and final answers are stored + verbatim. Tool payloads retain JSON numeric/boolean/null types while sensitive fields and Bearer credentials are + removed; phone and location filtering follows the configured redactor. Provider model history intentionally + preserves original messages, reasoning and images, including secrets, for accurate replay. +- **Configured event-log locations survive `storage(...)`.** Android continues using its existing `event-log` + directory. A storage directory must be used by only one process; multiple runtimes in that process coordinate. + - **Named conversation error codes.** `TurnErrorCodes` documents the codes used by thread admission, interruption, storage, questions, attachments and approvals. Provider/tool codes remain available through `RuntimeErrorCode`. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilder.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilder.kt index 1257700..3f08126 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilder.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilder.kt @@ -175,10 +175,14 @@ class AgentRuntimeBuilder { fun skills(vararg skills: HostSkill): AgentRuntimeBuilder = apply { hostSkills += skills } - /** Persists conversation items and model history independently of the optional workspace. */ + /** + * Persists conversation items and model history independently of the optional workspace. An explicitly configured + * event-log location is preserved. Use a storage directory from only one process; runtimes in that process coordinate. + * Provider history contains original messages, reasoning and images, including any secrets in those messages. + */ fun storage(directory: File): AgentRuntimeBuilder = apply { threadStorageRoot = directory - sessionEventLogRoot = File(directory, "events") + if (sessionEventLogRoot == null) sessionEventLogRoot = File(directory, "events") if (reliabilityStorageRoot == null) reliabilityStorageRoot = File(directory, "runtime") } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt new file mode 100644 index 0000000..0c99ef7 --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt @@ -0,0 +1,30 @@ +package cc.noharry.agent.runtime + +import java.util.Locale +import kotlinx.serialization.json.Json +import kotlinx.serialization.json.JsonArray +import kotlinx.serialization.json.JsonElement +import kotlinx.serialization.json.JsonObject +import kotlinx.serialization.json.JsonPrimitive + +/** Preserve JSON types and syntax while removing credentials and applying the host's text policy. */ +internal fun redactToolPayload(value: String, redactor: TraceRedactor): String { + val parsed = try { Json.parseToJsonElement(value) } catch (_: IllegalArgumentException) { null } + return parsed?.redactedToolValue(redactor)?.toString() ?: redactor.redact(redactSecrets(value)) +} + +private fun JsonElement.redactedToolValue(redactor: TraceRedactor): JsonElement = when (this) { + is JsonObject -> JsonObject(mapValues { (key, value) -> + if (key.isCredentialField()) JsonPrimitive("[REDACTED_SECRET]") else value.redactedToolValue(redactor) + }) + is JsonArray -> JsonArray(map { it.redactedToolValue(redactor) }) + is JsonPrimitive -> if (isString) JsonPrimitive(redactor.redact(redactSecrets(content))) else this +} + +private fun String.isCredentialField(): Boolean { + val normalized = lowercase(Locale.ROOT).filter(Char::isLetterOrDigit) + return normalized in setOf("authorization", "proxyauthorization", "bearer", "cookie", "setcookie") || + CREDENTIAL_SUFFIXES.any(normalized::endsWith) +} + +private val CREDENTIAL_SUFFIXES = listOf("token", "apikey", "secret", "password", "credential", "credentials", "privatekey") diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/TraceSecurity.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/TraceSecurity.kt index d510249..8463a6b 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/TraceSecurity.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/TraceSecurity.kt @@ -68,7 +68,7 @@ class StandardTraceRedactor( private val locations: Boolean = true, ) : TraceRedactor { override fun redact(value: String): String { - val withoutSecrets = SECRET_PATTERN.replace(value, REDACTED_SECRET) + val withoutSecrets = redactSecrets(value) val withoutPhones = if (!phones) { withoutSecrets } else { @@ -140,8 +140,10 @@ private const val REDACTED_SECRET = "[REDACTED_SECRET]" private const val REDACTED_PHONE = "[REDACTED_PHONE]" private const val REDACTED_LOCATION = "[REDACTED_LOCATION]" +internal fun redactSecrets(value: String): String = SECRET_PATTERN.replace(value, REDACTED_SECRET) + private val SECRET_PATTERN = Regex( - pattern = """(?i)\b(?:sk-[A-Za-z0-9_-]{8,}|token\s*[:=]\s*[\w.-]+|secret\s*[:=]\s*[\w.-]+)""", + pattern = """(?i)\b(?:sk-[A-Za-z0-9_-]{8,}|bearer\s+[^\s\"'<>]+|(?:[\w-]*token|[\w-]*secret|password|api[_-]?key)\s*[\"']?\s*[:=]\s*(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s\"',}\]]+))""", ) private val PHONE_PATTERN = Regex("""(? { - put("kind", "agent"); put("text", redact(item.text)); put("phase", item.phase.name) + put("kind", "agent"); put("text", if (item.phase == MessagePhase.FINAL) item.text else redact(item.text)) + put("phase", item.phase.name) } is ThreadItem.Reasoning -> { put("kind", "reasoning"); put("text", redact(item.text)) } is ThreadItem.ToolCall -> tool(item) @@ -72,8 +74,8 @@ internal class ThreadItemCodec( private fun JsonObjectBuilder.tool(item: ThreadItem.ToolCall) { put("kind", "tool"); put("tool", item.tool); put("source", item.source.name) item.server?.let { put("server", it) } - put("arguments", redact(item.arguments)) - item.output?.let { put("output", redact(it)) } + put("arguments", redactToolPayload(item.arguments, redactor)) + item.output?.let { put("output", redactToolPayload(it, redactor)) } item.approvedBy?.let { put("approvedBy", it.name) } item.network?.let { activity -> put("network", buildJsonObject { put("domain", activity.domain); put("decision", activity.decision) @@ -96,14 +98,14 @@ internal class ThreadItemCodec( } private fun JsonObjectBuilder.approval(item: Approval) { - put("kind", "approval"); put("tool", item.tool); put("arguments", redact(item.arguments)) + put("kind", "approval"); put("tool", item.tool); put("arguments", redactToolPayload(item.arguments, redactor)) put("domain", item.domain); put("reason", redact(item.reason)); put("state", item.state.name) item.expiresAt?.let { put("expiresAt", it) } } private fun input(part: InputPart): JsonObject = buildJsonObject { when (part) { - is InputPart.Text -> { put("kind", "text"); put("text", redact(part.text)) } + is InputPart.Text -> { put("kind", "text"); put("text", part.text) } is InputPart.Image -> { put("kind", "image"); put("bytes", Base64.getEncoder().encodeToString(part.bytes)); put("mimeType", part.mimeType) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt index 1c81317..554f4c9 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt @@ -76,7 +76,7 @@ internal class ThreadRecordCodec( private fun turn(turn: TurnResult): JsonObject = buildJsonObject { put("turnId", turn.turnId); put("status", turn.status.name) - put("finalResponse", redactor.redact(turn.finalResponse)) + put("finalResponse", turn.finalResponse) put("items", JsonArray(turn.items.map(items::encode))) turn.pending?.let { put("pending", items.encode(it)) } turn.usage?.let { usage -> put("usage", buildJsonObject { diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilderTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilderTest.kt index 579fe0e..dc38838 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilderTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/AgentRuntimeBuilderTest.kt @@ -162,6 +162,19 @@ class AgentRuntimeBuilderTest { ) } + @Test + fun conversationStoragePreservesAnExplicitEventLogRoot() = runBlocking { + val eventRoot = Files.createTempDirectory("builder-explicit-eventlog-").toFile() + val conversationRoot = Files.createTempDirectory("builder-conversations-").toFile() + val runtime = AgentRuntimeBuilder.create().sessionEventLogRoot(eventRoot).storage(conversationRoot) + .confirmationOnRun().buildEngine() + runtime.run(agentRequest()).toList() + runtime.querySessionEvents(SessionEventQuery("session-1", "request-1")) + assertTrue(officialStream(eventRoot, "session-1", "request-1").isFile) + assertFalse(File(conversationRoot, "events").exists()) + runtime.close() + } + @Test fun packagedDurablePluginWinsOverConfiguredRoot() = runBlocking { val pluginRoot = Files.createTempDirectory("builder-eventlog-plugin-").toFile() diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt new file mode 100644 index 0000000..1a3e2fb --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt @@ -0,0 +1,76 @@ +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.runtime.thread.ThreadStore +import cc.noharry.agent.spi.ToolSource +import java.io.File +import kotlinx.coroutines.runBlocking +import kotlinx.serialization.json.* +import org.junit.Assert.* +import org.junit.Test + +class ThreadStoragePrivacyTest { + @Test fun storedToolsKeepJsonTypesAndRemoveCredentials() { + val root = threadRoot() + val payload = """{"ts":1730900000000,"enabled":true,"empty":null,"nested":[{"api_key":"opaque-key","accessToken":"opaque-access","password":42,"authorization":"opaque-auth","secret":{"value":"opaque-nested"}}],"text":"Bearer opaque-bearer","phone":"13800138000"}""" + saveTool(root, payload) + val restored = ThreadStore(root).items("privacy").filterIsInstance().single() + for (value in listOf(restored.arguments, checkNotNull(restored.output))) { + val json = Json.parseToJsonElement(value).jsonObject + assertEquals(1730900000000L, json.getValue("ts").jsonPrimitive.long) + assertFalse(json.getValue("ts").jsonPrimitive.isString) + assertTrue(json.getValue("enabled").jsonPrimitive.boolean) + assertEquals(JsonNull, json["empty"]) + assertEquals("[REDACTED_PHONE]", json.getValue("phone").jsonPrimitive.content) + assertFalse(value.contains("opaque-")) + } + assertFalse(root.walkTopDown().filter(File::isFile).joinToString { it.readText() }.contains("opaque-")) + } + + @Test fun disabledPhoneAndLocationRulesStillRemoveCredentials() { + val root = threadRoot() + saveTool(root, """{"phone":"13800138000","text":"lat=31.2304 Bearer opaque-bearer","refresh_token":"opaque-refresh"}""", + StandardTraceRedactor(phones = false, locations = false)) + val output = ThreadStore(root).items("privacy").filterIsInstance().single().output.orEmpty() + assertTrue(output.contains("13800138000")) + assertTrue(output.contains("lat=31.2304")) + assertFalse(output.contains("opaque-")) + } + + @Test fun restartKeepsUserAndFinalAnswerOriginal() = runBlocking { + val root = threadRoot() + val original = "Contact 13800138000 at lat=31.2304 with Bearer literal-user-text" + threadBuilder(ThreadScriptModel(listOf(finishEvents(original))), root).build().use { runtime -> + assertEquals(original, runtime.startThread(ThreadOptions(threadId = "words")).run(original).finalResponse) + } + threadBuilder(ThreadScriptModel(emptyList()), root).build().use { runtime -> + val items = runtime.resumeThread("words").items() + assertEquals(original, (items.filterIsInstance().single().input.single() as InputPart.Text).text) + assertEquals(original, items.filterIsInstance().last { it.phase == MessagePhase.FINAL }.text) + } + val saved = File(root, "storage").listFiles().orEmpty().single { it.name.endsWith(".thread.json") } + val turn = Json.parseToJsonElement(saved.readText()).jsonObject.getValue("turns").jsonArray.single().jsonObject + assertEquals(original, turn.getValue("finalResponse").jsonPrimitive.content) + } + + @Test fun plainTextToolOutputAlsoRemovesBearerCredentials() { + val root = threadRoot() + saveTool(root, "Header: Bearer opaque-bearer and password=opaque-password") + assertFalse(ThreadStore(root).items("privacy").filterIsInstance().single().output.orEmpty().contains("opaque-")) + } + + @Test fun quotedPlainTextCredentialsAreRemovedInFull() { + val root = threadRoot() + saveTool(root, """password="alpha beta gamma" token='delta epsilon zeta' api_key="escaped\" quote value""" + '"') + val output = ThreadStore(root).items("privacy").filterIsInstance().single().output + assertEquals("[REDACTED_SECRET] [REDACTED_SECRET] [REDACTED_SECRET]", output) + } + + private fun saveTool(root: File, payload: String, redactor: TraceRedactor = DefaultTraceRedactor) { + val store = ThreadStore(root, redactor) + store.create("privacy", ThreadOptions()) + val item = ThreadItem.ToolCall("tool", "turn", "example", ToolSource.BACKEND, + arguments = payload, output = payload, status = ItemStatus.COMPLETED) + store.saveTurn("privacy", TurnResult("turn", TurnStatus.COMPLETED, "done", listOf(item))) + } +} From 8a0f3a145c7c5641b28db054a1427aa8462aa239 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:21:31 -0800 Subject: [PATCH 09/40] fix(runtime): preserve steering identity and explicit question binding Co-Authored-By: Codex --- CHANGELOG.md | 5 ++ agent-api/api/agent-api.api | 30 +++++++++-- .../kotlin/cc/noharry/agent/AgentThread.kt | 20 +++++-- .../kotlin/cc/noharry/agent/ThreadItem.kt | 2 + .../agent/runtime/DefaultAgentRuntime.kt | 2 + .../runtime/thread/DefaultAgentThread.kt | 12 ++--- .../runtime/thread/ThreadEventProjection.kt | 11 +++- .../agent/runtime/thread/ThreadExecution.kt | 17 ++++++ .../agent/runtime/thread/ThreadItemCodec.kt | 3 +- .../agent/runtime/ThreadApprovalFlowTest.kt | 53 +++++++++++++++++++ .../runtime/ThreadQuestionBindingTest.kt | 50 +++++++++++++++++ 11 files changed, 188 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d336122..d2f86e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,11 @@ called out; a patch release does not break it. - **Configured event-log locations survive `storage(...)`.** Android continues using its existing `event-log` directory. A storage directory must be used by only one process; multiple runtimes in that process coordinate. +- **Steering preserves input identity.** `SteerOptions` lets a host supply the request id echoed in + `ThreadItem.UserMessage`, including after restart. Ordinary steering never answers a pending question; + only an explicit `answering` question id does. Inputs can queue while a tool awaits approval. + Custom `AgentThread` implementations implement the options overload; the two convenience overloads delegate to it. + - **Named conversation error codes.** `TurnErrorCodes` documents the codes used by thread admission, interruption, storage, questions, attachments and approvals. Provider/tool codes remain available through `RuntimeErrorCode`. diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index 2f82c84..30f6b5f 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -33,8 +33,9 @@ public abstract interface class cc/noharry/agent/AgentThread { public static synthetic fun runStreamed$default (Lcc/noharry/agent/AgentThread;Lcc/noharry/agent/TurnInput;Lcc/noharry/agent/TurnOptions;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow; public static synthetic fun runStreamed$default (Lcc/noharry/agent/AgentThread;Ljava/lang/String;Lcc/noharry/agent/TurnOptions;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow; public abstract fun status (Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun steer (Ljava/lang/String;Lcc/noharry/agent/SteerOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; public fun steer (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun steer (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public fun steer (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; } public final class cc/noharry/agent/AgentThread$DefaultImpls { @@ -46,6 +47,7 @@ public final class cc/noharry/agent/AgentThread$DefaultImpls { public static synthetic fun runStreamed$default (Lcc/noharry/agent/AgentThread;Lcc/noharry/agent/TurnInput;Lcc/noharry/agent/TurnOptions;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow; public static synthetic fun runStreamed$default (Lcc/noharry/agent/AgentThread;Ljava/lang/String;Lcc/noharry/agent/TurnOptions;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow; public static fun steer (Lcc/noharry/agent/AgentThread;Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public static fun steer (Lcc/noharry/agent/AgentThread;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; } public abstract class cc/noharry/agent/Approval : cc/noharry/agent/PendingRequest { @@ -223,12 +225,28 @@ public abstract interface class cc/noharry/agent/RuntimeDiagnostics { public abstract fun subscribeSessionEvents (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Ljava/lang/AutoCloseable; } +public final class cc/noharry/agent/SteerOptions { + public fun ()V + public fun (Ljava/lang/String;Ljava/lang/String;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Ljava/lang/String; + public final fun component2 ()Ljava/lang/String; + public final fun copy (Ljava/lang/String;Ljava/lang/String;)Lcc/noharry/agent/SteerOptions; + public static synthetic fun copy$default (Lcc/noharry/agent/SteerOptions;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/SteerOptions; + public fun equals (Ljava/lang/Object;)Z + public final fun getAnswering ()Ljava/lang/String; + public final fun getRequestId ()Ljava/lang/String; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + public final class cc/noharry/agent/SteerResult : java/lang/Enum { public static final field ACCEPTED Lcc/noharry/agent/SteerResult; public static final field EMPTY_INPUT Lcc/noharry/agent/SteerResult; public static final field NOT_RUNNING Lcc/noharry/agent/SteerResult; public static final field QUESTION_NOT_FOUND Lcc/noharry/agent/SteerResult; public static final field QUEUE_FULL Lcc/noharry/agent/SteerResult; + public static final field REQUEST_ID_CONFLICT Lcc/noharry/agent/SteerResult; public static fun getEntries ()Lkotlin/enums/EnumEntries; public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/SteerResult; public static fun values ()[Lcc/noharry/agent/SteerResult; @@ -491,18 +509,20 @@ public final class cc/noharry/agent/ThreadItem$ToolCall : cc/noharry/agent/Threa } public final class cc/noharry/agent/ThreadItem$UserMessage : cc/noharry/agent/ThreadItem { - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/util/List;ZLcc/noharry/agent/ItemStatus;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/util/List;ZLcc/noharry/agent/ItemStatus;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;Ljava/util/List;ZLcc/noharry/agent/ItemStatus;Ljava/lang/String;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/util/List;ZLcc/noharry/agent/ItemStatus;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun component1 ()Ljava/lang/String; public final fun component2 ()Ljava/lang/String; public final fun component3 ()Ljava/util/List; public final fun component4 ()Z public final fun component5 ()Lcc/noharry/agent/ItemStatus; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/util/List;ZLcc/noharry/agent/ItemStatus;)Lcc/noharry/agent/ThreadItem$UserMessage; - public static synthetic fun copy$default (Lcc/noharry/agent/ThreadItem$UserMessage;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;ZLcc/noharry/agent/ItemStatus;ILjava/lang/Object;)Lcc/noharry/agent/ThreadItem$UserMessage; + public final fun component6 ()Ljava/lang/String; + public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/util/List;ZLcc/noharry/agent/ItemStatus;Ljava/lang/String;)Lcc/noharry/agent/ThreadItem$UserMessage; + public static synthetic fun copy$default (Lcc/noharry/agent/ThreadItem$UserMessage;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;ZLcc/noharry/agent/ItemStatus;Ljava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/ThreadItem$UserMessage; public fun equals (Ljava/lang/Object;)Z public fun getId ()Ljava/lang/String; public final fun getInput ()Ljava/util/List; + public final fun getRequestId ()Ljava/lang/String; public fun getStatus ()Lcc/noharry/agent/ItemStatus; public final fun getSteer ()Z public fun getTurnId ()Ljava/lang/String; diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/AgentThread.kt b/agent-api/src/main/kotlin/cc/noharry/agent/AgentThread.kt index ab9fe5c..3f688a5 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/AgentThread.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/AgentThread.kt @@ -9,14 +9,17 @@ interface AgentThread { fun runStreamed(input: TurnInput, options: TurnOptions = TurnOptions()): Flow suspend fun run(text: String, options: TurnOptions = TurnOptions()): TurnResult = run(TurnInput.text(text), options) fun runStreamed(text: String, options: TurnOptions = TurnOptions()): Flow = runStreamed(TurnInput.text(text), options) - suspend fun steer(text: String): SteerResult + /** Queues ordinary input without answering any asynchronous question. */ + suspend fun steer(text: String): SteerResult = steer(text, SteerOptions()) /** * Answers the asynchronous question whose complete [Question.id] is supplied. The question must still be pending * in the current turn; a stale, answered, or unknown id returns QUESTION_NOT_FOUND without posting input. - * Null preserves ordinary steering behavior. Implementations without explicit binding reject non-null ids. + * Null queues ordinary input without binding it to a question. */ suspend fun steer(text: String, answering: String?): SteerResult = - if (answering == null) steer(text) else SteerResult.QUESTION_NOT_FOUND + steer(text, SteerOptions(answering = answering)) + /** Queues input for the active turn, including while it is waiting for tool approval. */ + suspend fun steer(text: String, options: SteerOptions): SteerResult /** Requests cancellation of the current turn; keep collecting to receive its interrupted terminal result. */ suspend fun interrupt() suspend fun status(): ThreadStatus @@ -25,4 +28,13 @@ interface AgentThread { suspend fun items(afterTurnId: String? = null): List } -enum class SteerResult { ACCEPTED, NOT_RUNNING, EMPTY_INPUT, QUEUE_FULL, QUESTION_NOT_FOUND } +/** + * [requestId] identifies this input within the active turn and is echoed on [ThreadItem.UserMessage]. Repeating + * the same id with different text or question returns REQUEST_ID_CONFLICT. Null creates an id automatically. + * [answering] is a complete [Question.id]; null always means ordinary input, even with unanswered questions. + */ +data class SteerOptions(val requestId: String? = null, val answering: String? = null) { + init { require(requestId == null || requestId.isNotBlank()) { "Steering request id must not be blank" } } +} + +enum class SteerResult { ACCEPTED, NOT_RUNNING, EMPTY_INPUT, QUEUE_FULL, QUESTION_NOT_FOUND, REQUEST_ID_CONFLICT } diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt b/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt index b64f04c..5ac0550 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt @@ -19,6 +19,8 @@ sealed interface ThreadItem { val input: List, val steer: Boolean = false, override val status: ItemStatus = ItemStatus.COMPLETED, + /** The steering request id supplied by the host, or generated by the runtime; null for turn input. */ + val requestId: String? = null, ) : ThreadItem data class AgentMessage( diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt index 84a47db..9f2ca88 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt @@ -648,6 +648,8 @@ internal class DefaultAgentRuntime( idempotencyKey = paused?.toolCallId.orEmpty(), prompt = outcome.prompt, toolName = paused?.toolUse?.toolName, argumentsJson = paused?.toolUse?.argumentsJson, ) + // This turn stays in its original stream, so inputs can queue while the host decides. + steeringQueue.resume(request.requestId) val decision = approve(pending) if (decision == cc.noharry.agent.ApprovalState.APPROVED && paused != null) { steeringQueue.resume(request.requestId) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 391c769..7387dbb 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -139,6 +139,7 @@ internal class DefaultAgentThread( private suspend fun finalizeTurn(turn: ActiveThreadTurn): TurnResult { val projection = checkNotNull(turn.projection) turn.finalizing = true + projection.retainSteeringInputs(turn.acceptedInputs()) if (projection.result == null) { val error = turn.cancellation ?: TurnError("MISSING_TURN_RESULT", "The model stopped without completing the turn.") projection.fail(error, interrupted = error.code == "INTERRUPTED") @@ -209,22 +210,21 @@ internal class DefaultAgentThread( } finally { approval.cancel(); turn.approval = null } } - override suspend fun steer(text: String): SteerResult = steer(text, null) - - override suspend fun steer(text: String, answering: String?): SteerResult { + override suspend fun steer(text: String, options: SteerOptions): SteerResult { checkCurrent() if (text.isBlank()) return SteerResult.EMPTY_INPUT + val answering = options.answering val turn = active ?: return if (answering == null) SteerResult.NOT_RUNNING else SteerResult.QUESTION_NOT_FOUND - val questions = turn.items.filterIsInstance().filter { it.async && it.status == ItemStatus.IN_PROGRESS } - val question = if (answering == null) questions.lastOrNull() else questions.firstOrNull { it.id == answering } + val question = answering?.let { target -> turn.items.filterIsInstance().firstOrNull { it.async && it.id == target } } if (answering != null && question == null) return SteerResult.QUESTION_NOT_FOUND - val result = turn.owner.engine.postUserInput(PostUserInputRequest(turn.id, UUID.randomUUID().toString(), text, id, + val result = turn.postInput(PostUserInputRequest(turn.id, options.requestId ?: UUID.randomUUID().toString(), text, id, question?.id?.removePrefix("${turn.id}:question:"))) return when (result) { PostUserInputResult.Accepted, PostUserInputResult.Duplicate -> SteerResult.ACCEPTED is PostUserInputResult.Rejected -> when (result.code) { "INPUT_LIMIT" -> SteerResult.QUEUE_FULL "QUESTION_NOT_FOUND", "QUESTION_ALREADY_ANSWERED" -> SteerResult.QUESTION_NOT_FOUND + "REQUEST_ID_CONFLICT" -> SteerResult.REQUEST_ID_CONFLICT else -> SteerResult.NOT_RUNNING } else -> SteerResult.NOT_RUNNING diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt index 771c70e..63e85b6 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt @@ -5,6 +5,7 @@ package cc.noharry.agent.runtime.thread import cc.noharry.agent.* import cc.noharry.agent.spi.AgentEvent import cc.noharry.agent.spi.PendingConfirmation +import cc.noharry.agent.spi.PostUserInputRequest import cc.noharry.agent.spi.SessionEventPayload import cc.noharry.agent.spi.reliability.RuntimeResult import cc.noharry.agent.spi.reliability.RuntimeRunStatus @@ -74,6 +75,14 @@ internal class ThreadEventProjection( suspend fun resolveApproval(item: Approval) { complete(item) } + /** Inputs accepted before cancellation or an approval failure still belong to this turn's transcript. */ + suspend fun retainSteeringInputs(inputs: List) { + for (input in inputs) interaction(SessionEventPayload.UserInteraction( + "INPUT", "RECEIVED", inputRequestId = input.requestId, text = input.text, + )) + result = result?.copy(items = items()) + } + private suspend fun text(value: String, thinking: Boolean) { if (thinking) { finishMessage() @@ -123,7 +132,7 @@ internal class ThreadEventProjection( if (fact.kind == "INPUT") { val id = "$turnId:input:${fact.inputRequestId}" if (fact.state == "RECEIVED" && id !in records) { - instant(ThreadItem.UserMessage(id, turnId, listOf(InputPart.Text(fact.text)), steer = true)) + instant(ThreadItem.UserMessage(id, turnId, listOf(InputPart.Text(fact.text)), steer = true, requestId = fact.inputRequestId)) } return } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt index cd27bc1..5caf6ac 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt @@ -3,10 +3,13 @@ package cc.noharry.agent.runtime.thread import cc.noharry.agent.TurnError import cc.noharry.agent.ThreadItem import cc.noharry.agent.ThreadOptions +import cc.noharry.agent.spi.PostUserInputRequest +import cc.noharry.agent.spi.PostUserInputResult import java.util.Collections import java.util.WeakHashMap import kotlinx.coroutines.Job import kotlinx.coroutines.sync.Mutex +import kotlinx.coroutines.sync.withLock import kotlin.coroutines.AbstractCoroutineContextElement import kotlin.coroutines.CoroutineContext @@ -27,6 +30,8 @@ internal class ThreadExecutionSlot { } internal class ActiveThreadTurn(val id: String, val options: ThreadOptions, val owner: DefaultThreadRuntime, val generation: Long) { + private val steeringMutex = Mutex() + private val receivedInputs = linkedMapOf() var job: Job? = null var projection: ThreadEventProjection? = null @Volatile var approval: ThreadApproval? = null @@ -35,6 +40,18 @@ internal class ActiveThreadTurn(val id: String, val options: ThreadOptions, val @Volatile var cancellation: TurnError? = null private set + suspend fun postInput(request: PostUserInputRequest): PostUserInputResult = steeringMutex.withLock { + if (finalizing) return@withLock PostUserInputResult.RunNotActive + owner.engine.postUserInput(request).also { result -> + if (result == PostUserInputResult.Accepted || result == PostUserInputResult.Duplicate) { + receivedInputs.getOrPut(request.requestId) { request } + } + } + } + + /** Finalization waits for accepted posts to record their receipts before publishing its terminal snapshot. */ + suspend fun acceptedInputs(): List = steeringMutex.withLock { receivedInputs.values.toList() } + fun cancel(error: TurnError = TurnError("INTERRUPTED", "The turn was interrupted.")) { synchronized(this) { if (cancellation == null || error.code == "THREAD_DELETED") cancellation = error diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt index 59df366..e472cde 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt @@ -25,6 +25,7 @@ internal class ThreadItemCodec( when (item) { is ThreadItem.UserMessage -> { put("kind", "user"); put("input", JsonArray(item.input.map(::input))); put("steer", item.steer) + item.requestId?.let { put("requestId", it) } } is ThreadItem.AgentMessage -> { put("kind", "agent"); put("text", if (item.phase == MessagePhase.FINAL) item.text else redact(item.text)) @@ -57,7 +58,7 @@ internal class ThreadItemCodec( val turn = value.text("turnId") val status = value.enum("status", ItemStatus.COMPLETED) return when (value.text("kind")) { - "user" -> ThreadItem.UserMessage(id, turn, value.array("input").map { input(it as JsonObject) }, value.flag("steer"), status) + "user" -> ThreadItem.UserMessage(id, turn, value.array("input").map { input(it as JsonObject) }, value.flag("steer"), status, value.optionalText("requestId")) "agent" -> ThreadItem.AgentMessage(id, turn, value.text("text"), value.enum("phase", MessagePhase.COMMENTARY), status) "reasoning" -> ThreadItem.Reasoning(id, turn, value.text("text"), status) "tool" -> tool(value, id, turn, status) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt index e037048..7981cb0 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt @@ -10,6 +10,35 @@ import org.junit.Assert.* import org.junit.Test class ThreadApprovalFlowTest { + @Test fun inputQueuedDuringApprovalSurvivesDenial() = runBlocking { acceptedInputSurvivesApprovalEnd("deny") } + + @Test fun inputQueuedDuringApprovalSurvivesInterruption() = runBlocking { acceptedInputSurvivesApprovalEnd("interrupt") } + + @Test fun inputQueuedDuringApprovalSurvivesExpiry() = runBlocking { acceptedInputSurvivesApprovalEnd("expire") } + + @Test fun inputWhileWaitingForApprovalQueuesUntilExecutionContinues() = runBlocking { + val requests = mutableListOf() + approvalBuilder(requests = requests).build().use { runtime -> + val thread = runtime.startThread() + val events = mutableListOf() + thread.runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + assertEquals(ThreadStatus.WAITING_FOR_APPROVAL, thread.status()) + val before = requests.size + assertEquals(SteerResult.ACCEPTED, thread.steer("Then explain the setting", SteerOptions("during-approval"))) + assertEquals(before, requests.size) + (event.item as Approval).approve() + } + } + assertTurnEvents(events) + assertTrue(requests.last().messages.any { it.role == "user" && it.content.contains("Then explain the setting") }) + val input = events.filterIsInstance().map { it.item } + .filterIsInstance().single { it.steer } + assertEquals("during-approval", input.requestId) + } + } + @Test fun approvingContinuesTheOriginalFlowAndOnlyOneResponderWins() = runBlocking { approvalBuilder().build().use { runtime -> val thread = runtime.startThread() @@ -86,4 +115,28 @@ class ThreadApprovalFlowTest { assertEquals(ThreadStatus.IDLE, thread.status()) } } + + private suspend fun acceptedInputSurvivesApprovalEnd(action: String) { + val built = approvalBuilder().build() as DefaultThreadRuntime + DefaultThreadRuntime(built.engine, built.store, confirmationTimeoutMillis = 100).use { runtime -> + val thread = runtime.startThread() + val events = mutableListOf() + thread.runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + assertEquals(SteerResult.ACCEPTED, thread.steer("Remember this input", SteerOptions("approval-end"))) + when (action) { + "deny" -> (event.item as Approval).deny() + "interrupt" -> thread.interrupt() + } + } + } + assertTurnEvents(events) + val inputs = events.filterIsInstance().map { it.item } + .filterIsInstance().filter { it.steer } + assertEquals("approval-end", inputs.single().requestId) + assertEquals("Remember this input", (inputs.single().input.single() as InputPart.Text).text) + assertEquals(inputs, thread.items().filterIsInstance().filter { it.steer }) + } + } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadQuestionBindingTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadQuestionBindingTest.kt index 6b81dba..2141514 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadQuestionBindingTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadQuestionBindingTest.kt @@ -14,6 +14,56 @@ import org.junit.Assert.* import org.junit.Test class ThreadQuestionBindingTest { + @Test fun ordinaryInputDoesNotAnswerAnyQuestionOrGetLostAfterAnExplicitAnswer() = runBlocking { + val model = ThreeQuestionModel() + threadBuilder(model).build().use { runtime -> + val thread = runtime.startThread() + val collected = async { thread.runStreamed("plan a trip").toList() } + model.waiting.await() + val questions = thread.pendingRequests().filterIsInstance() + assertEquals(SteerResult.ACCEPTED, thread.steer("Walk through a park")) + assertEquals(SteerResult.ACCEPTED, thread.steer("Generous", questions.last().id)) + assertEquals(SteerResult.ACCEPTED, thread.steer("And stop for tea", SteerOptions(requestId = "tea"))) + model.release.complete(Unit) + val events = withTimeout(5000) { collected.await() } + assertTurnEvents(events) + val messages = model.requests.last().messages.filter { it.role == "user" }.map { it.content } + assertTrue(messages.any { "Walk through a park" in it && "Answer to question" !in it }) + assertTrue(messages.any { "And stop for tea" in it && "Answer to question" !in it }) + assertTrue(messages.any { "Generous" in it && "Budget?" in it }) + val completed = events.filterIsInstance().map { it.item }.filterIsInstance() + assertEquals(ItemStatus.COMPLETED, completed.single { it.id == questions.last().id }.status) + assertTrue(completed.filter { it.id != questions.last().id }.all { it.status == ItemStatus.DECLINED }) + } + } + + @Test fun hostRequestIdIsDeduplicatedEchoedAndRestoredAfterRestart() = runBlocking { + val root = threadRoot() + val model = ThreeQuestionModel() + threadBuilder(model, root).build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "request-id")) + val collected = async { thread.runStreamed("plan a trip").toList() } + model.waiting.await() + val options = SteerOptions(requestId = "host-message") + assertEquals(SteerResult.ACCEPTED, thread.steer("Take the scenic route", options)) + assertEquals(SteerResult.ACCEPTED, thread.steer("Take the scenic route", options)) + assertEquals(SteerResult.REQUEST_ID_CONFLICT, thread.steer("Use the highway", options)) + model.release.complete(Unit) + val events = withTimeout(5000) { collected.await() } + assertTurnEvents(events) + val started = events.filterIsInstance().map { it.item }.filterIsInstance() + val completed = events.filterIsInstance().map { it.item }.filterIsInstance() + assertEquals("host-message", started.single { it.steer }.requestId) + assertEquals(started.single { it.steer }, completed.single { it.steer }) + assertTrue(started.filter { !it.steer }.all { it.requestId == null }) + } + threadBuilder(ThreadScriptModel(emptyList()), root).build().use { runtime -> + val item = runtime.resumeThread("request-id").items().filterIsInstance().single { it.steer } + assertEquals("host-message", item.requestId) + assertEquals("Take the scenic route", (item.input.single() as InputPart.Text).text) + } + } + @Test fun replyingToFirstOfThreeQuestionsPreservesItsIdentityInModelInputAndEvents() = runBlocking { val model = ThreeQuestionModel() threadBuilder(model).build().use { runtime -> From c388524999dd53e526d8fc13a7fd4b1333107856 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:22:38 -0800 Subject: [PATCH 10/40] fix(runtime): separate turn identities from execution attempts Co-Authored-By: Codex --- CHANGELOG.md | 5 + agent-api/api/agent-api.api | 8 +- .../cc/noharry/agent/RuntimeDiagnostics.kt | 15 ++- .../agent/runtime/DefaultAgentRuntime.kt | 32 ++++-- .../runtime/thread/DefaultAgentThread.kt | 38 +++++-- .../thread/DefaultRuntimeDiagnostics.kt | 29 +++-- .../runtime/thread/DefaultThreadRuntime.kt | 2 +- .../runtime/thread/ThreadAttemptStore.kt | 73 +++++++++++++ .../agent/runtime/thread/ThreadExecution.kt | 1 + .../agent/runtime/thread/ThreadInput.kt | 4 +- .../agent/runtime/thread/ThreadStore.kt | 4 +- .../cc/noharry/agent/spi/AgentRuntime.kt | 1 + .../agent/runtime/ThreadDiagnosticsTest.kt | 7 +- .../runtime/ThreadExecutionIdentityTest.kt | 101 ++++++++++++++++++ .../runtime/ThreadQuestionBindingTest.kt | 3 +- 15 files changed, 281 insertions(+), 42 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadAttemptStore.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadExecutionIdentityTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index d2f86e6..46e4767 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,11 @@ called out; a patch release does not break it. only an explicit `answering` question id does. Inputs can queue while a tool awaits approval. Custom `AgentThread` implementations implement the options overload; the two convenience overloads delegate to it. +- **Turn ids are local to a thread.** Every execution gets an independent id, durably mapped to its public turn id + and attempt number. An unsaved attempt after process loss is interrupted before retrying with a fresh execution. + Diagnostic result/state/trace queries now require `(threadId, turnId)` and select its latest attempt; raw diagnostic + `runId` identifies an execution, while `sessionId` and `requestId` retain the public thread and turn ids. + - **Named conversation error codes.** `TurnErrorCodes` documents the codes used by thread admission, interruption, storage, questions, attachments and approvals. Provider/tool codes remain available through `RuntimeErrorCode`. diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index 30f6b5f..33dbe2a 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -214,11 +214,11 @@ public final class cc/noharry/agent/RespondResult : java/lang/Enum { } public abstract interface class cc/noharry/agent/RuntimeDiagnostics { - public abstract fun getRunState (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getRunState (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; public abstract fun getRuntimeEvidence (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getRuntimeHandoff (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getRuntimeResult (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public abstract fun getRuntimeTraceEvents (Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getRuntimeHandoff (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getRuntimeResult (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public abstract fun getRuntimeTraceEvents (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; public abstract fun getSessionEventLogHealth (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; public abstract fun querySessionEvents (Lcc/noharry/agent/spi/SessionEventQuery;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; public abstract fun replaySessionEvents (Ljava/lang/String;Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt b/agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt index 7ae497f..53dda6d 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/RuntimeDiagnostics.kt @@ -5,14 +5,19 @@ package cc.noharry.agent import cc.noharry.agent.spi.* import cc.noharry.agent.spi.reliability.* -/** Advanced diagnostic records, separate from the stable conversation API. */ +/** + * Advanced diagnostic records, separate from the stable conversation API. + * Conversation queries select the latest execution attempt for `(threadId, turnId)`. Returned raw records use + * `runId` for that execution's unique id, `sessionId` for the thread id and `requestId` for the public turn id. + * [querySessionEvents] accepts these raw identifiers and can query earlier attempts using their execution ids. + */ @ExperimentalAgentRuntimeApi interface RuntimeDiagnostics { - suspend fun getRunState(turnId: String): RuntimeRunSnapshot? - suspend fun getRuntimeResult(turnId: String): RuntimeResult? - suspend fun getRuntimeHandoff(turnId: String): RuntimeHandoff? + suspend fun getRunState(threadId: String, turnId: String): RuntimeRunSnapshot? + suspend fun getRuntimeResult(threadId: String, turnId: String): RuntimeResult? + suspend fun getRuntimeHandoff(threadId: String, turnId: String): RuntimeHandoff? suspend fun getRuntimeEvidence(evidenceId: String): RuntimeEvidence? - suspend fun getRuntimeTraceEvents(turnId: String): List + suspend fun getRuntimeTraceEvents(threadId: String, turnId: String): List suspend fun querySessionEvents(query: SessionEventQuery): List suspend fun replaySessionEvents(threadId: String, turnId: String): List suspend fun getSessionEventLogHealth(threadId: String, turnId: String): SessionEventLogHealth diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt index 9f2ca88..2da5573 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt @@ -295,16 +295,26 @@ internal class DefaultAgentRuntime( activationStore.clearSession(threadId) } - internal suspend fun notifyTurnFinished(result: cc.noharry.agent.TurnResult, sessionId: String) { - hookChain.onTurnFinished(result, cc.noharry.agent.spi.HookContext(sessionId, result.turnId, result.turnId)) + /** A persisted attempt without a saved conversation result cannot be resumed after process loss. */ + internal fun interruptAbandonedAttempt(executionId: String) { + val status = runStateController.snapshot(executionId)?.status ?: return + if (status == RuntimeRunStatus.COMPLETED || status == RuntimeRunStatus.FAILED || status == RuntimeRunStatus.CANCELLED) return + runStateController.applyRuntimeResult(RuntimeResult( + executionId, RuntimeRunStatus.CANCELLED, "Execution was interrupted before its turn result was saved.", + errorCode = "INTERRUPTED", + )) + } + + internal suspend fun notifyTurnFinished(result: cc.noharry.agent.TurnResult, sessionId: String, executionId: String) { + hookChain.onTurnFinished(result, cc.noharry.agent.spi.HookContext(sessionId, executionId, result.turnId)) } internal fun runThread( request: AgentRequest, approve: suspend (PendingConfirmation) -> cc.noharry.agent.ApprovalState, ): Flow = flow { - check(turnApprovals.putIfAbsent(request.requestId, approve) == null) { "Turn is already running" } - try { run(request).collect { emit(it) } } finally { turnApprovals.remove(request.requestId, approve) } + check(turnApprovals.putIfAbsent(request.executionId, approve) == null) { "Turn is already running" } + try { run(request).collect { emit(it) } } finally { turnApprovals.remove(request.executionId, approve) } } override suspend fun resumeConfirmation( @@ -472,7 +482,7 @@ internal class DefaultAgentRuntime( } private suspend fun FlowCollector.collectOrdinaryRun(request: AgentRequest) { - val runId = request.requestId + val runId = request.executionId var lease: SessionRunLease? = null try { val admitted = admitOrdinaryRun(request, runId) ?: return @@ -644,25 +654,25 @@ internal class DefaultAgentRuntime( val paused = outcome.pendingToolUse val pending = PendingConfirmation( pendingId = java.util.UUID.randomUUID().toString(), sessionId = request.sessionId, - runId = request.requestId, expiresAtEpochMillis = nowEpochMillis() + DEFAULT_CONFIRMATION_TIMEOUT_MILLIS, + runId = request.executionId, expiresAtEpochMillis = nowEpochMillis() + DEFAULT_CONFIRMATION_TIMEOUT_MILLIS, idempotencyKey = paused?.toolCallId.orEmpty(), prompt = outcome.prompt, toolName = paused?.toolUse?.toolName, argumentsJson = paused?.toolUse?.argumentsJson, ) // This turn stays in its original stream, so inputs can queue while the host decides. - steeringQueue.resume(request.requestId) + steeringQueue.resume(request.executionId) val decision = approve(pending) if (decision == cc.noharry.agent.ApprovalState.APPROVED && paused != null) { - steeringQueue.resume(request.requestId) + steeringQueue.resume(request.executionId) return nativeLoopFactory.resumeConfirmedToolUse(paused) { emitHost(it) } } val code = if (decision == cc.noharry.agent.ApprovalState.EXPIRED) "CONFIRMATION_EXPIRED" else "CONFIRMATION_DENIED" paused?.let { nativeLoopFactory.recordUnconfirmed(it, code) } if (paused != null) { - emitHost(AgentEvent.NativeToolCallStarted(request.requestId, paused.toolUse.toolName, paused.toolUse.argumentsJson, paused.toolCallId)) - emitHost(AgentEvent.NativeToolCallFinished(request.requestId, paused.toolUse.toolName, "{\"ok\":false,\"code\":\"$code\"}", paused.toolCallId)) + emitHost(AgentEvent.NativeToolCallStarted(request.executionId, paused.toolUse.toolName, paused.toolUse.argumentsJson, paused.toolCallId)) + emitHost(AgentEvent.NativeToolCallFinished(request.executionId, paused.toolUse.toolName, "{\"ok\":false,\"code\":\"$code\"}", paused.toolCallId)) } return NativeLoopOutcome.Terminal( - RuntimeResult(request.requestId, RuntimeRunStatus.FAILED, "Tool approval was ${decision.name.lowercase()}.", errorCode = code), + RuntimeResult(request.executionId, RuntimeRunStatus.FAILED, "Tool approval was ${decision.name.lowercase()}.", errorCode = code), outcome.summary, ) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 7387dbb..19d7491 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -76,7 +76,7 @@ internal class DefaultAgentThread( if (completed.mailbox == null) replay(completed.result) else try { withContext(NonCancellable) { - try { runtime.engine.notifyTurnFinished(completed.result, id) } catch (_: CancellationException) { } + try { runtime.engine.notifyTurnFinished(completed.result, id, checkNotNull(completed.executionId)) } catch (_: CancellationException) { } } completed.mailbox.emit(completed.result.terminalEvent(), awaitDelivery = false) } finally { completed.mailbox.close() } @@ -125,7 +125,7 @@ internal class DefaultAgentThread( try { job.start(); job.join() } catch (_: CancellationException) { turn.cancel() } return withContext(NonCancellable) { job.join() - FinishedThreadTurn(finalizeTurn(turn), mailbox) + FinishedThreadTurn(finalizeTurn(turn), mailbox, turn.executionId) } } catch (failure: Throwable) { mailbox.close() @@ -147,7 +147,10 @@ internal class DefaultAgentThread( val result = checkNotNull(projection.result) if (!isCurrent()) return result.failed(TurnError("THREAD_DELETED", "The thread was deleted.")) return try { - withContext(Dispatchers.IO) { runtime.store.saveTurn(id, result, generation) } + withContext(Dispatchers.IO) { + runtime.store.saveTurn(id, result, generation) + runtime.store.attempts.complete(id, turn.id, turn.executionId) + } if (isCurrent()) result else result.failed(TurnError("THREAD_DELETED", "The thread was deleted.")) } catch (_: Exception) { result.failed(TurnError("STORAGE_FAILED", "The turn could not be saved.")) @@ -158,12 +161,13 @@ internal class DefaultAgentThread( val projection = checkNotNull(turn.projection) try { projection.begin() + prepareAttempt(turn) val record = checkNotNull(runtime.store.load(id, generation)) { "Thread was deleted" }.copy(options = turn.options) if (input.answering != null && input.answering != record.pendingQuestion?.id) { throw ThreadInputException("QUESTION_NOT_FOUND", "The question is not pending in this thread.") } val resolved = resolveThreadAttachments(input) { runtime.engine.readThreadAttachment(id, it) } - val request = threadRequest(record, resolved, options, turn.id) + val request = threadRequest(record, resolved, options, turn.id, turn.executionId) if (request.inputImages.isNotEmpty() && (!runtime.imageInputEnabled || !runtime.supportsImages(request.modelRef))) { projection.fail(TurnError("IMAGE_INPUT_UNSUPPORTED", "The selected model does not accept image input.")) return @@ -182,6 +186,24 @@ internal class DefaultAgentThread( } finally { turn.approval?.cancel() } } + private suspend fun prepareAttempt(turn: ActiveThreadTurn) { + try { + withContext(Dispatchers.IO) { + runtime.store.attempts.active(id).forEach { old -> + if (runtime.store.turn(id, old.turnId, generation) == null) { + runtime.engine.interruptAbandonedAttempt(old.executionId) + } + runtime.store.attempts.complete(id, old.turnId, old.executionId) + } + runtime.store.attempts.begin(id, turn.id, turn.executionId) + } + } catch (cancelled: CancellationException) { + throw cancelled + } catch (_: Exception) { + throw ThreadInputException("STORAGE_FAILED", "The turn execution could not be recorded.") + } + } + private suspend fun approve(turn: ActiveThreadTurn, pending: PendingConfirmation, options: TurnOptions): ApprovalState { val projection = checkNotNull(turn.projection) val policy = options.approvalPolicy ?: turn.options.approvalPolicy ?: ApprovalPolicy.ASK @@ -196,7 +218,7 @@ internal class DefaultAgentThread( projection.toolDecision(pending.idempotencyKey, policy) return automatic } - val approval = ThreadApproval(pending, runtime.nowEpochMillis() + runtime.confirmationTimeoutMillis, runtime.nowEpochMillis) + val approval = ThreadApproval(pending.copy(runId = turn.id), runtime.nowEpochMillis() + runtime.confirmationTimeoutMillis, runtime.nowEpochMillis) turn.approval = approval try { projection.beginApproval(approval) @@ -217,7 +239,7 @@ internal class DefaultAgentThread( val turn = active ?: return if (answering == null) SteerResult.NOT_RUNNING else SteerResult.QUESTION_NOT_FOUND val question = answering?.let { target -> turn.items.filterIsInstance().firstOrNull { it.async && it.id == target } } if (answering != null && question == null) return SteerResult.QUESTION_NOT_FOUND - val result = turn.postInput(PostUserInputRequest(turn.id, options.requestId ?: UUID.randomUUID().toString(), text, id, + val result = turn.postInput(PostUserInputRequest(turn.executionId, options.requestId ?: UUID.randomUUID().toString(), text, id, question?.id?.removePrefix("${turn.id}:question:"))) return when (result) { PostUserInputResult.Accepted, PostUserInputResult.Duplicate -> SteerResult.ACCEPTED @@ -265,7 +287,9 @@ internal class DefaultAgentThread( } } -private data class FinishedThreadTurn(val result: TurnResult, val mailbox: ThreadEventMailbox? = null) +private data class FinishedThreadTurn( + val result: TurnResult, val mailbox: ThreadEventMailbox? = null, val executionId: String? = null, +) private fun TurnResult.failed(error: TurnError): TurnResult = copy( status = TurnStatus.FAILED, finalResponse = "", pending = null, error = error, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultRuntimeDiagnostics.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultRuntimeDiagnostics.kt index b3553c2..e95c5f1 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultRuntimeDiagnostics.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultRuntimeDiagnostics.kt @@ -6,15 +6,30 @@ import cc.noharry.agent.RuntimeDiagnostics import cc.noharry.agent.spi.AgentRuntime import cc.noharry.agent.spi.SessionEvent import cc.noharry.agent.spi.SessionEventQuery +import cc.noharry.agent.spi.SessionEventLogHealth +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.withContext -internal class DefaultRuntimeDiagnostics(private val runtime: AgentRuntime) : RuntimeDiagnostics { - override suspend fun getRunState(turnId: String) = runtime.getRunState(turnId) - override suspend fun getRuntimeResult(turnId: String) = runtime.getRuntimeResult(turnId) - override suspend fun getRuntimeHandoff(turnId: String) = runtime.getRuntimeHandoff(turnId) +internal class DefaultRuntimeDiagnostics( + private val runtime: AgentRuntime, + private val attempts: ThreadAttemptStore, +) : RuntimeDiagnostics { + private suspend fun execution(threadId: String, turnId: String): String? = withContext(Dispatchers.IO) { + attempts.latest(threadId, turnId)?.executionId + } + override suspend fun getRunState(threadId: String, turnId: String) = + execution(threadId, turnId)?.let { runtime.getRunState(it) } + override suspend fun getRuntimeResult(threadId: String, turnId: String) = + execution(threadId, turnId)?.let { runtime.getRuntimeResult(it) } + override suspend fun getRuntimeHandoff(threadId: String, turnId: String) = + execution(threadId, turnId)?.let { runtime.getRuntimeHandoff(it) } override suspend fun getRuntimeEvidence(evidenceId: String) = runtime.getRuntimeEvidence(evidenceId) - override suspend fun getRuntimeTraceEvents(turnId: String) = runtime.getRuntimeTraceEvents(turnId) + override suspend fun getRuntimeTraceEvents(threadId: String, turnId: String) = + execution(threadId, turnId)?.let { runtime.getRuntimeTraceEvents(it) }.orEmpty() override suspend fun querySessionEvents(query: SessionEventQuery) = runtime.querySessionEvents(query) - override suspend fun replaySessionEvents(threadId: String, turnId: String) = runtime.replaySessionEvents(threadId, turnId) - override suspend fun getSessionEventLogHealth(threadId: String, turnId: String) = runtime.getSessionEventLogHealth(threadId, turnId) + override suspend fun replaySessionEvents(threadId: String, turnId: String) = + execution(threadId, turnId)?.let { runtime.replaySessionEvents(threadId, it) }.orEmpty() + override suspend fun getSessionEventLogHealth(threadId: String, turnId: String) = + execution(threadId, turnId)?.let { runtime.getSessionEventLogHealth(threadId, it) } ?: SessionEventLogHealth.unknown() override fun subscribeSessionEvents(threadId: String, listener: (SessionEvent) -> Unit) = runtime.subscribeSessionEvents(threadId, listener) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt index 8eb3ae8..ef06be3 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt @@ -28,7 +28,7 @@ internal class DefaultThreadRuntime( ) : AgentRuntime { private val closed = AtomicBoolean() private val threads = ConcurrentHashMap() - override val diagnostics: RuntimeDiagnostics = DefaultRuntimeDiagnostics(engine) + override val diagnostics: RuntimeDiagnostics = DefaultRuntimeDiagnostics(engine, store.attempts) internal val admission = store.coordination.admission init { admission.register(this, concurrency) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadAttemptStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadAttemptStore.kt new file mode 100644 index 0000000..3218292 --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadAttemptStore.kt @@ -0,0 +1,73 @@ +package cc.noharry.agent.runtime.thread + +import java.io.File +import java.security.MessageDigest +import kotlinx.serialization.json.Json +import kotlinx.serialization.json.JsonArray +import kotlinx.serialization.json.JsonObject +import kotlinx.serialization.json.buildJsonObject +import kotlinx.serialization.json.put + +/** Durable mapping from a conversation-local turn id to its latest independent engine attempt. */ +internal class ThreadAttemptStore( + private val root: File?, + private val lock: Any, +) { + private val memory = mutableMapOf>() + + fun latest(threadId: String, turnId: String): ThreadAttempt? = synchronized(lock) { + read(threadId).firstOrNull { it.turnId == turnId } + } + + fun active(threadId: String): List = synchronized(lock) { read(threadId).filter { it.active } } + + fun begin(threadId: String, turnId: String, executionId: String): ThreadAttempt = synchronized(lock) { + val records = read(threadId) + val attempt = ThreadAttempt(turnId, executionId, (records.firstOrNull { it.turnId == turnId }?.attempt ?: 0) + 1, true) + write(threadId, records.filterNot { it.turnId == turnId } + attempt) + attempt + } + + fun complete(threadId: String, turnId: String, executionId: String) = synchronized(lock) { + val records = read(threadId) + if (records.none { it.turnId == turnId && it.executionId == executionId && it.active }) return@synchronized + write(threadId, records.map { if (it.turnId == turnId && it.executionId == executionId) it.copy(active = false) else it }) + } + + fun delete(threadId: String) = synchronized(lock) { + memory.remove(threadId) + root?.let { file(threadId).let { check(!it.exists() || it.delete()) { "Cannot delete turn attempts" } } } + Unit + } + + private fun read(threadId: String): List { + if (root == null) return memory[threadId].orEmpty() + val target = file(threadId) + if (!target.exists()) return emptyList() + val json = Json.parseToJsonElement(target.readText()) as JsonObject + require(json.number("version") == 1) { "Unsupported attempt storage version" } + return json.array("attempts").map { item -> + val value = item as JsonObject + ThreadAttempt(value.text("turnId"), value.text("executionId"), value.number("attempt"), value.flag("active")) + } + } + + private fun write(threadId: String, records: List) { + if (root == null) { memory[threadId] = records; return } + val encoded = buildJsonObject { + put("version", 1) + put("attempts", JsonArray(records.map { item -> buildJsonObject { + put("turnId", item.turnId); put("executionId", item.executionId) + put("attempt", item.attempt); put("active", item.active) + } })) + } + atomicWrite(file(threadId), encoded.toString()) + } + + private fun file(threadId: String): File { + val digest = MessageDigest.getInstance("SHA-256").digest(threadId.toByteArray(Charsets.UTF_8)) + return File(requireNotNull(root), digest.joinToString("") { "%02x".format(it.toInt() and 0xff) } + ".attempts.json") + } +} + +internal data class ThreadAttempt(val turnId: String, val executionId: String, val attempt: Int, val active: Boolean) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt index 5caf6ac..7fa146d 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt @@ -32,6 +32,7 @@ internal class ThreadExecutionSlot { internal class ActiveThreadTurn(val id: String, val options: ThreadOptions, val owner: DefaultThreadRuntime, val generation: Long) { private val steeringMutex = Mutex() private val receivedInputs = linkedMapOf() + val executionId: String = java.util.UUID.randomUUID().toString() var job: Job? = null var projection: ThreadEventProjection? = null @Volatile var approval: ThreadApproval? = null diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt index a59a602..7d4909d 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt @@ -10,7 +10,7 @@ internal fun TurnInput.snapshot(): TurnInput = copy(parts = parts.map { if (it is InputPart.Image) it.copy(bytes = it.bytes.copyOf()) else it }) -internal fun threadRequest(record: ThreadRecord, input: TurnInput, options: TurnOptions, turnId: String): AgentRequest { +internal fun threadRequest(record: ThreadRecord, input: TurnInput, options: TurnOptions, turnId: String, executionId: String): AgentRequest { val text = input.parts.mapNotNull { when (it) { is InputPart.Text -> it.text @@ -19,7 +19,7 @@ internal fun threadRequest(record: ThreadRecord, input: TurnInput, options: Turn } }.joinToString("\n") return AgentRequest( - requestId = turnId, sessionId = record.id, input = frameAnswer(text, input.answering, record.pendingQuestion), + requestId = turnId, executionId = executionId, sessionId = record.id, input = frameAnswer(text, input.answering, record.pendingQuestion), scene = record.options.scene, modelRef = options.model ?: record.options.model, workspaceId = record.options.workspace, currentStateKeys = options.currentStateKeys, sessionRunConflictPolicy = options.onConflict, instructions = record.options.instructions, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt index e871d0c..e6a83d6 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt @@ -25,6 +25,7 @@ internal class ThreadStore( private val root = root?.canonicalFile internal val coordination = this.root?.path?.let { roots.getOrPut(it) { ThreadCoordination() } } ?: ThreadCoordination() private val lock = coordination.lock + internal val attempts = ThreadAttemptStore(this.root, lock) private val codec = ThreadRecordCodec(redactor) private val memory = linkedMapOf() private val liveTurns = linkedMapOf>() @@ -108,6 +109,7 @@ internal class ThreadStore( } fun delete(threadId: String) = synchronized(lock) { + attempts.delete(threadId) removeFile(threadId, THREAD_SUFFIX) removeFile(threadId, HISTORY_SUFFIX) coordination.stores.forEach { it.clearCachedThread(threadId) } @@ -175,7 +177,7 @@ internal class ThreadStore( } } -private fun atomicWrite(target: File, contents: String) { +internal fun atomicWrite(target: File, contents: String) { val directory = requireNotNull(target.parentFile) check(directory.isDirectory || directory.mkdirs()) { "Cannot create thread storage directory" } val temporary = File(directory, ".${target.name}.${UUID.randomUUID()}.tmp") diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt index 8f316c0..2d11c73 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt @@ -121,6 +121,7 @@ internal data class AgentRequest( val sessionRunConflictPolicy: SessionRunConflictPolicy? = null, val inputImages: List = emptyList(), val instructions: String? = null, + val executionId: String = requestId, ) { /** Safe Java constructor used by host smoke and typical three-field callers. */ constructor(requestId: String, sessionId: String, input: String) : this( diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDiagnosticsTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDiagnosticsTest.kt index a0bd901..963b2a0 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDiagnosticsTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDiagnosticsTest.kt @@ -2,6 +2,7 @@ package cc.noharry.agent.runtime +import cc.noharry.agent.ThreadOptions import cc.noharry.agent.TurnOptions import cc.noharry.agent.spi.model.ModelEvent import kotlinx.coroutines.runBlocking @@ -13,15 +14,15 @@ class ThreadDiagnosticsTest { val root = threadRoot() val model = ThreadScriptModel(listOf(listOf(ModelEvent.Completed), finishEvents("done"))) threadBuilder(model, root).build().use { runtime -> - runtime.startThread().run("answer", TurnOptions(turnId = "empty-observation")) - val observation = runtime.diagnostics.getRuntimeTraceEvents("empty-observation") + runtime.startThread(ThreadOptions(threadId = "observation-thread")).run("answer", TurnOptions(turnId = "empty-observation")) + val observation = runtime.diagnostics.getRuntimeTraceEvents("observation-thread", "empty-observation") .first { it.eventName == "EMPTY_COMPLETION_OBSERVED" } assertEquals("1", observation.details["modelRound"]) assertEquals("0", observation.details["textChars"]) assertTrue(observation.details.containsKey("hadStateAdvancingWork")) } threadBuilder(ThreadScriptModel(listOf(finishEvents("done"))), root).build().use { runtime -> - val observation = runtime.diagnostics.getRuntimeTraceEvents("empty-observation") + val observation = runtime.diagnostics.getRuntimeTraceEvents("observation-thread", "empty-observation") .first { it.eventName == "EMPTY_COMPLETION_OBSERVED" } assertEquals("0", observation.details["thinkingChars"]) assertTrue(observation.details.containsKey("successfulBackendToolCount")) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadExecutionIdentityTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadExecutionIdentityTest.kt new file mode 100644 index 0000000..bd030fa --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadExecutionIdentityTest.kt @@ -0,0 +1,101 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.spi.HookContext +import cc.noharry.agent.spi.RuntimeHook +import cc.noharry.agent.spi.SessionEventQuery +import cc.noharry.agent.spi.reliability.* +import cc.noharry.agent.runtime.thread.ThreadStore +import cc.noharry.agent.runtime.reliability.FileBackedReliabilityStorage +import java.io.File +import kotlinx.coroutines.runBlocking +import org.junit.Assert.* +import org.junit.Test + +class ThreadExecutionIdentityTest { + @Test fun identicalTurnIdsInDifferentThreadsHaveIndependentExecutionsAndDiagnostics() = runBlocking { + val root = threadRoot() + val model = ThreadScriptModel(listOf(finishEvents("first"), finishEvents("second"))) + val starts = mutableListOf() + val finishes = mutableListOf() + val ids = mutableMapOf() + threadBuilder(model, root).hook(object : RuntimeHook { + override suspend fun onTurnStarted(context: HookContext) { starts += context } + override suspend fun onTurnFinished(result: TurnResult, context: HookContext) { finishes += context } + }).build().use { runtime -> + listOf("a", "b").forEach { threadId -> + val thread = runtime.startThread(ThreadOptions(threadId = threadId)) + val result = thread.run("hello", TurnOptions(turnId = "same")) + assertEquals(TurnStatus.COMPLETED, result.status) + assertTrue(result.items.all { it.turnId == "same" }) + val snapshot = checkNotNull(runtime.diagnostics.getRunState(threadId, "same")) + ids[threadId] = snapshot.runId + assertEquals(threadId, snapshot.sessionId) + assertNotEquals("same", snapshot.runId) + val events = runtime.diagnostics.replaySessionEvents(threadId, "same") + assertTrue(events.isNotEmpty()) + assertTrue(events.all { it.runId == snapshot.runId && it.requestId == "same" }) + assertEquals(events, runtime.diagnostics.querySessionEvents(SessionEventQuery(threadId, requestId = "same"))) + assertEquals(result, thread.run("duplicate", TurnOptions(turnId = "same"))) + } + assertNotEquals(ids["a"], ids["b"]) + assertEquals(2, model.requests.size) + assertEquals(starts, finishes) + assertTrue(starts.all { it.requestId == "same" && it.runId == ids[it.sessionId] }) + } + threadBuilder(ThreadScriptModel(emptyList()), root).build().use { runtime -> + ids.forEach { (threadId, executionId) -> + assertEquals(executionId, runtime.diagnostics.getRuntimeResult(threadId, "same")?.runId) + } + assertNull(runtime.diagnostics.getRunState("missing", "same")) + } + } + + @Test fun unsavedAttemptIsCancelledAndSameTurnStartsFreshAfterRestart() = runBlocking { + val root = threadRoot() + val storageRoot = File(root, "storage") + val store = ThreadStore(storageRoot) + store.create("crashed", ThreadOptions(threadId = "crashed")) + store.attempts.begin("crashed", "retry", "old-execution") + val reliability = FileBackedReliabilityStorage(File(storageRoot, "runtime")) + reliability.saveRun( + RuntimeRunSnapshot("old-execution", "crashed", RuntimeRunStatus.RUNNING, 1), + RuntimeRunEnvelope("old-execution", "retry", "crashed", RuntimeRunStatus.RUNNING, + RuntimeRunPhase.MODEL_RUNNING, 1, 1), + ) + val model = ThreadScriptModel(listOf(finishEvents("recovered"))) + threadBuilder(model, root).build().use { runtime -> + val thread = runtime.resumeThread("crashed") + val result = thread.run("retry", TurnOptions(turnId = "retry")) + assertEquals(TurnStatus.COMPLETED, result.status) + val latest = checkNotNull(store.attempts.latest("crashed", "retry")) + assertEquals(2, latest.attempt) + assertFalse(latest.active) + assertNotEquals("old-execution", latest.executionId) + assertEquals(latest.executionId, runtime.diagnostics.getRunState("crashed", "retry")?.runId) + assertEquals(RuntimeRunStatus.CANCELLED, reliability.readSnapshot("old-execution")?.status) + assertEquals("INTERRUPTED", reliability.readResult("old-execution")?.errorCode) + assertEquals(result, thread.run("again", TurnOptions(turnId = "retry"))) + assertEquals(1, model.requests.size) + } + } + + @Test fun savedResultWithUnclosedAttemptMarkerPreservesItsDiagnostics() = runBlocking { + val root = threadRoot() + val store = ThreadStore(File(root, "storage")) + threadBuilder(ThreadScriptModel(listOf(finishEvents("original answer"))), root).build().use { runtime -> + runtime.startThread(ThreadOptions(threadId = "saved")).run("hello", TurnOptions(turnId = "done")) + val executionId = checkNotNull(store.attempts.latest("saved", "done")).executionId + store.attempts.begin("saved", "done", executionId) + } + threadBuilder(ThreadScriptModel(listOf(finishEvents("new answer"))), root).build().use { runtime -> + runtime.resumeThread("saved").run("new", TurnOptions(turnId = "next")) + val previous = checkNotNull(runtime.diagnostics.getRuntimeResult("saved", "done")) + assertEquals(RuntimeRunStatus.COMPLETED, previous.status) + assertEquals("original answer", previous.response) + assertFalse(checkNotNull(store.attempts.latest("saved", "done")).active) + } + } +} diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadQuestionBindingTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadQuestionBindingTest.kt index 2141514..1fad240 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadQuestionBindingTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadQuestionBindingTest.kt @@ -105,7 +105,8 @@ class ThreadQuestionBindingTest { val events = withTimeout(5000) { collected.await() } assertTurnEvents(events) val reply = model.requests.last().messages.single { it.role == "user" && it.content.contains("Suzhou") } - assertTrue(reply.content.contains("Answer to question $turnId/questions/0 (Destination?)")) + val questionId = first.id.removePrefix("$turnId:question:") + assertTrue(reply.content.contains("Answer to question $questionId (Destination?)")) val completed = events.filterIsInstance().map { it.item }.filterIsInstance() assertEquals(ItemStatus.COMPLETED, completed.single { it.id == first.id }.status) } From d966cebc287b36ac55f24db961023253dfd3f215 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:23:38 -0800 Subject: [PATCH 11/40] fix(storage): recover damaged history without blocking deletion Co-Authored-By: Codex --- CHANGELOG.md | 4 ++ .../core/context/SessionHistoryStore.kt | 5 +- .../agent/runtime/thread/ThreadStore.kt | 18 +++-- .../runtime/ThreadStorageCorruptionTest.kt | 70 +++++++++++++++++++ 4 files changed, 90 insertions(+), 7 deletions(-) create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStorageCorruptionTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 46e4767..6097ba2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Damaged history does not block unrelated conversations.** Thread listing skips unreadable or unsupported + metadata. Invalid provider history is renamed to a `.corrupt` file and the conversation resumes with empty model + history. Deleting a conversation does not parse that history first. + - **Conversation storage preserves display text and valid tool JSON.** User input and final answers are stored verbatim. Tool payloads retain JSON numeric/boolean/null types while sensitive fields and Bearer credentials are removed; phone and location filtering follows the configured redactor. Provider model history intentionally diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt index 7dc7426..aeaaaac 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt @@ -119,14 +119,15 @@ internal class SessionHistoryStore @JvmOverloads constructor( session(sessionId)?.let { synchronized(it) { it.runs.flatten() } }.orEmpty() fun clearSession(sessionId: String) { - session(sessionId)?.let { session -> + // Deletion must not restore or parse persisted history, which may itself be damaged. + synchronized(sessions) { sessions[sessionId] }?.let { session -> synchronized(session) { session.latestStarted += 1 session.runs = emptyList() session.lastInputTokens = null - persistence?.delete(sessionId) } } + synchronized(started) { started.entries.removeAll { it.value.sessionId == sessionId } } persistence?.delete(sessionId) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt index e6a83d6..5f759be 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt @@ -57,8 +57,8 @@ internal class ThreadStore( } fun list(): List = synchronized(lock) { - val threads = root?.listFiles()?.filter { it.name.endsWith(THREAD_SUFFIX) }?.map { file -> - codec.decode(Json.parseToJsonElement(file.readText()) as JsonObject) + val threads = root?.listFiles()?.filter { it.name.endsWith(THREAD_SUFFIX) }?.mapNotNull { file -> + try { codec.decode(Json.parseToJsonElement(file.readText()) as JsonObject) } catch (_: Exception) { null } } ?: memory.values.toList() threads.filterNot { executionSlot(it.record.id).deleting }.map { it.record.info() }.sortedByDescending { it.updatedAt } } @@ -126,9 +126,7 @@ internal class ThreadStore( override val identity: Any get() = root?.path ?: this@ThreadStore override fun load(sessionId: String): StoredSessionHistory? = synchronized(lock) { if (root == null) modelMemory[sessionId] - else file(sessionId, HISTORY_SUFFIX).takeIf(File::isFile)?.let { - ModelHistoryCodec.decode(Json.parseToJsonElement(it.readText()) as JsonObject) - } + else readModelHistory(sessionId) } override fun save(sessionId: String, history: StoredSessionHistory) = synchronized(lock) { @@ -148,6 +146,16 @@ internal class ThreadStore( } } + private fun readModelHistory(sessionId: String): StoredSessionHistory? { + val target = file(sessionId, HISTORY_SUFFIX).takeIf(File::isFile) ?: return null + val contents = target.readText() + return try { ModelHistoryCodec.decode(Json.parseToJsonElement(contents) as JsonObject) } catch (_: RuntimeException) { + val suffix = if (File(target.path + ".corrupt").exists()) ".${UUID.randomUUID()}.corrupt" else ".corrupt" + Files.move(target.toPath(), File(target.path + suffix).toPath()) + null + } + } + private fun read(id: String): StoredThread? = if (root == null) memory[id] else { file(id, THREAD_SUFFIX).takeIf(File::isFile)?.let { codec.decode(Json.parseToJsonElement(it.readText()) as JsonObject) } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStorageCorruptionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStorageCorruptionTest.kt new file mode 100644 index 0000000..c169fe5 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStorageCorruptionTest.kt @@ -0,0 +1,70 @@ +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.kernel.core.context.SessionHistoryPersistence +import cc.noharry.agent.kernel.core.context.SessionHistoryStore +import cc.noharry.agent.kernel.core.context.StoredSessionHistory +import java.io.File +import kotlinx.coroutines.runBlocking +import org.junit.Assert.* +import org.junit.Test + +class ThreadStorageCorruptionTest { + @Test fun listingSkipsInvalidAndUnsupportedMetadata() = runBlocking { + val root = threadRoot() + threadBuilder(ThreadScriptModel(emptyList()), root).build().use { runtime -> + runtime.startThread(ThreadOptions(threadId = "valid")) + File(root, "storage/broken.thread.json").writeText("{invalid") + File(root, "storage/future.thread.json").writeText("""{"version":999}""") + assertEquals(listOf("valid"), runtime.listThreads().map { it.id }) + } + } + + @Test fun damagedModelHistoryIsQuarantinedAndTheThreadContinues() = runBlocking { + for (damaged in listOf("{invalid", """{"version":999,"runs":[]}""")) { + val root = savedHistory() + val history = historyFile(root) + history.writeText(damaged) + val model = ThreadScriptModel(listOf(finishEvents("new answer"))) + threadBuilder(model, root).build().use { runtime -> + val result = runtime.resumeThread("history").run("new input") + assertEquals(TurnStatus.COMPLETED, result.status) + assertFalse(model.requests.single().messages.any { "old input" in it.content }) + assertEquals(damaged, File(history.path + ".corrupt").readText()) + assertTrue(history.isFile) + } + } + } + + @Test fun deleteDoesNotNeedToReadDamagedModelHistory() = runBlocking { + val root = savedHistory() + val history = historyFile(root) + history.writeText("{invalid") + threadBuilder(ThreadScriptModel(emptyList()), root).build().use { runtime -> + runtime.deleteThread("history") + assertTrue(runtime.listThreads().isEmpty()) + assertFalse(history.exists()) + assertFalse(File(history.path + ".corrupt").exists()) + } + } + + @Test fun deletionNeverLoadsAPersistedHistory() { + val deleted = mutableListOf() + val persistence = object : SessionHistoryPersistence { + override fun load(sessionId: String): StoredSessionHistory? = error("History must not be read when deleting") + override fun save(sessionId: String, history: StoredSessionHistory) = Unit + override fun delete(sessionId: String) { deleted += sessionId } + override fun clear() = Unit + } + SessionHistoryStore(persistence = persistence).clearSession("damaged") + assertEquals(listOf("damaged"), deleted) + } + + private suspend fun savedHistory(): File = threadRoot().also { root -> + threadBuilder(ThreadScriptModel(listOf(finishEvents("old answer"))), root).build().use { runtime -> + runtime.startThread(ThreadOptions(threadId = "history")).run("old input") + } + } + + private fun historyFile(root: File): File = File(root, "storage").listFiles().orEmpty().single { it.name.endsWith(".history.json") } +} From 9ff6b17fdaa1b23a3716e98b3be1a0e2ab95a260 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:29:49 -0800 Subject: [PATCH 12/40] fix(runtime): isolate item and question ids from provider call ids Co-Authored-By: Codex --- CHANGELOG.md | 4 + .../kernel/core/loop/NativeRoundRunner.kt | 15 +++- .../kernel/core/loop/NativeUserInteraction.kt | 2 +- .../kernel/core/loop/RuntimeSteeringQueue.kt | 7 +- .../noharry/agent/model/OpenAiProviderJson.kt | 17 ++-- .../runtime/thread/ThreadToolProjection.kt | 2 +- .../core/loop/RuntimeSteeringQueueTest.kt | 6 +- .../agent/model/OpenAiMissingToolIdsTest.kt | 42 +++++++++ .../agent/runtime/AsyncUserInteractionTest.kt | 11 ++- .../agent/runtime/ThreadToolIdentityTest.kt | 89 +++++++++++++++++++ 10 files changed, 174 insertions(+), 21 deletions(-) create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/model/OpenAiMissingToolIdsTest.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadToolIdentityTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 6097ba2..6ca12ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ called out; a patch release does not break it. - **Configured event-log locations survive `storage(...)`.** Android continues using its existing `event-log` directory. A storage directory must be used by only one process; multiple runtimes in that process coordinate. +- **Repeated provider tool ids do not collide with conversation items.** Tool items use turn-local ids, duplicate + calls within one response retain distinct tool-result associations, and asynchronous questions use independent + batch ids. OpenAI chat responses without tool ids receive unique fallback ids in both streaming modes. + - **Steering preserves input identity.** `SteerOptions` lets a host supply the request id echoed in `ThreadItem.UserMessage`, including after restart. Ordinary steering never answers a pending question; only an explicit `answering` question id does. Inputs can queue while a tool awaits approval. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeRoundRunner.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeRoundRunner.kt index 1d420cb..475101c 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeRoundRunner.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeRoundRunner.kt @@ -35,6 +35,7 @@ import cc.noharry.agent.kernel.core.trace.LoopSessionRecorder import cc.noharry.agent.kernel.core.trace.ModelCallProbe import cc.noharry.agent.kernel.core.trace.NativePublicEventBuffer import java.security.MessageDigest +import java.util.UUID import kotlinx.coroutines.CancellationException import kotlinx.coroutines.Deferred import kotlinx.coroutines.Dispatchers @@ -82,6 +83,7 @@ internal class NativeRoundRunner( var thinkingSignature: String? = null val toolResults = mutableListOf() val pendingToolCalls = mutableListOf() + val seenToolCallIds = mutableSetOf() val cancellationHistory = CancellationLegalHistoryTracker() var immediateOutcome: RoundOutcome? = null val toolSchemaStarted = System.nanoTime() @@ -132,9 +134,10 @@ internal class NativeRoundRunner( return@roundEvents } if (event is ModelEvent.ToolCall) { - cancellationHistory.observe(event, thinking.toString(), thinkingSignature) + val identified = uniqueToolCall(event, seenToolCallIds) + cancellationHistory.observe(identified, thinking.toString(), thinkingSignature) if (immediateOutcome == null) { - pendingToolCalls += toolSet.unwrapCallTool(event)?.also { wireCalls[it.id] = event } ?: event + pendingToolCalls += toolSet.unwrapCallTool(identified)?.also { wireCalls[it.id] = identified } ?: identified } return@roundEvents } @@ -940,6 +943,14 @@ private fun String.isEchoedData(): Boolean { return runCatching { kotlinx.serialization.json.Json.parseToJsonElement(trimmed) }.isSuccess } +/** Some compatible providers repeat or omit ids; each call in one response still needs its own tool result. */ +private fun uniqueToolCall(event: ModelEvent.ToolCall, seen: MutableSet): ModelEvent.ToolCall { + if (event.id.isNotBlank() && seen.add(event.id)) return event + var id: String + do { id = "tool-call-${UUID.randomUUID()}" } while (!seen.add(id)) + return event.copy(id = id) +} + private fun missingFinish(message: String): RoundOutcome.Failed = RoundOutcome.Failed( ToolLoopFailure(RuntimeErrorCode.MODEL_FINISHED_WITHOUT_RUNTIME_FINISH.wireCode, message), ) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeUserInteraction.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeUserInteraction.kt index 3fa9cdb..23f8433 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeUserInteraction.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeUserInteraction.kt @@ -28,7 +28,7 @@ internal class NativeUserInteraction(private val inputs: RuntimeSteeringQueue) { val options = question["options"]?.let { parseOptions(it as? JsonArray ?: throw IllegalArgumentException("Invalid options")) }.orEmpty() UserInteraction("QUESTION", "PENDING", text = title, options = options) } - val registered = inputs.questions(context.runId, event.id, questions) + val registered = inputs.questions(context.runId, questions) inputs.projectPublic(context.runId, events) return buildJsonObject { put("accepted", true) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeSteeringQueue.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeSteeringQueue.kt index 74eb817..91faace 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeSteeringQueue.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeSteeringQueue.kt @@ -82,13 +82,13 @@ internal class RuntimeSteeringQueue( fun inFlight(runId: String): List = withRun(runId) { inFlight.toList() } ?: emptyList() - fun questions(runId: String, callId: String, questions: List): List { + fun questions(runId: String, questions: List): List { val run = checkNotNull(find(runId)) { "Run is not active" } return synchronized(run) { check(run.open) { "Run is not active" } check(run.questions.size + questions.size <= MAX_RUN_QUESTIONS) { "Question limit reached" } - val identified = questions.mapIndexed { index, question -> question.copy(questionId = "$runId/$callId/$index") } - check(identified.none { it.questionId in run.questions }) { "Question call id already used" } + val batch = ++run.questionBatch + val identified = questions.mapIndexed { index, question -> question.copy(questionId = "$runId/questions/$batch/$index") } identified.forEach { run.record(it) run.questions[it.questionId] = it @@ -144,6 +144,7 @@ internal class RuntimeSteeringQueue( val pending = ArrayDeque() val inFlight = mutableListOf() val questions = linkedMapOf() + var questionBatch = 0 fun record(fact: UserInteraction, public: Boolean = true) { recorder?.invoke(fact) ?: buffered.add(fact) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/model/OpenAiProviderJson.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/model/OpenAiProviderJson.kt index 3a7a04a..fece95d 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/model/OpenAiProviderJson.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/model/OpenAiProviderJson.kt @@ -21,6 +21,7 @@ import cc.noharry.agent.spi.model.ModelTool import cc.noharry.agent.model.ServerSideSearchCapability import cc.noharry.agent.spi.model.ModelEvent import cc.noharry.agent.spi.model.ModelResponseMetadata +import java.util.UUID internal fun openAiRequest( apiKey: String, @@ -238,12 +239,12 @@ private fun shouldReplayReasoningContent(model: String): Boolean { } private fun openAiToolCalls(calls: JsonArray?): List = - calls.orEmpty().mapNotNull { element -> - val call = element as? JsonObject ?: return@mapNotNull null - val function = call.obj("function") ?: return@mapNotNull null + calls.orEmpty().mapIndexedNotNull { index, element -> + val call = element as? JsonObject ?: return@mapIndexedNotNull null + val function = call.obj("function") ?: return@mapIndexedNotNull null ModelEvent.ToolCall( - id = call.string("id") ?: "openai-tool-call", - name = function.string("name") ?: return@mapNotNull null, + id = call.string("id")?.takeIf(String::isNotBlank) ?: "openai-tool-call-${UUID.randomUUID()}-$index", + name = function.string("name") ?: return@mapIndexedNotNull null, argumentsJson = function.rawOrString("arguments") ?: "{}", ) } @@ -274,8 +275,8 @@ private fun collectOpenAiToolCallDeltas( calls.orEmpty().forEachIndexed { fallbackIndex, element -> val call = element as? JsonObject ?: return@forEachIndexed val index = call.int("index") ?: fallbackIndex - val accumulator = accumulators.getOrPut(index) { OpenAiToolCallAccumulator() } - call.string("id")?.let { accumulator.id = it } + val accumulator = accumulators.getOrPut(index) { OpenAiToolCallAccumulator(id = "openai-tool-call-${UUID.randomUUID()}-$index") } + call.string("id")?.takeIf(String::isNotBlank)?.let { accumulator.id = it } val function = call.obj("function") ?: return@forEachIndexed function.string("name")?.let { accumulator.name = it } function.string("arguments")?.let { accumulator.arguments.append(it) } @@ -283,7 +284,7 @@ private fun collectOpenAiToolCallDeltas( } internal data class OpenAiToolCallAccumulator( - var id: String = "openai-tool-call", + var id: String, var name: String? = null, val arguments: StringBuilder = StringBuilder(), ) { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt index 007c8f0..aa506bd 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt @@ -34,7 +34,7 @@ internal class ThreadToolProjection( val id = event.toolCallId.ifEmpty { nextId() } if (id in calls) return val item = ThreadItem.ToolCall( - id = "$turnId:tool:$id", turnId = turnId, tool = event.toolName, + id = nextId(), turnId = turnId, tool = event.toolName, source = source(event.toolName), server = server(event.toolName), arguments = event.arguments, approvedBy = decisions.remove(event.toolCallId), ) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeSteeringQueueTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeSteeringQueueTest.kt index b9c4b35..079bd3c 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeSteeringQueueTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/loop/RuntimeSteeringQueueTest.kt @@ -58,7 +58,7 @@ class RuntimeSteeringQueueTest { @Test fun questionAnswerIsCorrelatedAndUnansweredQuestionsDoNotPreventSealing() { val facts = mutableListOf() val queue = queue(facts) - val ids = queue.questions("run", "ask", listOf( + val ids = queue.questions("run", listOf( UserInteraction("QUESTION", "PENDING", text = "Destination?"), UserInteraction("QUESTION", "PENDING", text = "Time?"), )).map { it.questionId } @@ -89,7 +89,7 @@ class RuntimeSteeringQueueTest { @Test fun closeRecordsTheReasonOnceAndLaterConsumptionOrClearAddsNothing() { val facts = mutableListOf() val queue = queue(facts) - val question = queue.questions("run", "ask", listOf(UserInteraction("QUESTION", "PENDING", text = "Destination?"))).single() + val question = queue.questions("run", listOf(UserInteraction("QUESTION", "PENDING", text = "Destination?"))).single() assertEquals(PostUserInputResult.Accepted, queue.post(input().copy(questionId = question.questionId))) val drained = queue.drain("run").single() queue.close("run", "CANCELLED") @@ -129,7 +129,7 @@ class RuntimeSteeringQueueTest { @Test fun questionsOnAClosedRunAreRefusedAsUnavailableNotAsBadArguments() { val queue = queue() queue.close("run", "COMPLETED") - val error = runCatching { queue.questions("run", "ask", listOf(UserInteraction("QUESTION", "PENDING", text = "?"))) }.exceptionOrNull() + val error = runCatching { queue.questions("run", listOf(UserInteraction("QUESTION", "PENDING", text = "?"))) }.exceptionOrNull() assertTrue(error is IllegalStateException) } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/model/OpenAiMissingToolIdsTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/model/OpenAiMissingToolIdsTest.kt new file mode 100644 index 0000000..e9ce2d8 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/model/OpenAiMissingToolIdsTest.kt @@ -0,0 +1,42 @@ +package cc.noharry.agent.model + +import cc.noharry.agent.spi.model.ModelEvent +import kotlinx.coroutines.flow.toList +import kotlinx.coroutines.runBlocking +import org.junit.Assert.* +import org.junit.Test + +class OpenAiMissingToolIdsTest { + @Test fun missingAndBlankChatIdsAreDistinctWithinAndAcrossResponses() = runBlocking { + val transport = FakeHttpTransport(executeResponse = providerResponse("""{"choices":[{"message":{"tool_calls":[ + {"function":{"name":"first","arguments":"{}"}}, + {"id":"","function":{"name":"second","arguments":"{}"}}, + {"id":"provider-id","function":{"name":"third","arguments":"{}"}} + ]}}]}""")) + val client = OpenAiModelClient(::contractApiKey, CONTRACT_MODEL, CONTRACT_BASE_URL, transport = transport) + val rounds = List(2) { client.complete(contractModelRequest()).toList().filterIsInstance() } + rounds.forEach { calls -> + assertEquals(listOf("first", "second", "third"), calls.map { it.name }) + assertEquals("provider-id", calls.last().id) + } + assertEquals(4, rounds.flatMap { it.take(2) }.map { it.id }.toSet().size) + assertTrue(rounds.flatten().all { it.id.isNotBlank() }) + } + + @Test fun streamedMissingIdsStayAttachedToTheirArgumentFragmentsAndAreUnique() = runBlocking { + val transport = FakeHttpTransport(streamText = """ + data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"name":"first","arguments":"{\"value\":"}},{"index":1,"id":"","function":{"name":"second","arguments":"{\"value\":"}}]}}]} + + data: {"choices":[{"delta":{"tool_calls":[{"index":1,"function":{"arguments":"2}"}},{"index":0,"function":{"arguments":"1}"}}]}}]} + + data: [DONE] + """.trimIndent()) + val client = OpenAiModelClient(::contractApiKey, CONTRACT_MODEL, CONTRACT_BASE_URL, stream = true, transport = transport) + val rounds = List(2) { client.complete(contractModelRequest()).toList().filterIsInstance() } + rounds.forEach { calls -> + assertEquals(listOf("first", "second"), calls.map { it.name }) + assertEquals(listOf("""{"value":1}""", """{"value":2}"""), calls.map { it.argumentsJson }) + } + assertEquals(4, rounds.flatten().map { it.id }.toSet().size) + } +} diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/AsyncUserInteractionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/AsyncUserInteractionTest.kt index 824cff8..c6e7bf0 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/AsyncUserInteractionTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/AsyncUserInteractionTest.kt @@ -92,7 +92,7 @@ class AsyncUserInteractionTest { val expired = seen.filterIsInstance().single { it.interaction.state == "EXPIRED" }.interaction assertEquals("COMPLETED", expired.reason) assertTrue(seen.indexOfFirst { it is AgentEvent.UserInteraction && it.interaction.state == "EXPIRED" } < seen.lastIndex) - assertEquals(PostUserInputResult.RunNotActive, runtime.postUserInput(PostUserInputRequest("run", "late", "answer", "session", "run/ask-1/0"))) + assertEquals(PostUserInputResult.RunNotActive, runtime.postUserInput(PostUserInputRequest("run", "late", "answer", "session", expired.questionId))) } finally { runtime.close() } } } @@ -101,10 +101,15 @@ class AsyncUserInteractionTest { val root = java.nio.file.Files.createTempDirectory("async-cancel-log").toFile() val model = QuestionModel(holdSecondRound = true) val runtime = AgentRuntimeBuilder.create().modelClient(model).sessionEventLogRoot(root).buildEngine() - val job = launch { runtime.run(AgentRequest("run", "session", "plan")).toList() } + val questionId = CompletableDeferred() + val job = launch { runtime.run(AgentRequest("run", "session", "plan")).collect { event -> + if (event is AgentEvent.UserInteraction && event.interaction.kind == "QUESTION" && event.interaction.state == "PENDING") { + questionId.complete(event.interaction.questionId) + } + } } try { withTimeout(10_000) { model.secondRoundStarted.await() } - assertEquals(PostUserInputResult.Accepted, runtime.postUserInput(PostUserInputRequest("run", "early", "Suzhou", "session", "run/ask-1/0"))) + assertEquals(PostUserInputResult.Accepted, runtime.postUserInput(PostUserInputRequest("run", "early", "Suzhou", "session", questionId.await()))) withTimeout(10_000) { job.cancelAndJoin() } assertEquals(2, model.calls) assertEquals(PostUserInputResult.RunNotActive, runtime.postUserInput(PostUserInputRequest("run", "late", "answer"))) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadToolIdentityTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadToolIdentityTest.kt new file mode 100644 index 0000000..95686dc --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadToolIdentityTest.kt @@ -0,0 +1,89 @@ +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.spi.ProviderConcurrencyDeclaration +import cc.noharry.agent.spi.model.* +import java.io.File +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.Flow +import kotlinx.coroutines.flow.flow +import kotlinx.coroutines.flow.toList +import org.junit.Assert.* +import org.junit.Test + +class ThreadToolIdentityTest { + @Test fun repeatedProviderCallIdAcrossRoundsKeepsBothToolItems() = runBlocking { readWithRepeatedIds(false) } + + @Test fun repeatedProviderCallIdWithinAReadBatchKeepsArgumentsAndResultsPaired() = runBlocking { readWithRepeatedIds(true) } + + @Test fun repeatedAsyncQuestionCallIdStillCreatesDistinctAnswerableQuestions() = runBlocking { + val model = RepeatedQuestionModel() + threadBuilder(model).build().use { runtime -> + val thread = runtime.startThread() + val collected = async { thread.runStreamed("plan").toList() } + withTimeout(5000) { model.waiting.await() } + val questions = thread.pendingRequests().filterIsInstance() + assertEquals(listOf("Destination?", "Budget?"), questions.map { it.text }) + assertEquals(2, questions.map { it.id }.toSet().size) + assertEquals(SteerResult.ACCEPTED, thread.steer("Suzhou", questions.first().id)) + assertEquals(SteerResult.ACCEPTED, thread.steer("Generous", questions.last().id)) + model.release.complete(Unit) + val events = withTimeout(5000) { collected.await() } + assertTurnEvents(events) + val result = (events.last() as ThreadEvent.TurnCompleted).result + assertEquals(TurnStatus.COMPLETED, result.status) + assertTrue(result.items.filterIsInstance().all { it.status == ItemStatus.COMPLETED }) + val inputs = model.requests.last().messages.filter { it.role == "user" }.map { it.content } + assertTrue(inputs.any { "Destination?" in it && "Suzhou" in it }) + assertTrue(inputs.any { "Budget?" in it && "Generous" in it }) + } + } + + private suspend fun readWithRepeatedIds(batched: Boolean) { + val root = threadRoot() + val workspace = File(root, "workspace").apply { mkdirs() } + File(workspace, "first.txt").writeText("first file contents") + File(workspace, "second.txt").writeText("second file contents") + val calls = listOf("first", "second").map { name -> + ModelEvent.ToolCall("provider-reused", "read_file", """{"path":"/$name.txt"}""") + } + val rounds = if (batched) listOf(calls + ModelEvent.Completed) else calls.map { listOf(it, ModelEvent.Completed) } + val model = ThreadScriptModel(rounds + listOf(finishEvents("done"))) + threadBuilder(model, root).build().use { runtime -> + val events = runtime.startThread().runStreamed("read both files").toList() + assertTurnEvents(events) + val result = (events.last() as ThreadEvent.TurnCompleted).result + assertEquals(TurnStatus.COMPLETED, result.status) + val tools = result.items.filterIsInstance().filter { it.tool == "read_file" } + assertEquals(2, tools.size) + assertEquals(2, tools.map { it.id }.toSet().size) + for ((index, name) in listOf("first", "second").withIndex()) { + assertEquals(calls[index].argumentsJson, tools[index].arguments) + assertTrue(tools[index].output.orEmpty().contains("$name file contents")) + assertEquals(ItemStatus.COMPLETED, tools[index].status) + } + if (batched) { + val messages = model.requests.last().messages.filter { it.toolName == "read_file" } + assertEquals(2, messages.filter { it.role == "assistant" }.map { it.toolCallId }.toSet().size) + assertEquals(messages.filter { it.role == "assistant" }.map { it.toolCallId }, messages.filter { it.role == "tool" }.map { it.toolCallId }) + } + } + } +} + +private class RepeatedQuestionModel : ModelClient { + override val providerConcurrency = ProviderConcurrencyDeclaration.threadSafe() + val requests = mutableListOf() + val waiting = CompletableDeferred() + val release = CompletableDeferred() + override fun complete(request: ModelRequest): Flow = flow { + requests += request.copy(messages = request.messages.toList()) + val question = when (requests.size) { 1 -> "Destination?"; 2 -> "Budget?"; else -> null } + if (question != null) emit(ModelEvent.ToolCall("question-call", "ask_async", """{"questions":[{"title":"$question"}]}""")) + else { + if (requests.size == 3) { waiting.complete(Unit); release.await() } + emit(ModelEvent.ToolCall("finish", "finish", """{"response":"done"}""")) + } + emit(ModelEvent.Completed) + } +} From b22e3479ef4725ca617d0e9d7ceaf89f2dc2a946 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:34:28 -0800 Subject: [PATCH 13/40] fix(runtime): continue denied approvals and close cancelled history Co-Authored-By: Codex --- CHANGELOG.md | 4 ++ .../agent/kernel/core/loop/NativeToolLoop.kt | 33 +++------ .../core/loop/NativeToolResumeSupport.kt | 41 ++++++++++++ .../core/loop/NativeToolUseController.kt | 2 +- .../agent/runtime/DefaultAgentRuntime.kt | 28 +------- .../runtime/ThreadApprovalContinuation.kt | 58 ++++++++++++++++ .../agent/runtime/run/NativeLoopFactory.kt | 7 ++ .../runtime/ThreadApprovalContinuationTest.kt | 67 +++++++++++++++++++ .../agent/runtime/ThreadApprovalFlowTest.kt | 4 +- .../agent/runtime/ThreadConcurrencyTest.kt | 2 +- .../runtime/ThreadReviewRegressionTest.kt | 2 +- 11 files changed, 195 insertions(+), 53 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolResumeSupport.kt create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuation.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuationTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ca12ff..d3a009f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Denied approvals continue the same turn.** Both explicit denial and `DENY_ALL` return a + `CONFIRMATION_DENIED` tool result to the model without executing the tool, so it can explain the outcome. + Cancelling or interrupting a pending approval records `CONFIRMATION_CANCELLED` in provider history. + - **Damaged history does not block unrelated conversations.** Thread listing skips unreadable or unsupported metadata. Invalid provider history is renamed to a `.corrupt` file and the conversation resumes with empty model history. Deleting a conversation does not parse that history first. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt index f6bfcd4..b8f9b1f 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt @@ -784,9 +784,13 @@ internal class NativeToolLoop( return NativeLoopOutcome.Terminal(result, summary, publicEvents.snapshot()) } - suspend fun resumeConfirmedToolUse( + suspend fun resumeConfirmedToolUse(pending: PendingNativeToolUse, emitPublicEvent: suspend (AgentEvent) -> Unit = {}): NativeLoopOutcome = + resumeAfterApproval(pending, null, emitPublicEvent) + + suspend fun resumeAfterApproval( pending: PendingNativeToolUse, - emitPublicEvent: suspend (AgentEvent) -> Unit = {}, + deniedCode: String?, + emitPublicEvent: suspend (AgentEvent) -> Unit, ): NativeLoopOutcome { val client = modelClient if (client == null) { @@ -810,7 +814,8 @@ internal class NativeToolLoop( confirmedEvent, ) } - val executed = toolUseController.executeConfirmedToolUse(pending, publicEvents) + val executed = if (deniedCode == null) toolUseController.executeConfirmedToolUse(pending, publicEvents) + else declinedToolResult(pending, deniedCode, publicEvents, sessionRecorder) if (pending.toolUse.source == ToolSource.BACKEND) { toolUseController.recordBackendObligation( pending.context.runId, @@ -820,7 +825,7 @@ internal class NativeToolLoop( ) } // Observe-only: the confirmed tool executes outside the round runner; record it here. - emitProbeConfirmedToolExecution( + if (deniedCode == null) emitProbeConfirmedToolExecution( toolName = pending.toolUse.toolName, callId = pending.toolCallId, argumentsJson = pending.toolUse.argumentsJson, @@ -830,7 +835,7 @@ internal class NativeToolLoop( val messages = restoredHistory(pending).toMutableList() messages += pending.toCallMessage() messages += pending.toToolCallEvent().toToolResultMessage(executed.resultJson, executed.images) - if (!executed.parsed.ok) { + if (deniedCode == null && !executed.parsed.ok) { // The user approved this call, not further attempts: the run stops, and the session sees the call and its result. persistHistory(pending.context.runId, restoredHistory(pending), pending.budgetSnapshot) sessionHistory?.record(pending.context.runId, messages + failedRunNotice(executed.parsed.code ?: "TOOL_FAILED")) @@ -845,7 +850,7 @@ internal class NativeToolLoop( client = client, runId = pending.context.runId, toolContext = pending.context, - hookContext = pending.context.toHookContext(approvedConfirmation = true), + hookContext = pending.context.toHookContext(approvedConfirmation = deniedCode == null), messages = messages, summaryBuilder = NativeLoopSummaryBuilder(), publicEvents = publicEvents, @@ -958,23 +963,7 @@ internal class NativeToolLoop( private suspend fun resumeContextMessage(runId: String): List = handoffProvider(runId)?.toResumeContextMessage()?.let { listOf(it) }.orEmpty() - private fun RuntimeHandoff.toResumeContextMessage(): ModelMessage = ModelMessage( - role = "system", - content = buildList { - task?.let { add("Task: $it") } - if (done.isNotEmpty()) add("Done: ${done.joinToString("; ")}") - if (nextActions.isNotEmpty()) add("Next: ${nextActions.joinToString("; ")}") - if (decisions.isNotEmpty()) add("Decisions: ${decisions.joinToString("; ")}") - if (doNotRepeat.isNotEmpty()) add("Do not repeat: ${doNotRepeat.joinToString("; ")}") - }.joinToString("\n"), - ) - private fun PendingNativeToolUse.toToolCallEvent(): ModelEvent.ToolCall = - ModelEvent.ToolCall( - id = toolCallId, - name = toolUse.toolName, - argumentsJson = toolUse.argumentsJson, - ) } /** A remembered capability preactivates a tool only when the tool has every term of it (search scores vary with the catalog). */ diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolResumeSupport.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolResumeSupport.kt new file mode 100644 index 0000000..bdca348 --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolResumeSupport.kt @@ -0,0 +1,41 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.kernel.core.loop + +import cc.noharry.agent.spi.ToolUseResult +import cc.noharry.agent.spi.model.ModelEvent +import cc.noharry.agent.spi.model.ModelMessage +import cc.noharry.agent.spi.reliability.RuntimeHandoff +import cc.noharry.agent.kernel.core.trace.NativePublicEventBuffer +import cc.noharry.agent.kernel.core.trace.LoopSessionRecorder + +internal suspend fun declinedToolResult( + pending: PendingNativeToolUse, + code: String, + events: NativePublicEventBuffer, + recorder: LoopSessionRecorder, +): ConfirmedToolUseResult { + val result = """{"ok":false,"code":"$code","message":"The user declined this action; the tool was not run."}""" + events.recordStarted(pending.toolCallId, pending.toolUse.toolName, pending.toolUse.argumentsJson) + events.recordFinished(pending.toolCallId, pending.toolUse.toolName, result) + recorder.recordToolFinished(pending.context, pending.toToolCallEvent(), pending.toolUse.source.toDynamicToolSource(), result) + return ConfirmedToolUseResult(result, ToolUseResult(false, result, code = code)) +} + +internal fun RuntimeHandoff.toResumeContextMessage(): ModelMessage = ModelMessage( + role = "system", + content = buildList { + task?.let { add("Task: $it") } + if (done.isNotEmpty()) add("Done: ${done.joinToString("; ")}") + if (nextActions.isNotEmpty()) add("Next: ${nextActions.joinToString("; ")}") + if (decisions.isNotEmpty()) add("Decisions: ${decisions.joinToString("; ")}") + if (doNotRepeat.isNotEmpty()) add("Do not repeat: ${doNotRepeat.joinToString("; ")}") + }.joinToString("\n"), + ) + +internal fun PendingNativeToolUse.toToolCallEvent(): ModelEvent.ToolCall = + ModelEvent.ToolCall( + id = toolCallId, + name = toolUse.toolName, + argumentsJson = toolUse.argumentsJson, + ) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolUseController.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolUseController.kt index ecd195a..b48f7f0 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolUseController.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolUseController.kt @@ -934,7 +934,7 @@ private fun PendingNativeToolUse.toToolCallEvent(toolUse: ToolUse): ModelEvent.T argumentsJson = toolUse.argumentsJson, ) -private fun ToolSource.toDynamicToolSource(): DynamicToolSource? = when (this) { +internal fun ToolSource.toDynamicToolSource(): DynamicToolSource? = when (this) { ToolSource.NATIVE_READ -> DynamicToolSource.NATIVE_READ ToolSource.NATIVE_WRITE -> DynamicToolSource.NATIVE_WRITE ToolSource.NETWORK -> DynamicToolSource.NETWORK diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt index 2da5573..f3ec886 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt @@ -650,32 +650,8 @@ internal class DefaultAgentRuntime( request: AgentRequest, outcome: NativeLoopOutcome.RequiresConfirmation, approve: suspend (PendingConfirmation) -> cc.noharry.agent.ApprovalState, - ): NativeLoopOutcome { - val paused = outcome.pendingToolUse - val pending = PendingConfirmation( - pendingId = java.util.UUID.randomUUID().toString(), sessionId = request.sessionId, - runId = request.executionId, expiresAtEpochMillis = nowEpochMillis() + DEFAULT_CONFIRMATION_TIMEOUT_MILLIS, - idempotencyKey = paused?.toolCallId.orEmpty(), prompt = outcome.prompt, - toolName = paused?.toolUse?.toolName, argumentsJson = paused?.toolUse?.argumentsJson, - ) - // This turn stays in its original stream, so inputs can queue while the host decides. - steeringQueue.resume(request.executionId) - val decision = approve(pending) - if (decision == cc.noharry.agent.ApprovalState.APPROVED && paused != null) { - steeringQueue.resume(request.executionId) - return nativeLoopFactory.resumeConfirmedToolUse(paused) { emitHost(it) } - } - val code = if (decision == cc.noharry.agent.ApprovalState.EXPIRED) "CONFIRMATION_EXPIRED" else "CONFIRMATION_DENIED" - paused?.let { nativeLoopFactory.recordUnconfirmed(it, code) } - if (paused != null) { - emitHost(AgentEvent.NativeToolCallStarted(request.executionId, paused.toolUse.toolName, paused.toolUse.argumentsJson, paused.toolCallId)) - emitHost(AgentEvent.NativeToolCallFinished(request.executionId, paused.toolUse.toolName, "{\"ok\":false,\"code\":\"$code\"}", paused.toolCallId)) - } - return NativeLoopOutcome.Terminal( - RuntimeResult(request.executionId, RuntimeRunStatus.FAILED, "Tool approval was ${decision.name.lowercase()}.", errorCode = code), - outcome.summary, - ) - } + ): NativeLoopOutcome = continueThreadApproval(request, outcome, approve, nativeLoopFactory, steeringQueue, + nowEpochMillis()) { emitHost(it) } private suspend fun FlowCollector.finishQuestionTurn( started: RuntimeRunSnapshot, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuation.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuation.kt new file mode 100644 index 0000000..f29ad4d --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuation.kt @@ -0,0 +1,58 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.ApprovalState +import cc.noharry.agent.spi.AgentEvent +import cc.noharry.agent.spi.AgentRequest +import cc.noharry.agent.spi.PendingConfirmation +import cc.noharry.agent.spi.reliability.RuntimeResult +import cc.noharry.agent.spi.reliability.RuntimeRunStatus +import cc.noharry.agent.kernel.core.loop.NativeLoopOutcome +import cc.noharry.agent.kernel.core.loop.RuntimeSteeringQueue +import cc.noharry.agent.runtime.run.NativeLoopFactory +import java.util.UUID +import kotlinx.coroutines.CancellationException +import kotlinx.coroutines.NonCancellable +import kotlinx.coroutines.withContext + +/** Same-stream approval never executes a denied tool; its result becomes the next model round's input. */ +internal suspend fun continueThreadApproval( + request: AgentRequest, + outcome: NativeLoopOutcome.RequiresConfirmation, + approve: suspend (PendingConfirmation) -> ApprovalState, + loops: NativeLoopFactory, + steering: RuntimeSteeringQueue, + now: Long, + emit: suspend (AgentEvent) -> Unit, +): NativeLoopOutcome { + val paused = outcome.pendingToolUse + val pending = PendingConfirmation( + pendingId = UUID.randomUUID().toString(), sessionId = request.sessionId, + runId = request.executionId, expiresAtEpochMillis = now + 60_000L, + idempotencyKey = paused?.toolCallId.orEmpty(), prompt = outcome.prompt, + toolName = paused?.toolUse?.toolName, argumentsJson = paused?.toolUse?.argumentsJson, + ) + steering.resume(request.executionId) + val decision = try { approve(pending) } catch (cancelled: CancellationException) { + withContext(NonCancellable) { paused?.let { loops.recordUnconfirmed(it, "CONFIRMATION_CANCELLED") } } + throw cancelled + } + if (paused != null) { + if (decision == ApprovalState.APPROVED) return loops.resumeConfirmedToolUse(paused, emit) + if (decision == ApprovalState.DENIED) return loops.resumeDeniedToolUse(paused, emit) + } + val code = when (decision) { + ApprovalState.EXPIRED -> "CONFIRMATION_EXPIRED" + ApprovalState.CANCELLED -> "CONFIRMATION_CANCELLED" + else -> "CONFIRMATION_DENIED" + } + paused?.let { + loops.recordUnconfirmed(it, code) + emit(AgentEvent.NativeToolCallStarted(request.executionId, it.toolUse.toolName, it.toolUse.argumentsJson, it.toolCallId)) + emit(AgentEvent.NativeToolCallFinished(request.executionId, it.toolUse.toolName, "{\"ok\":false,\"code\":\"$code\"}", it.toolCallId)) + } + val status = if (decision == ApprovalState.CANCELLED) RuntimeRunStatus.CANCELLED else RuntimeRunStatus.FAILED + return NativeLoopOutcome.Terminal(RuntimeResult(request.executionId, status, + "Tool approval was ${decision.name.lowercase()}.", errorCode = code), outcome.summary) +} diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt index 6d80db9..ec36c2d 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt @@ -163,6 +163,13 @@ internal class NativeLoopFactory( ).resumeConfirmedToolUse(pending, emitPublicEvent) } + suspend fun resumeDeniedToolUse(pending: PendingNativeToolUse, emitPublicEvent: suspend (AgentEvent) -> Unit): NativeLoopOutcome { + val runId = pending.context.runId + return loop(runId, workspaceFileSystem = workspaces[runId], + probeAttachment = probeAttachments[runId] ?: ProbeRunAttachment.disabled(runId)) + .resumeAfterApproval(pending, "CONFIRMATION_DENIED", emitPublicEvent) + } + suspend fun resumeUserInput( runId: String, sessionId: String, diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuationTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuationTest.kt new file mode 100644 index 0000000..4e73b13 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuationTest.kt @@ -0,0 +1,67 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.spi.model.ModelRequest +import kotlinx.coroutines.* +import org.junit.Assert.* +import org.junit.Test + +class ThreadApprovalContinuationTest { + @Test fun denialBecomesAToolResultAndTheModelCanAnswerWithoutExecuting() = runBlocking { + deniedTurn(ApprovalPolicy.ASK) + } + + @Test fun denyAllStillLetsTheModelAnswerWithoutExecuting() = runBlocking { + deniedTurn(ApprovalPolicy.DENY_ALL) + } + + @Test fun interruptedApprovalIsCancelledInTheNextModelRequestAfterRestart() = runBlocking { + cancelledApproval(collectorCancelled = false) + } + + @Test fun cancelledCollectorDoesNotLeaveAnAwaitingConfirmationPlaceholder() = runBlocking { + cancelledApproval(collectorCancelled = true) + } + + private suspend fun deniedTurn(policy: ApprovalPolicy) { + val requests = mutableListOf() + val provider = LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature"))) + threadBuilder(backendThenFinishModel(requests)).tools(provider).hook(confirmUntilApproved()).build().use { runtime -> + val events = mutableListOf() + runtime.startThread(ThreadOptions(approvalPolicy = policy)).runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) (event.item as Approval).deny() + } + assertTurnEvents(events) + val result = (events.last() as ThreadEvent.TurnCompleted).result + assertEquals("recovered", result.finalResponse) + assertTrue(provider.calledTools.isEmpty()) + assertTrue(requests.last().messages.any { it.role == "tool" && "CONFIRMATION_DENIED" in it.content }) + assertFalse(requests.last().messages.any { "awaiting_confirmation" in it.content }) + val denied = result.items.filterIsInstance().single { it.tool == qualifiedMcpTool("set_temperature") } + assertEquals(ItemStatus.DECLINED, denied.status) + } + } + + private suspend fun cancelledApproval(collectorCancelled: Boolean) = coroutineScope { + val root = threadRoot() + approvalBuilder(root).build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "cancelled")) + val pending = CompletableDeferred() + val running = launch { thread.runStreamed("set temperature").collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) pending.complete(Unit) + } } + withTimeout(5000) { pending.await() } + if (collectorCancelled) running.cancelAndJoin() else { thread.interrupt(); running.join() } + } + val model = ThreadScriptModel(listOf(finishEvents("next"))) + threadBuilder(model, root).build().use { runtime -> + runtime.resumeThread("cancelled").run("what happened?") + val history = model.requests.single().messages + assertTrue(history.any { it.role == "tool" && "CONFIRMATION_CANCELLED" in it.content }) + assertFalse(history.any { "awaiting_confirmation" in it.content }) + } + } +} diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt index 7981cb0..b25263e 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt @@ -69,10 +69,10 @@ class ThreadApprovalFlowTest { if (event is ThreadEvent.ItemStarted && event.item is Approval) (event.item as Approval).deny("No") } assertTurnEvents(events) - assertEquals("CONFIRMATION_DENIED", (events.last() as ThreadEvent.TurnFailed).error.code) + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) val completed = events.filterIsInstance().map { it.item } assertEquals(ApprovalState.DENIED, completed.filterIsInstance().single().state) - assertEquals(ItemStatus.DECLINED, completed.filterIsInstance().last().status) + assertEquals(ItemStatus.DECLINED, completed.filterIsInstance().single { it.tool == qualifiedMcpTool("set_temperature") }.status) } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadConcurrencyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadConcurrencyTest.kt index 653bfff..8ccc772 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadConcurrencyTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadConcurrencyTest.kt @@ -63,7 +63,7 @@ class ThreadConcurrencyTest { assertFalse(events.any { it is ThreadEvent.ItemStarted && it.item is Approval }) val tools = events.filterIsInstance().map { it.item }.filterIsInstance() assertTrue(tools.any { it.approvedBy == policy }) - assertEquals(policy == ApprovalPolicy.APPROVE_ALL, events.last() is ThreadEvent.TurnCompleted) + assertTrue(events.last() is ThreadEvent.TurnCompleted) } } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadReviewRegressionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadReviewRegressionTest.kt index ce65159..4bf46c0 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadReviewRegressionTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadReviewRegressionTest.kt @@ -71,7 +71,7 @@ class ThreadReviewRegressionTest { } } assertEquals(2, approvals) - assertEquals("CONFIRMATION_DENIED", (events.last() as ThreadEvent.TurnFailed).error.code) + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) assertTurnEvents(events) } } From db91093032ff4a9d717172e4eeade4207ab2a0a6 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:37:02 -0800 Subject: [PATCH 14/40] fix(runtime): preserve copied internal request identity defaults Co-Authored-By: Codex --- .../kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt | 2 +- .../src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt | 4 +++- .../kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt | 4 +++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt index 7d4909d..d737160 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt @@ -19,7 +19,7 @@ internal fun threadRequest(record: ThreadRecord, input: TurnInput, options: Turn } }.joinToString("\n") return AgentRequest( - requestId = turnId, executionId = executionId, sessionId = record.id, input = frameAnswer(text, input.answering, record.pendingQuestion), + requestId = turnId, executionIdOverride = executionId, sessionId = record.id, input = frameAnswer(text, input.answering, record.pendingQuestion), scene = record.options.scene, modelRef = options.model ?: record.options.model, workspaceId = record.options.workspace, currentStateKeys = options.currentStateKeys, sessionRunConflictPolicy = options.onConflict, instructions = record.options.instructions, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt index 2d11c73..6b99b00 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt @@ -121,8 +121,10 @@ internal data class AgentRequest( val sessionRunConflictPolicy: SessionRunConflictPolicy? = null, val inputImages: List = emptyList(), val instructions: String? = null, - val executionId: String = requestId, + private val executionIdOverride: String? = null, ) { + val executionId: String get() = executionIdOverride ?: requestId + /** Safe Java constructor used by host smoke and typical three-field callers. */ constructor(requestId: String, sessionId: String, input: String) : this( requestId = requestId, diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt index a0fba74..f9ac327 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt @@ -727,7 +727,9 @@ class RuntimeHookPolicyTest { runtime.startThread(cc.noharry.agent.ThreadOptions(threadId = "session-1")) .run("hello", cc.noharry.agent.TurnOptions(turnId = "request-1")) - assertEquals(listOf("started:request-1", "finished:request-1:COMPLETED"), events) + val executionId = checkNotNull(runtime.diagnostics.getRunState("session-1", "request-1")).runId + assertTrue(executionId != "request-1") + assertEquals(listOf("started:$executionId", "finished:$executionId:COMPLETED"), events) } } From 2c872529b8c3397b2bd51557e00015ca0bbf73fd Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:33:16 -0800 Subject: [PATCH 15/40] feat(storage): delete complete thread event logs after draining writers Co-Authored-By: Codex --- CHANGELOG.md | 4 + agent-api/api/agent-api.api | 2 + .../cc/noharry/agent/spi/SessionEventLog.kt | 9 +- .../eventlog/AsyncSessionEventDelivery.kt | 16 +- .../runtime/eventlog/AsyncSessionEventLog.kt | 37 ++++- .../eventlog/FileBackedSessionEventLog.kt | 35 +++- .../eventlog/InMemorySessionEventLog.kt | 9 + .../eventlog/SessionEventDecodeCache.kt | 8 + .../runtime/eventlog/SessionEventDeletion.kt | 18 ++ .../eventlog/SessionEventDeletionTest.kt | 156 ++++++++++++++++++ 10 files changed, 283 insertions(+), 11 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletion.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletionTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index d3a009f..fb65550 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ called out; a patch release does not break it. `CONFIRMATION_DENIED` tool result to the model without executing the tool, so it can explain the outcome. Cancelling or interrupting a pending approval records `CONFIRMATION_CANCELLED` in provider history. +- **Event logs can delete complete conversations.** `SessionEventLog.deleteThread` has an unsupported-by-default + implementation for custom backends. Built-in logs delete events, attachments, health and cached identities; + asynchronous logs drain accepted writes first and reset subscribers before a thread can be recreated. + - **Damaged history does not block unrelated conversations.** Thread listing skips unreadable or unsupported metadata. Invalid provider history is renamed to a `.corrupt` file and the conversation resumes with empty model history. Deleting a conversation does not parse that history first. diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index 33dbe2a..9dbda81 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -1323,6 +1323,7 @@ public final class cc/noharry/agent/spi/SessionEventAppend { public abstract interface class cc/noharry/agent/spi/SessionEventLog { public abstract fun append (Lcc/noharry/agent/spi/SessionEventAppend;)Lcc/noharry/agent/spi/SessionEvent; + public fun deleteThread (Ljava/lang/String;)Z public fun durability ()Lcc/noharry/agent/spi/SessionEventLogDurability; public fun health (Ljava/lang/String;Ljava/lang/String;)Lcc/noharry/agent/spi/SessionEventLogHealth; public fun putAttachment (Ljava/lang/String;Lcc/noharry/agent/spi/SessionAttachmentRef;[B)Z @@ -1333,6 +1334,7 @@ public abstract interface class cc/noharry/agent/spi/SessionEventLog { } public final class cc/noharry/agent/spi/SessionEventLog$DefaultImpls { + public static fun deleteThread (Lcc/noharry/agent/spi/SessionEventLog;Ljava/lang/String;)Z public static fun durability (Lcc/noharry/agent/spi/SessionEventLog;)Lcc/noharry/agent/spi/SessionEventLogDurability; public static fun health (Lcc/noharry/agent/spi/SessionEventLog;Ljava/lang/String;Ljava/lang/String;)Lcc/noharry/agent/spi/SessionEventLogHealth; public static fun putAttachment (Lcc/noharry/agent/spi/SessionEventLog;Ljava/lang/String;Lcc/noharry/agent/spi/SessionAttachmentRef;[B)Z diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventLog.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventLog.kt index b8d0e45..474a8ea 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventLog.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventLog.kt @@ -4,7 +4,7 @@ package cc.noharry.agent.spi * Append-only authority for runtime session events. * * Implementations allocate event identity and stream-local sequence atomically. The contract has - * no update or delete operation; query and replay return stable snapshots in append order. + * no update operation; query and replay return stable snapshots in append order. */ interface SessionEventLog { fun append(event: SessionEventAppend): SessionEvent @@ -13,6 +13,13 @@ interface SessionEventLog { fun replay(sessionId: String, runId: String): List + /** + * Deletes every event, attachment and health record owned by [threadId] (the event's `sessionId`). Drain accepted + * asynchronous writes before deleting, and prevent them from recreating the data. Return true after complete, + * idempotent deletion; false means deletion is unsupported. Failures must throw. The runtime first stops its turns. + */ + fun deleteThread(threadId: String): Boolean = false + /** Persistence class. Custom and legacy backends default to [SessionEventLogDurability.UNKNOWN]. */ fun durability(): SessionEventLogDurability = SessionEventLogDurability.UNKNOWN diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventDelivery.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventDelivery.kt index b48a406..cbd77c8 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventDelivery.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventDelivery.kt @@ -18,6 +18,8 @@ internal class AsyncSessionEventDelivery( private val dirty = AtomicBoolean(false) private val scheduled = AtomicBoolean(false) private val closed = AtomicBoolean(false) + private val cursorLock = Any() + private val generations = mutableMapOf() private val readGate = Any() private val executor = Executors.newSingleThreadExecutor { task -> Thread(task, "SessionEventLog-subscriber").apply { isDaemon = true } @@ -42,23 +44,31 @@ internal class AsyncSessionEventDelivery( private fun deliver() { for ((key, target) in positions()) { - var cursor = cursors[key] ?: initialPosition(key) + val fallback = initialPosition(key) + val version = synchronized(cursorLock) { generations.getOrPut(key.sessionId) { Any() } } + var cursor = synchronized(cursorLock) { cursors[key] ?: fallback } while (!closed.get() && cursor < target) { val events = synchronized(readGate) { if (closed.get()) emptyList() else runCatching { page(key, cursor) }.getOrDefault(emptyList()) } if (events.isEmpty()) break for (event in events) { - if (closed.get()) return + if (closed.get() || synchronized(cursorLock) { generations[key.sessionId] !== version }) return if (event.sequence != cursor + 1) return runCatching { listener(event) } cursor = event.sequence - cursors[key] = cursor + synchronized(cursorLock) { if (generations[key.sessionId] === version) cursors[key] = cursor } } } } } + /** Discard an old page already read by a slow subscriber and reset its cursors for a recreated thread. */ + fun forgetThread(threadId: String) { + synchronized(cursorLock) { generations.remove(threadId); cursors.keys.removeAll { it.sessionId == threadId } } + signal() + } + override fun close() { closed.set(true) // Wait for our disk reads, not arbitrary user code; no new read can start afterward. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt index 7efbc2a..85b4331 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt @@ -16,6 +16,7 @@ internal class AsyncSessionEventLog( private val now: () -> Long = System::currentTimeMillis, private val persistBatch: (List) -> Unit = durable::appendAllocatedBatch, ) : SessionEventLog, AutoCloseable { + private val rootGate = ROOT_GATES.computeIfAbsent(durable.storageIdentity) { ReentrantLock() } private val lock = ReentrantLock() private val changed = lock.newCondition() private val streams = linkedMapOf() @@ -29,13 +30,15 @@ internal class AsyncSessionEventLog( private var pendingBytes = 0L private var closing = false private var failure: String? = null - private val openedStreams = mutableSetOf() + private val openedStreams = java.util.Collections.synchronizedSet(mutableSetOf()) + + init { rootGate.withLock { synchronized(INSTANCES) { INSTANCES[this] = true } } } override fun append(event: SessionEventAppend): SessionEvent { validateAppendIdentity(event) validatePayload(event.payload) val bytes = encodePayload(event.payload).toString().length.toLong() * CHAR_BYTES + ENVELOPE_BYTES - val stored = lock.withLock { + val stored = rootGate.withLock { lock.withLock { awaitCapacity(bytes) val key = EventStreamKey(event.sessionId, event.runId) val state = streams.getOrPut(key) { @@ -55,7 +58,7 @@ internal class AsyncSessionEventLog( if (writer == null) writer = worker.submit(::writeLoop) changed.signalAll() accepted - } + } } signalDeliveries() return stored } @@ -82,7 +85,7 @@ internal class AsyncSessionEventLog( queue.isNotEmpty() } if (!ready) { - openedStreams.forEach(durable::endAsyncStream) + synchronized(openedStreams) { openedStreams.toList() }.forEach(durable::endAsyncStream) return } Thread.sleep(BATCH_DELAY_MS) @@ -150,6 +153,14 @@ internal class AsyncSessionEventLog( override fun durability() = SessionEventLogDurability.DURABLE + override fun deleteThread(threadId: String): Boolean = durable.deleteThread(threadId) + + private fun forgetThread(threadId: String) = lock.withLock { + streams.keys.removeAll { it.sessionId == threadId } + synchronized(openedStreams) { openedStreams.removeAll { it.sessionId == threadId } } + deliveries.forEach { it.forgetThread(threadId) } + } + override fun health(sessionId: String, runId: String): SessionEventLogHealth { val live = lock.withLock { streams[EventStreamKey(sessionId, runId)]?.let { state -> @@ -187,7 +198,7 @@ internal class AsyncSessionEventLog( } override fun putAttachment(sessionId: String, ref: SessionAttachmentRef, bytes: ByteArray): Boolean = - durable.putAttachment(sessionId, ref, bytes) + rootGate.withLock { durable.putAttachment(sessionId, ref, bytes) } override fun readAttachment(sessionId: String, sha256: String): ByteArray? = durable.readAttachment(sessionId, sha256) @@ -221,6 +232,22 @@ internal class AsyncSessionEventLog( writer?.get() worker.shutdown() } + + companion object { + private val ROOT_GATES = java.util.concurrent.ConcurrentHashMap() + private val INSTANCES = java.util.WeakHashMap() + + /** A raw file-log handle must also drain async wrappers already writing to the same root. */ + internal fun deleteFromRoot(identity: String, threadId: String, delete: () -> Boolean): Boolean { + require(threadId.isNotBlank()) { "threadId must not be blank" } + val gate = ROOT_GATES.computeIfAbsent(identity) { ReentrantLock() } + return gate.withLock { + val writers = synchronized(INSTANCES) { INSTANCES.keys.filter { it.rootGate === gate } } + writers.forEach { check(it.flush()) { "Cannot delete data while event-log writes have failed" } } + delete().also { deleted -> if (deleted) writers.forEach { it.forgetThread(threadId) } } + } + } + } } private data class AsyncStreamState(var accepted: Long, var persisted: Long, val initial: Long = accepted) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/FileBackedSessionEventLog.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/FileBackedSessionEventLog.kt index c78f91b..45ab77f 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/FileBackedSessionEventLog.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/FileBackedSessionEventLog.kt @@ -46,6 +46,9 @@ internal class FileBackedSessionEventLog( private val asyncCursors = linkedMapOf() private var streamReadCount = 0 private val attachments = SessionAttachmentStore(canonicalRoot) + internal val storageIdentity: String get() = canonicalRoot.path + + init { synchronized(INSTANCES) { INSTANCES[this] = true } } override fun append(event: SessionEventAppend): SessionEvent { val stored = withLogLock { @@ -73,10 +76,37 @@ internal class FileBackedSessionEventLog( acceptedListeners.subscribe(listener) override fun putAttachment(sessionId: String, ref: SessionAttachmentRef, bytes: ByteArray): Boolean = - runCatching { attachments.put(sessionId, ref, bytes) }.getOrDefault(false) + runCatching { withLogLock { attachments.put(sessionId, ref, bytes) } }.getOrDefault(false) override fun readAttachment(sessionId: String, sha256: String): ByteArray? = - runCatching { attachments.read(sessionId, sha256) }.getOrNull() + runCatching { withLogLock { attachments.read(sessionId, sha256) } }.getOrNull() + + override fun deleteThread(threadId: String): Boolean = + AsyncSessionEventLog.deleteFromRoot(storageIdentity, threadId) { deletePersistedThread(threadId) } + + private fun deletePersistedThread(threadId: String): Boolean = withLogLock { + validateEventIdentity(threadId, "threadId") + listOf(STREAMS_DIR, HEALTH_DIR, ATTACHMENTS_DIR).forEach { directory -> + deleteEventLogTree(containedDirectory(canonicalRoot, SESSION_EVENTS_DIR, SESSION_EVENTS_VERSION_DIR, + directory, encodeFileName(threadId))) + } + val index = containedFile(canonicalRoot, EVENT_ID_LIST_FILE) + check(!index.exists() || index.delete()) { "Cannot invalidate event id index" } + val generation = readEventIdGeneration() + check(generation < Long.MAX_VALUE) { "EventLog eventId generation overflow" } + writeForcedText(eventIdGenerationFile(), (generation + 1L).toString()) + val readers = synchronized(INSTANCES) { INSTANCES.keys.filter { it.canonicalRoot == canonicalRoot } } + readers.forEach { it.forgetThread(threadId) } + true + } + + private fun forgetThread(threadId: String) { + eventIdIndex.ids.clear() + eventIdIndex.seeded = false + decodedEvents.deleteThread(threadId) + liveHealth.keys.removeAll { it.sessionId == threadId } + asyncCursors.keys.removeAll { it.sessionId == threadId } + } /** Commits already accepted identities in order, once per stream per batch. */ internal fun appendAllocatedBatch(events: List) = withLogLock { @@ -822,6 +852,7 @@ internal class FileBackedSessionEventLog( private companion object { private val PROCESS_LOCKS = ConcurrentHashMap() + private val INSTANCES = java.util.WeakHashMap() fun processLockFor(root: File): Any = PROCESS_LOCKS.computeIfAbsent(root.canonicalPath) { Any() } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/InMemorySessionEventLog.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/InMemorySessionEventLog.kt index 941d4de..0b4f1e0 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/InMemorySessionEventLog.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/InMemorySessionEventLog.kt @@ -75,6 +75,15 @@ internal class InMemorySessionEventLog( override fun durability(): SessionEventLogDurability = SessionEventLogDurability.VOLATILE + override fun deleteThread(threadId: String): Boolean = synchronized(lock) { + require(threadId.isNotBlank()) { "threadId must not be blank" } + events.filter { it.sessionId == threadId }.forEach { eventIds.remove(it.eventId) } + events.removeAll { it.sessionId == threadId } + streams.keys.removeAll { it.sessionId == threadId } + liveHealth.keys.removeAll { it.sessionId == threadId } + true + } + override fun health(sessionId: String, runId: String): SessionEventLogHealth = synchronized(lock) { require(sessionId.isNotBlank()) { "sessionId must not be blank" } require(runId.isNotBlank()) { "runId must not be blank" } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDecodeCache.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDecodeCache.kt index 3a8cc93..ce30242 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDecodeCache.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDecodeCache.kt @@ -20,6 +20,14 @@ internal class SessionEventDecodeCache( fun cached(line: String): SessionEvent? = entries[line] + fun deleteThread(threadId: String) { + val iterator = entries.entries.iterator() + while (iterator.hasNext()) { + val entry = iterator.next() + if (entry.value.sessionId == threadId) { cachedChars -= entry.key.length; iterator.remove() } + } + } + fun read(line: String): SessionEvent { entries[line]?.let { return it } val decoded = decode(line) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletion.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletion.kt new file mode 100644 index 0000000..15a6f0f --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletion.kt @@ -0,0 +1,18 @@ +package cc.noharry.agent.runtime.eventlog + +import java.io.File +import java.nio.file.Files + +/** Removes contained event data without following a nested symlink outside the event-log root. */ +internal fun deleteEventLogTree(file: File) { + if (Files.isSymbolicLink(file.toPath())) { + Files.delete(file.toPath()) + return + } + if (!file.exists()) return + if (file.isDirectory) { + val children = checkNotNull(file.listFiles()) { "Cannot list event-log data for deletion" } + children.forEach(::deleteEventLogTree) + } + check(file.delete()) { "Cannot delete event-log data" } +} diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletionTest.kt new file mode 100644 index 0000000..e223e44 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletionTest.kt @@ -0,0 +1,156 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime.eventlog + +import cc.noharry.agent.spi.* +import java.io.File +import java.nio.file.Files +import java.util.Collections +import java.util.concurrent.CountDownLatch +import java.util.concurrent.Executors +import java.util.concurrent.TimeUnit +import java.util.concurrent.TimeoutException +import org.junit.Assert.* +import org.junit.Test + +class SessionEventDeletionTest { + @Test fun inMemoryDeletionRemovesOnlyTheSelectedThreadAndCanRepeat() { + val log = InMemorySessionEventLog() + val removed = log.append(event("removed")) + val kept = log.append(event("kept")) + assertTrue(log.deleteThread("removed")) + assertTrue(log.deleteThread("removed")) + assertTrue(log.query(SessionEventQuery("removed")).isEmpty()) + assertEquals(listOf(kept), log.query(SessionEventQuery("kept"))) + assertEquals(SessionEventLogHealthStatus.UNKNOWN, log.health("removed", removed.runId).status) + assertEquals(1L, log.append(event("removed")).sequence) + } + + @Test fun diskDeletionClearsAttachmentsAndCachesInEveryOpenReader() { + val root = Files.createTempDirectory("event-delete-").toFile() + val first = FileBackedSessionEventLog(root) + val other = FileBackedSessionEventLog(root) + val removed = first.append(event("removed")) + val kept = first.append(event("kept")) + val bytes = "image data".toByteArray() + val ref = SessionAttachmentRef(sha256Hex(bytes), "image/png", bytes.size.toLong(), "image") + assertTrue(first.putAttachment("removed", ref, bytes)) + other.replay("removed", "run") + other.health("removed", "run") + assertTrue(first.deleteThread("removed")) + assertTrue(first.deleteThread("removed")) + assertTrue(other.query(SessionEventQuery("removed")).isEmpty()) + assertNull(other.readAttachment("removed", ref.sha256)) + assertEquals(SessionEventLogHealthStatus.UNKNOWN, other.health("removed", "run").status) + assertFalse(root.walkTopDown().filter(File::isFile).any { it.readText().contains(removed.eventId) }) + assertEquals(listOf(kept), other.replay("kept", "run")) + assertEquals(1L, other.append(event("removed")).sequence) + } + + @Test fun deletionWaitsForAcceptedAsyncWritesAndTheyCannotResurrectTheThread() { + val root = Files.createTempDirectory("event-delete-async-").toFile() + val durable = FileBackedSessionEventLog(root) + val writing = CountDownLatch(1) + val release = CountDownLatch(1) + val log = AsyncSessionEventLog(durable, persistBatch = { + writing.countDown() + check(release.await(5, TimeUnit.SECONDS)) + durable.appendAllocatedBatch(it) + }) + val pool = Executors.newSingleThreadExecutor() + try { + log.append(event("removed")) + assertTrue(writing.await(5, TimeUnit.SECONDS)) + log.append(event("removed")) + val deletion = pool.submit { log.deleteThread("removed") } + assertFalse(deletion.isDone) + release.countDown() + assertTrue(deletion.get(5, TimeUnit.SECONDS)) + assertTrue(log.replay("removed", "run").isEmpty()) + log.close() + assertTrue(FileBackedSessionEventLog(root).query(SessionEventQuery("removed")).isEmpty()) + } finally { release.countDown(); log.close(); pool.shutdownNow() } + } + + @Test fun subscriberDropsAnOldPageAndReceivesEventsFromTheRecreatedThread() { + val root = Files.createTempDirectory("event-delete-subscriber-").toFile() + val log = AsyncSessionEventLog(FileBackedSessionEventLog(root)) + val blocked = CountDownLatch(1) + val release = CountDownLatch(1) + val recreated = CountDownLatch(1) + val seen = Collections.synchronizedList(mutableListOf()) + val subscription = log.subscribe { value -> + if (value.requestId == "old") { blocked.countDown(); check(release.await(5, TimeUnit.SECONDS)) } + seen += value.requestId + if (value.requestId == "new") recreated.countDown() + } + try { + log.append(event("removed", "old")) + assertTrue(blocked.await(5, TimeUnit.SECONDS)) + log.append(event("removed", "stale")) + assertTrue(log.deleteThread("removed")) + assertEquals(1L, log.append(event("removed", "new")).sequence) + release.countDown() + assertTrue(recreated.await(5, TimeUnit.SECONDS)) + assertFalse(seen.contains("stale")) + assertEquals(1, seen.count { it == "new" }) + } finally { release.countDown(); subscription.close(); log.close() } + } + + @Test fun deletingThroughAnotherAsyncOrRawHandleDrainsEveryWriterAtThatRoot() { + for (raw in listOf(false, true)) deleteThroughAnotherHandle(raw) + } + + private fun deleteThroughAnotherHandle(raw: Boolean) { + val root = Files.createTempDirectory("event-delete-shared-").toFile() + val durable = FileBackedSessionEventLog(root) + val writing = CountDownLatch(1) + val release = CountDownLatch(1) + val first = AsyncSessionEventLog(durable, persistBatch = { + writing.countDown(); check(release.await(5, TimeUnit.SECONDS)); durable.appendAllocatedBatch(it) + }) + val second = AsyncSessionEventLog(FileBackedSessionEventLog(root)) + val deleting: SessionEventLog = if (raw) FileBackedSessionEventLog(root) else second + val pool = Executors.newSingleThreadExecutor() + try { + first.append(event("removed")) + assertTrue(writing.await(5, TimeUnit.SECONDS)) + val deletion = pool.submit { deleting.deleteThread("removed") } + assertThrows(TimeoutException::class.java) { deletion.get(100, TimeUnit.MILLISECONDS) } + release.countDown() + assertTrue(deletion.get(5, TimeUnit.SECONDS)) + assertTrue(first.replay("removed", "run").isEmpty()) + assertEquals(1L, first.append(event("removed", "new")).sequence) + assertTrue(first.flush()) + assertEquals(listOf("new"), second.replay("removed", "run").map { it.requestId }) + } finally { release.countDown(); first.close(); second.close(); pool.shutdownNow() } + } + + @Test fun deletionDoesNotRepeatAnUnrelatedThreadsSlowSubscriberEvent() { + val root = Files.createTempDirectory("event-delete-unrelated-").toFile() + val log = AsyncSessionEventLog(FileBackedSessionEventLog(root)) + val blocked = CountDownLatch(1) + val release = CountDownLatch(1) + val delivered = CountDownLatch(2) + val seen = Collections.synchronizedList(mutableListOf()) + val subscription = log.subscribe { value -> + if (value.requestId == "one") { blocked.countDown(); check(release.await(5, TimeUnit.SECONDS)) } + seen += value.requestId + delivered.countDown() + } + try { + log.append(event("kept", "one")) + assertTrue(blocked.await(5, TimeUnit.SECONDS)) + assertTrue(log.deleteThread("removed")) + log.append(event("kept", "two")) + release.countDown() + assertTrue(delivered.await(5, TimeUnit.SECONDS)) + assertEquals(listOf("one", "two"), seen.toList()) + } finally { release.countDown(); subscription.close(); log.close() } + } + + private fun event(thread: String, request: String = "turn") = SessionEventAppend( + sessionId = thread, runId = "run", requestId = request, + type = SessionEventType.RUN_STARTED, payload = SessionEventPayload.RunLifecycle(status = "RUNNING", scene = "scene"), + ) +} From c285c7986617759313bfbe977d9d81b4842e7d89 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:38:00 -0800 Subject: [PATCH 16/40] feat(api): provide structured notice presentation values Co-Authored-By: Codex --- CHANGELOG.md | 3 ++ agent-api/api/agent-api.api | 35 ++++++++++++++++--- .../kotlin/cc/noharry/agent/NoticeDetails.kt | 22 ++++++++++++ .../kotlin/cc/noharry/agent/ThreadItem.kt | 1 + .../runtime/thread/NoticeDetailsCodec.kt | 26 ++++++++++++++ .../runtime/thread/ThreadEventProjection.kt | 14 +++++--- .../agent/runtime/thread/ThreadItemCodec.kt | 3 +- .../runtime/ThreadEventProjectionTest.kt | 22 ++++++++++++ 8 files changed, 116 insertions(+), 10 deletions(-) create mode 100644 agent-api/src/main/kotlin/cc/noharry/agent/NoticeDetails.kt create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/NoticeDetailsCodec.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index fb65550..a0ecb17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ called out; a patch release does not break it. implementation for custom backends. Built-in logs delete events, attachments, health and cached identities; asynchronous logs drain accepted writes first and reset subscribers before a thread can be recreated. +- **Notices include structured presentation values.** `Notice.details` carries retry ordinals/delays, remaining + budgets, compaction counts and workspace ids. Hosts can localize notices without parsing the English message. + - **Damaged history does not block unrelated conversations.** Thread listing skips unreadable or unsupported metadata. Invalid provider history is renamed to a `.corrupt` file and the conversation resumes with empty model history. Deleting a conversation does not parse that history first. diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index 9dbda81..fa6d588 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -165,6 +165,31 @@ public final class cc/noharry/agent/NetworkActivity { public fun toString ()Ljava/lang/String; } +public final class cc/noharry/agent/NoticeDetails { + public fun ()V + public fun (Ljava/lang/Integer;Ljava/lang/Long;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;)V + public synthetic fun (Ljava/lang/Integer;Ljava/lang/Long;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Ljava/lang/Integer; + public final fun component2 ()Ljava/lang/Long; + public final fun component3 ()Ljava/lang/Integer; + public final fun component4 ()Ljava/lang/Integer; + public final fun component5 ()Ljava/lang/Integer; + public final fun component6 ()Ljava/lang/Integer; + public final fun component7 ()Ljava/lang/String; + public final fun copy (Ljava/lang/Integer;Ljava/lang/Long;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;)Lcc/noharry/agent/NoticeDetails; + public static synthetic fun copy$default (Lcc/noharry/agent/NoticeDetails;Ljava/lang/Integer;Ljava/lang/Long;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/NoticeDetails; + public fun equals (Ljava/lang/Object;)Z + public final fun getAfterMessageCount ()Ljava/lang/Integer; + public final fun getAttempt ()Ljava/lang/Integer; + public final fun getBeforeMessageCount ()Ljava/lang/Integer; + public final fun getDelayMillis ()Ljava/lang/Long; + public final fun getRoundsRemaining ()Ljava/lang/Integer; + public final fun getToolCallsRemaining ()Ljava/lang/Integer; + public final fun getWorkspaceId ()Ljava/lang/String; + public fun hashCode ()I + public fun toString ()Ljava/lang/String; +} + public final class cc/noharry/agent/NoticeKind : java/lang/Enum { public static final field BUDGET_LOW Lcc/noharry/agent/NoticeKind; public static final field COMPACTION Lcc/noharry/agent/NoticeKind; @@ -441,16 +466,18 @@ public final class cc/noharry/agent/ThreadItem$FileChange : cc/noharry/agent/Thr } public final class cc/noharry/agent/ThreadItem$Notice : cc/noharry/agent/ThreadItem { - public fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/NoticeKind;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/NoticeKind;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/NoticeKind;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NoticeDetails;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/NoticeKind;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NoticeDetails;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun component1 ()Ljava/lang/String; public final fun component2 ()Ljava/lang/String; public final fun component3 ()Lcc/noharry/agent/NoticeKind; public final fun component4 ()Ljava/lang/String; public final fun component5 ()Lcc/noharry/agent/ItemStatus; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/NoticeKind;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;)Lcc/noharry/agent/ThreadItem$Notice; - public static synthetic fun copy$default (Lcc/noharry/agent/ThreadItem$Notice;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/NoticeKind;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;ILjava/lang/Object;)Lcc/noharry/agent/ThreadItem$Notice; + public final fun component6 ()Lcc/noharry/agent/NoticeDetails; + public final fun copy (Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/NoticeKind;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NoticeDetails;)Lcc/noharry/agent/ThreadItem$Notice; + public static synthetic fun copy$default (Lcc/noharry/agent/ThreadItem$Notice;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/NoticeKind;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NoticeDetails;ILjava/lang/Object;)Lcc/noharry/agent/ThreadItem$Notice; public fun equals (Ljava/lang/Object;)Z + public final fun getDetails ()Lcc/noharry/agent/NoticeDetails; public fun getId ()Ljava/lang/String; public final fun getKind ()Lcc/noharry/agent/NoticeKind; public final fun getMessage ()Ljava/lang/String; diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/NoticeDetails.kt b/agent-api/src/main/kotlin/cc/noharry/agent/NoticeDetails.kt new file mode 100644 index 0000000..a8423a6 --- /dev/null +++ b/agent-api/src/main/kotlin/cc/noharry/agent/NoticeDetails.kt @@ -0,0 +1,22 @@ +package cc.noharry.agent + +/** + * Structured notice values for host presentation. Hosts can localize [ThreadItem.Notice] without parsing its + * English fallback message. Fields unrelated to the notice's [NoticeKind] are null. + */ +data class NoticeDetails( + /** Retry ordinal, starting at one, for [NoticeKind.RETRY]. */ + val attempt: Int? = null, + /** Backoff in milliseconds for [NoticeKind.RETRY]. */ + val delayMillis: Long? = null, + /** Remaining model rounds for [NoticeKind.BUDGET_LOW]. */ + val roundsRemaining: Int? = null, + /** Remaining tool calls for [NoticeKind.BUDGET_LOW]. */ + val toolCallsRemaining: Int? = null, + /** Provider-history message count before [NoticeKind.COMPACTION]. */ + val beforeMessageCount: Int? = null, + /** Provider-history message count after [NoticeKind.COMPACTION]. */ + val afterMessageCount: Int? = null, + /** Selected workspace identifier for [NoticeKind.WORKSPACE_CHANGED]. */ + val workspaceId: String? = null, +) diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt b/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt index 5ac0550..01e0786 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt @@ -76,6 +76,7 @@ sealed interface ThreadItem { val kind: NoticeKind, val message: String, override val status: ItemStatus = ItemStatus.COMPLETED, + val details: NoticeDetails = NoticeDetails(), ) : ThreadItem data class Error( diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/NoticeDetailsCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/NoticeDetailsCodec.kt new file mode 100644 index 0000000..164fdc4 --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/NoticeDetailsCodec.kt @@ -0,0 +1,26 @@ +package cc.noharry.agent.runtime.thread + +import cc.noharry.agent.NoticeDetails +import kotlinx.serialization.json.JsonObject +import kotlinx.serialization.json.buildJsonObject +import kotlinx.serialization.json.put + +internal fun NoticeDetails.toJson(): JsonObject = buildJsonObject { + attempt?.let { put("attempt", it) } + delayMillis?.let { put("delayMillis", it) } + roundsRemaining?.let { put("roundsRemaining", it) } + toolCallsRemaining?.let { put("toolCallsRemaining", it) } + beforeMessageCount?.let { put("beforeMessageCount", it) } + afterMessageCount?.let { put("afterMessageCount", it) } + workspaceId?.let { put("workspaceId", it) } +} + +internal fun JsonObject?.noticeDetails(): NoticeDetails = NoticeDetails( + attempt = this?.optionalLong("attempt")?.toInt(), + delayMillis = this?.optionalLong("delayMillis"), + roundsRemaining = this?.optionalLong("roundsRemaining")?.toInt(), + toolCallsRemaining = this?.optionalLong("toolCallsRemaining")?.toInt(), + beforeMessageCount = this?.optionalLong("beforeMessageCount")?.toInt(), + afterMessageCount = this?.optionalLong("afterMessageCount")?.toInt(), + workspaceId = this?.optionalText("workspaceId"), +) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt index 63e85b6..7776834 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt @@ -55,10 +55,13 @@ internal class ThreadEventProjection( is AgentEvent.ExecOutputDelta -> tools.output(event.text) is AgentEvent.SearchActivity -> instant(ThreadItem.WebSearch(nextId(), turnId, event.provider, event.queryPreview, event.resultCount)) is AgentEvent.WorkspaceFileChanged -> instant(ThreadItem.FileChange(nextId(), turnId, event.path, event.addedLines, event.removedLines, event.toolName)) - is AgentEvent.WorkspaceChanged -> notice(NoticeKind.WORKSPACE_CHANGED, event.workspaceId) - is AgentEvent.RetryAttempted -> notice(NoticeKind.RETRY, "Retry ${event.attempt} in ${event.delayMillis} ms") - is AgentEvent.BudgetWarning -> notice(NoticeKind.BUDGET_LOW, "${event.roundsRemaining} rounds, ${event.toolCallsRemaining} tool calls remaining") - is AgentEvent.CompactionApplied -> notice(NoticeKind.COMPACTION, "History compacted from ${event.beforeMessageCount} to ${event.afterMessageCount} messages") + is AgentEvent.WorkspaceChanged -> notice(NoticeKind.WORKSPACE_CHANGED, event.workspaceId, NoticeDetails(workspaceId = event.workspaceId)) + is AgentEvent.RetryAttempted -> notice(NoticeKind.RETRY, "Retry ${event.attempt} in ${event.delayMillis} ms", + NoticeDetails(attempt = event.attempt, delayMillis = event.delayMillis)) + is AgentEvent.BudgetWarning -> notice(NoticeKind.BUDGET_LOW, "${event.roundsRemaining} rounds, ${event.toolCallsRemaining} tool calls remaining", + NoticeDetails(roundsRemaining = event.roundsRemaining, toolCallsRemaining = event.toolCallsRemaining)) + is AgentEvent.CompactionApplied -> notice(NoticeKind.COMPACTION, "History compacted from ${event.beforeMessageCount} to ${event.afterMessageCount} messages", + NoticeDetails(beforeMessageCount = event.beforeMessageCount, afterMessageCount = event.afterMessageCount)) is AgentEvent.UserInteraction -> interaction(event.interaction) is AgentEvent.SteeringAccepted -> Unit // The full canonical INPUT fact carries the message. is AgentEvent.ConfirmationRequired -> { finishText(); start(approval(event.pending)) } @@ -233,7 +236,8 @@ internal class ThreadEventProjection( } private suspend fun instant(item: ThreadItem) { start(item); complete(item) } - private suspend fun notice(kind: NoticeKind, message: String) = instant(ThreadItem.Notice(nextId(), turnId, kind, message)) + private suspend fun notice(kind: NoticeKind, message: String, details: NoticeDetails) = + instant(ThreadItem.Notice(nextId(), turnId, kind, message, details = details)) } private fun total(a: Int, b: Int): Int = (a.toLong() + b.coerceAtLeast(0)).coerceAtMost(Int.MAX_VALUE.toLong()).toInt() diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt index e472cde..0373525 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt @@ -43,6 +43,7 @@ internal class ThreadItemCodec( } is ThreadItem.Notice -> { put("kind", "notice"); put("noticeKind", item.kind.name); put("message", redact(item.message)) + put("details", item.details.toJson()) } is ThreadItem.Error -> { put("kind", "error"); put("code", item.code); put("message", redact(item.message)) @@ -64,7 +65,7 @@ internal class ThreadItemCodec( "tool" -> tool(value, id, turn, status) "search" -> ThreadItem.WebSearch(id, turn, value.text("provider"), value.text("query"), value.optionalLong("resultCount")?.toInt(), status) "file" -> ThreadItem.FileChange(id, turn, value.text("path"), value.number("added"), value.number("removed"), value.text("tool"), status) - "notice" -> ThreadItem.Notice(id, turn, value.enum("noticeKind", NoticeKind.WORKSPACE_CHANGED), value.text("message"), status) + "notice" -> ThreadItem.Notice(id, turn, value.enum("noticeKind", NoticeKind.WORKSPACE_CHANGED), value.text("message"), status, value.obj("details").noticeDetails()) "error" -> ThreadItem.Error(id, turn, value.text("code"), value.text("message"), value.flag("recoverable"), status) "question" -> Question(id, turn, value.text("text"), value.array("choices").map { (it as JsonPrimitive).content }, value.flag("async"), value.optionalLong("expiresAt"), status) "approval" -> StoredApproval(id, turn, value.text("tool"), value.text("arguments"), value.text("domain"), value.text("reason"), value.optionalLong("expiresAt"), status, value.enum("state", ApprovalState.CANCELLED)) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadEventProjectionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadEventProjectionTest.kt index 13f7745..561a58a 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadEventProjectionTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadEventProjectionTest.kt @@ -17,6 +17,28 @@ import org.junit.Assert.* import org.junit.Test class ThreadEventProjectionTest { + @Test fun noticesCarryLocalizableValuesThroughStorage() = runBlocking { + val events = project( + AgentEvent.RetryAttempted("execution", 2, 750), + AgentEvent.BudgetWarning("execution", 3, 5), + AgentEvent.CompactionApplied("execution", 48, 12, 36, 200), + AgentEvent.WorkspaceChanged("execution", "workspace-main"), + AgentEvent.ResultAvailable(RuntimeResult("execution", RuntimeRunStatus.COMPLETED, "Done")), + ) + lifecycle(events) + val notices = (events.last() as ThreadEvent.TurnCompleted).result.items.filterIsInstance() + assertEquals(listOf( + NoticeDetails(attempt = 2, delayMillis = 750), + NoticeDetails(roundsRemaining = 3, toolCallsRemaining = 5), + NoticeDetails(beforeMessageCount = 48, afterMessageCount = 12), + NoticeDetails(workspaceId = "workspace-main"), + ), notices.map { it.details }) + val codec = cc.noharry.agent.runtime.thread.ThreadItemCodec(DefaultTraceRedactor) + notices.forEach { assertEquals(it, codec.decode(codec.encode(it))) } + val old = kotlinx.serialization.json.JsonObject(codec.encode(notices.first()) - "details") + assertEquals(NoticeDetails(), (codec.decode(old) as ThreadItem.Notice).details) + } + @Test fun completeSnapshotsAndUsageSurviveIgnoredDeltas() = runBlocking { val events = project( AgentEvent.Started("run"), AgentEvent.ThinkingDelta("run", "Think"), From b568513fdeebc20a229a69d3b46a4fdd8e9383d7 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:38:18 -0800 Subject: [PATCH 17/40] feat(storage): delete SQLite and reliability session artifacts Co-Authored-By: Codex --- CHANGELOG.md | 4 + .../android/AndroidSqliteSessionStore.kt | 15 ++++ .../android/AndroidSqliteSessionStoreTest.kt | 27 +++++++ .../kernel/core/state/LoopHistoryStore.kt | 9 +++ .../kernel/core/state/ReliabilityStorage.kt | 3 + .../core/state/ReliabilityStorageFiles.kt | 1 + .../agent/kernel/core/state/SessionStore.kt | 3 + .../FileBackedReliabilityStorage.kt | 24 ++++++ .../SessionArtifactDeletionTest.kt | 73 +++++++++++++++++++ 9 files changed, 159 insertions(+) create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/reliability/SessionArtifactDeletionTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index a0ecb17..17f4168 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ called out; a patch release does not break it. `CONFIRMATION_DENIED` tool result to the model without executing the tool, so it can explain the outcome. Cancelling or interrupting a pending approval records `CONFIRMATION_CANCELLED` in provider history. +- **Session storage backends support complete deletion.** SQLite removes the session's seven conversation tables + in one transaction while preserving the shared memory index. Reliability storage removes run directories and + shared evidence, and loop history can be deleted from disk and memory. + - **Event logs can delete complete conversations.** `SessionEventLog.deleteThread` has an unsupported-by-default implementation for custom backends. Built-in logs delete events, attachments, health and cached identities; asynchronous logs drain accepted writes first and reset subscribers before a thread can be recreated. diff --git a/agent-runtime-android/src/main/kotlin/cc/noharry/agent/runtime/android/AndroidSqliteSessionStore.kt b/agent-runtime-android/src/main/kotlin/cc/noharry/agent/runtime/android/AndroidSqliteSessionStore.kt index 397d6cf..dd5ef8b 100644 --- a/agent-runtime-android/src/main/kotlin/cc/noharry/agent/runtime/android/AndroidSqliteSessionStore.kt +++ b/agent-runtime-android/src/main/kotlin/cc/noharry/agent/runtime/android/AndroidSqliteSessionStore.kt @@ -33,6 +33,21 @@ internal class AndroidSqliteSessionStore( if (databaseHolder.isInitialized()) database.close() } + override fun deleteThread(threadId: String): Boolean = locked { + require(threadId.isNotBlank()) { "threadId must not be blank" } + database.beginTransaction() + try { + val ownedRuns = "SELECT $COL_RUN_ID FROM $TABLE_RUNS WHERE $COL_SESSION_ID=?" + listOf(TABLE_MESSAGES, TABLE_TOOL_EVENTS, TABLE_USAGE, TABLE_VFS_OPS, TABLE_MODEL_CALLS).forEach { table -> + database.delete(table, "$COL_SESSION_ID=? OR $COL_RUN_ID IN ($ownedRuns)", arrayOf(threadId, threadId)) + } + database.delete(TABLE_RUNS, "$COL_SESSION_ID=?", arrayOf(threadId)) + database.delete(TABLE_SESSIONS, "$COL_SESSION_ID=?", arrayOf(threadId)) + database.setTransactionSuccessful() + true + } finally { database.endTransaction() } + } + override fun upsertSession(session: StoredSession) { locked { val values = ContentValues().apply { diff --git a/agent-runtime-android/src/test/kotlin/cc/noharry/agent/runtime/android/AndroidSqliteSessionStoreTest.kt b/agent-runtime-android/src/test/kotlin/cc/noharry/agent/runtime/android/AndroidSqliteSessionStoreTest.kt index 8c55548..20b4464 100644 --- a/agent-runtime-android/src/test/kotlin/cc/noharry/agent/runtime/android/AndroidSqliteSessionStoreTest.kt +++ b/agent-runtime-android/src/test/kotlin/cc/noharry/agent/runtime/android/AndroidSqliteSessionStoreTest.kt @@ -27,6 +27,33 @@ class AndroidSqliteSessionStoreTest { @get:Rule val temp = TemporaryFolder() + @Test + fun deletionRemovesSevenSessionTablesButKeepsOtherSessionsAndSharedMemory() { + val file = temp.newFile("delete-session.sqlite") + val store = AndroidSqliteSessionStore(file) + try { + store.persistSampleEvidence() + store.upsertSession(StoredSession("kept", "Kept", createdAtEpochMillis = 1, updatedAtEpochMillis = 1)) + store.upsertRun(storedRun().copy(runId = "kept-run", sessionId = "kept")) + store.recordToolFinished(StoredToolResult("late", "run-1", "COMPLETED", 9, "{}", "hash", true)) + SQLiteDatabase.openDatabase(file.path, null, SQLiteDatabase.OPEN_READWRITE).use { db -> + db.execSQL("INSERT INTO memory_index(memory_id,summary,updated_at) VALUES('shared','Remember',1)") + } + assertTrue(store.deleteThread("session-1")) + assertTrue(store.deleteThread("session-1")) + assertEquals(listOf("kept"), store.listSessions().map { it.sessionId }) + assertTrue(store.transcript("session-1").messages.isEmpty()) + assertTrue(store.toolEvents("run-1").isEmpty()) + assertEquals(0, store.usage("session-1").totalTokens) + assertTrue(store.vfsOperations("run-1").isEmpty()) + assertTrue(store.modelCalls("run-1").isEmpty()) + SQLiteDatabase.openDatabase(file.path, null, SQLiteDatabase.OPEN_READONLY).use { db -> + db.rawQuery("SELECT COUNT(*) FROM memory_index", null).use { it.moveToFirst(); assertEquals(1, it.getInt(0)) } + db.rawQuery("SELECT COUNT(*) FROM runs WHERE session_id='session-1'", null).use { it.moveToFirst(); assertEquals(0, it.getInt(0)) } + } + } finally { store.close() } + } + @Test fun persistsTranscriptToolVfsAndUsageEvidence() { val databaseFile = temp.newFile("runtime-session-store.sqlite") diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/LoopHistoryStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/LoopHistoryStore.kt index 0599089..10eae82 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/LoopHistoryStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/LoopHistoryStore.kt @@ -37,6 +37,8 @@ internal interface LoopHistoryStore { fun read(runId: String): LoopHistory? fun clearCached(runId: String) + + fun delete(runId: String) } /** @@ -62,6 +64,8 @@ internal class InMemoryLoopHistoryStore(private val budgetBytes: Int = MAX_LOOP_ override fun clearCached(runId: String) { histories.remove(runId) } + + override fun delete(runId: String) = clearCached(runId) } internal class FileBackedLoopHistoryStore(private val root: File, budgetBytes: Int = MAX_LOOP_HISTORY_BYTES) : LoopHistoryStore { @@ -85,6 +89,11 @@ internal class FileBackedLoopHistoryStore(private val root: File, budgetBytes: I memory.clearCached(runId) } + override fun delete(runId: String) { + historyFile(runId).let { check(!it.exists() || it.delete()) { "Cannot delete loop history" } } + memory.delete(runId) + } + private fun historyFile(runId: String): File = File(File(root, RUNS_DIR), encodeFileName(runId)).resolve(LOOP_HISTORY_FILE) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/ReliabilityStorage.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/ReliabilityStorage.kt index 6f1c855..0de4634 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/ReliabilityStorage.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/ReliabilityStorage.kt @@ -10,6 +10,9 @@ import cc.noharry.agent.spi.reliability.RuntimeTraceEvent import cc.noharry.agent.spi.reliability.RuntimeWorkpad internal interface ReliabilityStorage { + /** Deletes all persisted artifacts for the session, including supplied ids whose run metadata may be damaged. */ + fun deleteSession(sessionId: String, knownRunIds: Set = emptySet()): Set + fun saveRun(snapshot: RuntimeRunSnapshot, envelope: RuntimeRunEnvelope) fun readSnapshot(runId: String): RuntimeRunSnapshot? diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/ReliabilityStorageFiles.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/ReliabilityStorageFiles.kt index 66e7d4e..bcfb3ad 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/ReliabilityStorageFiles.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/ReliabilityStorageFiles.kt @@ -121,6 +121,7 @@ internal fun File.deleteTreeWith( fileDeleter: ReliabilityFileDeleter = DefaultReliabilityFileDeleter, directoryLister: ReliabilityDirectoryLister = DefaultReliabilityDirectoryLister, ): Boolean { + if (java.nio.file.Files.isSymbolicLink(toPath())) return try { fileDeleter.delete(this) } catch (_: Exception) { false } if (!exists()) return true if (isDirectory) { val children = try { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/SessionStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/SessionStore.kt index fb5e4bc..7fc12a9 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/SessionStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/SessionStore.kt @@ -4,6 +4,9 @@ import cc.noharry.agent.spi.InternalAgentRuntimeApi /** @suppress */ @InternalAgentRuntimeApi interface SessionStore { + /** Deletes session-owned rows only. False means this store does not support complete deletion. */ + fun deleteThread(threadId: String): Boolean = false + fun upsertSession(session: StoredSession) fun upsertRun(run: StoredRun) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/reliability/FileBackedReliabilityStorage.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/reliability/FileBackedReliabilityStorage.kt index d503013..b0cf23e 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/reliability/FileBackedReliabilityStorage.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/reliability/FileBackedReliabilityStorage.kt @@ -68,6 +68,30 @@ internal class FileBackedReliabilityStorage( } } + override fun deleteSession(sessionId: String, knownRunIds: Set): Set = storageLock.withLock { + require(sessionId.isNotBlank()) { "sessionId must not be blank" } + val records = sessionRunsForDeletion(sessionId, knownRunIds) + val failures = mutableListOf() + records.forEach { record -> check(deleteRunRecord(record, failures)) { "Cannot delete session run artifacts: $failures" } } + // Known ids may have lost their run directory while shared evidence still exists. + val removed = records.mapTo(linkedSetOf()) { it.runId } + knownRunIds + removed.forEach { check(deleteSharedRecordsForRun(it).isEmpty()) { "Cannot delete shared session evidence" } } + removed + } + + private fun sessionRunsForDeletion(sessionId: String, knownRunIds: Set): List { + val directory = runsDir() + if (!directory.exists()) return emptyList() + val children = checkNotNull(directoryLister.listFiles(directory)) { "Cannot list session run artifacts" } + val known = knownRunIds.associateBy(::encodeFileName) + return children.filter(File::isDirectory).mapNotNull { child -> + known[child.name]?.let { return@mapNotNull storedRunRecord(child).copy(runId = it) } + val snapshot = File(child, RUN_FILE).decodeOrNull(ReliabilityJsonCodecs::decodeSnapshot) + checkNotNull(snapshot) { "Cannot determine ownership of run artifacts: ${child.name}" } + if (snapshot.sessionId == sessionId) storedRunRecord(child) else null + } + } + override fun readSnapshot(runId: String): RuntimeRunSnapshot? = storageLock.withReadLock { runFile(runId, RUN_FILE).decodeOrNull(ReliabilityJsonCodecs::decodeSnapshot) } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/reliability/SessionArtifactDeletionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/reliability/SessionArtifactDeletionTest.kt new file mode 100644 index 0000000..48de48e --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/reliability/SessionArtifactDeletionTest.kt @@ -0,0 +1,73 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime.reliability + +import cc.noharry.agent.kernel.core.state.* +import cc.noharry.agent.spi.model.ModelMessage +import cc.noharry.agent.spi.reliability.* +import java.io.File +import java.nio.file.Files +import org.junit.Assert.* +import org.junit.Test + +class SessionArtifactDeletionTest { + @Test fun sessionDeletionRemovesRunsEvidenceAndLoopFilesWithoutTouchingOtherSessions() { + val root = Files.createTempDirectory("delete-artifacts-").toFile() + val storage = FileBackedReliabilityStorage(root) + val history = FileBackedLoopHistoryStore(root) + saveRun(storage, "removed", "one") + saveRun(storage, "removed", "two") + saveRun(storage, "kept", "three") + history.save("one", listOf(ModelMessage("user", "private history"))) + assertEquals(setOf("one", "two"), storage.deleteSession("removed")) + assertTrue(storage.deleteSession("removed").isEmpty()) + assertNull(storage.readSnapshot("one")) + assertNull(storage.readEvidence("evidence-one")) + assertTrue(File(root, "runs").listFiles().orEmpty().none { it.name == encodeFileName("one") }) + assertNotNull(storage.readSnapshot("three")) + assertNotNull(storage.readEvidence("evidence-three")) + history.delete("one") + assertNull(history.read("one")) + } + + @Test fun aKnownRunCanBeDeletedWhenItsMetadataIsDamaged() { + val root = Files.createTempDirectory("delete-damaged-run-").toFile() + val storage = FileBackedReliabilityStorage(root) + saveRun(storage, "removed", "one") + File(root, "runs/${encodeFileName("one")}/run.json").writeText("{invalid") + assertEquals(setOf("one"), storage.deleteSession("removed", setOf("one"))) + assertNull(storage.readEvidence("evidence-one")) + } + + @Test fun failedDeletesAreReportedAndCanBeRetried() { + val root = Files.createTempDirectory("delete-failing-run-").toFile() + val storage = FileBackedReliabilityStorage(root) + saveRun(storage, "removed", "one") + val failing = FileBackedReliabilityStorage(root, fileDeleter = ReliabilityFileDeleter { false }) + assertThrows(IllegalStateException::class.java) { failing.deleteSession("removed") } + assertNotNull(storage.readSnapshot("one")) + assertEquals(setOf("one"), storage.deleteSession("removed")) + } + + @Test fun loopHistoryDeletionClearsDiskAndMemoryAndNeverFollowsNestedLinks() { + val root = Files.createTempDirectory("delete-loop-history-").toFile() + val store = FileBackedLoopHistoryStore(root) + store.save("one", listOf(ModelMessage("user", "private history"))) + store.delete("one") + store.delete("one") + assertNull(store.read("one")) + assertNull(FileBackedLoopHistoryStore(root).read("one")) + val outside = Files.createTempDirectory("retained-workspace-").toFile() + val retained = File(outside, "keep.txt").apply { writeText("keep") } + val directory = File(root, "with-link").apply { mkdirs() } + Files.createSymbolicLink(File(directory, "workspace").toPath(), outside.toPath()) + assertTrue(directory.deleteTreeWith()) + assertEquals("keep", retained.readText()) + } + + private fun saveRun(storage: FileBackedReliabilityStorage, session: String, run: String) { + storage.saveRun(RuntimeRunSnapshot(run, session, RuntimeRunStatus.COMPLETED, 1), + RuntimeRunEnvelope(run, run, session, RuntimeRunStatus.COMPLETED, RuntimeRunPhase.TERMINAL, 1, 1)) + storage.saveEvidence(RuntimeEvidence("evidence-$run", run, RuntimeEvidenceType.RESULT_WRITTEN, "private evidence", 1)) + } +} From 52d7ab4a2fa420996ce68d3508dfd37f56b84da8 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:41:24 -0800 Subject: [PATCH 18/40] fix(runtime): scope remembered approvals and record their source Co-Authored-By: Codex --- CHANGELOG.md | 5 + agent-api/api/agent-api.api | 21 ++-- .../kotlin/cc/noharry/agent/ThreadItem.kt | 5 +- .../agent/runtime/NetworkToolBackend.kt | 55 ++++++----- .../runtime/thread/DefaultAgentThread.kt | 9 +- .../agent/runtime/thread/ThreadApproval.kt | 21 ++-- .../runtime/thread/ThreadEventProjection.kt | 2 +- .../agent/runtime/thread/ThreadItemCodec.kt | 9 +- .../runtime/thread/ThreadToolProjection.kt | 8 +- .../agent/runtime/ThreadApprovalPolicyTest.kt | 98 +++++++++++++++++++ .../agent/runtime/ThreadConcurrencyTest.kt | 3 +- .../agent/runtime/ThreadPersistenceTest.kt | 3 +- 12 files changed, 183 insertions(+), 56 deletions(-) create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalPolicyTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 17f4168..c3f8bbc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,11 @@ called out; a patch release does not break it. - **Notices include structured presentation values.** `Notice.details` carries retry ordinals/delays, remaining budgets, compaction counts and workspace ids. Hosts can localize notices without parsing the English message. +- **Approval areas and sources are precise.** Remembered network approvals use the network backend's canonical + host parser; invalid targets are never remembered. MCP approvals cover one tool, with separate namespaces for + web, MCP and other tools. `ToolCall.approvedBy` now uses `ApprovalSource.USER`, `REMEMBERED` or `AUTOMATIC`; + a denied call has no approval source. Older snapshots with an ambiguous REMEMBER policy leave the source unset. + - **Damaged history does not block unrelated conversations.** Thread listing skips unreadable or unsupported metadata. Invalid provider history is renamed to a `.corrupt` file and the conversation resumes with empty model history. Deleting a conversation does not parse that history first. diff --git a/agent-api/api/agent-api.api b/agent-api/api/agent-api.api index fa6d588..9639dba 100644 --- a/agent-api/api/agent-api.api +++ b/agent-api/api/agent-api.api @@ -81,6 +81,15 @@ public final class cc/noharry/agent/ApprovalScope : java/lang/Enum { public static fun values ()[Lcc/noharry/agent/ApprovalScope; } +public final class cc/noharry/agent/ApprovalSource : java/lang/Enum { + public static final field AUTOMATIC Lcc/noharry/agent/ApprovalSource; + public static final field REMEMBERED Lcc/noharry/agent/ApprovalSource; + public static final field USER Lcc/noharry/agent/ApprovalSource; + public static fun getEntries ()Lkotlin/enums/EnumEntries; + public static fun valueOf (Ljava/lang/String;)Lcc/noharry/agent/ApprovalSource; + public static fun values ()[Lcc/noharry/agent/ApprovalSource; +} + public final class cc/noharry/agent/ApprovalState : java/lang/Enum { public static final field APPROVED Lcc/noharry/agent/ApprovalState; public static final field CANCELLED Lcc/noharry/agent/ApprovalState; @@ -506,10 +515,10 @@ public final class cc/noharry/agent/ThreadItem$Reasoning : cc/noharry/agent/Thre } public final class cc/noharry/agent/ThreadItem$ToolCall : cc/noharry/agent/ThreadItem { - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/ToolSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NetworkActivity;Lcc/noharry/agent/ApprovalPolicy;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/ToolSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NetworkActivity;Lcc/noharry/agent/ApprovalPolicy;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/ToolSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NetworkActivity;Lcc/noharry/agent/ApprovalSource;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/ToolSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NetworkActivity;Lcc/noharry/agent/ApprovalSource;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun component1 ()Ljava/lang/String; - public final fun component10 ()Lcc/noharry/agent/ApprovalPolicy; + public final fun component10 ()Lcc/noharry/agent/ApprovalSource; public final fun component2 ()Ljava/lang/String; public final fun component3 ()Ljava/lang/String; public final fun component4 ()Lcc/noharry/agent/spi/ToolSource; @@ -518,10 +527,10 @@ public final class cc/noharry/agent/ThreadItem$ToolCall : cc/noharry/agent/Threa public final fun component7 ()Ljava/lang/String; public final fun component8 ()Lcc/noharry/agent/ItemStatus; public final fun component9 ()Lcc/noharry/agent/NetworkActivity; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/ToolSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NetworkActivity;Lcc/noharry/agent/ApprovalPolicy;)Lcc/noharry/agent/ThreadItem$ToolCall; - public static synthetic fun copy$default (Lcc/noharry/agent/ThreadItem$ToolCall;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/ToolSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NetworkActivity;Lcc/noharry/agent/ApprovalPolicy;ILjava/lang/Object;)Lcc/noharry/agent/ThreadItem$ToolCall; + public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/ToolSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NetworkActivity;Lcc/noharry/agent/ApprovalSource;)Lcc/noharry/agent/ThreadItem$ToolCall; + public static synthetic fun copy$default (Lcc/noharry/agent/ThreadItem$ToolCall;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/spi/ToolSource;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcc/noharry/agent/ItemStatus;Lcc/noharry/agent/NetworkActivity;Lcc/noharry/agent/ApprovalSource;ILjava/lang/Object;)Lcc/noharry/agent/ThreadItem$ToolCall; public fun equals (Ljava/lang/Object;)Z - public final fun getApprovedBy ()Lcc/noharry/agent/ApprovalPolicy; + public final fun getApprovedBy ()Lcc/noharry/agent/ApprovalSource; public final fun getArguments ()Ljava/lang/String; public fun getId ()Ljava/lang/String; public final fun getNetwork ()Lcc/noharry/agent/NetworkActivity; diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt b/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt index 01e0786..53d71f9 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/ThreadItem.kt @@ -48,7 +48,8 @@ sealed interface ThreadItem { val output: String? = null, override val status: ItemStatus = ItemStatus.IN_PROGRESS, val network: NetworkActivity? = null, - val approvedBy: ApprovalPolicy? = null, + /** How this call was approved; null when no approval was granted or no gate was needed. */ + val approvedBy: ApprovalSource? = null, ) : ThreadItem data class WebSearch( @@ -92,6 +93,8 @@ sealed interface ThreadItem { enum class ItemStatus { IN_PROGRESS, COMPLETED, FAILED, DECLINED } enum class MessagePhase { COMMENTARY, FINAL } +/** The origin of a granted approval, independent of the thread's current approval policy. */ +enum class ApprovalSource { USER, REMEMBERED, AUTOMATIC } enum class NoticeKind { RETRY, COMPACTION, BUDGET_LOW, WORKSPACE_CHANGED } /** Metadata about a network tool; payloads remain on the tool item. */ diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt index 8677318..853828a 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt @@ -224,35 +224,40 @@ internal class NetworkToolBackend( }.toString() } - private fun parseFetchTarget(argumentsJson: String): FetchTarget { - val arguments = parseObject(argumentsJson) - ?: return FetchTarget(errorResult = errorResult(RuntimeErrorCode.NETWORK_URL_INVALID.wireCode, "web_fetch arguments must be a JSON object.")) - val url = arguments.stringField("url")?.trim().orEmpty() - val maxBytes = arguments.intField("max_bytes") ?: DEFAULT_WEB_FETCH_MAX_BYTES - if (maxBytes <= 0 || maxBytes > MAX_WEB_FETCH_BYTES) { - return FetchTarget(errorResult = errorResult(RuntimeErrorCode.READ_BUDGET_EXCEEDED.wireCode, "max_bytes out of range.")) - } - val normalizedUrl = normalizedUrl(url) - ?: return FetchTarget(errorResult = errorResult(RuntimeErrorCode.NETWORK_URL_INVALID.wireCode, "URL must be absolute http or https.")) - val host = normalizedUrl.host - if (host.isDeniedLiteralHost()) { - return FetchTarget(host = host, errorResult = privateAddressDeniedResult()) - } - return FetchTarget(url = normalizedUrl, host = host, maxBytes = maxBytes) - } - - private fun normalizedUrl(url: String): HttpUrl? { - val parsed = url.toHttpUrlOrNull() ?: return null - if (parsed.username.isNotEmpty() || parsed.password.isNotEmpty()) return null - val canonicalHost = parsed.host.trimEnd('.') - if (canonicalHost.isBlank()) return null - return parsed.newBuilder().host(canonicalHost).fragment(null).build() - } - private fun normalizedRedirect(base: HttpUrl, location: String): HttpUrl? = base.resolve(location)?.let { normalizedUrl(it.toString()) } } +/** The same normalized, validated host used by web_fetch authorization and execution. */ +internal fun webFetchApprovalHost(argumentsJson: String): String? = + runCatching { parseFetchTarget(argumentsJson).takeIf { it.errorResult == null }?.host }.getOrNull() + +private fun parseFetchTarget(argumentsJson: String): FetchTarget { + val arguments = parseObject(argumentsJson) + ?: return FetchTarget(errorResult = errorResult(RuntimeErrorCode.NETWORK_URL_INVALID.wireCode, "web_fetch arguments must be a JSON object.")) + val url = arguments.stringField("url")?.trim().orEmpty() + val maxBytes = arguments.intField("max_bytes") ?: DEFAULT_WEB_FETCH_MAX_BYTES + if (maxBytes <= 0 || maxBytes > MAX_WEB_FETCH_BYTES) { + return FetchTarget(errorResult = errorResult(RuntimeErrorCode.READ_BUDGET_EXCEEDED.wireCode, "max_bytes out of range.")) + } + val normalizedUrl = normalizedUrl(url) + ?: return FetchTarget(errorResult = errorResult(RuntimeErrorCode.NETWORK_URL_INVALID.wireCode, "URL must be absolute http or https.")) + val host = normalizedUrl.host + if (host.isDeniedLiteralHost()) { + return FetchTarget(host = host, errorResult = privateAddressDeniedResult()) + } + return FetchTarget(url = normalizedUrl, host = host, maxBytes = maxBytes) +} + +private fun normalizedUrl(url: String): HttpUrl? { + val parsed = url.toHttpUrlOrNull() ?: return null + if (parsed.username.isNotEmpty() || parsed.password.isNotEmpty()) return null + val canonicalHost = parsed.host.trimEnd('.') + if (canonicalHost.isBlank()) return null + return parsed.newBuilder().host(canonicalHost).fragment(null).build() +} + + /** Controls whether [NetworkToolBackend] gates web_fetch per host. */ @ExperimentalAgentRuntimeApi enum class NetworkToolConfirmationPolicy { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 19d7491..db87e7e 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -211,11 +211,12 @@ internal class DefaultAgentThread( val automatic = when (policy) { ApprovalPolicy.APPROVE_ALL -> ApprovalState.APPROVED ApprovalPolicy.DENY_ALL -> ApprovalState.DENIED - ApprovalPolicy.REMEMBER -> if (domain in runtime.store.rememberedDomains(id)) ApprovalState.APPROVED else null + ApprovalPolicy.REMEMBER -> if (domain != null && domain in runtime.store.rememberedDomains(id)) ApprovalState.APPROVED else null ApprovalPolicy.ASK -> null } if (automatic != null) { - projection.toolDecision(pending.idempotencyKey, policy) + if (automatic == ApprovalState.APPROVED) projection.toolDecision(pending.idempotencyKey, + if (policy == ApprovalPolicy.REMEMBER) ApprovalSource.REMEMBERED else ApprovalSource.AUTOMATIC) return automatic } val approval = ThreadApproval(pending.copy(runId = turn.id), runtime.nowEpochMillis() + runtime.confirmationTimeoutMillis, runtime.nowEpochMillis) @@ -223,10 +224,10 @@ internal class DefaultAgentThread( try { projection.beginApproval(approval) val decision = approval.await() - if (decision == ApprovalState.APPROVED && (policy == ApprovalPolicy.REMEMBER || approval.scope == ApprovalScope.THREAD)) { + if (domain != null && decision == ApprovalState.APPROVED && (policy == ApprovalPolicy.REMEMBER || approval.scope == ApprovalScope.THREAD)) { withContext(Dispatchers.IO) { runtime.store.rememberDomain(id, domain, generation) } } - projection.toolDecision(pending.idempotencyKey, policy) + if (decision == ApprovalState.APPROVED) projection.toolDecision(pending.idempotencyKey, ApprovalSource.USER) projection.resolveApproval(approval.snapshot()) return decision } finally { approval.cancel(); turn.approval = null } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt index fbb51d2..4bc5aa8 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt @@ -4,12 +4,9 @@ package cc.noharry.agent.runtime.thread import cc.noharry.agent.* import cc.noharry.agent.spi.PendingConfirmation -import java.net.URI +import cc.noharry.agent.runtime.webFetchApprovalHost import kotlinx.coroutines.CompletableDeferred import kotlinx.coroutines.withTimeoutOrNull -import kotlinx.serialization.json.Json -import kotlinx.serialization.json.JsonObject -import kotlinx.serialization.json.JsonPrimitive /** Decision ownership is atomic; expiry and cancellation compete with responses on the same lock. */ internal class ThreadApproval( @@ -21,7 +18,7 @@ internal class ThreadApproval( override val turnId = pending.runId override val tool = pending.toolName.orEmpty() override val arguments = pending.argumentsJson ?: "{}" - override val domain = approvalDomain(tool, arguments) + override val domain = approvalDomain(tool, arguments) ?: "web_fetch:invalid" override val reason = pending.prompt private val decision = CompletableDeferred() @Volatile override var state: ApprovalState = ApprovalState.PENDING @@ -68,12 +65,12 @@ internal class ThreadApproval( } } -internal fun approvalDomain(tool: String, arguments: String): String { - if (tool.startsWith("mcp__")) return tool.removePrefix("mcp__").substringBefore("__") - if (tool == "web_fetch") { - val json = runCatching { Json.parseToJsonElement(arguments) as? JsonObject }.getOrNull() - val url = (json?.get("url") as? JsonPrimitive)?.content - runCatching { url?.let { URI(it).host } }.getOrNull()?.let { return "web_fetch:$it" } +/** Invalid network targets cannot create a remembered approval for a broader area. */ +internal fun approvalDomain(tool: String, arguments: String): String? { + if (tool.startsWith("mcp__")) { + val qualified = tool.removePrefix("mcp__") + return "mcp:${qualified.substringBefore("__")}:${qualified.substringAfter("__", "")}" } - return tool + if (tool == "web_fetch") return webFetchApprovalHost(arguments)?.let { "web_fetch:$it" } + return "tool:$tool" } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt index 7776834..de2b126 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadEventProjection.kt @@ -74,7 +74,7 @@ internal class ThreadEventProjection( suspend fun beginApproval(item: Approval) { finishText(); start(item) } - suspend fun toolDecision(callId: String, policy: ApprovalPolicy) { tools.decision(callId, policy) } + suspend fun toolDecision(callId: String, source: ApprovalSource) { tools.decision(callId, source) } suspend fun resolveApproval(item: Approval) { complete(item) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt index 0373525..613f696 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt @@ -90,7 +90,7 @@ internal class ThreadItemCodec( id, turn, value.text("tool"), value.enum("source", ToolSource.BACKEND), value.optionalText("server"), value.text("arguments"), value.optionalText("output"), status, value.obj("network")?.let { NetworkActivity(it.text("domain"), it.text("decision"), it.optionalLong("statusCode")?.toInt(), it.flag("truncated")) }, - value.optionalText("approvedBy")?.let { ApprovalPolicy.valueOf(it) }, + value.optionalText("approvedBy")?.let { approvalSource(it, status) }, ) private fun JsonObjectBuilder.question(item: Question) { @@ -128,6 +128,13 @@ internal class ThreadItemCodec( private fun redact(value: String): String = redactor.redact(value) } +/** Pre-release snapshots recorded a policy instead of a source; REMEMBER did not distinguish who approved. */ +private fun approvalSource(value: String, status: ItemStatus): ApprovalSource? = when (value) { + "ASK" -> ApprovalSource.USER.takeIf { status == ItemStatus.COMPLETED } + "APPROVE_ALL" -> ApprovalSource.AUTOMATIC + else -> ApprovalSource.entries.firstOrNull { it.name == value } +} + /** Loaded approvals describe a past decision and can never execute a tool again. */ internal data class StoredApproval( override val id: String, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt index aa506bd..c9b6342 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt @@ -18,13 +18,13 @@ internal class ThreadToolProjection( private val emit: suspend (ThreadEvent) -> Unit, ) { private val calls = linkedMapOf() - private val decisions = mutableMapOf() + private val decisions = mutableMapOf() - suspend fun decision(callId: String, policy: ApprovalPolicy) { + suspend fun decision(callId: String, source: ApprovalSource) { val current = calls[callId] - if (current == null) decisions[callId] = policy + if (current == null) decisions[callId] = source else { - val decided = current.copy(approvedBy = policy) + val decided = current.copy(approvedBy = source) calls[callId] = decided update(decided) } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalPolicyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalPolicyTest.kt new file mode 100644 index 0000000..0ba1e46 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalPolicyTest.kt @@ -0,0 +1,98 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.spi.* +import cc.noharry.agent.spi.model.ModelEvent +import cc.noharry.agent.kernel.core.tools.NetworkToolPolicyDecision +import cc.noharry.agent.runtime.thread.approvalDomain +import cc.noharry.agent.runtime.thread.ThreadItemCodec +import kotlinx.coroutines.runBlocking +import kotlinx.serialization.json.JsonObject +import kotlinx.serialization.json.JsonPrimitive +import org.junit.Assert.* +import org.junit.Test + +class ThreadApprovalPolicyTest { + @Test fun legacyAskDenialsAndExpirationsDoNotClaimUserApproval() { + val codec = ThreadItemCodec(DefaultTraceRedactor) + for (status in listOf(ItemStatus.DECLINED, ItemStatus.FAILED, ItemStatus.COMPLETED)) { + val item = ThreadItem.ToolCall("item", "turn", "tool", ToolSource.BACKEND, status = status, + approvedBy = ApprovalSource.USER) + val encoded = codec.encode(item) + val legacy = JsonObject(encoded + ("approvedBy" to JsonPrimitive("ASK"))) + val expected = ApprovalSource.USER.takeIf { status == ItemStatus.COMPLETED } + assertEquals(expected, (codec.decode(legacy) as ThreadItem.ToolCall).approvedBy) + assertEquals(ApprovalSource.USER, (codec.decode(encoded) as ThreadItem.ToolCall).approvedBy) + } + } + + @Test fun approvalSourceDescribesTheDecisionAndDenialNeverClaimsApproval() = runBlocking { + for (policy in ApprovalPolicy.entries) approvalBuilder().build().use { runtime -> + val events = mutableListOf() + runtime.startThread(ThreadOptions(approvalPolicy = policy)).runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) (event.item as Approval).approve() + } + assertTurnEvents(events) + val tool = events.filterIsInstance().map { it.item } + .filterIsInstance().single { it.tool == qualifiedMcpTool("set_temperature") } + val source = when (policy) { + ApprovalPolicy.ASK, ApprovalPolicy.REMEMBER -> ApprovalSource.USER + ApprovalPolicy.APPROVE_ALL -> ApprovalSource.AUTOMATIC + ApprovalPolicy.DENY_ALL -> null + } + assertEquals(source, tool.approvedBy) + } + } + + @Test fun rememberingOneMcpToolDoesNotApproveAnotherToolOnTheSameServer() = runBlocking { + val names = listOf("set_temperature", "set_fan") + val scripts = names.flatMapIndexed { index, name -> listOf( + listOf(schemaRead(name), ModelEvent.Completed), + listOf(ModelEvent.ToolCall("call-$index", qualifiedMcpTool(name), "{}"), ModelEvent.Completed), + ) } + listOf(finishEvents("done")) + val hook = object : RuntimeHook { + override suspend fun onPreToolUse(call: ToolUse, context: HookContext): HookDecision = + if (call.source != ToolSource.BACKEND || context.approvedConfirmation) HookDecision.Allow() + else HookDecision.RequireConfirmation("Needs approval", "Approve this tool?") + } + val provider = LoopMcpProvider(exposedTools = names.map(::mcpTool)) + threadBuilder(ThreadScriptModel(scripts)).tools(provider).hook(hook).build().use { runtime -> + val approvals = mutableListOf() + runtime.startThread(ThreadOptions(approvalPolicy = ApprovalPolicy.REMEMBER)).runStreamed("set both").collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + approvals += event.item as Approval + (event.item as Approval).approve() + } + } + assertEquals(2, approvals.size) + assertEquals(2, approvals.map { it.domain }.toSet().size) + assertEquals(names, provider.calledTools) + assertTrue(approvals.all { it.domain.startsWith("mcp:") }) + } + } + + @Test fun networkApprovalAreasUseTheSameCanonicalHostsAsTheNetworkPolicy() { + val backend = NetworkToolBackend() + for (url in listOf("https://FOO_BAR.example/path", " https://foo_bar.example./other ")) { + val arguments = """{"url":"$url"}""" + val policy = backend.authorize("run", arguments) as NetworkToolPolicyDecision.RequiresConfirmation + assertEquals("web_fetch:foo_bar.example", approvalDomain("web_fetch", arguments)) + assertEquals("foo_bar.example", backend.activityDomain("web_fetch", arguments)) + assertTrue(policy.prompt.contains("foo_bar.example")) + } + assertNotEquals(approvalDomain("web_fetch", """{"url":"https://example.com"}"""), + approvalDomain("mcp__example.com__fetch", "{}")) + assertNotEquals(approvalDomain("mcp__server_one__first", "{}"), approvalDomain("mcp__server_one__second", "{}")) + } + + @Test fun invalidNetworkTargetsNeverGetARememberableCatchAllArea() { + for (arguments in listOf("{}", "not-json", """{"url":"invalid"}""", """{"url":"https://user:password@example.com"}""", + """{"url":"https://example.com","max_bytes":0}""", """{"url":"http://127.0.0.1"}""")) { + assertNull(approvalDomain("web_fetch", arguments)) + assertTrue(NetworkToolBackend().authorize("run", arguments) is NetworkToolPolicyDecision.Denied) + } + } +} diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadConcurrencyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadConcurrencyTest.kt index 8ccc772..7b923ff 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadConcurrencyTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadConcurrencyTest.kt @@ -62,7 +62,8 @@ class ThreadConcurrencyTest { assertTurnEvents(events) assertFalse(events.any { it is ThreadEvent.ItemStarted && it.item is Approval }) val tools = events.filterIsInstance().map { it.item }.filterIsInstance() - assertTrue(tools.any { it.approvedBy == policy }) + if (policy == ApprovalPolicy.APPROVE_ALL) assertTrue(tools.any { it.approvedBy == ApprovalSource.AUTOMATIC }) + else assertTrue(tools.all { it.approvedBy == null }) assertTrue(events.last() is ThreadEvent.TurnCompleted) } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadPersistenceTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadPersistenceTest.kt index 787cfc7..eeec85a 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadPersistenceTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadPersistenceTest.kt @@ -22,11 +22,12 @@ class ThreadPersistenceTest { assertEquals("remember", runtime.listThreads().single().id) val thread = runtime.resumeThread("remember") assertTrue(thread.items().any { it is Approval }) + assertTrue(thread.items().filterIsInstance().any { it.approvedBy == ApprovalSource.USER }) val events = thread.runStreamed("set it again").toList() assertTurnEvents(events) assertFalse(events.any { it is ThreadEvent.ItemStarted && it.item is Approval }) val tools = events.filterIsInstance().map { it.item }.filterIsInstance() - assertTrue(tools.any { it.approvedBy == ApprovalPolicy.REMEMBER }) + assertTrue(tools.any { it.approvedBy == ApprovalSource.REMEMBERED }) } } From ed2f9b6ccafe8363d92821e34f437e7352ec08c4 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:49:38 -0800 Subject: [PATCH 19/40] fix(runtime): delete complete conversation data across runtimes Co-Authored-By: Codex --- CHANGELOG.md | 5 + .../android/AndroidAgentRuntimeTest.kt | 30 ++++++ .../kernel/core/state/RunStateController.kt | 13 +++ .../agent/runtime/DefaultAgentRuntime.kt | 15 +++ .../agent/runtime/RuntimeWorkspaceRef.kt | 2 + .../runtime/run/RuntimeSessionRecorder.kt | 19 ++++ .../cc/noharry/agent/runtime/run/TodoStore.kt | 7 +- .../runtime/thread/DefaultThreadRuntime.kt | 6 +- .../runtime/thread/ThreadAttemptStore.kt | 4 + .../agent/runtime/thread/ThreadStore.kt | 8 ++ .../agent/runtime/ThreadDataDeletionTest.kt | 94 +++++++++++++++++++ 11 files changed, 199 insertions(+), 4 deletions(-) create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDataDeletionTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index c3f8bbc..fdfd408 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Deleting a thread clears its complete runtime data.** After stopping its turns, deletion removes conversation + snapshots and quarantined histories, execution mappings, event logs and attachments, SQLite rows, reliability + artifacts, loop history and its saved plan. All runtimes sharing its storage clear their cached state. Shared + workspaces and global memory are preserved. A custom event/session store that cannot delete causes an explicit failure. + - **Denied approvals continue the same turn.** Both explicit denial and `DENY_ALL` return a `CONFIRMATION_DENIED` tool result to the model without executing the tool, so it can explain the outcome. Cancelling or interrupting a pending approval records `CONFIRMATION_CANCELLED` in provider history. diff --git a/agent-runtime-android/src/test/kotlin/cc/noharry/agent/runtime/android/AndroidAgentRuntimeTest.kt b/agent-runtime-android/src/test/kotlin/cc/noharry/agent/runtime/android/AndroidAgentRuntimeTest.kt index beb741c..5337320 100644 --- a/agent-runtime-android/src/test/kotlin/cc/noharry/agent/runtime/android/AndroidAgentRuntimeTest.kt +++ b/agent-runtime-android/src/test/kotlin/cc/noharry/agent/runtime/android/AndroidAgentRuntimeTest.kt @@ -6,8 +6,13 @@ import cc.noharry.agent.spi.ProviderConcurrencyDeclaration import cc.noharry.agent.spi.model.ModelClient import cc.noharry.agent.spi.model.ModelEvent import cc.noharry.agent.spi.model.ModelRequest +import cc.noharry.agent.ThreadOptions +import cc.noharry.agent.TurnStatus +import android.database.sqlite.SQLiteDatabase import java.io.File import kotlinx.coroutines.flow.flowOf +import kotlinx.coroutines.runBlocking +import org.junit.Assert.assertEquals import org.junit.Assert.assertFalse import org.junit.Assert.assertThrows import org.junit.Assert.assertTrue @@ -26,6 +31,31 @@ class AndroidAgentRuntimeTest { override fun complete(request: ModelRequest) = flowOf(ModelEvent.Completed) } + @Test + fun deletingAThreadThroughTheAndroidFacadeRemovesItsSqliteRows() = runBlocking { + val context = RuntimeEnvironment.getApplication() + val responding = object : ModelClient { + override val providerConcurrency = ProviderConcurrencyDeclaration.serialized() + override fun complete(request: ModelRequest) = flowOf( + ModelEvent.ToolCall("finish", "finish", """{"response":"done"}"""), ModelEvent.Completed, + ) + } + AndroidAgentRuntime.builder(context, "deletion").model(responding).build().use { runtime -> + assertEquals(TurnStatus.COMPLETED, runtime.startThread(ThreadOptions(threadId = "removed")).run("hello").status) + val dbFile = File(context.filesDir, "agent-runtime/runtimes/deletion/workspace").walkTopDown() + .single { it.name == "runtime-session-store.sqlite" } + SQLiteDatabase.openDatabase(dbFile.path, null, SQLiteDatabase.OPEN_READONLY).use { db -> + db.rawQuery("SELECT COUNT(*) FROM messages", null).use { it.moveToFirst(); assertTrue(it.getInt(0) > 0) } + } + runtime.deleteThread("removed") + SQLiteDatabase.openDatabase(dbFile.path, null, SQLiteDatabase.OPEN_READONLY).use { db -> + listOf("sessions", "runs", "messages", "tool_events", "usage", "vfs_ops", "model_calls").forEach { table -> + db.rawQuery("SELECT COUNT(*) FROM $table", null).use { it.moveToFirst(); assertEquals(table, 0, it.getInt(0)) } + } + } + } + } + @Test fun aNamedRuntimeKeepsItsFilesApart() { val context = RuntimeEnvironment.getApplication() diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/RunStateController.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/RunStateController.kt index 6173e7a..c8fe609 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/RunStateController.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/state/RunStateController.kt @@ -136,6 +136,19 @@ internal class RunStateController( fun snapshot(runId: String): RuntimeRunSnapshot? = runState(runId)?.snapshot + fun deleteSession(sessionId: String, knownRunIds: Set): Set { + val cached = runs.values.filter { it.snapshot.sessionId == sessionId }.mapTo(linkedSetOf()) { it.snapshot.runId } + val identified = cached + knownRunIds + val deleted = storage?.deleteSession(sessionId, identified).orEmpty() + identified + deleted.forEach { runId -> locks.withRunLock(runId) { + runs.remove(runId) + openConfusions.remove(runId) + artifacts.evictRun(runId) + locks.retire(runId) + } } + return deleted + } + fun workpad(runId: String): RuntimeWorkpad? = artifacts.workpad(runId) fun result(runId: String): RuntimeResult? = artifacts.result(runId) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt index f3ec886..892f23d 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt @@ -293,6 +293,21 @@ internal class DefaultAgentRuntime( internal fun clearThreadHistory(threadId: String) { sessionHistory?.clearSession(threadId) activationStore.clearSession(threadId) + workspaceRegistry.clearSession(threadId) + } + + /** Called after the conversation's turns have drained, including across runtimes sharing its storage. */ + internal suspend fun deleteThreadData(threadId: String, knownExecutionIds: Set): Set { + check(sessionEventLog?.deleteThread(threadId) != false) { "The configured event log does not support thread deletion" } + val executions = runStateController.deleteSession(threadId, knownExecutionIds) + sessionRecorder.deleteThread(threadId, executions) + check(todoStore?.clear(threadId) != false) { "Cannot delete the thread's saved plan" } + clearThreadHistory(threadId) + executions.forEach { executionId -> + loopHistoryStore.delete(executionId) + workspaceRegistry.clearRun(executionId) + } + return executions } /** A persisted attempt without a saved conversation result cannot be resumed after process loss. */ diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeWorkspaceRef.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeWorkspaceRef.kt index 2c28b4d..c03e7fc 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeWorkspaceRef.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/RuntimeWorkspaceRef.kt @@ -54,6 +54,8 @@ internal class RuntimeWorkspaceRegistry( fun clearRun(runId: String) { runSelections.remove(runId) } + + fun clearSession(sessionId: String) { sessionSelections.remove(sessionId) } } internal sealed interface RuntimeWorkspaceSelection { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/RuntimeSessionRecorder.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/RuntimeSessionRecorder.kt index a096878..9933627 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/RuntimeSessionRecorder.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/RuntimeSessionRecorder.kt @@ -74,6 +74,25 @@ internal class RuntimeSessionRecorder( private val modelRequestStarts = mutableMapOf() private val firstContentTimings = mutableMapOf() + fun deleteThread(threadId: String, runIds: Set) { + check(store?.deleteThread(threadId) != false) { "The configured session store does not support thread deletion" } + synchronized(pendingLock) { pendingToolRecordings.removeAll { it.context.sessionId == threadId } } + synchronized(counterBaselines) { runIds.forEach(counterBaselines::remove) } + synchronized(modelCallSequences) { runIds.forEach(modelCallSequences::remove) } + synchronized(eventLock) { + runIdentities.entries.removeAll { it.value.sessionId == threadId } + runIds.forEach { runId -> + runStartSequences.remove(runId) + finishedEventRuns.remove(runId) + toolStartSequences.keys.removeAll { it.startsWith("$runId:") } + chunkSequences.remove(runId) + preparationTimings.remove(runId) + modelRequestStarts.remove(runId) + firstContentTimings.remove(runId) + } + } + } + fun startRun(request: AgentRequest, runId: String) { startRun(request, runId, RuntimeRunStatus.RUNNING) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/TodoStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/TodoStore.kt index 3eb758a..309facf 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/TodoStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/TodoStore.kt @@ -8,6 +8,7 @@ import cc.noharry.agent.kernel.core.state.encodeFileName import cc.noharry.agent.kernel.core.state.writeReliabilityText import cc.noharry.agent.vfs.VfsFileSystem import cc.noharry.agent.vfs.VfsReadResult +import cc.noharry.agent.vfs.VfsStatResult import cc.noharry.agent.vfs.VfsWriteMode import cc.noharry.agent.vfs.VfsWriteResult import java.io.File @@ -56,8 +57,10 @@ internal class TodoStore private constructor( override suspend fun clear(sessionId: String): Boolean { val file = todoDir?.let { File(it, fileName(sessionId)) } - if (file != null) return file.delete() - return workspace?.deleteTree(todoPath(sessionId)) == true + if (file != null) return !file.exists() || file.delete() + val path = todoPath(sessionId) + if (workspace?.stat(path) == VfsStatResult.NotFound) return true + return workspace?.deleteTree(path) == true } } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt index ef06be3..14024a8 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt @@ -81,10 +81,12 @@ internal class DefaultThreadRuntime( try { drain.await() withContext(Dispatchers.IO) { - admission.owners().forEach { it.engine.clearThreadHistory(threadId) } + var executions = store.attempts.executionIds(threadId) + val owners = admission.owners() + owners.forEach { executions = it.engine.deleteThreadData(threadId, executions) } store.delete(threadId) + owners.forEach { it.threads.remove(threadId) } } - threads.remove(threadId) } finally { synchronized(store.coordination.lock) { slot.deleting = false } } } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadAttemptStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadAttemptStore.kt index 3218292..2025ce2 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadAttemptStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadAttemptStore.kt @@ -21,6 +21,10 @@ internal class ThreadAttemptStore( fun active(threadId: String): List = synchronized(lock) { read(threadId).filter { it.active } } + fun executionIds(threadId: String): Set = synchronized(lock) { + try { read(threadId).mapTo(linkedSetOf()) { it.executionId } } catch (_: RuntimeException) { emptySet() } + } + fun begin(threadId: String, turnId: String, executionId: String): ThreadAttempt = synchronized(lock) { val records = read(threadId) val attempt = ThreadAttempt(turnId, executionId, (records.firstOrNull { it.turnId == turnId }?.attempt ?: 0) + 1, true) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt index 5f759be..d18eb88 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt @@ -112,6 +112,7 @@ internal class ThreadStore( attempts.delete(threadId) removeFile(threadId, THREAD_SUFFIX) removeFile(threadId, HISTORY_SUFFIX) + deleteQuarantinedHistory(threadId) coordination.stores.forEach { it.clearCachedThread(threadId) } Unit } @@ -122,6 +123,13 @@ internal class ThreadStore( modelMemory.remove(threadId) } + private fun deleteQuarantinedHistory(threadId: String) { + if (root == null) return + val prefix = file(threadId, HISTORY_SUFFIX).name + "." + root.listFiles().orEmpty().filter { it.name.startsWith(prefix) && it.name.endsWith(".corrupt") } + .forEach { check(it.delete()) { "Cannot delete quarantined model history" } } + } + fun modelHistoryPersistence(): SessionHistoryPersistence = object : SessionHistoryPersistence { override val identity: Any get() = root?.path ?: this@ThreadStore override fun load(sessionId: String): StoredSessionHistory? = synchronized(lock) { diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDataDeletionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDataDeletionTest.kt new file mode 100644 index 0000000..cd00dc3 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadDataDeletionTest.kt @@ -0,0 +1,94 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.spi.* +import cc.noharry.agent.spi.model.ModelEvent +import cc.noharry.agent.runtime.eventlog.InMemorySessionEventLog +import cc.noharry.agent.runtime.eventlog.openFileBackedSessionEventLog +import cc.noharry.agent.runtime.thread.DefaultThreadRuntime +import java.io.File +import java.security.MessageDigest +import kotlinx.coroutines.runBlocking +import org.junit.Assert.* +import org.junit.Test + +class ThreadDataDeletionTest { + @Test fun aDeletedThreadsSavedPlanCannotReturnWhenItsIdIsReused() = runBlocking { + val root = threadRoot() + val model = ThreadScriptModel(listOf( + listOf(ModelEvent.ToolCall("todo", "update_todo", """{"items":[{"text":"private old plan","status":"done"}]}"""), ModelEvent.Completed), + finishEvents("saved"), finishEvents("fresh"), + )) + threadBuilder(model, root).build().use { runtime -> + assertEquals(TurnStatus.COMPLETED, runtime.startThread(ThreadOptions(threadId = "plan")).run("plan something").status) + assertTrue(File(root, "workspace").walkTopDown().any { it.isFile && it.parentFile.name == "todo" }) + runtime.deleteThread("plan") + runtime.deleteThread("plan") + runtime.startThread(ThreadOptions(threadId = "plan")).run("hello") + val request = model.requests.last() + assertFalse(request.system.orEmpty().contains("private old plan")) + assertFalse(request.messages.any { it.content.contains("private old plan") }) + assertFalse(File(root, "workspace").walkTopDown().any { it.isFile && it.parentFile.name == "todo" }) + } + } + + @Test fun deletionClearsAllRuntimeCopiesAndDiskArtifactsButPreservesTheWorkspace() = runBlocking { + val root = threadRoot() + val first = threadBuilder(ThreadScriptModel(listOf(finishEvents("first"))), root).build() as DefaultThreadRuntime + val second = threadBuilder(ThreadScriptModel(listOf(finishEvents("second"))), root).build() as DefaultThreadRuntime + try { + first.startThread(ThreadOptions(threadId = "removed")).run("first", TurnOptions(turnId = "one")) + second.resumeThread("removed").run("second", TurnOptions(turnId = "two")) + val one = checkNotNull(first.diagnostics.getRuntimeResult("removed", "one")) + val two = checkNotNull(second.diagnostics.getRuntimeResult("removed", "two")) + val evidence = one.evidenceIds + two.evidenceIds + assertTrue(evidence.isNotEmpty()) + assertTrue(first.diagnostics.querySessionEvents(SessionEventQuery("removed")).isNotEmpty()) + val retained = File(root, "workspace/keep.txt").apply { parentFile.mkdirs(); writeText("shared workspace") } + val storage = File(root, "storage") + val history = storage.listFiles().orEmpty().single { it.name.endsWith(".history.json") } + File(history.path + ".corrupt").writeText("private damaged history") + val attachment = addAttachment(File(storage, "events")) + second.deleteThread("removed") + for (runtime in listOf(first, second)) { + assertTrue(runtime.listThreads().isEmpty()) + assertTrue(runtime.diagnostics.querySessionEvents(SessionEventQuery("removed")).isEmpty()) + evidence.forEach { assertNull(runtime.diagnostics.getRuntimeEvidence(it)) } + listOf(one.runId, two.runId).forEach { assertNull(runtime.engine.getRuntimeResult(it)); assertNull(runtime.engine.getRunState(it)) } + assertNull(runtime.engine.readThreadAttachment("removed", attachment)) + } + assertFalse(storage.listFiles().orEmpty().any { it.name.endsWith(".corrupt") || it.name.endsWith(".thread.json") || it.name.endsWith(".attempts.json") }) + assertTrue(File(storage, "runtime/runs").listFiles().orEmpty().isEmpty()) + assertTrue(File(storage, "runtime/evidence").listFiles().orEmpty().isEmpty()) + assertEquals("shared workspace", retained.readText()) + assertEquals(TurnStatus.COMPLETED, first.startThread(ThreadOptions(threadId = "removed")).run("fresh", TurnOptions(turnId = "one")).status) + } finally { first.close(); second.close() } + } + + @Test fun unsupportedCustomEventLogFailsDeletionExplicitly() = runBlocking { + val memory = InMemorySessionEventLog() + val unsupported = object : SessionEventLog { + override fun append(event: SessionEventAppend) = memory.append(event) + override fun query(query: SessionEventQuery) = memory.query(query) + override fun replay(sessionId: String, runId: String) = memory.replay(sessionId, runId) + } + threadBuilder(ThreadScriptModel(listOf(finishEvents("answer")))).sessionEventLog(unsupported).build().use { runtime -> + runtime.startThread(ThreadOptions(threadId = "kept")).run("hello") + val failure = runCatching { runtime.deleteThread("kept") }.exceptionOrNull() + assertTrue(failure is IllegalStateException) + assertTrue(failure?.message.orEmpty().contains("does not support")) + assertEquals(listOf("kept"), runtime.listThreads().map { it.id }) + } + } + + private fun addAttachment(root: File): String { + val bytes = "attachment content".toByteArray() + val sha = MessageDigest.getInstance("SHA-256").digest(bytes).joinToString("") { "%02x".format(it.toInt() and 255) } + val log = openFileBackedSessionEventLog(root) + assertTrue(log.putAttachment("removed", SessionAttachmentRef(sha, "image/png", bytes.size.toLong(), "image"), bytes)) + (log as? AutoCloseable)?.close() + return sha + } +} From 40b4184f468d6d23062c5a3ccf98c0f351d822b8 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:50:58 -0800 Subject: [PATCH 20/40] fix(runtime): inherit child approval policies without waiting for a user Co-Authored-By: Codex --- CHANGELOG.md | 6 ++ agent-runtime/api/agent-runtime.api | 10 +- .../agent/kernel/core/loop/NativeToolLoop.kt | 1 + .../kernel/core/tools/MaterializerRecords.kt | 1 + .../kernel/core/tools/WorkspaceCallMapping.kt | 2 + .../agent/runtime/DefaultAgentRuntime.kt | 2 + .../cc/noharry/agent/runtime/Subagents.kt | 28 +++++- .../agent/runtime/run/NativeLoopFactory.kt | 4 +- .../runtime/thread/DefaultAgentThread.kt | 1 + .../runtime/thread/DefaultThreadRuntime.kt | 7 +- .../agent/runtime/thread/ThreadInput.kt | 1 + .../runtime/workspace/VirtualWorkspace.kt | 2 +- .../cc/noharry/agent/spi/AgentRuntime.kt | 1 + .../cc/noharry/agent/spi/WorkspacePort.kt | 1 + .../runtime/SubagentApprovalPolicyTest.kt | 91 +++++++++++++++++++ 15 files changed, 148 insertions(+), 10 deletions(-) create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SubagentApprovalPolicyTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index fdfd408..afc3aff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,12 @@ called out; a patch release does not break it. artifacts, loop history and its saved plan. All runtimes sharing its storage clear their cached state. Shared workspaces and global memory are preserved. A custom event/session store that cannot delete causes an explicit failure. +- **Subagents inherit the spawning turn's approval policy.** `SubagentSpec.approvalPolicy` includes per-turn + overrides. Child runtimes sharing `Subagents` use it as their default; custom launchers should pass it explicitly. + Approval gates without a user channel are denied immediately unless automatically allowed. The coordinator also + answers gates emitted by custom launchers using the inherited policy. Children remain unable to ask the user + after approval or denial resumes their loop. + - **Denied approvals continue the same turn.** Both explicit denial and `DENY_ALL` return a `CONFIRMATION_DENIED` tool result to the model without executing the tool, so it can explain the outcome. Cancelling or interrupting a pending approval records `CONFIRMATION_CANCELLED` in provider history. diff --git a/agent-runtime/api/agent-runtime.api b/agent-runtime/api/agent-runtime.api index ad2937e..a4e20ee 100644 --- a/agent-runtime/api/agent-runtime.api +++ b/agent-runtime/api/agent-runtime.api @@ -666,10 +666,11 @@ public final class cc/noharry/agent/runtime/SubagentReport { } public final class cc/noharry/agent/runtime/SubagentSpec { - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILcc/noharry/agent/spi/model/ModelRef;ZLjava/lang/String;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILcc/noharry/agent/spi/model/ModelRef;ZLjava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILcc/noharry/agent/spi/model/ModelRef;ZLjava/lang/String;Lcc/noharry/agent/ApprovalPolicy;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILcc/noharry/agent/spi/model/ModelRef;ZLjava/lang/String;Lcc/noharry/agent/ApprovalPolicy;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun component1 ()Ljava/lang/String; public final fun component10 ()Ljava/lang/String; + public final fun component11 ()Lcc/noharry/agent/ApprovalPolicy; public final fun component2 ()Ljava/lang/String; public final fun component3 ()Ljava/lang/String; public final fun component4 ()Ljava/lang/String; @@ -678,11 +679,12 @@ public final class cc/noharry/agent/runtime/SubagentSpec { public final fun component7 ()I public final fun component8 ()Lcc/noharry/agent/spi/model/ModelRef; public final fun component9 ()Z - public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILcc/noharry/agent/spi/model/ModelRef;ZLjava/lang/String;)Lcc/noharry/agent/runtime/SubagentSpec; - public static synthetic fun copy$default (Lcc/noharry/agent/runtime/SubagentSpec;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILcc/noharry/agent/spi/model/ModelRef;ZLjava/lang/String;ILjava/lang/Object;)Lcc/noharry/agent/runtime/SubagentSpec; + public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILcc/noharry/agent/spi/model/ModelRef;ZLjava/lang/String;Lcc/noharry/agent/ApprovalPolicy;)Lcc/noharry/agent/runtime/SubagentSpec; + public static synthetic fun copy$default (Lcc/noharry/agent/runtime/SubagentSpec;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILcc/noharry/agent/spi/model/ModelRef;ZLjava/lang/String;Lcc/noharry/agent/ApprovalPolicy;ILjava/lang/Object;)Lcc/noharry/agent/runtime/SubagentSpec; public fun equals (Ljava/lang/Object;)Z public final fun getAgentType ()Ljava/lang/String; public final fun getAllowDeviceControl ()Z + public final fun getApprovalPolicy ()Lcc/noharry/agent/ApprovalPolicy; public final fun getDepth ()I public final fun getId ()Ljava/lang/String; public final fun getLabel ()Ljava/lang/String; diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt index b8f9b1f..b24e140 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt @@ -146,6 +146,7 @@ internal class NativeToolLoop( requestId = request.requestId, scene = request.scene, modelRef = request.modelRef, + approvalPolicy = request.approvalPolicy, ) sessionRecorder.appendMessage(toolContext, messages.first()) runContextMessage(runContext, runContextAsSystem)?.let { messages += it; sessionRecorder.appendMessage(toolContext, it) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/MaterializerRecords.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/MaterializerRecords.kt index 737a83c..bdddf9f 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/MaterializerRecords.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/MaterializerRecords.kt @@ -8,6 +8,7 @@ internal data class MaterializerContext( val scene: String? = null, val modelRef: ModelRef? = null, val timeoutMillis: Long = DEFAULT_MATERIALIZER_TIMEOUT_MILLIS, + val approvalPolicy: cc.noharry.agent.ApprovalPolicy = cc.noharry.agent.ApprovalPolicy.ASK, ) internal sealed interface MaterializerReadResult { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/WorkspaceCallMapping.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/WorkspaceCallMapping.kt index b1d1f60..a8c2a4a 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/WorkspaceCallMapping.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/WorkspaceCallMapping.kt @@ -10,6 +10,7 @@ internal fun MaterializerContext.toWorkspaceCallContext(): WorkspaceCallContext requestId = requestId, scene = scene, modelRef = modelRef, + approvalPolicy = approvalPolicy, ) internal fun WorkspaceCallContext.toMaterializerContext( @@ -22,4 +23,5 @@ internal fun WorkspaceCallContext.toMaterializerContext( scene = scene, modelRef = modelRef, timeoutMillis = timeoutMillis, + approvalPolicy = approvalPolicy, ) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt index 892f23d..3c01e1d 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt @@ -290,6 +290,8 @@ internal class DefaultAgentRuntime( internal suspend fun readThreadAttachment(threadId: String, sha256: String): ByteArray? = runtimeIo { sessionEventLog?.readAttachment(threadId, sha256) } + internal fun childApprovalPolicy(threadId: String): cc.noharry.agent.ApprovalPolicy? = subagents?.approvalPolicyFor(threadId) + internal fun clearThreadHistory(threadId: String) { sessionHistory?.clearSession(threadId) activationStore.clearSession(threadId) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/Subagents.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/Subagents.kt index fe33d07..3290329 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/Subagents.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/Subagents.kt @@ -4,6 +4,8 @@ package cc.noharry.agent.runtime import cc.noharry.agent.ThreadEvent import cc.noharry.agent.ThreadItem import cc.noharry.agent.TurnStatus +import cc.noharry.agent.Approval +import cc.noharry.agent.ApprovalPolicy import cc.noharry.agent.spi.ExperimentalAgentRuntimeApi import cc.noharry.agent.spi.model.ModelRef import cc.noharry.agent.spi.reliability.RuntimeRunStatus @@ -96,6 +98,10 @@ class Subagents( /** Whether [sessionId] is a child's own session, which a host keeps out of its conversation list. */ fun isSubagentSession(sessionId: String): Boolean = synchronized(lock) { children.values.any { it.spec.sessionId == sessionId } } + internal fun approvalPolicyFor(sessionId: String): ApprovalPolicy? = synchronized(lock) { + children.values.firstOrNull { it.spec.sessionId == sessionId }?.spec?.approvalPolicy + } + /** Stops [parentSessionId]'s children (every child without one) and reports nothing, e.g. when conversations go. */ fun cancelSession(parentSessionId: String? = null) { val stopped = synchronized(lock) { @@ -159,6 +165,7 @@ class Subagents( modelRef = config.modelRef ?: call.modelRef, allowDeviceControl = config.allowDeviceControl, agentType = agentType, + approvalPolicy = call.approvalPolicy, ) activeRuns += call.runId Child(spec, nowEpochMillis()).also { children[id] = it } @@ -229,7 +236,10 @@ class Subagents( private suspend fun runChild(child: Child) { try { withTimeout(config.maxDurationMillis) { - launcher.launch(child.spec).collect { observe(child, it) } + launcher.launch(child.spec).collect { event -> + respondToChildApproval(child, event) + observe(child, event) + } } settle(child, SubagentState.FAILED, error = "The subagent ended without a result.") } catch (_: TimeoutCancellationException) { @@ -280,6 +290,13 @@ class Subagents( } } + /** A custom launcher may still emit a gate, but this child has no user channel to answer it. */ + private suspend fun respondToChildApproval(child: Child, event: ThreadEvent) { + val approval = (event as? ThreadEvent.ItemStarted)?.item as? Approval ?: return + if (child.spec.approvalPolicy == ApprovalPolicy.APPROVE_ALL) approval.approve() + else approval.deny("A subagent cannot request approval from the user.") + } + private fun settle(child: Child, state: SubagentState, result: String = "", error: String = "") { val report = synchronized(lock) { if (child.state.finished) return @@ -446,6 +463,8 @@ data class SubagentSpec( val allowDeviceControl: Boolean, /** The [SubagentType] the model named, or null for a general subagent. */ val agentType: String? = null, + /** The spawning turn's effective policy, including its turn override. Launchers should apply it to the child. */ + val approvalPolicy: ApprovalPolicy = ApprovalPolicy.ASK, ) /** @@ -514,7 +533,12 @@ data class SubagentStatus( data class SubagentReport(val parentSessionId: String, val statuses: List) /** Who calls a subagent tool. */ -internal data class SubagentCall(val sessionId: String, val runId: String, val modelRef: ModelRef?) +internal data class SubagentCall( + val sessionId: String, + val runId: String, + val modelRef: ModelRef?, + val approvalPolicy: ApprovalPolicy = ApprovalPolicy.ASK, +) internal val SUBAGENT_TOOL_NAMES = setOf(SPAWN_AGENT, WAIT_AGENT, CANCEL_AGENT) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt index ec36c2d..277fa39 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt @@ -160,13 +160,15 @@ internal class NativeLoopFactory( runId, workspaceFileSystem = workspaces[runId], probeAttachment = probe, + childRun = subagents?.isSubagentSession(pending.context.sessionId) == true, ).resumeConfirmedToolUse(pending, emitPublicEvent) } suspend fun resumeDeniedToolUse(pending: PendingNativeToolUse, emitPublicEvent: suspend (AgentEvent) -> Unit): NativeLoopOutcome { val runId = pending.context.runId return loop(runId, workspaceFileSystem = workspaces[runId], - probeAttachment = probeAttachments[runId] ?: ProbeRunAttachment.disabled(runId)) + probeAttachment = probeAttachments[runId] ?: ProbeRunAttachment.disabled(runId), + childRun = subagents?.isSubagentSession(pending.context.sessionId) == true) .resumeAfterApproval(pending, "CONFIRMATION_DENIED", emitPublicEvent) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index db87e7e..2aa7f58 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -219,6 +219,7 @@ internal class DefaultAgentThread( if (policy == ApprovalPolicy.REMEMBER) ApprovalSource.REMEMBERED else ApprovalSource.AUTOMATIC) return automatic } + if (runtime.engine.childApprovalPolicy(id) != null) return ApprovalState.DENIED val approval = ThreadApproval(pending.copy(runId = turn.id), runtime.nowEpochMillis() + runtime.confirmationTimeoutMillis, runtime.nowEpochMillis) turn.approval = approval try { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt index 14024a8..01f3ecc 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt @@ -40,7 +40,7 @@ internal class DefaultThreadRuntime( override fun startThread(options: ThreadOptions): AgentThread { checkOpen() val id = options.threadId ?: UUID.randomUUID().toString() - val record = store.create(id, mergeThreadOptions(ThreadOptions(), options)) + val record = store.create(id, newThreadOptions(id, options)) return handle(record) } @@ -48,11 +48,14 @@ internal class DefaultThreadRuntime( checkOpen() require(threadId.isNotBlank()) { "Thread id must not be blank" } require(options.threadId == null || options.threadId == threadId) { "Thread id does not match options" } - val saved = store.load(threadId) ?: store.create(threadId, mergeThreadOptions(ThreadOptions(), options)) + val saved = store.load(threadId) ?: store.create(threadId, newThreadOptions(threadId, options)) val merged = mergeThreadOptions(saved.options, options) return handle(saved.copy(options = merged)).also { it.configure(merged) } } + private fun newThreadOptions(threadId: String, options: ThreadOptions): ThreadOptions = + mergeThreadOptions(ThreadOptions(approvalPolicy = engine.childApprovalPolicy(threadId)), options) + override suspend fun listThreads(): List = withContext(Dispatchers.IO) { checkOpen() store.list().map { info -> diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt index d737160..6dbc743 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt @@ -23,6 +23,7 @@ internal fun threadRequest(record: ThreadRecord, input: TurnInput, options: Turn scene = record.options.scene, modelRef = options.model ?: record.options.model, workspaceId = record.options.workspace, currentStateKeys = options.currentStateKeys, sessionRunConflictPolicy = options.onConflict, instructions = record.options.instructions, + approvalPolicy = options.approvalPolicy ?: record.options.approvalPolicy ?: ApprovalPolicy.ASK, inputImages = input.parts.filterIsInstance().mapIndexed { index, image -> ModelImage(image.bytes, image.mimeType, "thread:${record.id}/$turnId/image/$index") }, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/workspace/VirtualWorkspace.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/workspace/VirtualWorkspace.kt index 412edd2..b40f541 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/workspace/VirtualWorkspace.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/workspace/VirtualWorkspace.kt @@ -76,7 +76,7 @@ internal class VirtualWorkspace( "grep" -> grep(argumentsJson, context) "search_tools" -> toolSearch.search(argumentsJson, context) in SUBAGENT_TOOL_NAMES -> subagentTools?.let { - WorkspaceExecutionResult(it(toolName, argumentsJson, SubagentCall(context.sessionId, context.runId, context.modelRef))) + WorkspaceExecutionResult(it(toolName, argumentsJson, SubagentCall(context.sessionId, context.runId, context.modelRef, context.approvalPolicy))) } ?: WorkspaceExecutionResult(errorResult(RuntimeErrorCode.UNSUPPORTED_NATIVE_TOOL.wireCode, "Subagents are not configured.")) "write_file", "edit_file", diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt index 6b99b00..efea040 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt @@ -122,6 +122,7 @@ internal data class AgentRequest( val inputImages: List = emptyList(), val instructions: String? = null, private val executionIdOverride: String? = null, + val approvalPolicy: cc.noharry.agent.ApprovalPolicy = cc.noharry.agent.ApprovalPolicy.ASK, ) { val executionId: String get() = executionIdOverride ?: requestId diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt index 93c7339..333123e 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt @@ -21,6 +21,7 @@ internal data class WorkspaceCallContext( val requestId: String = "", val scene: String? = null, val modelRef: ModelRef? = null, + val approvalPolicy: cc.noharry.agent.ApprovalPolicy = cc.noharry.agent.ApprovalPolicy.ASK, ) /** Workspace tool execution result. [resultJson] is the model-visible payload. */ diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SubagentApprovalPolicyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SubagentApprovalPolicyTest.kt new file mode 100644 index 0000000..946a9f7 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SubagentApprovalPolicyTest.kt @@ -0,0 +1,91 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.spi.model.ModelEvent +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.Flow +import kotlinx.coroutines.flow.flow +import org.junit.Assert.* +import org.junit.Test + +class SubagentApprovalPolicyTest { + @Test fun actualParentTurnPolicyReachesChildrenAndUnavailableApprovalNeverWaits() = runBlocking { + for (policy in ApprovalPolicy.entries) childApproval(policy, shared = true) + } + + @Test fun customLauncherApprovalGatesAreAnsweredWithoutAUserChannel() = runBlocking { + for (policy in ApprovalPolicy.entries) childApproval(policy, shared = false) + } + + private suspend fun childApproval(policy: ApprovalPolicy, shared: Boolean) { + val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) + val captured = CompletableDeferred() + val finished = CompletableDeferred>() + val provider = LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature"))) + val model = ThreadScriptModel(childRounds(shared)) + lateinit var subagents: Subagents + subagents = Subagents(launcher = { spec -> + captured.complete(spec) + runChild(spec, if (shared) subagents else null, provider, model, finished) + }, scope = scope) + try { + runParent(subagents, policy) + val events = withTimeout(5000) { finished.await() } + assertEquals(policy, captured.await().approvalPolicy) + assertTurnEvents(events) + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) + val approvals = events.filterIsInstance().count { it.item is Approval } + assertEquals(if (shared) 0 else 1, approvals) + assertEquals(if (policy == ApprovalPolicy.APPROVE_ALL) listOf("set_temperature") else emptyList(), provider.calledTools) + if (shared) { + assertTrue(events.none { it is ThreadEvent.ItemStarted && it.item is Question }) + val unavailable = model.requests.last().messages.count { it.role == "tool" && "INTERACTION_UNAVAILABLE" in it.content } + assertEquals(2, unavailable) + } + } finally { subagents.cancelSession(); scope.cancel() } + } + + private suspend fun runParent(subagents: Subagents, policy: ApprovalPolicy) { + val model = ThreadScriptModel(listOf( + listOf(ModelEvent.ToolCall("spawn", "spawn_agent", """{"task":"set temperature"}"""), ModelEvent.Completed), + finishEvents("delegated"), + )) + threadBuilder(model).subagents(subagents).build().use { runtime -> + runtime.startThread(ThreadOptions(approvalPolicy = ApprovalPolicy.DENY_ALL)) + .run("delegate", TurnOptions(approvalPolicy = policy)) + } + } + + private fun runChild( + spec: SubagentSpec, + shared: Subagents?, + provider: LoopMcpProvider, + model: ThreadScriptModel, + finished: CompletableDeferred>, + ): Flow = flow { + try { + threadBuilder(model).tools(provider).hook(confirmUntilApproved()) + .apply { shared?.let(::subagents) }.build().use { runtime -> + val events = mutableListOf() + // The shared registry supplies defaults; a custom launcher intentionally exercises the fallback. + runtime.resumeThread(spec.sessionId).runStreamed(spec.task).collect { event -> + events += event + emit(event) + } + finished.complete(events) + } + } catch (error: Throwable) { finished.completeExceptionally(error); throw error } + } + + private fun childRounds(questions: Boolean): List> = buildList { + add(listOf(schemaRead("set_temperature"), ModelEvent.Completed)) + add(listOf(ModelEvent.ToolCall("action", qualifiedMcpTool("set_temperature"), "{}"), ModelEvent.Completed)) + if (questions) { + add(listOf(ModelEvent.ToolCall("async", "ask_async", """{"questions":[{"title":"Which room?"}]}"""), ModelEvent.Completed)) + add(listOf(ModelEvent.ToolCall("ask", "ask", """{"question":"Which room?"}"""), ModelEvent.Completed)) + } + add(finishEvents("child finished")) + } +} From 027f2c8d530c9efeb59611ec456646f1a26765f5 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:52:24 -0800 Subject: [PATCH 21/40] docs(api): complete migration guidance and identity contracts Co-Authored-By: Codex --- CHANGELOG.md | 125 +++++++++++------- .../cc/noharry/agent/spi/RuntimeContextSpi.kt | 9 ++ .../cc/noharry/agent/spi/RuntimeHooks.kt | 3 + .../cc/noharry/agent/spi/SessionEvent.kt | 3 + .../noharry/agent/spi/SessionEventAppend.kt | 3 + .../cc/noharry/agent/spi/ToolProvider.kt | 6 + 6 files changed, 101 insertions(+), 48 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index afc3aff..212439a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -108,75 +108,106 @@ called out; a patch release does not break it. Hosts set their own policies explicitly. MCP server ids containing underscores are grouped correctly. - **Breaking: model and hook SPI.** `ModelMessage.reasoningContent` carries replayable reasoning; `ServerSideSearchCapability` moves to `cc.noharry.agent.model`. Hooks use `onTurnStarted` / `onTurnFinished`, - and subagent launchers return `Flow`. Diagnostic access and prompt/catalog inspection are under - experimental `RuntimeDiagnostics`. Advanced tuning types move to `cc.noharry.agent.runtime`. + and subagent launchers return `Flow`. Diagnostic access uses experimental `RuntimeDiagnostics`; + prompt/catalog inspection uses `RuntimeInspection`. Advanced tuning types move to `cc.noharry.agent.runtime`. ### 0.5.0 migration -| 0.4.x entry | 0.5.0 entry | +Rebuild host code against 0.5.0. The module/package changes and constructor changes are binary breaks. +Kotlin hosts import `cc.noharry.agent.builder`; Java hosts construct with `AgentRuntimeBuilder.create()`. + +| 0.4.x runtime entry | 0.5.0 entry | |---|---| | `run(AgentRequest)` | `startThread` / `resumeThread`, then `run` / `runStreamed` | -| `TextDelta`, thinking and tool events | `ItemStarted`, `ItemDelta`, `ItemUpdated`, `ItemCompleted` | -| `ResultAvailable` / `Finished` / `Failed` | `TurnCompleted` / `TurnFailed` | -| `resumeConfirmation` / `getPendingConfirmation` | `pendingRequests`, `Approval.approve` / `deny` | -| `resumeUserInput` / `getOpenConfusion` | next turn's input / `pendingRequests` | -| `postUserInput` | `thread.steer` | -| run state and history | `thread.status`, `thread.items`, `TurnResult` | -| evidence, traces and raw event log | `runtime.diagnostics` | -| protocol request methods | removed; expose a host tool instead | +| `close` | `close` | +| `resumeConfirmation` | `Approval.approve` / `deny`; keep collecting the original turn | +| `getPendingConfirmation`, `getOpenConfusion` | `thread.pendingRequests()`, `TurnResult.pending` | +| `cancelPendingConfirmation` | `thread.interrupt()`, or let the approval expire | +| `resumeUserInput` | Next turn's `run`; `TurnInput.answering` can name a blocking question | +| `postUserInput` | `thread.steer`; name an async question in `SteerOptions.answering` to answer it | +| `getRunState` | `thread.status()` | +| `getRuntimeResult` | `TurnResult` from `run` or `TurnCompleted`; saved visible history through `items()` | +| `getRuntimeHandoff`, `getRuntimeEvidence`, `getRuntimeTraceEvents` | `runtime.diagnostics`; turn queries take `(threadId, turnId)` | +| Event-log query/replay/subscribe/health methods | `runtime.diagnostics`; screens normally consume `thread.items()` | +| Protocol-request methods | Removed; expose a host tool instead | +| `KernelRuntimeBuilder`, `CoreAgentRuntime` | `AgentRuntime.builder()` / `AgentRuntimeBuilder.create()` | + +| 0.4.x `AgentEvent` | 0.5.0 event or item | +|---|---| +| `Started` | `TurnStarted` | +| `UserInteraction` | `Question` item lifecycle; accepted input is a `UserMessage` | +| `ThinkingDelta` | `ItemDelta` on a `Reasoning` item | +| `TextDelta` | `ItemDelta` on an `AgentMessage` item | +| `TokenUsageDelta` | Cumulative `UsageUpdated`; final totals in `TurnResult.usage` | +| `ConfirmationRequired` | `ItemStarted(Approval)` | +| `RuntimeBlocked` | `Question` plus `TurnCompleted(WAITING_FOR_ANSWER)`, or `TurnFailed` | +| `RuntimeProtocolRequestCreated` | Removed from the host API | +| `RetryAttempted` | `Notice(RETRY)` with structured details | +| `BudgetWarning` | `Notice(BUDGET_LOW)` with structured details | +| `CompactionApplied` | `Notice(COMPACTION)` with structured details | +| `EmptyCompletionObserved` | `diagnostics.getRuntimeTraceEvents(threadId, turnId)` | +| `SteeringAccepted` | `ItemCompleted(UserMessage(steer = true))`, including its request id | +| `NativeToolCallStarted` | `ItemStarted(ToolCall)` | +| `NativeToolCallFinished` | `ItemCompleted(ToolCall)` | +| `NetworkToolActivity` | `ItemUpdated(ToolCall)` with `network` metadata | +| `SearchActivity` | `WebSearch` item | +| `ExecOutputDelta` | `ItemDelta` on a `ToolCall` item | +| `WorkspaceFileChanged` | `FileChange` item | +| `WorkspaceChanged` | `Notice(WORKSPACE_CHANGED)` with a workspace id | +| `ResultAvailable`, `Finished` | `TurnCompleted` | +| `Failed` | `TurnFailed` | + +| 0.4.x configuration | 0.5.0 configuration | +|---|---| +| `agent-kernel-api`, `agent-kernel-core` dependencies | `agent-api`, `agent-runtime` | +| `cc.noharry.agent.kernel.api` imports | `cc.noharry.agent` for conversation contracts; `.spi`, `.spi.model`, `.spi.mcp` for extensions | | `modelClient`, `toolProvider(s)`, `systemPrompt`, `skill` | `model`, `tools`, `instructions`, `skills` | | `loopSettings` | `settings(LoopSettings(...))` | | `loopBudget`, `contextWindow`, `modelRetry` | `limits(LoopLimits(...))` | -| `imageInput`, deferred tool flags, `runContextAsSystem`, `lessons`, native tool flags | corresponding `LoopSettings` fields | -| hook/model/tool/session concurrency setters | `LoopSettings.hookTimeoutMillis` / `RuntimeConcurrency` | -| separate durable conversation setup | `storage(directory)`; Android configures it automatically | -| `profile`, `plugin`, `nowEpochMillis` | removed from host API; internal composition/test facilities | -| workspace, hook, context provider, observer, history, subagents, search, policy and evidence configuration | retained under their existing names; advanced options stay experimental | +| `imageInput`, deferred tool flags, `runContextAsSystem`, `lessons`, native tool flags | Corresponding `LoopSettings` fields | +| Hook/model/tool/session concurrency setters | `LoopSettings.hookTimeoutMillis` / `RuntimeConcurrency` | +| `sessionStore`, separate durable history setup | `storage(directory)`; Android configures SQLite and app-private storage automatically | +| `profile`, `plugin`, `nowEpochMillis` | Removed from the host API; composition/test facilities are internal | +| Workspace, hooks, context providers, observers, `sessionHistory`, subagents, search, policy and evidence setters | Retained; advanced configuration remains experimental | | Android `DurableSessionEventLogPlugin.appPrivate` | `appPrivateSessionEventLog(context)` | +| Java file-backed event-log factory | `SessionEventLogs.openFileBackedSessionEventLog(File)` | + +0.4.0 history is not imported into the new conversation store: old sessions do not appear in `listThreads()` and +have no old items in `items()`. Existing SQLite v5 data is preserved; starting a conversation with an old session id +continues writing to that SQLite session. Old event-log records can be read with the low-level +`diagnostics.querySessionEvents(SessionEventQuery(sessionId, runId = originalRunId))`; they have no execution mapping +for the new turn-based diagnostic methods. Provider history in 0.4.0 was memory-only. Applications that keep their own +transcript can continue displaying it. + + +### Other 0.5.0 changes +Public constructors for model clients, A2A, Android Use, HTTP/MCP transports and `SessionHistory` gained options; +recompile their callers. Kernel loop, scheduler, tool-registry and prompt internals are no longer host API. -Fixes for Claude and OpenAI hosts, nothing in Chinese or about a car unless the host is, and an API cleaned up for use -as a public library. **Breaking** in behaviour where noted, for hosts that use what is removed or hidden below, and for -binaries compiled against the old constructors of `AnthropicModelClient`, `OpenAiModelClient`, `A2aServerConfig`, -`AndroidUseOptions`, `SessionHistory`, the kernel's loop classes `NativeToolLoop`, `NativeRoundRunner`, -`NativeToolUseController` and `ToolCallFailureBreaker`, and its prompt pieces `BootstrapPromptProvider.build`, -`ContextBootstrapPromptResolver`, `SessionHistoryStore` and `RuntimeContextHooks.collectContextSystemSuffix`, and -`McpHttpClient` (Kotlin source that names its arguments is unchanged; new parameters come with defaults). - -- **Test seams and internal diagnostics are not API.** These are marked `@InternalAgentRuntimeApi`: Kotlin callers - need an opt-in (Java and existing binaries are unaffected), the API dumps leave them out, and they may change in any - release. - - `SessionRunScheduler`'s `beforeClaimGrantedForTest`, `beforeNonCancellableMutexForTest`, `afterAttachJobForTest`, - `holdMutexForTest` and `snapshot()`, with `SessionRunSchedulerSnapshot`. - - The cache counters of `ToolProviderRegistry` and `ProviderConcurrencyLimiter`, and `ToolProviderRegistry`'s - companion with `clearEnvironmentProviderCatalogCacheForTests()`. - - `RuntimeVfsPerformanceCounters`. Its counter names, the `RUNTIME_COUNTER_*` constants, stay public, since the - per-run deltas are recorded under them. - **The probe emitter hub is gone** (`RuntimeProbeEmitterHub`, `RuntimeProbeStageEmitter`, `ProbeEmitterRegistration`). The runtime never installed an emitter, so `emitterFor` always returned null. Probe evidence (`runtimeEvidence(RuntimeEvidenceConfig(…))`) is unchanged. - **Java hosts write only what they change.** Interface methods with a body now compile to JVM default methods, so a Java `ModelClient` implements only `complete`, and a Java `RuntimeHook` only the callbacks it uses. The `DefaultImpls` - classes stay beside them, so Kotlin binaries compiled against earlier releases keep working. + classes remain available for Kotlin compatibility within the new package layout; the 0.4.x package migration + still requires rebuilding hosts. - **`agent-a2a` is a plain JVM library** (a jar, not an Android library), so a server or desktop host can use the A2A - client and server too. Its API is unchanged. An Android app that uses it without `agent-a2a-client-official` now + client and server too. An Android app that uses it without `agent-a2a-client-official` now declares the `INTERNET` permission itself, which the library's manifest used to add. - **A2A on Android 6 (API 23).** The direct and official A2A clients' failures were made with a constructor Android only has from API 24, and request headers were copied with `Map.forEach` (API 24 too): on Android 6 a refused endpoint crashed the host instead of returning a failure, and requests failed without core library desugaring. - **API docs for the JVM artifacts.** The javadoc jars of `agent-api` and `agent-runtime` were empty; they now hold the API docs, like the other artifacts'. -- **The answer goes out as written** (behaviour change). The agent's words to the user went through the trace - redactor, which turned long numbers (2^40 is 1099511627776, an order number) into `[REDACTED_PHONE]` and hid - coordinates and key-shaped text. Its text (`AgentEvent.TextDelta`), a completed run's `RuntimeResult.response`, its - questions (the waiting run's blocker message, `getOpenConfusion`, `AgentEvent.UserInteraction` cards) now go out - exactly as the model wrote them. Thinking, tool events, summaries and the reports of runs that did not complete are - filtered as before; a host that wants the answer filtered applies a redactor itself, on the whole text or the result - (`DefaultTraceRedactor.redact(…)`). +- **Live conversation content is original.** `AgentMessage`, `Reasoning`, `ToolCall` and `Question` snapshots carry + live content without storage redaction. User input and final answers remain original in saved visible history; + tool payloads and diagnostic records follow the configured redactor. Hosts that want different display rules + apply them to the live text. Provider model history is stored verbatim, including signed reasoning and images. - **A question that looks like a key no longer ends the run.** The durable event log refuses text that starts like a credential (`sk-`, `Bearer `), and a question card (`ask_async`) whose title or option did so failed the run: it was the one record not left out of the log when refused. It now is, and the card still reaches the host. Likewise a - user's reply that starts like a key (`postUserInput`) is now accepted and reaches the model, left out of the log, + user's reply that starts like a key (`thread.steer`) is now accepted and reaches the model, left out of the log, where it was refused with an exception. - **A runtime without a workspace reaches its tools.** Tools from providers (`functionTools`, MCP) are found with `search_tools`, which only a workspace ran: without one, the model was offered `search_tools` and the file tools, all @@ -289,11 +320,9 @@ binaries compiled against the old constructors of `AnthropicModelClient`, `OpenA words with it beyond the commonest (turn, on, open, status…). Words keep their accented and non-Latin letters, which were dropped; a run of Chinese characters is still one word, so a Chinese request outside the topics matches nothing by words alone. A lesson's scene, the same host label on every request, no longer counts as one of its words. -- **Hosts choose what is hidden.** Every long run of digits (ten characters or more of digits, spaces and dashes) in a - run's public results, events and summaries became `[REDACTED_PHONE]`, an order or tracking number included, with no - way out: the builder's setter was internal. `AgentRuntimeBuilder.traceRedactor` (experimental) is now open, and - `StandardTraceRedactor(phones = false, locations = false)` keeps phone numbers or coordinates. Secrets are hidden - after any host's redactor. `TraceRedactor` is a `fun interface`, and `DefaultTraceRedactor` is unchanged. +- **Hosts choose storage redaction.** The stable `AgentRuntimeBuilder.traceRedactor` accepts a `TraceRedactor`. + `StandardTraceRedactor(phones = false, locations = false)` preserves phone numbers and coordinates in tool + snapshots and diagnostics. Credential filtering still applies to tool payloads after custom redaction. ## 0.4.0 (2026-11-01) diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeContextSpi.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeContextSpi.kt index 60707ae..8e6fdf6 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeContextSpi.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeContextSpi.kt @@ -46,8 +46,11 @@ data class RuntimeObserverActionPreflight( ) data class RuntimeContextRequest( + /** Unique execution-attempt id; it can change when a public turn is retried after process loss. */ val runId: String, + /** Public conversation id ([cc.noharry.agent.AgentThread.id]). */ val sessionId: String, + /** Public turn id ([cc.noharry.agent.TurnResult.turnId]), scoped to [sessionId]. */ val requestId: String, val scene: String?, val input: String, @@ -65,8 +68,11 @@ data class RuntimeContextRequest( @ExperimentalAgentRuntimeApi data class RuntimeTurnInput( + /** Unique execution-attempt id; it can change when a public turn is retried after process loss. */ val runId: String, + /** Public conversation id ([cc.noharry.agent.AgentThread.id]). */ val sessionId: String, + /** Public turn id ([cc.noharry.agent.TurnResult.turnId]), scoped to [sessionId]. */ val requestId: String, val scene: String?, val input: String, @@ -79,8 +85,11 @@ data class RuntimeTurnInput( @ExperimentalAgentRuntimeApi data class RuntimeCompletedTurn( + /** Unique execution-attempt id; it can change when a public turn is retried after process loss. */ val runId: String, + /** Public conversation id ([cc.noharry.agent.AgentThread.id]). */ val sessionId: String, + /** Public turn id ([cc.noharry.agent.TurnResult.turnId]), scoped to [sessionId]. */ val requestId: String, val scene: String?, val inputDigest: String, diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeHooks.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeHooks.kt index 472fec7..5f0e3c3 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeHooks.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/RuntimeHooks.kt @@ -50,8 +50,11 @@ data class ToolUseResult( /** Context passed to host hooks and policy rules. */ data class HookContext( + /** Public conversation id ([cc.noharry.agent.AgentThread.id]). */ val sessionId: String, + /** Unique execution-attempt id; it can change when a public turn is retried after process loss. */ val runId: String, + /** Public turn id ([cc.noharry.agent.TurnResult.turnId]), scoped to [sessionId]. */ val requestId: String, val approvedConfirmation: Boolean = false, ) diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEvent.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEvent.kt index f86c3cb..bba8ba8 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEvent.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEvent.kt @@ -12,8 +12,11 @@ package cc.noharry.agent.spi data class SessionEvent( val schemaVersion: Int, val eventId: String, + /** Public conversation id ([cc.noharry.agent.AgentThread.id]). */ val sessionId: String, + /** Unique execution-attempt id; it can change when a public turn is retried after process loss. */ val runId: String, + /** Public turn id ([cc.noharry.agent.TurnResult.turnId]), scoped to [sessionId]. */ val requestId: String, val sequence: Long, val recordedAtEpochMillis: Long, diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventAppend.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventAppend.kt index 91e975d..b6a934a 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventAppend.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/SessionEventAppend.kt @@ -6,8 +6,11 @@ package cc.noharry.agent.spi * Input for appending one event; identity, sequence, and timestamp are log-owned. */ data class SessionEventAppend( + /** Public conversation id ([cc.noharry.agent.AgentThread.id]). */ val sessionId: String, + /** Unique execution-attempt id; it can change when a public turn is retried after process loss. */ val runId: String, + /** Public turn id ([cc.noharry.agent.TurnResult.turnId]), scoped to [sessionId]. */ val requestId: String, val type: SessionEventType, val payload: SessionEventPayload = SessionEventPayload.Empty, diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/spi/ToolProvider.kt b/agent-api/src/main/kotlin/cc/noharry/agent/spi/ToolProvider.kt index e55a35a..8dcb9e5 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/spi/ToolProvider.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/spi/ToolProvider.kt @@ -64,8 +64,11 @@ interface ToolCatalogCacheIdentity { /** Runtime context passed to provider initialization. */ data class ToolInitializeContext( + /** Public conversation id, or empty for initialization outside a turn. */ val sessionId: String = "", + /** Unique execution-attempt id, or empty for initialization outside a turn. */ val runId: String = "", + /** Public turn id scoped to [sessionId], or empty outside a turn. */ val requestId: String = "", ) @@ -107,8 +110,11 @@ data class ToolDescriptor( /** Runtime context passed to tool calls. */ data class ToolCallContext( + /** Public conversation id ([cc.noharry.agent.AgentThread.id]). */ val sessionId: String, + /** Unique execution-attempt id; it can change when a public turn is retried after process loss. */ val runId: String, + /** Public turn id ([cc.noharry.agent.TurnResult.turnId]), scoped to [sessionId]. */ val requestId: String, ) From c9efda25e1c83822950025d194e0877537573161 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 00:58:52 -0800 Subject: [PATCH 22/40] test(runtime): migrate approval and question contracts to thread flows Co-Authored-By: Codex --- .../runtime/ConfirmationCloseLoopTest.kt | 282 +++++++----------- .../runtime/ConfirmationContextResumeTest.kt | 13 +- .../agent/runtime/ConfirmationHistoryTest.kt | 154 +++++----- .../agent/runtime/NativeAskResumeTest.kt | 45 ++- 4 files changed, 216 insertions(+), 278 deletions(-) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationCloseLoopTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationCloseLoopTest.kt index ac26eac..e522e81 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationCloseLoopTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationCloseLoopTest.kt @@ -1,195 +1,127 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime -import cc.noharry.agent.spi.AgentEvent -import cc.noharry.agent.spi.AgentRequest -import cc.noharry.agent.spi.AgentRuntime -import cc.noharry.agent.spi.CancelPendingConfirmationRequest -import cc.noharry.agent.spi.CancelPendingResult -import cc.noharry.agent.spi.ConfirmationChoice -import cc.noharry.agent.spi.ConfirmationDecision -import cc.noharry.agent.spi.ConfirmationResumeResult -import cc.noharry.agent.spi.reliability.RuntimeRunStatus -import cc.noharry.agent.spi.reliability.SuggestedNextAction -import cc.noharry.agent.kernel.core.state.InMemoryConfirmationStore -import cc.noharry.agent.kernel.core.state.RunStateController -import kotlinx.coroutines.flow.toList + +import cc.noharry.agent.* +import cc.noharry.agent.spi.model.ModelEvent import kotlinx.coroutines.runBlocking -import org.junit.Assert.assertEquals -import org.junit.Assert.assertNotNull -import org.junit.Assert.assertNull -import org.junit.Assert.assertTrue +import org.junit.Assert.* import org.junit.Test class ConfirmationCloseLoopTest { - @Test - fun runEmitsPendingConfirmationWhenConfigured() = runBlocking { - val runtime = AgentRuntimeBuilder.create().confirmationOnRun().buildEngine() - - val events = runtime.run(agentRequest()).toList() - val confirmationEvent = events.filterIsInstance() - .single() - - assertEquals("session-1", confirmationEvent.pending.sessionId) - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState("request-1")?.status) - assertEquals(confirmationEvent.pending.pendingId, runtime.getRunState("request-1")?.pendingConfirmationId) - assertEquals(confirmationEvent.pending, runtime.getPendingConfirmation(confirmationEvent.pending.pendingId)) + @Test fun pendingApprovalBelongsToTheActiveTurnAndIsVisibleFromAnotherHandle() = runBlocking { + approvalBuilder().build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "session-1")) + thread.runStreamed("set temperature", TurnOptions(turnId = "request-1")).collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + val pending = event.item as Approval + assertEquals("request-1", pending.turnId) + assertEquals(ThreadStatus.WAITING_FOR_APPROVAL, thread.status()) + assertEquals(pending, runtime.resumeThread(thread.id).pendingRequests().single()) + pending.approve() + } + } + assertTrue(thread.pendingRequests().isEmpty()) + } } - @Test - fun confirmationStoreAllocatesUniquePendingIdsWithinRun() { - val store = InMemoryConfirmationStore(nowEpochMillis = { 1_000L }) - - val first = store.create("request-1", "session-1", expiresInMillis = 10_000) - val firstResume = store.resume( - ConfirmationDecision(first.pendingId, "resume-1", ConfirmationChoice.APPROVE), - ) - val second = store.create("request-1", "session-1", expiresInMillis = 10_000) - val duplicateFirst = store.resume( - ConfirmationDecision(first.pendingId, "resume-duplicate", ConfirmationChoice.APPROVE), - ) - - assertEquals("request-1:confirmation", first.pendingId) - assertEquals("request-1:confirmation:2", second.pendingId) - assertEquals(ConfirmationResumeResult.Accepted, firstResume.apiResult) - assertEquals(ConfirmationResumeResult.AlreadyConsumed, duplicateFirst.apiResult) - assertNull(store.getPending(first.pendingId)) - assertEquals(second, store.getPending(second.pendingId)) + @Test fun successiveApprovalIdsAreUniqueAndTheCurrentRequestCannotConsumeThePreviousOne() = runBlocking { + val model = ThreadScriptModel(listOf( + listOf(schemaRead("set_temperature"), ModelEvent.Completed), + listOf(ModelEvent.ToolCall("first", qualifiedMcpTool("set_temperature"), "{}"), ModelEvent.Completed), + listOf(ModelEvent.ToolCall("second", qualifiedMcpTool("set_temperature"), "{}"), ModelEvent.Completed), + finishEvents("done"), + )) + threadBuilder(model).tools(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) + .hook(confirmUntilApproved()).build().use { runtime -> + val thread = runtime.startThread() + val approvals = mutableListOf() + thread.runStreamed("set it twice").collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + val pending = event.item as Approval + approvals.firstOrNull()?.let { assertEquals(RespondResult.ALREADY_ANSWERED, it.approve()) } + approvals += pending + assertEquals(pending, thread.pendingRequests().single()) + assertEquals(RespondResult.ACCEPTED, pending.approve()) + } + } + assertEquals(2, approvals.size) + assertEquals(2, approvals.map { it.id }.toSet().size) + } } - @Test - fun waitingConfirmationSnapshotCarriesCurrentPendingId() { - val controller = RunStateController(nowEpochMillis = { 1_000L }) - val started = controller.startRun(agentRequest(), runId = "request-1") - - controller.markWaitingConfirmation( - started = started, - prompt = "Approve example.org?", - pendingConfirmationId = "request-1:confirmation:2", - ) - - val snapshot = controller.snapshot("request-1") - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, snapshot?.status) - assertEquals(SuggestedNextAction.RESUME_CONFIRMATION, snapshot?.suggestedNextAction) - assertEquals("request-1:confirmation:2", snapshot?.pendingConfirmationId) + @Test fun approvingCompletesTheOriginalTurnAndOnlyTheFirstResponseWins() = runBlocking { + approvalBuilder().build().use { runtime -> + val thread = runtime.startThread() + val events = mutableListOf() + thread.runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + val pending = event.item as Approval + assertEquals(RespondResult.ACCEPTED, pending.approve()) + assertEquals(RespondResult.ALREADY_ANSWERED, pending.approve()) + } + } + assertTurnEvents(events) + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) + assertEquals(ThreadStatus.IDLE, thread.status()) + assertTrue(thread.pendingRequests().isEmpty()) + } } - @Test - fun approveConfirmationCompletesRunAndIsIdempotent() = runBlocking { - val runtime = runtimeWithPendingConfirmation() - val pending = pendingConfirmation(runtime) - - val accepted = runtime.resumeConfirmation( - ConfirmationDecision( - pendingId = pending.pendingId, - requestId = "resume-1", - choice = ConfirmationChoice.APPROVE, - ), - ) - val duplicate = runtime.resumeConfirmation( - ConfirmationDecision( - pendingId = pending.pendingId, - requestId = "resume-1", - choice = ConfirmationChoice.APPROVE, - ), - ) - - assertEquals(ConfirmationResumeResult.Accepted, accepted) - assertEquals(ConfirmationResumeResult.AlreadyConsumed, duplicate) - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRunState("request-1")?.status) - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRuntimeResult("request-1")?.status) - assertNull(runtime.getPendingConfirmation(pending.pendingId)) + @Test fun denialDoesNotExecuteTheToolAndLetsTheModelExplain() = runBlocking { + val provider = LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature"))) + threadBuilder(backendThenFinishModel(mutableListOf())).tools(provider).hook(confirmUntilApproved()).build().use { runtime -> + val thread = runtime.startThread() + val events = mutableListOf() + thread.runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + assertEquals(RespondResult.ACCEPTED, (event.item as Approval).deny()) + } + } + assertTurnEvents(events) + assertEquals("recovered", (events.last() as ThreadEvent.TurnCompleted).result.finalResponse) + assertTrue(provider.calledTools.isEmpty()) + assertTrue(thread.pendingRequests().isEmpty()) + } } - @Test - fun denyConfirmationCancelsRunWithoutApproval() = runBlocking { - val runtime = runtimeWithPendingConfirmation() - val pending = pendingConfirmation(runtime) - - val denied = runtime.resumeConfirmation( - ConfirmationDecision( - pendingId = pending.pendingId, - requestId = "resume-1", - choice = ConfirmationChoice.DENY, - ), - ) - - assertTrue(denied is ConfirmationResumeResult.Rejected) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState("request-1")?.status) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRuntimeResult("request-1")?.status) + @Test fun interruptWithdrawsApprovalAndAStaleHandleCannotExecuteTheTool() = runBlocking { + approvalBuilder().build().use { runtime -> + val thread = runtime.startThread() + var stale: Approval? = null + val events = mutableListOf() + thread.runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + stale = event.item as Approval + thread.interrupt() + } + } + assertTurnEvents(events) + assertEquals(TurnStatus.INTERRUPTED, (events.last() as ThreadEvent.TurnCompleted).result.status) + assertEquals(RespondResult.NOT_FOUND, checkNotNull(stale).approve()) + assertTrue(thread.pendingRequests().isEmpty()) + } } - @Test - fun cancelPendingConfirmationCancelsRun() = runBlocking { - val runtime = runtimeWithPendingConfirmation() - val pending = pendingConfirmation(runtime) - - val cancelled = runtime.cancelPendingConfirmation( - CancelPendingConfirmationRequest( - pendingId = pending.pendingId, - requestId = "cancel-1", - reason = "host cancelled", - ), - ) - - assertTrue(cancelled is CancelPendingResult.Cancelled) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState("request-1")?.status) - assertNull(runtime.getPendingConfirmation(pending.pendingId)) - } - - @Test - fun resumeExpiredConfirmationReturnsExpired() = runBlocking { + @Test fun anExpiredApprovalRefusesLateResponsesAndClosesTheTurn() = runBlocking { var now = 1_000L - val runtime = AgentRuntimeBuilder.create() - .nowEpochMillis { now } - .confirmationOnRun(expiresInMillis = 5) - .buildEngine() - runtime.run(agentRequest()).toList() - val pending = pendingConfirmation(runtime) - - now = 1_006L - val expired = runtime.resumeConfirmation( - ConfirmationDecision( - pendingId = pending.pendingId, - requestId = "resume-1", - choice = ConfirmationChoice.APPROVE, - ), - ) - - assertEquals(ConfirmationResumeResult.Expired, expired) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState("request-1")?.status) - assertNull(runtime.getPendingConfirmation(pending.pendingId)) - } - - @Test - fun missingConfirmationReturnsNotFound() = runBlocking { - val runtime = AgentRuntimeBuilder.create().buildEngine() - - val result = runtime.resumeConfirmation( - ConfirmationDecision( - pendingId = "missing", - requestId = "resume-1", - choice = ConfirmationChoice.APPROVE, - ), - ) - - assertEquals(ConfirmationResumeResult.NotFound, result) - } - - private suspend fun runtimeWithPendingConfirmation(): AgentRuntime { - val runtime = AgentRuntimeBuilder.create().confirmationOnRun().buildEngine() - runtime.run(agentRequest()).toList() - return runtime + approvalBuilder().nowEpochMillis { now }.build().use { runtime -> + val thread = runtime.startThread() + val events = mutableListOf() + thread.runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + val pending = event.item as Approval + now = checkNotNull(pending.expiresAt) + 1 + assertEquals(RespondResult.EXPIRED, pending.approve()) + } + } + assertTurnEvents(events) + assertEquals(TurnErrorCodes.CONFIRMATION_EXPIRED, (events.last() as ThreadEvent.TurnFailed).error.code) + assertTrue(thread.pendingRequests().isEmpty()) + } } - - private suspend fun pendingConfirmation(runtime: AgentRuntime) = - runtime.getPendingConfirmation("request-1:confirmation").also { - assertNotNull(it) - } ?: error("Expected pending confirmation.") - - private fun agentRequest(): AgentRequest = AgentRequest( - requestId = "request-1", - sessionId = "session-1", - input = "trigger confirmation", - ) } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationContextResumeTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationContextResumeTest.kt index a386390..b248dd6 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationContextResumeTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationContextResumeTest.kt @@ -1,11 +1,14 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime +import cc.noharry.agent.Approval +import cc.noharry.agent.ThreadEvent +import cc.noharry.agent.ThreadOptions +import cc.noharry.agent.TurnOptions import cc.noharry.agent.spi.* import cc.noharry.agent.spi.model.ModelRequest import cc.noharry.agent.kernel.core.state.FileBackedLoopHistoryStore import java.nio.file.Files -import kotlinx.coroutines.flow.toList import kotlinx.coroutines.runBlocking import org.junit.Assert.assertEquals import org.junit.Assert.assertTrue @@ -31,11 +34,11 @@ class ConfirmationContextResumeTest { val runtime = AgentRuntimeBuilder.create().workspaceRoot(root) .toolProvider(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) .hook(confirmUntilApproved()).contextProvider(provider) - .modelClient(backendThenFinishModel(requests)).buildEngine() + .modelClient(backendThenFinishModel(requests)).build() try { - val events = runtime.run(AgentRequest("context-run", "context-session", "set temperature", currentStateKeys = setOf("media.volume"))).toList() - val pending = events.filterIsInstance().single().pending.pendingId - runtime.resumeConfirmation(approve(pending)) + runtime.startThread(ThreadOptions(threadId = "context-session")) + .runStreamed("set temperature", TurnOptions(turnId = "context-run", currentStateKeys = setOf("media.volume"))) + .collect { event -> if (event is ThreadEvent.ItemStarted && event.item is Approval) (event.item as Approval).approve() } assertTrue(requests.size >= 3) assertTrue(requests.all { it.system.orEmpty().contains("RESUME_SENTINEL") }) assertEquals(1, providerCalls) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationHistoryTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationHistoryTest.kt index aa699e7..a125cb8 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationHistoryTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationHistoryTest.kt @@ -2,11 +2,8 @@ package cc.noharry.agent.runtime -import cc.noharry.agent.spi.AgentEvent -import cc.noharry.agent.spi.AgentRequest -import cc.noharry.agent.spi.CancelPendingConfirmationRequest -import cc.noharry.agent.spi.ConfirmationChoice -import cc.noharry.agent.spi.ConfirmationDecision +import cc.noharry.agent.* + import cc.noharry.agent.spi.HookContext import cc.noharry.agent.spi.HookDecision import cc.noharry.agent.spi.ProviderConcurrencyDeclaration @@ -23,11 +20,9 @@ import cc.noharry.agent.spi.ToolUse import cc.noharry.agent.spi.model.ModelClient import cc.noharry.agent.spi.model.ModelEvent import cc.noharry.agent.spi.model.ModelRequest -import cc.noharry.agent.spi.reliability.RuntimeRunStatus import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.FlowCollector import kotlinx.coroutines.flow.flow -import kotlinx.coroutines.flow.toList import kotlinx.coroutines.runBlocking import org.junit.Assert.assertEquals import org.junit.Assert.assertTrue @@ -80,93 +75,106 @@ class ConfirmationHistoryTest { private fun runtime(client: ModelClient, door: Door) = AgentRuntimeBuilder.create() .modelClient(client).toolProvider(door).sessionHistory(SessionHistory()).sessionToolActivations(SessionToolActivations()) .hook(AskFirst, ToolMatcher.toolName("mcp__car__unlock_door")) - .buildEngine() - - private suspend fun cc.noharry.agent.spi.AgentRuntime.pause(runId: String, input: String) = - run(AgentRequest(runId, "s1", input)).toList().filterIsInstance().single().pending + .build() + + private suspend fun AgentThread.collectTurn( + turnId: String, + input: String, + respond: suspend (Approval) -> Unit, + ): List { + val events = mutableListOf() + runStreamed(input, TurnOptions(turnId = turnId)).collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) respond(event.item as Approval) + } + assertTurnEvents(events) + return events + } - @Test fun anApprovedCallResumesWithItsThinkingSignatureAndWordsAndNoHandoffNote() = runBlocking { + @Test fun anApprovedCallResumesWithItsThinkingSignatureAndWordsAndNoHandoffNote() = runBlocking { val script = Script(listOf(unlock, answer)) - val runtime = runtime(script, Door()) - val pending = runtime.pause("r1", "开主驾车门") - runtime.resumeConfirmation(ConfirmationDecision(pending.pendingId, "d1", ConfirmationChoice.APPROVE)) - - val resumed = script.seen[1].messages - val call = resumed.single { it.role == "assistant" && it.toolCallId == "call_1" } - assertEquals("sig-1", call.thinkingSignature) - assertEquals("我来开门。", call.assistantText) - assertEquals("开主驾车门", resumed.first().content) - assertTrue(resumed.none { it.role == "system" }) + runtime(script, Door()).use { runtime -> + runtime.startThread(ThreadOptions(threadId = "s1")).collectTurn("r1", "开主驾车门") { it.approve() } + val resumed = script.seen[1].messages + val call = resumed.single { it.role == "assistant" && it.toolCallId == "call_1" } + assertEquals("sig-1", call.thinkingSignature) + assertEquals("我来开门。", call.assistantText) + assertEquals("开主驾车门", resumed.first().content) + assertTrue(resumed.none { it.role == "system" }) + } } - @Test fun theConfirmationSaysWhichCallWaitsAndWithWhatArguments() = runBlocking { + @Test fun theApprovalSaysWhichCallWaitsAndWithWhatArguments() = runBlocking { val slowly = object : RuntimeHook { override suspend fun onPreToolUse(call: ToolUse, context: HookContext) = HookDecision.Allow(updatedArgumentsJson = """{"door":"driver","speed":"slow"}""") } - val runtime = AgentRuntimeBuilder.create() - .modelClient(Script(listOf(unlock, answer))).toolProvider(Door()) + AgentRuntimeBuilder.create().modelClient(Script(listOf(unlock, answer))).toolProvider(Door()) .hook(slowly, ToolMatcher.toolName("mcp__car__unlock_door")) .hook(AskFirst, ToolMatcher.toolName("mcp__car__unlock_door")) - .buildEngine() - val pending = runtime.pause("r1", "开主驾车门") - - assertEquals("开门吗?", pending.prompt) - assertEquals("mcp__car__unlock_door", pending.toolName) - assertEquals("""{"door":"driver","speed":"slow"}""", pending.argumentsJson) - assertEquals(pending, runtime.getPendingConfirmation(pending.pendingId)) + .build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "s1")) + thread.collectTurn("r1", "开主驾车门") { pending -> + assertEquals("开门吗?", pending.reason) + assertEquals("mcp__car__unlock_door", pending.tool) + assertEquals("""{"door":"driver","speed":"slow"}""", pending.arguments) + assertEquals(pending, thread.pendingRequests().single()) + pending.approve() + } + } } - @Test fun aFailedApprovedCallEndsTheRunAndTheNextRunSeesIt() = runBlocking { + @Test fun aFailedApprovedCallEndsTheTurnAndTheNextTurnSeesIt() = runBlocking { val script = Script(listOf(unlock, answer)) - val runtime = runtime(script, Door("""{"ok":false,"code":"DOOR_JAMMED"}""")) - val pending = runtime.pause("r1", "开主驾车门") - runtime.resumeConfirmation(ConfirmationDecision(pending.pendingId, "d1", ConfirmationChoice.APPROVE)) - runtime.run(AgentRequest("r2", "s1", "门开了吗")).toList() - - assertEquals(RuntimeRunStatus.FAILED, runtime.getRuntimeResult("r1")?.status) - val next = script.seen[1].messages - assertTrue(next.any { it.role == "tool" && it.content.contains("DOOR_JAMMED") }) - assertTrue(next.any { it.role == "user" && it.content.contains("ended without an answer") }) + runtime(script, Door("""{"ok":false,"code":"DOOR_JAMMED"}""")).use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "s1")) + val events = thread.collectTurn("r1", "开主驾车门") { it.approve() } + assertEquals("DOOR_JAMMED", (events.last() as ThreadEvent.TurnFailed).error.code) + thread.run("门开了吗") + val next = script.seen[1].messages + assertTrue(next.any { it.role == "tool" && it.content.contains("DOOR_JAMMED") }) + assertTrue(next.any { it.role == "user" && it.content.contains("ended without an answer") }) + } } - @Test fun theNextRunKnowsTheUserDeclined() = runBlocking { - val script = Script(listOf(unlock, answer)) + @Test fun theCurrentAndNextTurnKnowTheUserDeclined() = runBlocking { + val script = Script(listOf(unlock, answer, answer)) val door = Door() - val runtime = runtime(script, door) - val pending = runtime.pause("r1", "开主驾车门") - runtime.resumeConfirmation(ConfirmationDecision(pending.pendingId, "d1", ConfirmationChoice.DENY)) - runtime.run(AgentRequest("r2", "s1", "门开了吗")).toList() - - assertTrue(door.calls.isEmpty()) - val next = script.seen[1].messages - assertEquals("开主驾车门", next.first().content) - assertTrue(next.any { it.role == "assistant" && it.toolCallId == "call_1" && it.thinkingSignature == "sig-1" }) - assertTrue(next.any { it.role == "tool" && it.content.contains("USER_DECLINED") }) - assertEquals("门开了吗", next.last().content) + runtime(script, door).use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "s1")) + thread.collectTurn("r1", "开主驾车门") { it.deny() } + thread.run("门开了吗") + assertTrue(door.calls.isEmpty()) + for (request in script.seen.drop(1)) { + assertTrue(request.messages.any { it.role == "assistant" && it.toolCallId == "call_1" && it.thinkingSignature == "sig-1" }) + assertTrue(request.messages.any { it.role == "tool" && it.content.contains("CONFIRMATION_DENIED") }) + } + assertEquals("门开了吗", script.seen.last().messages.last().content) + } } - @Test fun theNextRunKnowsTheConfirmationWasWithdrawn() = runBlocking { + @Test fun theNextTurnKnowsTheApprovalWasWithdrawn() = runBlocking { val script = Script(listOf(unlock, answer)) - val runtime = runtime(script, Door()) - val pending = runtime.pause("r1", "开主驾车门") - runtime.cancelPendingConfirmation(CancelPendingConfirmationRequest(pending.pendingId, "c1")) - runtime.run(AgentRequest("r2", "s1", "门开了吗")).toList() - - assertTrue(script.seen[1].messages.any { it.role == "tool" && it.content.contains("CONFIRMATION_CANCELLED") }) + runtime(script, Door()).use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "s1")) + thread.collectTurn("r1", "开主驾车门") { thread.interrupt() } + thread.run("门开了吗") + assertTrue(script.seen[1].messages.any { it.role == "tool" && it.content.contains("CONFIRMATION_CANCELLED") }) + } } - @Test fun whileTheConfirmationWaitsTheSessionShowsTheCallAsWaiting() = runBlocking { + @Test fun whileApprovalWaitsTheSessionShowsTheCallAsWaiting() = runBlocking { val history = SessionHistory() - val runtime = AgentRuntimeBuilder.create() - .modelClient(Script(listOf(unlock))).toolProvider(Door()).sessionHistory(history) - .sessionToolActivations(SessionToolActivations()) - .hook(AskFirst, ToolMatcher.toolName("mcp__car__unlock_door")) - .buildEngine() - runtime.pause("r1", "开主驾车门") - - val waiting = history.messages("s1") - assertTrue(waiting.any { it.role == "assistant" && it.toolCallId == "call_1" }) - assertTrue(waiting.last().content.contains("awaiting_confirmation")) + AgentRuntimeBuilder.create().modelClient(Script(listOf(unlock))).toolProvider(Door()).sessionHistory(history) + .sessionToolActivations(SessionToolActivations()).hook(AskFirst, ToolMatcher.toolName("mcp__car__unlock_door")) + .build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "s1")) + thread.collectTurn("r1", "开主驾车门") { + val waiting = history.messages("s1") + assertTrue(waiting.any { it.role == "assistant" && it.toolCallId == "call_1" }) + assertTrue(waiting.last().content.contains("awaiting_confirmation")) + thread.interrupt() + } + } } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeAskResumeTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeAskResumeTest.kt index 07264fd..fde46b3 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeAskResumeTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeAskResumeTest.kt @@ -1,16 +1,13 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime -import cc.noharry.agent.spi.AgentEvent -import cc.noharry.agent.spi.AgentRequest +import cc.noharry.agent.* import cc.noharry.agent.spi.ProviderConcurrencyDeclaration import cc.noharry.agent.spi.SessionEventType import cc.noharry.agent.spi.model.ModelClient import cc.noharry.agent.spi.model.ModelEvent import cc.noharry.agent.spi.model.ModelRequest -import cc.noharry.agent.spi.reliability.RuntimeRunStatus import kotlinx.coroutines.flow.flowOf -import kotlinx.coroutines.flow.toList import kotlinx.coroutines.runBlocking import org.junit.Assert.assertEquals import org.junit.Assert.assertFalse @@ -18,7 +15,7 @@ import org.junit.Assert.assertTrue import org.junit.Test class NativeAskResumeTest { - @Test fun askPausesAndReplyResumesTheSameRunWithoutExecEngineExposure() = runBlocking { + @Test fun askCompletesItsTurnAndAnExplicitReplyStartsANewTurnWithoutExecExposure() = runBlocking { val requests = mutableListOf() val model = object : ModelClient { override val providerConcurrency = ProviderConcurrencyDeclaration.serialized() @@ -31,19 +28,19 @@ class NativeAskResumeTest { }) } } - val runtime = AgentRuntimeBuilder.create().modelClient(model).buildEngine() + val runtime = AgentRuntimeBuilder.create().modelClient(model).build() try { - val events = runtime.run(AgentRequest("q", "s", "设置音量")).toList() - val run = events.filterIsInstance().single().runId - assertEquals(RuntimeRunStatus.WAITING_USER_INPUT, runtime.getRunState(run)?.status) - assertEquals("目标音量是多少?", runtime.getOpenConfusion(run)?.question) - val result = runtime.resumeUserInput(AgentRequest("reply", "s", "18", resumeRunId = run)) - assertEquals(run, result?.runId) - assertEquals(RuntimeRunStatus.COMPLETED, result?.status) - assertTrue(requests.last().messages.any { it.role == "user" && it.content == "18" }) + val thread = runtime.startThread(ThreadOptions(threadId = "s")) + val question = thread.run("设置音量", TurnOptions(turnId = "q")) + assertEquals(TurnStatus.WAITING_FOR_ANSWER, question.status) + assertEquals("目标音量是多少?", (question.pending as Question).text) + val result = thread.run(TurnInput(listOf(InputPart.Text("18")), answering = question.pending!!.id)) + assertTrue(result.turnId != question.turnId) + assertEquals(TurnStatus.COMPLETED, result.status) + assertTrue(requests.last().messages.any { it.role == "user" && it.content.contains("18") && it.content.contains("目标音量是多少?") }) assertTrue(requests.all { r -> r.tools.any { it.name == "ask" } }) assertFalse(requests.any { r -> r.tools.any { it.name == "exec_js" } }) - val log = runtime.replaySessionEvents("s", run) + val log = runtime.diagnostics.replaySessionEvents("s", question.turnId) assertTrue(log.any { it.type == SessionEventType.TOOL_RESULT }) } finally { runtime.close() @@ -57,14 +54,12 @@ class NativeAskResumeTest { override fun complete(request: ModelRequest) = flowOf(ModelEvent.ToolCall("ask-1", "ask", """{"question":"$question"}""")) } - val runtime = AgentRuntimeBuilder.create().modelClient(model).buildEngine() + val runtime = AgentRuntimeBuilder.create().modelClient(model).build() try { - val events = runtime.run(AgentRequest("q", "s", "Count.")).toList() - val run = events.filterIsInstance().single().runId - - assertEquals(question, runtime.getOpenConfusion(run)?.question) - assertEquals(question, events.filterIsInstance().single().blocker.message) - assertEquals(question, events.filterIsInstance().joinToString("") { it.text }) + val result = runtime.startThread().run("Count.") + assertEquals(question, (result.pending as Question).text) + assertEquals(question, result.finalResponse) + assertEquals(question, result.items.filterIsInstance().single().text) } finally { runtime.close() } @@ -79,10 +74,10 @@ class NativeAskResumeTest { else ModelEvent.ToolCall("end", "finish", """{"response":"已纠正"}"""), ) } - val runtime = AgentRuntimeBuilder.create().modelClient(model).buildEngine() + val runtime = AgentRuntimeBuilder.create().modelClient(model).build() try { - runtime.run(AgentRequest("q", "s", "你好")).toList() - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRunState("q")?.status) + val result = runtime.startThread().run("你好") + assertEquals(TurnStatus.COMPLETED, result.status) assertEquals(2, rounds) } finally { runtime.close() From cd06bad486a212ac5a6e81e54088c4ab81f11dca Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:02:28 -0800 Subject: [PATCH 23/40] fix(runtime): drain child work before deleting its parent thread Co-Authored-By: Codex --- CHANGELOG.md | 3 + .../agent/runtime/DefaultAgentRuntime.kt | 1 + .../cc/noharry/agent/runtime/Subagents.kt | 109 ++++++++++++-- .../runtime/thread/DefaultThreadRuntime.kt | 1 + .../agent/runtime/ThreadChildDeletionTest.kt | 140 ++++++++++++++++++ 5 files changed, 244 insertions(+), 10 deletions(-) create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadChildDeletionTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 212439a..642d90c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,9 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Thread deletion drains background children.** Their jobs are cancelled and joined before storage is removed; + queued reports are discarded so a late child cannot report into a recreated conversation with the same id. + - **Deleting a thread clears its complete runtime data.** After stopping its turns, deletion removes conversation snapshots and quarantined histories, execution mappings, event logs and attachments, SQLite rows, reliability artifacts, loop history and its saved plan. All runtimes sharing its storage clear their cached state. Shared diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt index 3c01e1d..e9436e7 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt @@ -300,6 +300,7 @@ internal class DefaultAgentRuntime( /** Called after the conversation's turns have drained, including across runtimes sharing its storage. */ internal suspend fun deleteThreadData(threadId: String, knownExecutionIds: Set): Set { + subagents?.drainSession(threadId) check(sessionEventLog?.deleteThread(threadId) != false) { "The configured event log does not support thread deletion" } val executions = runStateController.deleteSession(threadId, knownExecutionIds) sessionRecorder.deleteThread(threadId, executions) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/Subagents.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/Subagents.kt index 3290329..3125d81 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/Subagents.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/Subagents.kt @@ -13,8 +13,10 @@ import cc.noharry.agent.kernel.core.tools.TERMINAL_TOOLS import kotlinx.coroutines.CancellationException import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.CoroutineStart +import kotlinx.coroutines.CompletableDeferred import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.Job +import kotlinx.coroutines.NonCancellable import kotlinx.coroutines.SupervisorJob import kotlinx.coroutines.TimeoutCancellationException import kotlinx.coroutines.delay @@ -22,6 +24,8 @@ import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.MutableStateFlow import kotlinx.coroutines.flow.first import kotlinx.coroutines.launch +import kotlinx.coroutines.joinAll +import kotlinx.coroutines.withContext import kotlinx.coroutines.withTimeout import kotlinx.coroutines.withTimeoutOrNull import kotlinx.serialization.json.Json @@ -61,6 +65,9 @@ class Subagents( private val children = linkedMapOf() private val activeRuns = hashSetOf() private val pendingReports = mutableListOf() + private val drainingSessions = mutableSetOf() + private val activeDeliveries = mutableMapOf() + private val deliveryDrains = mutableMapOf>() private var listener: ((SubagentReport) -> Unit)? = null @Volatile private var statusListener: ((SubagentStatus) -> Unit)? = null @@ -70,18 +77,22 @@ class Subagents( /** Bumped on every settle or stall, so a waiting wait_agent re-checks. */ private val changes = MutableStateFlow(0L) - /** Where results and stalls go once the run that would have collected them has ended; queued until set. */ + /** + * Where results and stalls go once the run that would have collected them has ended; queued until set. + * To delete the conversation, start a separate coroutine and return from the callback; synchronous deletion is rejected. + */ fun onReport(listener: ((SubagentReport) -> Unit)?) { val queued = synchronized(lock) { this.listener = listener if (listener == null) emptyList() else pendingReports.toList().also { pendingReports.clear() } } - queued.forEach { listener?.invoke(it) } + queued.forEach(::report) } /** * Every visible change of a child, for a host to show and log: started, each tool call and model call, stalled * or moving again, finished. Called off the caller's thread, outside any lock. + * To delete the conversation, start a separate coroutine and return from the callback; synchronous deletion is rejected. */ fun onStatus(listener: ((SubagentStatus) -> Unit)?) { statusListener = listener @@ -114,6 +125,37 @@ class Subagents( } } + /** Deletion waits for child finalizers and discards reports belonging to the removed conversation. */ + internal suspend fun drainSession(parentSessionId: String) = withContext(NonCancellable) { + val sessions = linkedSetOf(parentSessionId) + var deliveries: List> = emptyList() + val stopped = synchronized(lock) { + do { + val count = sessions.size + children.values.filter { it.spec.parentSessionId in sessions }.forEach { sessions += it.spec.sessionId } + } while (sessions.size != count) + drainingSessions.addAll(sessions) + deliveries = sessions.filter { (activeDeliveries[it] ?: 0) > 0 } + .map { deliveryDrains.getOrPut(it) { CompletableDeferred() } } + pendingReports.removeAll { it.parentSessionId in sessions } + children.values.filter { it.spec.parentSessionId in sessions }.onEach { it.handedOver = true } + } + try { + stopped.forEach { child -> + settle(child, SubagentState.CANCELLED, error = "The conversation was deleted.") + child.job?.cancel() + } + stopped.mapNotNull { it.job }.joinAll() + deliveries.forEach { it.await() } + } finally { + synchronized(lock) { + stopped.forEach { children.remove(it.spec.id); activeRuns.remove(it.ownerRunId) } + pendingReports.removeAll { it.parentSessionId in sessions } + drainingSessions.removeAll(sessions) + } + } + } + internal suspend fun execute(toolName: String, argumentsJson: String, call: SubagentCall): String { val arguments = runCatching { Json.parseToJsonElement(argumentsJson) as? JsonObject }.getOrNull() ?: JsonObject(emptyMap()) return when (toolName) { @@ -144,6 +186,7 @@ class Subagents( return failure("SUBAGENT_TYPE_UNKNOWN", "There is no agent type $agentType (types: $known); leave agent out for a general subagent.") } val child = synchronized(lock) { + if (call.sessionId in drainingSessions) return failure("SUBAGENT_SESSION_DELETED", "The conversation is being deleted.") val depth = (children.values.firstOrNull { it.spec.sessionId == call.sessionId }?.spec?.depth ?: 0) + 1 if (depth > config.maxDepth) { return failure("SUBAGENT_DEPTH_LIMIT", "A subagent cannot start subagents of its own; do the work yourself.") @@ -168,12 +211,10 @@ class Subagents( approvalPolicy = call.approvalPolicy, ) activeRuns += call.runId - Child(spec, nowEpochMillis()).also { children[id] = it } + registerChild(spec) } - // Assigned before it starts: a conversation closed right after the spawn must find the job to stop it. - val job = scope.launch(start = CoroutineStart.LAZY) { runChild(child) } - child.job = job - job.start() + // Registered with the child under the same lock: deletion always sees the job it must cancel and join. + child.job?.start() startWatchdog() notifyStatus(child) return buildJsonObject { @@ -184,6 +225,11 @@ class Subagents( }.toString() } + private fun registerChild(spec: SubagentSpec): Child = Child(spec, nowEpochMillis()).also { child -> + children[spec.id] = child + child.job = scope.launch(start = CoroutineStart.LAZY) { runChild(child) } + } + private suspend fun waitFor(arguments: JsonObject, call: SubagentCall): String { val ids = (arguments["ids"] as? JsonArray)?.mapNotNull { (it as? JsonPrimitive)?.contentOrNull }?.toSet() val timeoutMillis = ((arguments["timeout_seconds"] as? JsonPrimitive)?.intOrNull ?: DEFAULT_WAIT_SECONDS) @@ -314,7 +360,12 @@ class Subagents( private fun notifyStatus(child: Child) { val listener = statusListener ?: return - listener(synchronized(lock) { child.status() }) + val status = synchronized(lock) { + if (children[child.spec.id] !== child || child.spec.parentSessionId in drainingSessions) return + beginDelivery(child.spec.parentSessionId) + child.status() + } + deliver(child.spec.parentSessionId) { listener(status) } } private fun startWatchdog() { @@ -364,8 +415,46 @@ class Subagents( } private fun report(report: SubagentReport) { - val target = synchronized(lock) { listener ?: run { pendingReports += report; null } } - target?.invoke(report) + val delivery = synchronized(lock) { + if (report.parentSessionId in drainingSessions) return + val accepted = report.copy(statuses = report.statuses.filter { children[it.id]?.spec?.parentSessionId == report.parentSessionId }) + .takeIf { it.statuses.isNotEmpty() } ?: return + val target = listener ?: run { pendingReports += accepted; return } + beginDelivery(report.parentSessionId) + accepted to target + } + deliver(report.parentSessionId) { delivery.second(delivery.first) } + } + + /** Caller holds [lock]; a deletion marks the session before registering its delivery barrier. */ + private fun beginDelivery(sessionId: String) { activeDeliveries[sessionId] = (activeDeliveries[sessionId] ?: 0) + 1 } + + private fun endDelivery(sessionId: String) = synchronized(lock) { + val remaining = activeDeliveries.getValue(sessionId) - 1 + if (remaining == 0) { activeDeliveries.remove(sessionId); deliveryDrains.remove(sessionId)?.complete(Unit) } + else activeDeliveries[sessionId] = remaining + } + + private fun deliver(sessionId: String, callback: () -> Unit) { + val previous = CALLBACK_SESSIONS.get().orEmpty() + val ancestors = synchronized(lock) { + generateSequence(sessionId) { id -> children.values.firstOrNull { it.spec.sessionId == id }?.spec?.parentSessionId }.toSet() + } + CALLBACK_SESSIONS.set(previous + ancestors) + try { callback() } finally { + if (previous.isEmpty()) CALLBACK_SESSIONS.remove() else CALLBACK_SESSIONS.set(previous) + endDelivery(sessionId) + } + } + + internal companion object { + private val CALLBACK_SESSIONS = ThreadLocal>() + + internal fun checkDeletionAllowed(threadId: String) { + check(CALLBACK_SESSIONS.get()?.contains(threadId) != true) { + "Cannot delete a conversation synchronously from its subagent callback. Schedule deletion after returning." + } + } } private inner class Child(val spec: SubagentSpec, val startedAt: Long) { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt index 01f3ecc..49a2caa 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt @@ -66,6 +66,7 @@ internal class DefaultThreadRuntime( override suspend fun deleteThread(threadId: String) { checkOpen() + cc.noharry.agent.runtime.Subagents.checkDeletionAllowed(threadId) val executing = currentCoroutineContext()[ThreadExecutionContext] check(executing?.ownsActiveTurn(store.coordination, threadId) != true) { "Cannot delete a thread from its own active turn. Delete it after the turn completes." diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadChildDeletionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadChildDeletionTest.kt new file mode 100644 index 0000000..773e20e --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadChildDeletionTest.kt @@ -0,0 +1,140 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.spi.model.ModelEvent +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.flow +import org.junit.Assert.* +import org.junit.Test + +class ThreadChildDeletionTest { + @Test fun aGrandchildCallbackCannotSynchronouslyDeleteItsAncestorConversation() = runBlocking { + val subagents = Subagents(config = SubagentConfig(maxDepth = 2), launcher = { flow { + emit(ThreadEvent.TurnCompleted(TurnResult("child", TurnStatus.COMPLETED, "report", emptyList()))) + } }) + threadBuilder(ThreadScriptModel(listOf(finishEvents("ready"), finishEvents("usable")))) + .subagents(subagents).build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "parent")) + thread.run("hello") + subagents.execute("spawn_agent", """{"task":"child"}""", SubagentCall("parent", "parent-run", null)) + withTimeout(5000) { while (subagents.statuses("parent").none { it.state.finished }) yield() } + val childSession = subagents.statuses("parent").single().sessionId + subagents.execute("spawn_agent", """{"task":"grandchild"}""", SubagentCall(childSession, "child-run", null)) + withTimeout(5000) { while (subagents.statuses(childSession).none { it.state.finished }) yield() } + subagents.runEnded("child-run") + var failure: Throwable? = null + subagents.onReport { failure = runCatching { runBlocking { runtime.deleteThread("parent") } }.exceptionOrNull() } + assertTrue(failure is IllegalStateException) + assertTrue(failure?.message.orEmpty().contains("subagent callback")) + assertEquals(TurnStatus.COMPLETED, thread.run("again").status) + runtime.deleteThread("parent") + assertTrue(runtime.listThreads().isEmpty()) + } + } + + @Test fun synchronousDeletionFromAReportCallbackIsRejectedBeforeInvalidatingTheThread() = runBlocking { + val finished = CompletableDeferred() + val subagents = Subagents(launcher = { flow { + emit(ThreadEvent.TurnCompleted(TurnResult("child", TurnStatus.COMPLETED, "old report", emptyList()))) + finished.complete(Unit) + } }) + threadBuilder(ThreadScriptModel(listOf(finishEvents("ready"), finishEvents("still usable")))) + .subagents(subagents).build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "parent")) + thread.run("hello") + subagents.execute("spawn_agent", """{"task":"work"}""", SubagentCall("parent", "parent-run", null)) + withTimeout(5000) { finished.await() } + subagents.runEnded("parent-run") + var failure: Throwable? = null + subagents.onReport { failure = runCatching { runBlocking { runtime.deleteThread("parent") } }.exceptionOrNull() } + assertTrue(failure is IllegalStateException) + assertTrue(failure?.message.orEmpty().contains("subagent callback")) + assertEquals(TurnStatus.COMPLETED, thread.run("again").status) + runtime.deleteThread("parent") + assertTrue(runtime.listThreads().isEmpty()) + } + } + + @Test fun deletionWaitsForQueuedReportDeliveryOnAnUnrelatedRegistrationThread() = runBlocking { + val finished = CompletableDeferred() + val subagents = Subagents(launcher = { flow { + emit(ThreadEvent.TurnCompleted(TurnResult("child", TurnStatus.COMPLETED, "old report", emptyList()))) + finished.complete(Unit) + } }) + val parent = SubagentCall("parent", "old-run", null) + subagents.execute("spawn_agent", """{"task":"old task"}""", parent) + withTimeout(5000) { finished.await() } + subagents.runEnded(parent.runId) + val entered = java.util.concurrent.CountDownLatch(1) + val release = java.util.concurrent.CountDownLatch(1) + val pool = java.util.concurrent.Executors.newSingleThreadExecutor() + try { + val registration = pool.submit { subagents.onReport { + entered.countDown(); check(release.await(5, java.util.concurrent.TimeUnit.SECONDS)) + } } + assertTrue(entered.await(5, java.util.concurrent.TimeUnit.SECONDS)) + val deletion = async { subagents.drainSession("parent") } + assertNull(withTimeoutOrNull(100) { deletion.await(); "deleted" }) + release.countDown() + withTimeout(5000) { deletion.await() } + registration.get(5, java.util.concurrent.TimeUnit.SECONDS) + val recreatedReports = mutableListOf() + subagents.onReport { recreatedReports += it } + subagents.execute("spawn_agent", """{"task":"new task"}""", SubagentCall("parent", "new-run", null)) + withTimeout(5000) { while (subagents.statuses("parent").none { it.state.finished }) yield() } + subagents.runEnded("new-run") + assertEquals(listOf("new task"), recreatedReports.flatMap { it.statuses }.map { it.task }) + } finally { release.countDown(); pool.shutdownNow(); subagents.drainSession("parent") } + } + + @Test fun deletionWaitsForLateChildCleanupAndItsReportCannotReachTheRecreatedThread() = runBlocking { + val entered = CompletableDeferred() + val cleaning = CompletableDeferred() + val releaseCleanup = CompletableDeferred() + val cleaned = CompletableDeferred() + val reports = java.util.Collections.synchronizedList(mutableListOf()) + val subagents = Subagents(launcher = { flow { + entered.complete(Unit) + try { awaitCancellation() } finally { withContext(NonCancellable) { + cleaning.complete(Unit); releaseCleanup.await(); cleaned.complete(Unit) + } } + } }) + subagents.onReport { reports += it } + val model = ThreadScriptModel(listOf( + listOf(ModelEvent.ToolCall("child", "spawn_agent", """{"task":"background work"}"""), ModelEvent.Completed), + finishEvents("started"), finishEvents("fresh"), + )) + threadBuilder(model).subagents(subagents).build().use { runtime -> + runtime.startThread(ThreadOptions(threadId = "parent")).run("delegate") + withTimeout(5000) { entered.await() } + val deleting = async { runtime.deleteThread("parent") } + withTimeout(5000) { cleaning.await() } + assertFalse(deleting.isCompleted) + releaseCleanup.complete(Unit) + withTimeout(5000) { deleting.await() } + assertTrue(cleaned.isCompleted) + assertFalse(subagents.hasUnfinished("parent")) + assertEquals(TurnStatus.COMPLETED, runtime.startThread(ThreadOptions(threadId = "parent")).run("new conversation").status) + assertTrue(reports.isEmpty()) + } + } + + @Test fun deletionDiscardsReportsQueuedBeforeAListenerWasAttached() = runBlocking { + val completed = CompletableDeferred() + val subagents = Subagents(launcher = { spec -> flow { + emit(ThreadEvent.TurnCompleted(TurnResult("child-turn", TurnStatus.COMPLETED, "old report", emptyList()))) + completed.complete(Unit) + } }) + val parent = SubagentCall("parent", "parent-run", null) + subagents.execute("spawn_agent", """{"task":"finish quickly"}""", parent) + withTimeout(5000) { completed.await() } + subagents.runEnded(parent.runId) + subagents.drainSession("parent") + val reports = mutableListOf() + subagents.onReport { reports += it } + assertTrue(reports.isEmpty()) + assertTrue(subagents.statuses("parent").isEmpty()) + } +} From f25600d13c7670b91212f053b6c066b5f1c30c64 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:03:16 -0800 Subject: [PATCH 24/40] test(runtime): verify tool policies and images through live approvals Co-Authored-By: Codex --- .../agent/runtime/RuntimeHookPolicyTest.kt | 91 ++++++------------- .../agent/runtime/RuntimeLoopBudgetTest.kt | 14 +-- .../agent/runtime/ThreadRuntimeFixtures.kt | 22 +++++ .../agent/runtime/ToolResultImageLoopTest.kt | 12 +-- 4 files changed, 61 insertions(+), 78 deletions(-) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt index f9ac327..742d2ed 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeHookPolicyTest.kt @@ -2,7 +2,9 @@ package cc.noharry.agent.runtime import cc.noharry.agent.spi.AgentEvent -import cc.noharry.agent.spi.ConfirmationResumeResult +import cc.noharry.agent.Approval +import cc.noharry.agent.ThreadEvent +import cc.noharry.agent.TurnStatus import cc.noharry.agent.spi.HookContext import cc.noharry.agent.spi.HookDecision import cc.noharry.agent.spi.HookFailurePolicy @@ -328,18 +330,13 @@ class RuntimeHookPolicyTest { .toolProvider(backend) .hook(confirmUntilApproved()) .modelClient(backendThenFinishModel(seenRequests)) - .buildEngine() + .build() - val pending = runtime.run(agentRequest()).toList() - .filterIsInstance() - .single() - .pending - val accepted = runtime.resumeConfirmation(approve(pending.pendingId)) + val events = runtime.use { it.startThread().collectApproving(agentRequest().input) } - assertEquals(ConfirmationResumeResult.Accepted, accepted) assertEquals(listOf("set_temperature"), backend.calledTools) - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRuntimeResult("request-1")?.status) - assertEquals("recovered", runtime.getRuntimeResult("request-1")?.response) + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) + assertEquals("recovered", (events.last() as ThreadEvent.TurnCompleted).result.finalResponse) } @Test @@ -350,7 +347,8 @@ class RuntimeHookPolicyTest { "not-json" to MCP_RESULT_INVALID_JSON_CODE, ) - failures.forEachIndexed { index, (resultJson, expectedCode) -> + failures.forEach { (resultJson, expectedCode) -> + val requests = mutableListOf() val backend = LoopMcpProvider( resultJson = resultJson, exposedTools = listOf(mcpTool("set_temperature")), @@ -359,18 +357,13 @@ class RuntimeHookPolicyTest { .workspaceRoot(hookWorkspace()) .toolProvider(backend) .hook(confirmUntilApproved()) - .modelClient(backendThenFinishModel(mutableListOf())) - .buildEngine() + .modelClient(backendThenFinishModel(requests)) + .build() - val pending = runtime.run(agentRequest().copy(requestId = "confirmed-failure-$index")).toList() - .filterIsInstance() - .single() - .pending - - assertEquals(ConfirmationResumeResult.Accepted, runtime.resumeConfirmation(approve(pending.pendingId))) - val result = runtime.getRuntimeResult("confirmed-failure-$index") - assertEquals(RuntimeRunStatus.FAILED, result?.status) - assertEquals(expectedCode, result?.errorCode) + val events = runtime.use { it.startThread().collectApproving(agentRequest().input) } + val failure = (events.last() as ThreadEvent.TurnFailed).error + assertEquals(expectedCode, failure.code) + assertEquals(2, requests.size) assertEquals(listOf("set_temperature"), backend.calledTools) } } @@ -385,15 +378,10 @@ class RuntimeHookPolicyTest { .hook(rewriteToolArguments("set_temperature", TEMPERATURE_REWRITE_ARGS)) .hook(confirmUntilApproved()) .modelClient(backendThenFinishModel(seenRequests)) - .buildEngine() + .build() - val pending = runtime.run(agentRequest()).toList() - .filterIsInstance() - .single() - .pending - val accepted = runtime.resumeConfirmation(approve(pending.pendingId)) + runtime.use { it.startThread().collectApproving(agentRequest().input) } - assertEquals(ConfirmationResumeResult.Accepted, accepted) assertEquals(listOf("set_temperature"), backend.calledTools) assertEquals(listOf(TEMPERATURE_REWRITE_ARGS), backend.calledArguments) } @@ -411,15 +399,10 @@ class RuntimeHookPolicyTest { """.trimIndent(), ) .modelClient(backendThenFinishModel(seenRequests)) - .buildEngine() + .build() - val pending = runtime.run(agentRequest()).toList() - .filterIsInstance() - .single() - .pending - val accepted = runtime.resumeConfirmation(approve(pending.pendingId)) + runtime.use { it.startThread().collectApproving(agentRequest().input) } - assertEquals(ConfirmationResumeResult.Accepted, accepted) assertEquals(listOf("set_temperature"), backend.calledTools) } @@ -433,11 +416,11 @@ class RuntimeHookPolicyTest { .policyConfigJson(BACKEND_DENY_POLICY) .hook(confirmUntilApproved()) .modelClient(backendThenFinishModel(seenRequests)) - .buildEngine() + .build() - val events = runtime.run(agentRequest()).toList() + val events = runtime.use { it.startThread().runStreamed(agentRequest().input).toList() } - assertTrue(events.filterIsInstance().isEmpty()) + assertTrue(events.none { it is ThreadEvent.ItemStarted && it.item is Approval }) assertTrue(backend.calledTools.isEmpty()) assertTrue(seenRequests.containsToolResult("POLICY_DENIED")) assertTrue(seenRequests.containsToolResult("policy blocked")) @@ -453,18 +436,13 @@ class RuntimeHookPolicyTest { .policyConfigJson(BACKEND_CONFIRM_POLICY) .hook(confirmWithPrompt("Host needs approval", "Host approval?")) .modelClient(backendThenFinishModel(seenRequests)) - .buildEngine() + .build() - val pending = runtime.run(agentRequest()).toList() - .filterIsInstance() - .single() - .pending - val prompt = runtime.getRuntimeHandoff("request-1")?.nextActions?.single().orEmpty() - val accepted = runtime.resumeConfirmation(approve(pending.pendingId)) + var prompt = "" + runtime.use { it.startThread().collectApproving(agentRequest().input) { approval -> prompt = approval.reason } } assertTrue(prompt.contains("Approve backend?")) assertTrue(prompt.contains("Host approval?")) - assertEquals(ConfirmationResumeResult.Accepted, accepted) assertEquals(listOf("set_temperature"), backend.calledTools) } @@ -480,16 +458,12 @@ class RuntimeHookPolicyTest { .toolProvider(backend) .hook(alwaysAsks, ToolMatcher.source(ToolSource.BACKEND)) .modelClient(backendThenFinishModel(mutableListOf())) - .buildEngine() + .build() - val pending = runtime.run(agentRequest()).toList() - .filterIsInstance() - .single() - .pending + val events = runtime.use { it.startThread().collectApproving(agentRequest().input) } - assertEquals(ConfirmationResumeResult.Accepted, runtime.resumeConfirmation(approve(pending.pendingId))) assertEquals(listOf("set_temperature"), backend.calledTools) - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRuntimeResult("request-1")?.status) + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) } @Test @@ -617,15 +591,10 @@ class RuntimeHookPolicyTest { .toolProvider(backend) .policyConfigPath("/config/policy/backend-confirm.json") .modelClient(backendThenFinishModel(seenRequests)) - .buildEngine() + .build() - val pending = runtime.run(agentRequest()).toList() - .filterIsInstance() - .single() - .pending - val accepted = runtime.resumeConfirmation(approve(pending.pendingId)) + runtime.use { it.startThread().collectApproving(agentRequest().input) } - assertEquals(ConfirmationResumeResult.Accepted, accepted) assertEquals(listOf("set_temperature"), backend.calledTools) } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeLoopBudgetTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeLoopBudgetTest.kt index a8bc115..8d7211d 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeLoopBudgetTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeLoopBudgetTest.kt @@ -2,7 +2,8 @@ package cc.noharry.agent.runtime import cc.noharry.agent.spi.AgentEvent -import cc.noharry.agent.spi.ConfirmationResumeResult +import cc.noharry.agent.ThreadEvent +import cc.noharry.agent.TurnStatus import cc.noharry.agent.spi.model.ModelEvent import cc.noharry.agent.spi.model.ModelRequest import cc.noharry.agent.spi.reliability.RuntimeErrorCode @@ -150,18 +151,13 @@ class RuntimeLoopBudgetTest { .workspaceRoot(workspace()) .hook(confirmUntilApproved()) .modelClient(backendThenFinishModel(seenRequests)) - .buildEngine() + .build() - val pending = runtime.run(agentRequest()).toList() - .filterIsInstance() - .single() - .pending - val accepted = runtime.resumeConfirmation(approve(pending.pendingId)) + val events = runtime.use { it.startThread().collectApproving(agentRequest().input) } val resumedMessages = seenRequests.last().messages val assistantIndex = resumedMessages.indexOfFirst { it.toolCallId == "tool-1" } - assertEquals(ConfirmationResumeResult.Accepted, accepted) - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRuntimeResult("request-1")?.status) + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) assertTrue(assistantIndex >= 0) assertEquals("assistant", resumedMessages[assistantIndex].role) assertEquals("tool", resumedMessages[assistantIndex + 1].role) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadRuntimeFixtures.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadRuntimeFixtures.kt index a51585a..ebc5803 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadRuntimeFixtures.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadRuntimeFixtures.kt @@ -39,6 +39,28 @@ internal fun assertTurnEvents(events: List) { assertTrue(open.isEmpty()) } +/** Drives the real approval card in its original turn and verifies that the fixture actually reached a gate. */ +internal suspend fun AgentThread.collectApproving( + input: String, + options: TurnOptions = TurnOptions(), + inspect: suspend (Approval) -> Unit = {}, +): List { + val events = mutableListOf() + var approvals = 0 + runStreamed(input, options).collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) { + approvals++ + val pending = event.item as Approval + inspect(pending) + assertEquals(RespondResult.ACCEPTED, pending.approve()) + } + } + assertTrue("Expected an approval gate", approvals > 0) + assertTurnEvents(events) + return events +} + internal class ThreadScriptModel( private val scripts: List>, val requests: MutableList = mutableListOf(), diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ToolResultImageLoopTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ToolResultImageLoopTest.kt index 2ba18ae..96b3542 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ToolResultImageLoopTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ToolResultImageLoopTest.kt @@ -1,7 +1,6 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime -import cc.noharry.agent.spi.AgentEvent import cc.noharry.agent.spi.HookContext import cc.noharry.agent.spi.HookDecision import cc.noharry.agent.spi.ProviderConcurrencyDeclaration @@ -16,7 +15,6 @@ import cc.noharry.agent.spi.model.ModelEvent import cc.noharry.agent.spi.model.ModelImage import cc.noharry.agent.spi.model.ModelMessage import cc.noharry.agent.spi.model.ModelRequest -import kotlinx.coroutines.flow.toList import kotlinx.coroutines.runBlocking import org.junit.Assert.assertEquals import org.junit.Assert.assertTrue @@ -29,7 +27,7 @@ class ToolResultImageLoopTest { fun providerScreenshotReachesTheNextModelRequest() = runBlocking { val seen = mutableListOf() - runtime(seen, imageInput = true).run(agentRequest()).toList() + runtime(seen, imageInput = true).use { it.startThread().run(agentRequest().input) } val toolMessage = seen[2].screenshotResult() assertEquals(listOf(SCREENSHOT_PATH), toolMessage.images.map { it.sourcePath }) @@ -40,7 +38,7 @@ class ToolResultImageLoopTest { fun textOnlyModelGetsAPlaceholderInstead() = runBlocking { val seen = mutableListOf() - runtime(seen, imageInput = false).run(agentRequest()).toList() + runtime(seen, imageInput = false).use { it.startThread().run(agentRequest().input) } val toolMessage = seen[2].screenshotResult() assertTrue(toolMessage.images.isEmpty()) @@ -52,9 +50,7 @@ class ToolResultImageLoopTest { val seen = mutableListOf() val runtime = runtime(seen, imageInput = true, confirmation = ConfirmBackendCalls) - val pending = runtime.run(agentRequest()).toList() - .filterIsInstance().single().pending.pendingId - runtime.resumeConfirmation(approve(pending)) + runtime.use { it.startThread().collectApproving(agentRequest().input) } val toolMessage = seen.last().screenshotResult() assertEquals(listOf(SCREENSHOT_PATH), toolMessage.images.map { it.sourcePath }) @@ -77,7 +73,7 @@ class ToolResultImageLoopTest { seenRequests = seen, ), ) - .buildEngine() + .build() private fun ModelRequest.screenshotResult(): ModelMessage = messages.single { it.role == "tool" && it.toolName == qualifiedMcpTool(TOOL_NAME) } From ed3e0a0c8b10ffca0492205e6eeb777a75d76271 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:09:09 -0800 Subject: [PATCH 25/40] refactor(storage): separate turn snapshots and share image blobs Co-Authored-By: Codex --- CHANGELOG.md | 4 + .../agent/runtime/thread/ModelHistoryCodec.kt | 25 +++--- .../agent/runtime/thread/ThreadBlobStore.kt | 34 ++++++++ .../agent/runtime/thread/ThreadItemCodec.kt | 7 +- .../agent/runtime/thread/ThreadRecordCodec.kt | 19 +++-- .../agent/runtime/thread/ThreadStore.kt | 64 ++++++++++----- .../agent/runtime/ThreadStorageLayoutTest.kt | 78 +++++++++++++++++++ .../agent/runtime/ThreadStoragePrivacyTest.kt | 4 +- 8 files changed, 192 insertions(+), 43 deletions(-) create mode 100644 agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadBlobStore.kt create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStorageLayoutTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 642d90c..538178f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Conversation snapshots are stored once per turn.** A small metadata file serves thread listing; each result has + its own file, and visible snapshots and provider history share content-addressed image blobs. Disk-backed threads + release complete result objects after saving. Earlier development snapshots migrate from the inline layout on load. + - **Thread deletion drains background children.** Their jobs are cancelled and joined before storage is removed; queued reports are discarded so a late child cannot report into a recreated conversation with the same id. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ModelHistoryCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ModelHistoryCodec.kt index 5b1f919..7260504 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ModelHistoryCodec.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ModelHistoryCodec.kt @@ -14,24 +14,24 @@ import kotlinx.serialization.json.put /** Provider history preserves signed thinking, tool payloads and images exactly; it is not a public log. */ internal object ModelHistoryCodec { - fun encode(history: StoredSessionHistory): JsonObject = buildJsonObject { + fun encode(history: StoredSessionHistory, blobs: ThreadBlobStore? = null): JsonObject = buildJsonObject { put("version", 1) - put("runs", JsonArray(history.runs.map { JsonArray(it.map(::message)) })) + put("runs", JsonArray(history.runs.map { run -> JsonArray(run.map { message(it, blobs) }) })) history.lastInputTokens?.let { put("lastInputTokens", it) } } - fun decode(value: JsonObject): StoredSessionHistory { + fun decode(value: JsonObject, blobs: ThreadBlobStore? = null): StoredSessionHistory { require(value.number("version") == 1) { "Unsupported model history version" } return StoredSessionHistory( - value.array("runs").map { run -> (run as JsonArray).map { message(it as JsonObject) } }, + value.array("runs").map { run -> (run as JsonArray).map { message(it as JsonObject, blobs) } }, value.optionalLong("lastInputTokens"), ) } - private fun message(value: ModelMessage): JsonObject = buildJsonObject { + private fun message(value: ModelMessage, blobs: ThreadBlobStore?): JsonObject = buildJsonObject { put("role", value.role) put("content", value.content) - put("images", JsonArray(value.images.map(::image))) + put("images", JsonArray(value.images.map { image(it, blobs) })) value.toolCallId?.let { put("toolCallId", it) } value.toolName?.let { put("toolName", it) } value.toolArgumentsJson?.let { put("toolArgumentsJson", it) } @@ -41,9 +41,9 @@ internal object ModelHistoryCodec { put("assistantText", value.assistantText) } - private fun message(value: JsonObject): ModelMessage = ModelMessage( + private fun message(value: JsonObject, blobs: ThreadBlobStore?): ModelMessage = ModelMessage( role = value.text("role"), content = value.text("content"), - images = value.array("images").map { image(it as JsonObject) }, + images = value.array("images").map { image(it as JsonObject, blobs) }, toolCallId = value.optionalText("toolCallId"), toolName = value.optionalText("toolName"), toolArgumentsJson = value.optionalText("toolArgumentsJson"), thinkingSignature = value.optionalText("thinkingSignature"), @@ -51,15 +51,16 @@ internal object ModelHistoryCodec { assistantText = value.text("assistantText"), reasoningContent = value.optionalText("reasoningContent"), ) - private fun image(value: ModelImage): JsonObject = buildJsonObject { - put("bytes", Base64.getEncoder().encodeToString(value.bytes)) + private fun image(value: ModelImage, blobs: ThreadBlobStore?): JsonObject = buildJsonObject { + if (blobs == null) put("bytes", Base64.getEncoder().encodeToString(value.bytes)) + else { put("blobSha256", blobs.put(value.bytes)); put("byteSize", value.bytes.size) } put("mediaType", value.mediaType) put("sourcePath", value.sourcePath) put("detail", value.detail) } - private fun image(value: JsonObject): ModelImage = ModelImage( - Base64.getDecoder().decode(value.text("bytes")), value.text("mediaType"), value.text("sourcePath"), + private fun image(value: JsonObject, blobs: ThreadBlobStore?): ModelImage = ModelImage( + imageBytes(value, blobs), value.text("mediaType"), value.text("sourcePath"), value.optionalText("detail") ?: "auto", ) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadBlobStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadBlobStore.kt new file mode 100644 index 0000000..50ed538 --- /dev/null +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadBlobStore.kt @@ -0,0 +1,34 @@ +package cc.noharry.agent.runtime.thread + +import java.io.File +import java.security.MessageDigest +import java.util.Base64 +import kotlinx.serialization.json.JsonObject + +/** One thread's content-addressed image bytes, shared by visible snapshots and provider history. */ +internal class ThreadBlobStore(private val root: File) { + fun put(bytes: ByteArray): String { + val sha = storageHash(bytes) + val target = File(root, sha) + if (!target.isFile || !target.readBytes().contentEquals(bytes)) atomicWrite(target, bytes) + return sha + } + + fun read(sha: String): ByteArray { + require(SHA256.matches(sha)) { "Invalid thread image reference" } + val target = File(root, sha) + check(target.isFile) { "Missing thread image" } + val bytes = target.readBytes() + check(storageHash(bytes) == sha) { "Corrupt thread image" } + return bytes + } + + private companion object { val SHA256 = Regex("[0-9a-f]{64}") } +} + +internal fun imageBytes(value: JsonObject, blobs: ThreadBlobStore?): ByteArray = + value.optionalText("blobSha256")?.let { checkNotNull(blobs) { "Missing thread image store" }.read(it) } + ?: Base64.getDecoder().decode(value.text("bytes")) + +internal fun storageHash(bytes: ByteArray): String = MessageDigest.getInstance("SHA-256").digest(bytes) + .joinToString("") { "%02x".format(it.toInt() and 0xff) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt index 613f696..7ee7dca 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadItemCodec.kt @@ -17,6 +17,7 @@ import kotlinx.serialization.json.put internal class ThreadItemCodec( private val redactor: TraceRedactor, + private val blobs: ThreadBlobStore? = null, ) { fun encode(item: ThreadItem): JsonObject = buildJsonObject { put("id", item.id) @@ -109,7 +110,9 @@ internal class ThreadItemCodec( when (part) { is InputPart.Text -> { put("kind", "text"); put("text", part.text) } is InputPart.Image -> { - put("kind", "image"); put("bytes", Base64.getEncoder().encodeToString(part.bytes)); put("mimeType", part.mimeType) + put("kind", "image"); put("mimeType", part.mimeType) + if (blobs == null) put("bytes", Base64.getEncoder().encodeToString(part.bytes)) + else { put("blobSha256", blobs.put(part.bytes)); put("byteSize", part.bytes.size) } } is InputPart.Attachment -> { put("kind", "attachment"); put("sha256", part.ref.sha256); put("mediaType", part.ref.mediaType) @@ -120,7 +123,7 @@ internal class ThreadItemCodec( private fun input(value: JsonObject): InputPart = when (value.text("kind")) { "text" -> InputPart.Text(value.text("text")) - "image" -> InputPart.Image(Base64.getDecoder().decode(value.text("bytes")), value.text("mimeType")) + "image" -> InputPart.Image(imageBytes(value, blobs), value.text("mimeType")) "attachment" -> InputPart.Attachment(SessionAttachmentRef(value.text("sha256"), value.text("mediaType"), value.long("byteSize"), value.text("logicalName"))) else -> error("Unknown thread input kind") } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt index 554f4c9..a13f5ca 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadRecordCodec.kt @@ -23,35 +23,38 @@ internal data class ThreadRecord( internal data class StoredThread( val record: ThreadRecord, - val turns: List = emptyList(), + val turnIds: List = emptyList(), val rememberedDomains: Set = emptySet(), ) internal class ThreadRecordCodec( private val redactor: TraceRedactor, + blobs: ThreadBlobStore? = null, ) { - private val items = ThreadItemCodec(redactor) + private val items = ThreadItemCodec(redactor, blobs) fun encode(thread: StoredThread): JsonObject = buildJsonObject { - put("version", 1) + put("version", 2) put("id", thread.record.id) put("createdAt", thread.record.createdAt) put("updatedAt", thread.record.updatedAt) put("status", thread.record.status.name) put("options", options(thread.record.options)) thread.record.pendingQuestion?.let { put("pendingQuestion", items.encode(it)) } - put("turns", JsonArray(thread.turns.map(::turn))) + put("turnIds", JsonArray(thread.turnIds.map(::JsonPrimitive))) put("rememberedDomains", JsonArray(thread.rememberedDomains.map(::JsonPrimitive))) } fun decode(value: JsonObject): StoredThread { - require(value.number("version") == 1) { "Unsupported thread storage version" } + require(value.number("version") in 1..2) { "Unsupported thread storage version" } val record = ThreadRecord( value.text("id"), value.obj("options")?.let(::options) ?: ThreadOptions(), value.long("createdAt"), value.long("updatedAt"), value.enum("status", ThreadStatus.IDLE), value.obj("pendingQuestion")?.let { items.decode(it) as Question }, ) - return StoredThread(record, value.array("turns").map { turn(it as JsonObject) }, + val turns = if (value.number("version") == 1) value.array("turns").map { (it as JsonObject).text("turnId") } + else value.array("turnIds").map { (it as JsonPrimitive).content } + return StoredThread(record, turns, value.array("rememberedDomains").mapTo(linkedSetOf()) { (it as JsonPrimitive).content }) } @@ -74,7 +77,7 @@ internal class ThreadRecordCodec( instructions = value.optionalText("instructions"), approvalPolicy = value.enum("approvalPolicy", ApprovalPolicy.ASK), ) - private fun turn(turn: TurnResult): JsonObject = buildJsonObject { + fun turn(turn: TurnResult): JsonObject = buildJsonObject { put("turnId", turn.turnId); put("status", turn.status.name) put("finalResponse", turn.finalResponse) put("items", JsonArray(turn.items.map(items::encode))) @@ -89,7 +92,7 @@ internal class ThreadRecordCodec( }) } } - private fun turn(value: JsonObject): TurnResult = TurnResult( + fun turn(value: JsonObject): TurnResult = TurnResult( value.text("turnId"), value.enum("status", TurnStatus.FAILED), value.text("finalResponse"), value.array("items").map { items.decode(it as JsonObject) }, value.obj("usage")?.let { Usage(it.number("inputTokens"), it.number("outputTokens"), it.number("reasoningTokens"), it.number("cacheReadTokens"), it.number("cacheWriteTokens")) }, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt index d18eb88..f35832d 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadStore.kt @@ -3,6 +3,7 @@ package cc.noharry.agent.runtime.thread import cc.noharry.agent.* import cc.noharry.agent.kernel.core.context.SessionHistoryPersistence import cc.noharry.agent.kernel.core.context.StoredSessionHistory +import cc.noharry.agent.kernel.core.state.deleteTreeWith import cc.noharry.agent.runtime.DefaultTraceRedactor import cc.noharry.agent.runtime.TraceRedactor import java.io.File @@ -10,7 +11,6 @@ import java.io.FileOutputStream import java.nio.file.AtomicMoveNotSupportedException import java.nio.file.Files import java.nio.file.StandardCopyOption -import java.security.MessageDigest import java.util.UUID import java.util.concurrent.ConcurrentHashMap import kotlinx.serialization.json.Json @@ -19,7 +19,7 @@ import kotlinx.serialization.json.JsonObject /** One private storage root for provider history and redacted thread snapshots. Call from the runtime I/O dispatcher. */ internal class ThreadStore( root: File? = null, - redactor: TraceRedactor = DefaultTraceRedactor, + private val redactor: TraceRedactor = DefaultTraceRedactor, private val nowEpochMillis: () -> Long = System::currentTimeMillis, ) { private val root = root?.canonicalFile @@ -28,7 +28,7 @@ internal class ThreadStore( internal val attempts = ThreadAttemptStore(this.root, lock) private val codec = ThreadRecordCodec(redactor) private val memory = linkedMapOf() - private val liveTurns = linkedMapOf>() + private val memoryTurns = linkedMapOf>() private val modelMemory = mutableMapOf() init { synchronized(lock) { coordination.stores.add(this) } } @@ -69,7 +69,7 @@ internal class ThreadStore( if (generation != null && !isCurrent(threadId, generation)) return@synchronized beforeSaveTurnForTest?.invoke(result) val current = requireNotNull(read(threadId)) { "Thread does not exist: $threadId" } - val turns = current.turns.filterNot { it.turnId == result.turnId } + result + val turns = current.turnIds.filterNot { it == result.turnId } + result.turnId val pending = when { result.status == TurnStatus.WAITING_FOR_ANSWER -> result.pending as? Question result.error?.code in INPUT_REJECTION_CODES -> current.record.pendingQuestion @@ -77,21 +77,21 @@ internal class ThreadStore( } val record = current.record.copy(updatedAt = nowEpochMillis(), status = if (pending != null) ThreadStatus.WAITING_FOR_ANSWER else ThreadStatus.IDLE, pendingQuestion = pending) - write(current.copy(record = record, turns = turns)) - liveTurns.getOrPut(threadId) { linkedMapOf() }[result.turnId] = result + writeTurn(threadId, result) + write(current.copy(record = record, turnIds = turns)) } fun items(threadId: String, afterTurnId: String? = null, generation: Long? = null): List = synchronized(lock) { requireGeneration(threadId, generation) - val turns = read(threadId)?.turns.orEmpty() - val offset = afterTurnId?.let { id -> turns.indexOfFirst { it.turnId == id }.let { if (it < 0) turns.size else it + 1 } } ?: 0 - turns.drop(offset).flatMap { liveTurns[threadId]?.get(it.turnId)?.items ?: it.items } + val turns = read(threadId)?.turnIds.orEmpty() + val offset = afterTurnId?.let { id -> turns.indexOf(id).let { if (it < 0) turns.size else it + 1 } } ?: 0 + turns.drop(offset).flatMap { readTurn(threadId, it)?.items.orEmpty() } } fun turn(threadId: String, turnId: String, generation: Long? = null): TurnResult? = synchronized(lock) { requireGeneration(threadId, generation) - val saved = read(threadId)?.turns?.firstOrNull { it.turnId == turnId } ?: return@synchronized null - liveTurns[threadId]?.get(turnId) ?: saved + if (turnId !in read(threadId)?.turnIds.orEmpty()) return@synchronized null + readTurn(threadId, turnId) } fun updateOptions(threadId: String, options: ThreadOptions, generation: Long? = null) = synchronized(lock) { @@ -113,13 +113,14 @@ internal class ThreadStore( removeFile(threadId, THREAD_SUFFIX) removeFile(threadId, HISTORY_SUFFIX) deleteQuarantinedHistory(threadId) + if (root != null) check(dataDirectory(threadId).deleteTreeWith()) { "Cannot delete thread snapshots and images" } coordination.stores.forEach { it.clearCachedThread(threadId) } Unit } private fun clearCachedThread(threadId: String) { memory.remove(threadId) - liveTurns.remove(threadId) + memoryTurns.remove(threadId) modelMemory.remove(threadId) } @@ -139,7 +140,7 @@ internal class ThreadStore( override fun save(sessionId: String, history: StoredSessionHistory) = synchronized(lock) { if (root == null) modelMemory[sessionId] = history - else atomicWrite(file(sessionId, HISTORY_SUFFIX), ModelHistoryCodec.encode(history).toString()) + else atomicWrite(file(sessionId, HISTORY_SUFFIX), ModelHistoryCodec.encode(history, blobs(sessionId)).toString()) } override fun delete(sessionId: String) = synchronized(lock) { @@ -157,7 +158,7 @@ internal class ThreadStore( private fun readModelHistory(sessionId: String): StoredSessionHistory? { val target = file(sessionId, HISTORY_SUFFIX).takeIf(File::isFile) ?: return null val contents = target.readText() - return try { ModelHistoryCodec.decode(Json.parseToJsonElement(contents) as JsonObject) } catch (_: RuntimeException) { + return try { ModelHistoryCodec.decode(Json.parseToJsonElement(contents) as JsonObject, blobs(sessionId)) } catch (_: RuntimeException) { val suffix = if (File(target.path + ".corrupt").exists()) ".${UUID.randomUUID()}.corrupt" else ".corrupt" Files.move(target.toPath(), File(target.path + suffix).toPath()) null @@ -165,7 +166,27 @@ internal class ThreadStore( } private fun read(id: String): StoredThread? = if (root == null) memory[id] else { - file(id, THREAD_SUFFIX).takeIf(File::isFile)?.let { codec.decode(Json.parseToJsonElement(it.readText()) as JsonObject) } + file(id, THREAD_SUFFIX).takeIf(File::isFile)?.let { target -> + val json = Json.parseToJsonElement(target.readText()) as JsonObject + codec.decode(json).also { stored -> + if (json.number("version") == 1) { + json.array("turns").forEach { writeTurn(id, codec.turn(it as JsonObject)) } + write(stored) + } + } + } + } + + private fun readTurn(threadId: String, turnId: String): TurnResult? { + if (root == null) return memoryTurns[threadId]?.get(turnId) + val target = turnFile(threadId, turnId).takeIf(File::isFile) ?: return null + return ThreadRecordCodec(redactor, blobs(threadId)).turn(Json.parseToJsonElement(target.readText()) as JsonObject) + .also { check(it.turnId == turnId) { "Turn snapshot identity mismatch" } } + } + + private fun writeTurn(threadId: String, result: TurnResult) { + if (root == null) memoryTurns.getOrPut(threadId) { linkedMapOf() }[result.turnId] = result + else atomicWrite(turnFile(threadId, result.turnId), ThreadRecordCodec(redactor, blobs(threadId)).turn(result).toString()) } private fun write(thread: StoredThread) { @@ -180,10 +201,13 @@ internal class ThreadStore( } private fun file(id: String, suffix: String): File { - val digest = MessageDigest.getInstance("SHA-256").digest(id.toByteArray(Charsets.UTF_8)) - return File(requireNotNull(root), digest.joinToString("") { "%02x".format(it.toInt() and 0xff) } + suffix) + return File(requireNotNull(root), storageHash(id.toByteArray(Charsets.UTF_8)) + suffix) } + private fun dataDirectory(id: String): File = file(id, ".data") + private fun turnFile(threadId: String, turnId: String): File = File(dataDirectory(threadId), "turns/${storageHash(turnId.toByteArray(Charsets.UTF_8))}.json") + private fun blobs(threadId: String): ThreadBlobStore? = root?.let { ThreadBlobStore(File(dataDirectory(threadId), "blobs")) } + private companion object { val roots = ConcurrentHashMap() val INPUT_REJECTION_CODES = setOf("QUESTION_NOT_FOUND", "IMAGE_INPUT_UNSUPPORTED", "ATTACHMENT_NOT_FOUND", @@ -193,13 +217,15 @@ internal class ThreadStore( } } -internal fun atomicWrite(target: File, contents: String) { +internal fun atomicWrite(target: File, contents: String) = atomicWrite(target, contents.toByteArray(Charsets.UTF_8)) + +internal fun atomicWrite(target: File, contents: ByteArray) { val directory = requireNotNull(target.parentFile) check(directory.isDirectory || directory.mkdirs()) { "Cannot create thread storage directory" } val temporary = File(directory, ".${target.name}.${UUID.randomUUID()}.tmp") try { FileOutputStream(temporary).use { output -> - output.write(contents.toByteArray(Charsets.UTF_8)) + output.write(contents) output.fd.sync() } try { diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStorageLayoutTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStorageLayoutTest.kt new file mode 100644 index 0000000..80b41c3 --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStorageLayoutTest.kt @@ -0,0 +1,78 @@ +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import cc.noharry.agent.runtime.thread.ThreadStore +import cc.noharry.agent.runtime.thread.ThreadRecordCodec +import java.io.File +import java.util.Base64 +import kotlinx.coroutines.runBlocking +import kotlinx.serialization.json.* +import org.junit.Assert.* +import org.junit.Test + +class ThreadStorageLayoutTest { + @Test fun snapshotsAreSeparateAndRepeatedImagesAreSharedWithProviderHistory() = runBlocking { + val root = threadRoot() + val image = ByteArray(128 * 1024) { (it % 251).toByte() } + val model = ThreadScriptModel(List(12) { finishEvents("answer") }) + threadBuilder(model, root).build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "images")) + var first: File? = null + var firstText = "" + repeat(12) { index -> + thread.run(TurnInput(listOf(InputPart.Text("image $index"), InputPart.Image(image, "image/png"))), TurnOptions(turnId = "turn-$index")) + if (index == 0) { + first = snapshotFiles(root).single() + firstText = first!!.readText() + } + } + assertEquals(firstText, first!!.readText()) + assertEquals(12, snapshotFiles(root).size) + val blobs = File(root, "storage").walkTopDown().filter { it.isFile && it.parentFile.name == "blobs" && it.path.contains(".data/") }.toList() + assertEquals(1, blobs.size) + assertArrayEquals(image, blobs.single().readBytes()) + val metadata = File(root, "storage").listFiles().orEmpty().single { it.name.endsWith(".thread.json") }.readText() + assertFalse(metadata.contains("input")) + assertFalse(metadata.contains("base64")) + assertTrue(metadata.toByteArray().size < 4096) + val history = File(root, "storage").listFiles().orEmpty().single { it.name.endsWith(".history.json") }.readText() + assertTrue(history.contains("blobSha256")) + assertFalse(history.contains(Base64.getEncoder().encodeToString(image))) + } + threadBuilder(ThreadScriptModel(emptyList()), root).build().use { runtime -> + val items = runtime.resumeThread("images").items().filterIsInstance() + assertEquals(12, items.size) + items.forEach { assertArrayEquals(image, it.input.filterIsInstance().single().bytes) } + } + } + + @Test fun listingReadsOnlyMetadataEvenWhenAnOldSnapshotIsDamaged() = runBlocking { + val root = threadRoot() + threadBuilder(ThreadScriptModel(listOf(finishEvents("answer"))), root).build().use { runtime -> + runtime.startThread(ThreadOptions(threadId = "listed")).run("hello") + snapshotFiles(root).single().writeText("{invalid") + assertEquals(listOf("listed"), runtime.listThreads().map { it.id }) + } + } + + @Test fun oldInlineSnapshotsMigrateOnceWithoutLosingTheirImages() { + val root = threadRoot() + val store = ThreadStore(root) + store.create("old", ThreadOptions()) + val target = root.listFiles().orEmpty().single { it.name.endsWith(".thread.json") } + val image = byteArrayOf(1, 2, 3) + val turn = TurnResult("old-turn", TurnStatus.COMPLETED, "old answer", + listOf(ThreadItem.UserMessage("input", "old-turn", listOf(InputPart.Image(image, "image/png"))))) + val original = Json.parseToJsonElement(target.readText()).jsonObject + target.writeText(JsonObject(original + mapOf("version" to JsonPrimitive(1), + "turns" to JsonArray(listOf(ThreadRecordCodec(DefaultTraceRedactor).turn(turn)))) - "turnIds").toString()) + val restored = checkNotNull(ThreadStore(root).turn("old", "old-turn")) + assertEquals("old answer", restored.finalResponse) + assertArrayEquals(image, (restored.items.single() as ThreadItem.UserMessage).input.filterIsInstance().single().bytes) + assertEquals(2, Json.parseToJsonElement(target.readText()).jsonObject.getValue("version").jsonPrimitive.int) + assertEquals(1, root.walkTopDown().count { it.isFile && it.parentFile.name == "turns" }) + } + + private fun snapshotFiles(root: File): List = File(root, "storage").walkTopDown() + .filter { it.isFile && it.parentFile.name == "turns" }.toList() +} diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt index 1a3e2fb..13f6822 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt @@ -48,8 +48,8 @@ class ThreadStoragePrivacyTest { assertEquals(original, (items.filterIsInstance().single().input.single() as InputPart.Text).text) assertEquals(original, items.filterIsInstance().last { it.phase == MessagePhase.FINAL }.text) } - val saved = File(root, "storage").listFiles().orEmpty().single { it.name.endsWith(".thread.json") } - val turn = Json.parseToJsonElement(saved.readText()).jsonObject.getValue("turns").jsonArray.single().jsonObject + val saved = File(root, "storage").walkTopDown().single { it.isFile && it.parentFile.name == "turns" } + val turn = Json.parseToJsonElement(saved.readText()).jsonObject assertEquals(original, turn.getValue("finalResponse").jsonPrimitive.content) } From bdbdb4b79959bbb13f39a63b74e29bb1d932c523 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:15:18 -0800 Subject: [PATCH 26/40] fix(storage): count images and reasoning in model history limits Co-Authored-By: Codex --- CHANGELOG.md | 3 +++ .../core/context/SessionHistoryStore.kt | 22 +++++++++++------ .../noharry/agent/runtime/SessionHistory.kt | 9 +++---- .../core/context/SessionHistoryStoreTest.kt | 24 +++++++++++++++++-- 4 files changed, 45 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 538178f..410d36b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,9 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) +- **Model-history byte guards include multimodal and reasoning data.** Images, reasoning, thinking signatures, + assistant text and deferred-tool metadata count alongside message text when old runs are trimmed. + - **Conversation snapshots are stored once per turn.** A small metadata file serves thread listing; each result has its own file, and visible snapshots and provider history share content-addressed image blobs. Disk-backed threads release complete result objects after saving. Earlier development snapshots migrate from the inline layout on load. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt index aeaaaac..8879466 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt @@ -1,3 +1,5 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + package cc.noharry.agent.kernel.core.context import cc.noharry.agent.spi.model.ModelMessage @@ -151,10 +153,11 @@ internal class SessionHistoryStore @JvmOverloads constructor( } private fun trimmed(runs: List>): List> { - if (runs.sumOf { it.historyBytes() } <= maxBytes) return runs - var kept = runs - while (kept.isNotEmpty() && kept.sumOf { it.historyBytes() } > maxBytes / 2) kept = kept.drop(1) - return kept + var bytes = runs.sumOf { it.historyBytes() } + if (bytes <= maxBytes) return runs + var removed = 0 + while (removed < runs.size && bytes > maxBytes / 2) { bytes -= runs[removed].historyBytes(); removed += 1 } + return runs.drop(removed) } private class SessionRuns { @@ -172,10 +175,15 @@ internal class SessionHistoryStore @JvmOverloads constructor( internal fun SessionHistoryStore?.prefixed(runId: String, own: List): List = this?.prefixed(runId, own) ?: own -private fun List.historyBytes(): Int = - sumOf { it.content.utf8Size() + it.toolArgumentsJson.orEmpty().utf8Size() } +private fun List.historyBytes(): Long = sumOf { message -> + listOfNotNull(message.role, message.content, message.toolCallId, message.toolName, message.toolArgumentsJson, + message.thinkingSignature, message.reasoningContent, message.assistantText).sumOf { it.utf8Size() } + + message.toolAdditions.sumOf { it.utf8Size() } + message.images.sumOf { image -> + image.bytes.size.toLong() + image.mediaType.utf8Size() + image.sourcePath.utf8Size() + image.detail.utf8Size() + } +} -private fun String.utf8Size(): Int = toByteArray(Charsets.UTF_8).size +private fun String.utf8Size(): Long = toByteArray(Charsets.UTF_8).size.toLong() /** Each unanswered call gets its result right after it: providers such as DeepSeek reject a result that comes later. */ private fun List.withClosedToolCalls(): List { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/SessionHistory.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/SessionHistory.kt index f3e940f..ab96a00 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/SessionHistory.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/SessionHistory.kt @@ -11,13 +11,14 @@ import cc.noharry.agent.kernel.core.context.SessionHistoryStore * with the session's earlier runs (their inputs, tool calls, results and answers) and the run is appended when it ends, * so the conversation grows like one long chat and the provider's prompt cache covers everything before the new input. * A host that does this no longer needs to restate the conversation in [AgentRuntimeBuilder.runContext]. - * Memory only. + * The conversation facade binds this to its model-history storage when `storage(...)` is configured. * - * Length is kept down by conversation compaction (with [AgentRuntimeBuilder.contextWindowTokens]), which summarizes the + * Length is kept down by conversation compaction (with [LoopLimits.contextWindowTokens]), which summarizes the * oldest runs instead of dropping them. * * @param maxBytesPerSession a memory guard, not the working limit: past it the oldest runs are dropped, down to half of - * it, and the model no longer sees them. Keep it well above what the context window holds before compaction. + * it, and the model no longer sees them. Images, reasoning, thinking signatures and other replayable fields count + * toward this guard. Keep it well above what the context window holds before compaction. */ class SessionHistory @JvmOverloads constructor( maxBytesPerSession: Int = DEFAULT_MAX_BYTES_PER_SESSION, @@ -36,7 +37,7 @@ class SessionHistory @JvmOverloads constructor( internal val store = SessionHistoryStore(maxBytesPerSession, maxSessions, maxRunsInFlight) - /** The messages [sessionId]'s next run will start with; empty for a new session or after a restart. */ + /** The messages [sessionId]'s next run will start with; empty when no history is available in memory or storage. */ fun messages(sessionId: String): List = store.messages(sessionId) /** Forgets [sessionId]'s runs, e.g. when the host deletes or resets that conversation. */ diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt index 70cca7b..6d5cc02 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt @@ -1,5 +1,8 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + package cc.noharry.agent.kernel.core.context import cc.noharry.agent.spi.model.ModelMessage +import cc.noharry.agent.spi.model.ModelImage import org.junit.Assert.assertEquals import org.junit.Assert.assertTrue import org.junit.Test @@ -60,15 +63,32 @@ class SessionHistoryStoreTest { @Test fun pastTheCapWholeOldestRunsGoDownToHalf() { - val store = SessionHistoryStore(maxBytes = 40) + val store = SessionHistoryStore(maxBytes = 56) listOf("a", "b", "c", "d", "e").forEach { name -> store.start(name, "session") store.record(name, listOf(user(name.repeat(10)))) } - // 5 runs of 10 bytes exceed 40; the oldest go until at most 20 bytes are left, newest runs whole. + // Each run holds 10 content bytes and a 4-byte role. Five exceed 56, so two whole runs remain below 28. assertEquals(listOf("d".repeat(10), "e".repeat(10)), store.messages("session").map { it.content }) } + @Test + fun imagesReasoningSignaturesAndReplayMetadataCountTowardTheByteGuard() { + val messages = listOf( + ModelMessage("user", "image", images = listOf(ModelImage(ByteArray(100), "image/png", "image"))), + ModelMessage("assistant", "", reasoningContent = "r".repeat(100)), + ModelMessage("assistant", "", thinkingSignature = "s".repeat(100)), + ModelMessage("assistant", "", assistantText = "a".repeat(100)), + ModelMessage("system", "", toolAdditions = listOf("tool".repeat(30))), + ) + messages.forEach { message -> + val store = SessionHistoryStore(maxBytes = 80) + store.start("run", "session") + store.record("run", listOf(message)) + assertTrue(store.messages("session").isEmpty()) + } + } + @Test fun clearingASessionAlsoStopsARunInFlightFromWritingItBack() { val store = SessionHistoryStore() From bca628424fa4c42b261cda8404fd0f47b91326b2 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:09:14 -0800 Subject: [PATCH 27/40] test(runtime): migrate workspace and interrupted history to thread turns Co-Authored-By: Codex --- .../NativeToolLoopCompletionObligationTest.kt | 71 +++-- .../runtime/NativeToolLoopNoModelTest.kt | 12 +- .../agent/runtime/NativeToolLoopTest.kt | 43 ++- .../runtime/NativeToolLoopTestSupport.kt | 82 ------ .../NativeToolLoopToolsAndFailureTest.kt | 117 +++----- .../runtime/RuntimeWorkspaceBindingTest.kt | 272 +++++------------- 6 files changed, 173 insertions(+), 424 deletions(-) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopCompletionObligationTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopCompletionObligationTest.kt index cd67397..9bcc992 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopCompletionObligationTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopCompletionObligationTest.kt @@ -3,7 +3,11 @@ package cc.noharry.agent.runtime import cc.noharry.agent.spi.AgentEvent import cc.noharry.agent.spi.AgentRequest -import cc.noharry.agent.spi.CancelPendingConfirmationRequest +import cc.noharry.agent.Approval +import cc.noharry.agent.RespondResult +import cc.noharry.agent.ThreadEvent +import cc.noharry.agent.ThreadOptions +import cc.noharry.agent.TurnOptions import cc.noharry.agent.spi.CompletionImpact import cc.noharry.agent.spi.HookContext import cc.noharry.agent.spi.HookDecision @@ -204,15 +208,14 @@ class NativeToolLoopCompletionObligationTest { ), ), ) - .buildEngine() - val pending = runtime.run(AgentRequest("request-1", "session-1", "remember home")).toList() - .filterIsInstance() - .single() - .pending - runtime.cancelPendingConfirmation( - CancelPendingConfirmationRequest(pending.pendingId, "cancel-1", "host cancelled"), - ) - val result = runtime.getRuntimeResult("request-1")!! + .build() + val result = runtime.use { + val thread = it.startThread(ThreadOptions(threadId = "session-1")) + thread.runStreamed("remember home", TurnOptions(turnId = "request-1")).collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) thread.interrupt() + } + checkNotNull(it.diagnostics.getRuntimeResult("session-1", "request-1")) + } assertEquals(RuntimeRunStatus.CANCELLED, result.status) assertNotEquals(RuntimeCompletionOutcome.SUCCEEDED, result.completion.outcome) assertFalse(RuntimeCompletionSummary.firstPartyPass(result.status, result.completion)) @@ -220,7 +223,7 @@ class NativeToolLoopCompletionObligationTest { } @Test - fun rebuildResumeKeepsUnresolvedObserverObligation() = runBlocking { + fun approvalContinuationKeepsUnresolvedObserverObligation() = runBlocking { val runtime = AgentRuntimeBuilder.create() .workspaceRoot(Files.createTempDirectory("obligation-ws-").toFile()) .turnObserver(RecordingObserver()) @@ -229,22 +232,22 @@ class NativeToolLoopCompletionObligationTest { .modelClient( FakeModelClient(schemaThenBackendRounds(finish = true)), ) - .buildEngine() - val pending = runtime.run(AgentRequest("request-1", "session-1", "remember this")).toList() - .filterIsInstance() - .single() - runtime.resumeConfirmation(approve(pending.pending.pendingId)) - val result = requireNotNull(runtime.getRuntimeResult("request-1")) + .build() + val result = runtime.use { + it.startThread(ThreadOptions(threadId = "session-1")) + .collectApproving("remember this", TurnOptions(turnId = "request-1")) + checkNotNull(it.diagnostics.getRuntimeResult("session-1", "request-1")) + } assertFalse(RuntimeCompletionSummary.firstPartyPass(result.status, result.completion)) assertTrue(result.completion.requiredUnresolved >= 1) assertNotEquals(RuntimeCompletionOutcome.SUCCEEDED, result.completion.outcome) } @Test - fun processRestartRebuildResumeIsUnsupportedWhileObligationRemainsUnresolved() = runBlocking { + fun restartingCannotReexecuteAnInterruptedApprovalWithUnresolvedObligations() = runBlocking { val root = Files.createTempDirectory("obligation-rebuild-").toFile() val first = AgentRuntimeBuilder.create() - .reliabilityStorageRoot(root) + .reliabilityStorageRoot(root).storage(java.io.File(root, "threads")) .workspaceRoot(Files.createTempDirectory("obligation-restart-ws-").toFile()) .turnObserver(RecordingObserver()) .toolProvider(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) @@ -252,13 +255,16 @@ class NativeToolLoopCompletionObligationTest { .modelClient( FakeModelClient(schemaThenBackendRounds()), ) - .buildEngine() - val pending = first.run(AgentRequest("request-1", "session-1", "remember this")).toList() - .filterIsInstance() - .single() + .build() + first.use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "session-1")) + thread.runStreamed("remember this", TurnOptions(turnId = "request-1")).collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) thread.interrupt() + } + } val seen = mutableListOf() val restored = AgentRuntimeBuilder.create() - .reliabilityStorageRoot(root) + .reliabilityStorageRoot(root).storage(java.io.File(root, "threads")) .modelClient( FakeModelClient( eventsByRound = listOf( @@ -267,13 +273,16 @@ class NativeToolLoopCompletionObligationTest { seenRequests = seen, ), ) - .buildEngine() - val resume = restored.resumeConfirmation(approve(pending.pending.pendingId)) - assertTrue( - resume is cc.noharry.agent.spi.ConfirmationResumeResult.Rejected || - resume is cc.noharry.agent.spi.ConfirmationResumeResult.NotFound, - ) - assertTrue(seen.isEmpty()) + .build() + restored.use { runtime -> + val thread = runtime.resumeThread("session-1") + assertTrue(thread.pendingRequests().isEmpty()) + assertEquals(RespondResult.NOT_FOUND, thread.items().filterIsInstance().single().approve()) + val interrupted = checkNotNull(runtime.diagnostics.getRuntimeResult("session-1", "request-1")) + assertTrue(interrupted.completion.requiredUnresolved >= 1) + assertFalse(RuntimeCompletionSummary.firstPartyPass(interrupted.status, interrupted.completion)) + assertTrue(seen.isEmpty()) + } } @Test diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopNoModelTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopNoModelTest.kt index f03e0b5..cc22c5b 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopNoModelTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopNoModelTest.kt @@ -27,16 +27,8 @@ class NativeToolLoopNoModelTest { } @Test - fun userInputResumeFailsClosedWhenModelMissing() = runBlocking { - val outcome = loopWithoutModel().resumeUserInput( - runId = "request-1", - sessionId = "session-1", - requestId = "request-1", - answer = "more detail", - scene = null, - modelRef = null, - ) as NativeLoopOutcome.Terminal - assertNoModelFailure(outcome) + fun publicRuntimeRequiresAModelBeforeAnyTurnCanStart() { + org.junit.Assert.assertThrows(IllegalArgumentException::class.java) { AgentRuntimeBuilder.create().build() } } @Test diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopTest.kt index 8996aac..3c370a5 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopTest.kt @@ -1,4 +1,5 @@ package cc.noharry.agent.runtime +import cc.noharry.agent.ThreadEvent import cc.noharry.agent.spi.AgentEvent import cc.noharry.agent.spi.ToolCallContext import cc.noharry.agent.spi.ToolCallResult @@ -262,31 +263,23 @@ class NativeToolLoopTest { } @Test - fun resumeRejectsPureNarrationFinishWhenRetryAlreadyExistsInHistory() = runBlocking { - val historyStore = InMemoryLoopHistoryStore() - val runId = "run-invalid-finish-resume" - val secondNarration = "Now let me update the todo list and finish with a comprehensive response." - historyStore.seedInvalidFinishRetry(runId) - val seenRequests = mutableListOf() - val loop = nativeLoopWithFinishResponse( - response = secondNarration, - seenRequests = seenRequests, - historyStore = historyStore, - ) - - val outcome = loop.resumeUserInput( - runId = runId, - sessionId = "session-1", - requestId = "request-1", - answer = "continue", - scene = null, - modelRef = null, - ) as NativeLoopOutcome.Terminal - - assertEquals(RuntimeRunStatus.FAILED, outcome.result.status) - assertEquals(INVALID_FINISH_RESPONSE_CODE, outcome.result.errorCode) - assertEquals(INVALID_FINISH_RESPONSE_MESSAGE, outcome.result.response) - assertEquals(1, seenRequests.size) + fun approvalContinuationDoesNotResetAnAlreadyUsedNarrationRetry() = runBlocking { + val first = "All operations are complete. Let me now update the todo list and finish with a complete summary." + val second = "Now let me update the todo list and finish with a comprehensive response." + val model = ThreadScriptModel(listOf( + listOf(schemaRead("set_temperature"), ModelEvent.Completed), + finishEvents(first), + listOf(ModelEvent.ToolCall("action", qualifiedMcpTool("set_temperature"), "{}"), ModelEvent.Completed), + finishEvents(second), + )) + threadBuilder(model).tools(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) + .hook(confirmUntilApproved()).build().use { runtime -> + val events = runtime.startThread().collectApproving("set temperature") + val error = (events.last() as ThreadEvent.TurnFailed).error + assertEquals(INVALID_FINISH_RESPONSE_CODE, error.code) + assertEquals(INVALID_FINISH_RESPONSE_MESSAGE, error.message) + assertEquals(4, model.requests.size) + } } @Test diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopTestSupport.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopTestSupport.kt index 7ae74f0..02b4351 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopTestSupport.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopTestSupport.kt @@ -31,88 +31,6 @@ import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.flow import org.junit.Assert.assertTrue -internal fun nativeLoopWithFinishResponse( - response: String, - seenRequests: MutableList, - historyStore: InMemoryLoopHistoryStore, -): NativeToolLoop = - NativeToolLoop( - modelClient = FakeModelClient( - eventsByRound = listOf( - listOf( - ModelEvent.ToolCall("finish-2", "finish", """{"response":"$response"}"""), - ModelEvent.Completed, - ), - ), - seenRequests = seenRequests, - ), - mcpRegistry = ToolProviderRegistry(), - workspace = null, - loopHistoryStore = historyStore, - ) - -internal fun InMemoryLoopHistoryStore.seedInvalidFinishRetry(runId: String) { - save( - runId, - listOf( - ModelMessage(role = "user", content = "finish with done"), - ModelMessage( - role = "assistant", - content = "", - toolCallId = "finish-1", - toolName = "finish", - toolArgumentsJson = """{"response":"All tasks completed! Let me update the todo and provide the final response."}""", - ), - ModelMessage( - role = "tool", - content = invalidFinishResponseResult(), - toolCallId = "finish-1", - toolName = "finish", - ), - ), - ) -} - -internal fun nativeLoop( - modelClient: ModelClient, - historyStore: InMemoryLoopHistoryStore, - mcpRegistry: ToolProviderRegistry = ToolProviderRegistry(), - withWorkspace: Boolean = false, - runId: String = "request-1", -): NativeToolLoop { - val activationStore = ToolActivationStore() - val workspace = if (withWorkspace) { - val vfs = VfsFileSystem.singleFileRoot(Files.createTempDirectory("native-loop-test-").toFile()) - VirtualWorkspace( - fileSystem = vfs, - materializer = VirtualFileMaterializer( - mcpRegistry = mcpRegistry, - activationStore = activationStore, - ), - mcpRegistry = mcpRegistry, - activationStore = activationStore, - runId = runId, - ) - } else { - null - } - return NativeToolLoop( - modelClient = modelClient, - mcpRegistry = mcpRegistry, - workspace = workspace, - loopHistoryStore = historyStore, - activationStore = activationStore, - ) -} - -internal fun finishModel(response: String, seenRequests: MutableList): ModelClient = - FakeModelClient( - eventsByRound = listOf( - listOf(ModelEvent.ToolCall("finish-1", "finish", """{"response":"$response"}"""), ModelEvent.Completed), - ), - seenRequests = seenRequests, - ) - internal fun assertCancelledToolResultClosed( messages: List, toolCallId: String, diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopToolsAndFailureTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopToolsAndFailureTest.kt index 18e8e91..0a42a74 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopToolsAndFailureTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/NativeToolLoopToolsAndFailureTest.kt @@ -1,6 +1,8 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime +import cc.noharry.agent.ThreadOptions +import cc.noharry.agent.TurnStatus import cc.noharry.agent.spi.AgentEvent import cc.noharry.agent.spi.ProviderConcurrencyDeclaration import cc.noharry.agent.spi.ToolCallContext @@ -273,94 +275,45 @@ class NativeToolLoopToolsAndFailureTest { } @Test - fun cancellationAfterModelToolCallSavesSyntheticCancelledResultForResume() = runBlocking { - val historyStore = InMemoryLoopHistoryStore() - val firstLoop = nativeLoop( - modelClient = object : ModelClient { - override val providerConcurrency: ProviderConcurrencyDeclaration = - ProviderConcurrencyDeclaration.serialized() - override fun complete(request: ModelRequest): Flow = flow { - emit(ModelEvent.ToolCall("cancel-stream", "set_temperature", """{"degreesCelsius":21}""")) - throw CancellationException("stream cancelled") - } - }, - historyStore = historyStore, - mcpRegistry = ToolProviderRegistry(listOf(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature"))))), - ) - - val error = try { - firstLoop.run(agentRequest(), runId = "request-1") - null - } catch (error: CancellationException) { - error + fun cancellationAfterModelToolCallPersistsALegalResultForTheNextTurn() = runBlocking { + val root = threadRoot() + val model = object : ModelClient { + override val providerConcurrency = ProviderConcurrencyDeclaration.serialized() + override fun complete(request: ModelRequest): Flow = flow { + emit(ModelEvent.ToolCall("cancel-stream", "set_temperature", """{"degreesCelsius":21}""")) + throw CancellationException("stream cancelled") + } + } + threadBuilder(model, root).tools(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) + .build().use { runtime -> + val result = runtime.startThread(ThreadOptions(threadId = "session-1")).run("set temperature") + assertEquals(TurnStatus.INTERRUPTED, result.status) + } + val next = ThreadScriptModel(listOf(finishEvents("continued"))) + threadBuilder(next, root).build().use { runtime -> + assertEquals(TurnStatus.COMPLETED, runtime.resumeThread("session-1").run("continue").status) + assertCancelledToolResultClosed(next.requests.single().messages, "cancel-stream", "set_temperature") } - val savedHistory = requireNotNull(historyStore.read("request-1")).messages - - assertTrue(error is CancellationException) - assertCancelledToolResultClosed(savedHistory, "cancel-stream", "set_temperature") - - val resumeRequests = mutableListOf() - val resumedLoop = nativeLoop( - modelClient = finishModel("resumed", resumeRequests), - historyStore = historyStore, - ) - val resumed = resumedLoop.resumeUserInput( - runId = "request-1", - sessionId = "session-1", - requestId = "request-1", - answer = "continue", - scene = null, - modelRef = null, - ) as NativeLoopOutcome.Terminal - - assertEquals(RuntimeRunStatus.COMPLETED, resumed.result.status) - assertCancelledToolResultClosed(resumeRequests.single().messages, "cancel-stream", "set_temperature") } @Test - fun cancellationDuringBackendToolSavesSyntheticCancelledResultForResume() = runBlocking { - val historyStore = InMemoryLoopHistoryStore() + fun cancellationDuringBackendExecutionPersistsALegalResultForTheNextTurn() = runBlocking { + val root = threadRoot() val backend = CancellingMcpProvider() - val firstLoop = nativeLoop( - modelClient = FakeModelClient( - eventsByRound = listOf( - listOf(setTemperatureSchemaCall(), ModelEvent.Completed), - listOf(setTemperatureBackendCall(), ModelEvent.Completed), - ), - ), - historyStore = historyStore, - mcpRegistry = ToolProviderRegistry(listOf(backend)), - withWorkspace = true, - ) - - val error = try { - firstLoop.run(agentRequest(), runId = "request-1") - null - } catch (error: CancellationException) { - error + val model = FakeModelClient(eventsByRound = listOf( + listOf(setTemperatureSchemaCall(), ModelEvent.Completed), + listOf(setTemperatureBackendCall(), ModelEvent.Completed), + )) + threadBuilder(model, root).tools(backend).build().use { runtime -> + val result = runtime.startThread(ThreadOptions(threadId = "session-1")).run("set temperature") + assertEquals(TurnStatus.INTERRUPTED, result.status) + assertEquals(listOf("set_temperature"), backend.calledTools) + } + val next = ThreadScriptModel(listOf(finishEvents("continued"))) + threadBuilder(next, root).build().use { runtime -> + assertEquals(TurnStatus.COMPLETED, runtime.resumeThread("session-1").run("continue").status) + assertCancelledToolResultClosed(next.requests.single().messages, "backend-1", qualifiedMcpTool("set_temperature")) } - val savedHistory = requireNotNull(historyStore.read("request-1")).messages - - assertTrue(error is CancellationException) - assertEquals(listOf("set_temperature"), backend.calledTools) - assertCancelledToolResultClosed(savedHistory, "backend-1", qualifiedMcpTool("set_temperature")) - - val resumeRequests = mutableListOf() - val resumedLoop = nativeLoop( - modelClient = finishModel("resumed", resumeRequests), - historyStore = historyStore, - ) - val resumed = resumedLoop.resumeUserInput( - runId = "request-1", - sessionId = "session-1", - requestId = "request-1", - answer = "continue", - scene = null, - modelRef = null, - ) as NativeLoopOutcome.Terminal - - assertEquals(RuntimeRunStatus.COMPLETED, resumed.result.status) - assertCancelledToolResultClosed(resumeRequests.single().messages, "backend-1", qualifiedMcpTool("set_temperature")) } @Test diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeWorkspaceBindingTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeWorkspaceBindingTest.kt index f116ef4..2bc87b6 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeWorkspaceBindingTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/RuntimeWorkspaceBindingTest.kt @@ -1,233 +1,117 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime -import cc.noharry.agent.spi.AgentEvent -import cc.noharry.agent.spi.AgentRequest + +import cc.noharry.agent.* import cc.noharry.agent.spi.model.ModelEvent import cc.noharry.agent.spi.model.ModelRequest -import cc.noharry.agent.spi.reliability.RuntimeCompletionOutcome import cc.noharry.agent.spi.reliability.RuntimeErrorCode -import cc.noharry.agent.spi.reliability.RuntimeResult -import cc.noharry.agent.spi.reliability.RuntimeRunStatus -import cc.noharry.agent.kernel.core.loop.failed import cc.noharry.agent.vfs.VfsFileSystem import java.io.File import java.nio.file.Files import kotlinx.coroutines.flow.toList import kotlinx.coroutines.runBlocking -import org.junit.Assert.assertEquals -import org.junit.Assert.assertTrue +import org.junit.Assert.* import org.junit.Test class RuntimeWorkspaceBindingTest { - @Test - fun requestSelectsRegisteredWorkspaceForNativeTools() = runBlocking { + @Test fun threadSelectsRegisteredWorkspaceForNativeTools() = runBlocking { val alpha = workspace("alpha content") val beta = workspace("beta content") - val seenRequests = mutableListOf() - val runtime = AgentRuntimeBuilder.create() - .workspace(RuntimeWorkspaceRef("alpha", VfsFileSystem.singleFileRoot(alpha))) - .workspace(RuntimeWorkspaceRef("beta", VfsFileSystem.singleFileRoot(beta))) - .defaultWorkspace("alpha") - .modelClient(readThenFinishModel(seenRequests, "done")) - .buildEngine() - - val events = runtime.run(agentRequest(workspaceId = "beta")).toList() - - assertEquals("done", events.filterIsInstance().single().result.response) - assertEquals("beta", events.filterIsInstance().single().workspaceId) - assertTrue(seenRequests[1].messages.last().content.contains("beta content")) + val requests = mutableListOf() + workspaceBuilder(alpha, beta, readThenFinishModel(requests)).build().use { runtime -> + val events = runtime.startThread(ThreadOptions(workspace = "beta")).runStreamed("read note").toList() + assertEquals("done", (events.last() as ThreadEvent.TurnCompleted).result.finalResponse) + val changed = events.filterIsInstance().map { it.item } + .filterIsInstance().single { it.kind == NoticeKind.WORKSPACE_CHANGED } + assertEquals("beta", changed.details.workspaceId) + assertTrue(requests[1].messages.last().content.contains("beta content")) + } } - @Test - fun sessionInheritsLastSelectedWorkspaceWhenRequestOmitsWorkspaceId() = runBlocking { - val alpha = workspace("alpha content") - val beta = workspace("beta content") - val seenRequests = mutableListOf() - val runtime = AgentRuntimeBuilder.create() - .workspace(RuntimeWorkspaceRef("alpha", VfsFileSystem.singleFileRoot(alpha))) - .workspace(RuntimeWorkspaceRef("beta", VfsFileSystem.singleFileRoot(beta))) - .defaultWorkspace("alpha") - .modelClient(readThenFinishModel(seenRequests, "done")) - .buildEngine() - - runtime.run(agentRequest(requestId = "request-1", workspaceId = "beta")).toList() - runtime.run(agentRequest(requestId = "request-2")).toList() - - assertTrue(seenRequests[1].messages.last().content.contains("beta content")) - assertTrue(seenRequests[3].messages.last().content.contains("beta content")) + @Test fun threadRetainsSelectedWorkspaceWhenResumeOmitsTheOption() = runBlocking { + val requests = mutableListOf() + workspaceBuilder(workspace("alpha content"), workspace("beta content"), readThenFinishModel(requests)).build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(workspace = "beta")) + thread.run("read note") + runtime.resumeThread(thread.id).run("read again") + assertTrue(requests[1].messages.last().content.contains("beta content")) + assertTrue(requests[3].messages.last().content.contains("beta content")) + } } - @Test - fun sameRuntimeResumeReadsSpecifiedWorkspaceViaReadFile() = runBlocking { - val alpha = workspace("alpha-note") - val beta = workspace("beta-note") - val root = Files.createTempDirectory("workspace-resume-same-runtime-").toFile() - val seen = mutableListOf() - sameRuntime(root, alpha, beta, seen).use { runtime -> - val pending = runtime.run(agentRequest(workspaceId = "beta")).toList() - .filterIsInstance() - .single() - runtime.resumeConfirmation(approve(pending.pending.pendingId)) - val result = runtime.getRuntimeResult("request-1") - assertEquals(RuntimeRunStatus.COMPLETED, result?.status) - val toolText = seen.flatMap { it.messages }.filter { it.role == "tool" }.joinToString { it.content } + @Test fun approvalContinuationReadsTheSelectedWorkspace() = runBlocking { + val requests = mutableListOf() + workspaceBuilder(workspace("alpha-note"), workspace("beta-note"), askThenReadThenFinishModel(requests)).build().use { runtime -> + val events = runtime.startThread(ThreadOptions(workspace = "beta")).collectApproving("read note") + assertEquals(TurnStatus.COMPLETED, (events.last() as ThreadEvent.TurnCompleted).result.status) + val toolText = requests.flatMap { it.messages }.filter { it.role == "tool" }.joinToString { it.content } assertTrue(toolText.contains("beta-note")) - assertTrue(seen.flatMap { it.messages }.none { it.content.contains("alpha-note") }) + assertTrue(requests.flatMap { it.messages }.none { it.content.contains("alpha-note") }) } } - @Test - fun processRestartResumeIsUnsupportedWithoutModelOrTools() = runBlocking { + @Test fun restartingPreservesWorkspaceButCannotExecuteAnOldApproval() = runBlocking { + val root = Files.createTempDirectory("workspace-restart-").toFile() val alpha = workspace("alpha-note") val beta = workspace("beta-note") - val root = Files.createTempDirectory("workspace-resume-process-restart-").toFile() - val pending = waitingRuntime(root, alpha, beta).run(agentRequest(workspaceId = "beta")).toList() - .filterIsInstance() - .single() - val seen = mutableListOf() - resumeRuntime(root, alpha, beta, seen).use { restored -> - val result = restored.resumeConfirmation(approve(pending.pending.pendingId)) - assertTrue( - result is cc.noharry.agent.spi.ConfirmationResumeResult.Rejected || - result is cc.noharry.agent.spi.ConfirmationResumeResult.NotFound, - ) - assertEquals(emptyList(), seen) + workspaceBuilder(alpha, beta, FakeModelClient(schemaThenBackendRounds())).storage(root).build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "session-1", workspace = "beta")) + thread.runStreamed("set temperature").collect { event -> + if (event is ThreadEvent.ItemStarted && event.item is Approval) thread.interrupt() + } + } + val requests = mutableListOf() + workspaceBuilder(alpha, beta, readThenFinishModel(requests)).storage(root).build().use { restored -> + val thread = restored.resumeThread("session-1") + assertTrue(thread.pendingRequests().isEmpty()) + val old = thread.items().filterIsInstance().single() + assertEquals(RespondResult.NOT_FOUND, old.approve()) + assertTrue(requests.isEmpty()) + assertEquals(TurnStatus.COMPLETED, thread.run("read note").status) + assertTrue(requests.last().messages.any { it.role == "tool" && "beta-note" in it.content }) + assertFalse(requests.last().messages.any { "alpha-note" in it.content }) } } - @Test - fun unknownWorkspaceFailsBeforeModelCall() = runBlocking { - val seenRequests = mutableListOf() - val runtime = AgentRuntimeBuilder.create() - .workspace(RuntimeWorkspaceRef("known", VfsFileSystem.singleFileRoot(workspace("content")))) - .modelClient(readThenFinishModel(seenRequests, "done")) - .buildEngine() - - val events = runtime.run(agentRequest(workspaceId = "missing")).toList() - val result = events.filterIsInstance().single().result - val failed = events.filterIsInstance().single() - - assertEquals(emptyList(), seenRequests) - assertEquals(RuntimeRunStatus.FAILED, result.status) - assertEquals(RuntimeErrorCode.WORKSPACE_NOT_CONFIGURED.wireCode, result.errorCode) - assertEquals(RuntimeErrorCode.WORKSPACE_NOT_CONFIGURED.wireCode, failed.code) - assertTrue(failed.message.contains("missing")) + @Test fun unknownWorkspaceFailsBeforeModelCall() = runBlocking { + val requests = mutableListOf() + AgentRuntimeBuilder.create().workspace(RuntimeWorkspaceRef("known", VfsFileSystem.singleFileRoot(workspace("content")))) + .modelClient(readThenFinishModel(requests)).build().use { runtime -> + val result = runtime.startThread(ThreadOptions(workspace = "missing")).run("read note") + assertTrue(requests.isEmpty()) + assertEquals(TurnStatus.FAILED, result.status) + assertEquals(RuntimeErrorCode.WORKSPACE_NOT_CONFIGURED.wireCode, result.error?.code) + assertTrue(result.error?.message.orEmpty().contains("missing")) + } } - private fun readThenFinishModel( - seenRequests: MutableList, - response: String, - ): FakeModelClient = - FakeModelClient( - eventsByRound = listOf( - listOf(ModelEvent.ToolCall("read-1", "read_file", """{"path":"/note.txt"}"""), ModelEvent.Completed), - listOf(ModelEvent.ToolCall("finish-1", "finish", """{"response":"$response"}"""), ModelEvent.Completed), - listOf(ModelEvent.ToolCall("read-2", "read_file", """{"path":"/note.txt"}"""), ModelEvent.Completed), - listOf(ModelEvent.ToolCall("finish-2", "finish", """{"response":"$response"}"""), ModelEvent.Completed), - ), - seenRequests = seenRequests, - ) - - private fun agentRequest( - requestId: String = "request-1", - workspaceId: String? = null, - ): AgentRequest = - AgentRequest( - requestId = requestId, - sessionId = "session-1", - input = "read note", - workspaceId = workspaceId, - ) - - private fun workspace(content: String): File = - Files.createTempDirectory("runtime-workspace-binding-").toFile().canonicalFile.also { - File(it, "note.txt").writeText(content) - } - - private fun waitingRuntime(root: File, alpha: File, beta: File): cc.noharry.agent.spi.AgentRuntime = - workspaceRuntime(root, alpha, beta, askThenWaitModel()) - - private fun resumeRuntime( - root: File, - alpha: File, - beta: File, - seen: MutableList, - ): cc.noharry.agent.spi.AgentRuntime = workspaceRuntime(root, alpha, beta, readThenFinishModel(seen, "done")) - - private fun sameRuntime( - root: File, - alpha: File, - beta: File, - seen: MutableList, - ): cc.noharry.agent.spi.AgentRuntime = workspaceRuntime(root, alpha, beta, askThenReadThenFinishModel(seen, "done")) - - private fun workspaceRuntime( - root: File, - alpha: File, - beta: File, - model: FakeModelClient, - ): cc.noharry.agent.spi.AgentRuntime = + private fun workspaceBuilder(alpha: File, beta: File, model: FakeModelClient): AgentRuntimeBuilder = AgentRuntimeBuilder.create() - .reliabilityStorageRoot(root) .workspace(RuntimeWorkspaceRef("alpha", VfsFileSystem.singleFileRoot(alpha))) .workspace(RuntimeWorkspaceRef("beta", VfsFileSystem.singleFileRoot(beta))) .defaultWorkspace("alpha") .toolProvider(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) - .hook(confirmUntilApproved()) - .modelClient(model) - .buildEngine() + .hook(confirmUntilApproved()).modelClient(model) + + private fun readThenFinishModel(requests: MutableList): FakeModelClient = FakeModelClient( + eventsByRound = List(2) { index -> listOf( + listOf(ModelEvent.ToolCall("read-$index", "read_file", """{"path":"/note.txt"}"""), ModelEvent.Completed), + finishEvents("done"), + ) }.flatten(), seenRequests = requests, + ) + + private fun askThenReadThenFinishModel(requests: MutableList): FakeModelClient = FakeModelClient( + eventsByRound = listOf( + listOf(schemaRead("set_temperature"), ModelEvent.Completed), + listOf(ModelEvent.ToolCall("action", qualifiedMcpTool("set_temperature"), "{}"), ModelEvent.Completed), + listOf(ModelEvent.ToolCall("read", "read_file", """{"path":"/note.txt"}"""), ModelEvent.Completed), + finishEvents("done"), + ), seenRequests = requests, + ) - private fun askThenReadThenFinishModel( - seenRequests: MutableList, - response: String, - ): FakeModelClient = - FakeModelClient( - eventsByRound = listOf( - listOf(schemaRead("set_temperature"), ModelEvent.Completed), - listOf( - ModelEvent.ToolCall( - "tool-ask", - qualifiedMcpTool("set_temperature"), - "{}", - ), - ModelEvent.Completed, - ), - listOf(ModelEvent.ToolCall("read-1", "read_file", """{"path":"/note.txt"}"""), ModelEvent.Completed), - listOf(ModelEvent.ToolCall("finish-1", "finish", """{"response":"$response"}"""), ModelEvent.Completed), - ), - seenRequests = seenRequests, - ) - - private suspend fun assertProcessRestartAdmissionUnsupported( - result: RuntimeResult?, - runtime: cc.noharry.agent.spi.AgentRuntime, - ) { - assertEquals(RuntimeRunStatus.CANCELLED, result?.status) - assertEquals(RuntimeErrorCode.PROCESS_RESTART_ADMISSION_UNSUPPORTED.wireCode, result?.errorCode) - assertEquals(RuntimeCompletionOutcome.UNKNOWN, result?.completion?.outcome) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState("request-1")?.status) - } - - private fun askThenWaitModel(): FakeModelClient = - FakeModelClient( - eventsByRound = schemaThenBackendRounds(), - ) - - private fun resumeRequest(requestId: String = "answer-1", workspaceId: String?): AgentRequest = - AgentRequest( - requestId = requestId, - sessionId = "session-1", - input = "continue", - resumeRunId = "request-1", - workspaceId = workspaceId, - ) - - private inline fun cc.noharry.agent.spi.AgentRuntime.use(block: (cc.noharry.agent.spi.AgentRuntime) -> Unit) { - try { - block(this) - } finally { - close() + private fun workspace(content: String): File = + Files.createTempDirectory("runtime-workspace-binding-").toFile().canonicalFile.also { + File(it, "note.txt").writeText(content) } - } } From 55c7f28a26859b30d67f8f4f9742e902886635b3 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:30:51 -0800 Subject: [PATCH 28/40] fix(runtime): a new approval policy applies to the turn already running A host that changes a thread's policy (Bothy's approval mode switch) while a turn waits for an approval now has that approval decided by the new policy, and later approvals in the same turn follow it too. Thread turns no longer let the network backend remember hosts on its own, so remembered areas have one owner. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 + .../agent/kernel/core/loop/NativeToolLoop.kt | 1 + .../kernel/core/tools/MaterializerRecords.kt | 1 + .../kernel/core/tools/WorkspaceCallMapping.kt | 2 + .../agent/runtime/DefaultAgentRuntime.kt | 6 +- .../agent/runtime/NetworkToolBackend.kt | 7 +- .../runtime/thread/DefaultAgentThread.kt | 27 +++++--- .../runtime/thread/DefaultThreadRuntime.kt | 2 +- .../agent/runtime/thread/ThreadApproval.kt | 14 +++- .../agent/runtime/thread/ThreadExecution.kt | 1 + .../agent/runtime/thread/ThreadInput.kt | 4 +- .../runtime/workspace/VirtualWorkspace.kt | 2 +- .../cc/noharry/agent/spi/AgentRuntime.kt | 4 ++ .../cc/noharry/agent/spi/WorkspacePort.kt | 1 + .../agent/runtime/ThreadLivePolicyTest.kt | 65 +++++++++++++++++++ 15 files changed, 124 insertions(+), 15 deletions(-) create mode 100644 agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadLivePolicyTest.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index 410d36b..8b23569 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -84,6 +84,8 @@ called out; a patch release does not break it. - **Thread option patches preserve saved approval policy.** Null values on resume retain saved defaults; `ThreadOptions.reset` clears selected model, workspace, scene or instruction overrides. New threads still use ASK. + A policy given to `resumeThread` while a turn runs applies to that turn at once: an approval it is waiting for is + decided by the new policy (`APPROVE_ALL` approves, `DENY_ALL` denies, `REMEMBER` approves a remembered area). - **Independent budgets survive settings changes.** `LoopSettings.limits` defaults to null, so a settings call does not reset limits configured through `limits(...)`. An explicit settings budget still replaces them. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt index b24e140..3d54416 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolLoop.kt @@ -147,6 +147,7 @@ internal class NativeToolLoop( scene = request.scene, modelRef = request.modelRef, approvalPolicy = request.approvalPolicy, + approvalState = request.approvalState, ) sessionRecorder.appendMessage(toolContext, messages.first()) runContextMessage(runContext, runContextAsSystem)?.let { messages += it; sessionRecorder.appendMessage(toolContext, it) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/MaterializerRecords.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/MaterializerRecords.kt index bdddf9f..334a1ba 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/MaterializerRecords.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/MaterializerRecords.kt @@ -9,6 +9,7 @@ internal data class MaterializerContext( val modelRef: ModelRef? = null, val timeoutMillis: Long = DEFAULT_MATERIALIZER_TIMEOUT_MILLIS, val approvalPolicy: cc.noharry.agent.ApprovalPolicy = cc.noharry.agent.ApprovalPolicy.ASK, + val approvalState: cc.noharry.agent.spi.ApprovalPolicyState? = null, ) internal sealed interface MaterializerReadResult { diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/WorkspaceCallMapping.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/WorkspaceCallMapping.kt index a8c2a4a..b4ee90e 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/WorkspaceCallMapping.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/tools/WorkspaceCallMapping.kt @@ -11,6 +11,7 @@ internal fun MaterializerContext.toWorkspaceCallContext(): WorkspaceCallContext scene = scene, modelRef = modelRef, approvalPolicy = approvalPolicy, + approvalState = approvalState, ) internal fun WorkspaceCallContext.toMaterializerContext( @@ -24,4 +25,5 @@ internal fun WorkspaceCallContext.toMaterializerContext( modelRef = modelRef, timeoutMillis = timeoutMillis, approvalPolicy = approvalPolicy, + approvalState = approvalState, ) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt index e9436e7..3dc7211 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/DefaultAgentRuntime.kt @@ -332,7 +332,11 @@ internal class DefaultAgentRuntime( approve: suspend (PendingConfirmation) -> cc.noharry.agent.ApprovalState, ): Flow = flow { check(turnApprovals.putIfAbsent(request.executionId, approve) == null) { "Turn is already running" } - try { run(request).collect { emit(it) } } finally { turnApprovals.remove(request.executionId, approve) } + networkToolBackend.useThreadApprovals(request.executionId) + try { run(request).collect { emit(it) } } finally { + turnApprovals.remove(request.executionId, approve) + networkToolBackend.clearRun(request.executionId) + } } override suspend fun resumeConfirmation( diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt index 853828a..f5b18d6 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/NetworkToolBackend.kt @@ -37,6 +37,7 @@ internal class NetworkToolBackend( /** Fetches a page web_fetch's own request could not get. */ private val fetchFallback: WebFetchService? = null, ) : NetworkToolPort { + private val threadApprovalRuns = ConcurrentHashMap.newKeySet() private val confirmedHostsByRun = ConcurrentHashMap>() init { @@ -50,7 +51,7 @@ internal class NetworkToolBackend( if (confirmationPolicy == NetworkToolConfirmationPolicy.ALLOW_ALL_HOSTS) { return NetworkToolPolicyDecision.Allowed } - if (confirmedHostsByRun[runId]?.contains(host) == true) { + if (runId !in threadApprovalRuns && confirmedHostsByRun[runId]?.contains(host) == true) { return NetworkToolPolicyDecision.Allowed } return NetworkToolPolicyDecision.RequiresConfirmation( @@ -66,7 +67,10 @@ internal class NetworkToolBackend( authorize(runId, argumentsJson) } + internal fun useThreadApprovals(runId: String) { threadApprovalRuns.add(runId) } + override fun rememberConfirmed(runId: String, argumentsJson: String) { + if (runId in threadApprovalRuns) return val target = parseFetchTarget(argumentsJson) val host = target.host ?: return if (target.errorResult != null) return @@ -74,6 +78,7 @@ internal class NetworkToolBackend( } fun clearRun(runId: String) { + threadApprovalRuns.remove(runId) confirmedHostsByRun.remove(runId) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 2aa7f58..8aac9cb 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -26,9 +26,13 @@ internal class DefaultAgentThread( internal fun isCurrent(): Boolean = runtime.store.isCurrent(id, generation) private fun checkCurrent() { check(isCurrent()) { "Thread was deleted" } } - internal fun configure(options: ThreadOptions) { + internal fun configure(options: ThreadOptions, explicitPolicy: ApprovalPolicy? = null) { runtime.store.updateOptions(id, options, generation) defaults = options + if (explicitPolicy != null) active?.let { turn -> + turn.approvalState.policy = explicitPolicy + turn.approval?.let { gate -> gate.applyPolicy(explicitPolicy, gate.domain in runtime.store.rememberedDomains(id)) } + } } override suspend fun run(input: TurnInput, options: TurnOptions): TurnResult { @@ -110,7 +114,9 @@ internal class DefaultAgentThread( private suspend fun ProducerScope.execute(input: TurnInput, options: TurnOptions, turnId: String): FinishedThreadTurn { val mailbox = ThreadEventMailbox(this) - val turn = ActiveThreadTurn(turnId, defaults, runtime, generation) + val turn = ActiveThreadTurn(turnId, defaults, runtime, generation).also { + it.approvalState.policy = options.approvalPolicy ?: defaults.approvalPolicy ?: ApprovalPolicy.ASK + } val projection = ThreadEventProjection(id, turnId, input, { error("Approval must be handled in the active turn") }) { event -> turn.items = turn.projection?.items().orEmpty() if (event !is ThreadEvent.TurnCompleted && event !is ThreadEvent.TurnFailed) { @@ -167,12 +173,12 @@ internal class DefaultAgentThread( throw ThreadInputException("QUESTION_NOT_FOUND", "The question is not pending in this thread.") } val resolved = resolveThreadAttachments(input) { runtime.engine.readThreadAttachment(id, it) } - val request = threadRequest(record, resolved, options, turn.id, turn.executionId) + val request = threadRequest(record, resolved, options, turn.id, turn.executionId, turn.approvalState) if (request.inputImages.isNotEmpty() && (!runtime.imageInputEnabled || !runtime.supportsImages(request.modelRef))) { projection.fail(TurnError("IMAGE_INPUT_UNSUPPORTED", "The selected model does not accept image input.")) return } - runtime.engine.runThread(request) { pending -> approve(turn, pending, options) }.collect(projection::accept) + runtime.engine.runThread(request) { pending -> approve(turn, pending) }.collect(projection::accept) if (projection.result == null) projection.fail(TurnError("MISSING_TURN_RESULT", "The model stopped without completing the turn.")) } catch (_: CancellationException) { turn.approval?.cancel() @@ -204,9 +210,9 @@ internal class DefaultAgentThread( } } - private suspend fun approve(turn: ActiveThreadTurn, pending: PendingConfirmation, options: TurnOptions): ApprovalState { + private suspend fun approve(turn: ActiveThreadTurn, pending: PendingConfirmation): ApprovalState { val projection = checkNotNull(turn.projection) - val policy = options.approvalPolicy ?: turn.options.approvalPolicy ?: ApprovalPolicy.ASK + val policy = turn.approvalState.policy val domain = approvalDomain(pending.toolName.orEmpty(), pending.argumentsJson.orEmpty()) val automatic = when (policy) { ApprovalPolicy.APPROVE_ALL -> ApprovalState.APPROVED @@ -223,12 +229,17 @@ internal class DefaultAgentThread( val approval = ThreadApproval(pending.copy(runId = turn.id), runtime.nowEpochMillis() + runtime.confirmationTimeoutMillis, runtime.nowEpochMillis) turn.approval = approval try { + approval.applyPolicy(turn.approvalState.policy, domain != null && domain in runtime.store.rememberedDomains(id)) + if (approval.state != ApprovalState.PENDING) { + approval.approvedBy?.let { projection.toolDecision(pending.idempotencyKey, it) } + return approval.state + } projection.beginApproval(approval) val decision = approval.await() - if (domain != null && decision == ApprovalState.APPROVED && (policy == ApprovalPolicy.REMEMBER || approval.scope == ApprovalScope.THREAD)) { + if (domain != null && decision == ApprovalState.APPROVED && (turn.approvalState.policy == ApprovalPolicy.REMEMBER || approval.scope == ApprovalScope.THREAD)) { withContext(Dispatchers.IO) { runtime.store.rememberDomain(id, domain, generation) } } - if (decision == ApprovalState.APPROVED) projection.toolDecision(pending.idempotencyKey, ApprovalSource.USER) + if (decision == ApprovalState.APPROVED) projection.toolDecision(pending.idempotencyKey, approval.approvedBy ?: ApprovalSource.USER) projection.resolveApproval(approval.snapshot()) return decision } finally { approval.cancel(); turn.approval = null } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt index 49a2caa..fb207ef 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt @@ -50,7 +50,7 @@ internal class DefaultThreadRuntime( require(options.threadId == null || options.threadId == threadId) { "Thread id does not match options" } val saved = store.load(threadId) ?: store.create(threadId, newThreadOptions(threadId, options)) val merged = mergeThreadOptions(saved.options, options) - return handle(saved.copy(options = merged)).also { it.configure(merged) } + return handle(saved.copy(options = merged)).also { it.configure(merged, options.approvalPolicy) } } private fun newThreadOptions(threadId: String, options: ThreadOptions): ThreadOptions = diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt index 4bc5aa8..6a6a804 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt @@ -25,6 +25,8 @@ internal class ThreadApproval( private set @Volatile var scope: ApprovalScope = ApprovalScope.ONCE private set + @Volatile var approvedBy: ApprovalSource? = null + private set override val status: ItemStatus get() = when (state) { ApprovalState.PENDING -> ItemStatus.IN_PROGRESS ApprovalState.APPROVED -> ItemStatus.COMPLETED @@ -34,13 +36,14 @@ internal class ThreadApproval( override suspend fun approve(scope: ApprovalScope): RespondResult = respond(ApprovalState.APPROVED, scope) override suspend fun deny(reason: String?): RespondResult = respond(ApprovalState.DENIED, ApprovalScope.ONCE) - private fun respond(value: ApprovalState, scope: ApprovalScope): RespondResult = synchronized(this) { + private fun respond(value: ApprovalState, scope: ApprovalScope, source: ApprovalSource = ApprovalSource.USER): RespondResult = synchronized(this) { if (state == ApprovalState.PENDING && clock() >= expiresAt) complete(ApprovalState.EXPIRED) when (state) { ApprovalState.EXPIRED -> RespondResult.EXPIRED ApprovalState.CANCELLED -> RespondResult.NOT_FOUND ApprovalState.PENDING -> { this.scope = scope + approvedBy = source.takeIf { value == ApprovalState.APPROVED } complete(value) RespondResult.ACCEPTED } @@ -48,6 +51,15 @@ internal class ThreadApproval( } } + fun applyPolicy(policy: ApprovalPolicy, remembered: Boolean) { + when (policy) { + ApprovalPolicy.APPROVE_ALL -> respond(ApprovalState.APPROVED, ApprovalScope.ONCE, ApprovalSource.AUTOMATIC) + ApprovalPolicy.DENY_ALL -> respond(ApprovalState.DENIED, ApprovalScope.ONCE) + ApprovalPolicy.REMEMBER -> if (remembered) respond(ApprovalState.APPROVED, ApprovalScope.THREAD, ApprovalSource.REMEMBERED) + ApprovalPolicy.ASK -> Unit + } + } + suspend fun await(): ApprovalState { val remaining = (expiresAt - clock()).coerceAtLeast(0) if (withTimeoutOrNull(remaining) { decision.await() } == null) synchronized(this) { complete(ApprovalState.EXPIRED) } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt index 7fa146d..ea2ebbe 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt @@ -33,6 +33,7 @@ internal class ActiveThreadTurn(val id: String, val options: ThreadOptions, val private val steeringMutex = Mutex() private val receivedInputs = linkedMapOf() val executionId: String = java.util.UUID.randomUUID().toString() + val approvalState = cc.noharry.agent.spi.ApprovalPolicyState(options.approvalPolicy ?: cc.noharry.agent.ApprovalPolicy.ASK) var job: Job? = null var projection: ThreadEventProjection? = null @Volatile var approval: ThreadApproval? = null diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt index 6dbc743..17692f0 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadInput.kt @@ -10,7 +10,7 @@ internal fun TurnInput.snapshot(): TurnInput = copy(parts = parts.map { if (it is InputPart.Image) it.copy(bytes = it.bytes.copyOf()) else it }) -internal fun threadRequest(record: ThreadRecord, input: TurnInput, options: TurnOptions, turnId: String, executionId: String): AgentRequest { +internal fun threadRequest(record: ThreadRecord, input: TurnInput, options: TurnOptions, turnId: String, executionId: String, approvalState: cc.noharry.agent.spi.ApprovalPolicyState): AgentRequest { val text = input.parts.mapNotNull { when (it) { is InputPart.Text -> it.text @@ -23,7 +23,7 @@ internal fun threadRequest(record: ThreadRecord, input: TurnInput, options: Turn scene = record.options.scene, modelRef = options.model ?: record.options.model, workspaceId = record.options.workspace, currentStateKeys = options.currentStateKeys, sessionRunConflictPolicy = options.onConflict, instructions = record.options.instructions, - approvalPolicy = options.approvalPolicy ?: record.options.approvalPolicy ?: ApprovalPolicy.ASK, + approvalPolicy = approvalState.policy, approvalState = approvalState, inputImages = input.parts.filterIsInstance().mapIndexed { index, image -> ModelImage(image.bytes, image.mimeType, "thread:${record.id}/$turnId/image/$index") }, diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/workspace/VirtualWorkspace.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/workspace/VirtualWorkspace.kt index b40f541..aa3059a 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/workspace/VirtualWorkspace.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/workspace/VirtualWorkspace.kt @@ -76,7 +76,7 @@ internal class VirtualWorkspace( "grep" -> grep(argumentsJson, context) "search_tools" -> toolSearch.search(argumentsJson, context) in SUBAGENT_TOOL_NAMES -> subagentTools?.let { - WorkspaceExecutionResult(it(toolName, argumentsJson, SubagentCall(context.sessionId, context.runId, context.modelRef, context.approvalPolicy))) + WorkspaceExecutionResult(it(toolName, argumentsJson, SubagentCall(context.sessionId, context.runId, context.modelRef, context.approvalState?.policy ?: context.approvalPolicy))) } ?: WorkspaceExecutionResult(errorResult(RuntimeErrorCode.UNSUPPORTED_NATIVE_TOOL.wireCode, "Subagents are not configured.")) "write_file", "edit_file", diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt index efea040..c431ba5 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/AgentRuntime.kt @@ -123,6 +123,7 @@ internal data class AgentRequest( val instructions: String? = null, private val executionIdOverride: String? = null, val approvalPolicy: cc.noharry.agent.ApprovalPolicy = cc.noharry.agent.ApprovalPolicy.ASK, + val approvalState: ApprovalPolicyState? = null, ) { val executionId: String get() = executionIdOverride ?: requestId @@ -382,3 +383,6 @@ internal sealed interface CancelPendingResult { data object NotFound : CancelPendingResult } + +/** Shared only by an active turn and its tool contexts; explicit host policy patches update it. */ +internal class ApprovalPolicyState(@Volatile var policy: cc.noharry.agent.ApprovalPolicy) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt index 333123e..579a1a9 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/spi/WorkspacePort.kt @@ -22,6 +22,7 @@ internal data class WorkspaceCallContext( val scene: String? = null, val modelRef: ModelRef? = null, val approvalPolicy: cc.noharry.agent.ApprovalPolicy = cc.noharry.agent.ApprovalPolicy.ASK, + val approvalState: ApprovalPolicyState? = null, ) /** Workspace tool execution result. [resultJson] is the model-visible payload. */ diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadLivePolicyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadLivePolicyTest.kt new file mode 100644 index 0000000..ebe2e4a --- /dev/null +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadLivePolicyTest.kt @@ -0,0 +1,65 @@ +@file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) + +package cc.noharry.agent.runtime + +import cc.noharry.agent.* +import kotlinx.coroutines.CompletableDeferred +import kotlinx.coroutines.async +import kotlinx.coroutines.runBlocking +import kotlinx.coroutines.withTimeout +import org.junit.Assert.* +import org.junit.Test + +/** A host that changes a thread's approval policy while a turn waits decides the waiting approval by the new policy. */ +class ThreadLivePolicyTest { + @Test fun approveAllApprovesTheWaitingApprovalAutomatically() = runBlocking { + val events = waitThenPatch(ApprovalPolicy.APPROVE_ALL) + assertEquals(ApprovalState.APPROVED, completed(events).single().state) + assertEquals(ApprovalSource.AUTOMATIC, setTemperature(events).approvedBy) + assertTrue(events.last() is ThreadEvent.TurnCompleted) + assertTurnEvents(events) + } + + @Test fun denyAllDeniesTheWaitingApprovalAndTheTurnGoesOn() = runBlocking { + val events = waitThenPatch(ApprovalPolicy.DENY_ALL) + assertEquals(ApprovalState.DENIED, completed(events).single().state) + assertEquals(ItemStatus.DECLINED, setTemperature(events).status) + assertTrue(events.last() is ThreadEvent.TurnCompleted) + assertTurnEvents(events) + } + + @Test fun rememberWithoutAnApprovedAreaKeepsWaitingForThePerson() = runBlocking { + val events = waitThenPatch(ApprovalPolicy.REMEMBER) { approval -> approval.approve() } + assertEquals(ApprovalState.APPROVED, completed(events).single().state) + assertEquals(ApprovalSource.USER, setTemperature(events).approvedBy) + assertTurnEvents(events) + } + + private suspend fun waitThenPatch( + policy: ApprovalPolicy, + thenRespond: suspend (Approval) -> Unit = {}, + ): List = kotlinx.coroutines.coroutineScope { + approvalBuilder().build().use { runtime -> + val thread = runtime.startThread(ThreadOptions(threadId = "live")) + val waiting = CompletableDeferred() + val events = mutableListOf() + val turn = async { + thread.runStreamed("set temperature").collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) waiting.complete(event.item as Approval) + } + } + val approval = withTimeout(10_000) { waiting.await() } + runtime.resumeThread("live", ThreadOptions(approvalPolicy = policy)) + thenRespond(approval) + withTimeout(10_000) { turn.await() } + events + } + } + + private fun setTemperature(events: List): ThreadItem.ToolCall = + completed(events).single { it.tool == "mcp__default__set_temperature" } + + private inline fun completed(events: List): List = + events.filterIsInstance().map { it.item }.filterIsInstance() +} From 3fb1211fd222dfa691d6874f2e23bde56c1e43bb Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:31:22 -0800 Subject: [PATCH 29/40] test(runtime): session scheduling through thread turns Approvals now wait inside the turn, so the scheduling tests check that a waiting approval keeps its execution and queues the thread's next turn, that concurrent responses cannot start a second execution, and that interrupting or replacing an approved turn cannot revive it, instead of the old release-and-resume path. Co-Authored-By: Claude Opus 5.5 --- .../SessionSchedulingCloseIntegrationTest.kt | 77 ++-- .../SessionSchedulingIntegrationTest.kt | 57 ++- ...SessionSchedulingIntegrationTestSupport.kt | 37 -- ...SessionSchedulingRestartIntegrationTest.kt | 126 ++----- .../SessionSchedulingResumeIntegrationTest.kt | 335 +++++++----------- 5 files changed, 223 insertions(+), 409 deletions(-) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingCloseIntegrationTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingCloseIntegrationTest.kt index 2c229b5..4032dd7 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingCloseIntegrationTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingCloseIntegrationTest.kt @@ -1,11 +1,17 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime +import cc.noharry.agent.ThreadEvent +import cc.noharry.agent.ThreadOptions +import cc.noharry.agent.TurnOptions +import cc.noharry.agent.TurnStatus +import cc.noharry.agent.runtime.thread.DefaultThreadRuntime import cc.noharry.agent.spi.AgentEvent import cc.noharry.agent.spi.reliability.RuntimeCompletionOutcome import cc.noharry.agent.spi.reliability.RuntimeErrorCode import cc.noharry.agent.spi.reliability.RuntimeRunStatus import kotlinx.coroutines.CompletableDeferred +import kotlinx.coroutines.async import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.flow.collect import kotlinx.coroutines.flow.toList @@ -25,48 +31,35 @@ class SessionSchedulingCloseIntegrationTest { val observer = CountingTerminalObserver() val holdA = CompletableDeferred() val enteredA = CompletableDeferred() - val runtime = AgentRuntimeBuilder.create() - .workspaceRoot(java.nio.file.Files.createTempDirectory("sched-close-").toFile()) - .modelClient(MixedWaitingAndHoldModel(holdA, enteredA)) - .toolProvider(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) - .policyRule(confirmUnlessApprovedPolicy()) - .sessionConcurrency(maxActiveSessions = 1) - .turnObserver(observer) - .buildEngine() as DefaultAgentRuntime - try { - runtime.run(request(RUN_B1, SESSION_B)).toList() - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState(RUN_B1)?.status) - - val active = launch { runtime.run(request(RUN_A1, SESSION_A)).toList() } - enteredA.await() - val queued = launch { runtime.run(request(RUN_A2, SESSION_A)).toList() } - awaitQueued(runtime, RUN_A2) - - runtime.close() - active.join() - queued.join() - - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState(RUN_A1)?.status) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState(RUN_A2)?.status) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState(RUN_B1)?.status) - assertEquals(RuntimeErrorCode.RUNTIME_CLOSED.wireCode, runtime.getRuntimeResult(RUN_A1)?.errorCode) - assertEquals(RuntimeErrorCode.RUNTIME_CLOSED.wireCode, runtime.getRuntimeResult(RUN_A2)?.errorCode) - assertEquals(RuntimeErrorCode.RUNTIME_CLOSED.wireCode, runtime.getRuntimeResult(RUN_B1)?.errorCode) - assertEquals(RuntimeCompletionOutcome.UNKNOWN, runtime.getRuntimeResult(RUN_A1)?.completion?.outcome) - assertEquals(1, observer.counts[RUN_A1]) - assertEquals(1, observer.counts[RUN_A2]) - assertEquals(1, observer.counts[RUN_B1]) - - val afterClose = runtime.run(request(RUN_C1, SESSION_C)).toList() - assertTrue(afterClose.none { it is AgentEvent.Started }) - assertEquals( - RuntimeErrorCode.RUNTIME_CLOSED.wireCode, - afterClose.filterIsInstance().single().code, - ) - assertNull(runtime.getRunState(RUN_C1)) - } finally { - runtime.close() - } + threadBuilder(MixedWaitingAndHoldModel(holdA, enteredA)) + .tools(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) + .policyRule(confirmUnlessApprovedPolicy()).sessionConcurrency(maxActiveSessions = 2) + .turnObserver(observer).build().use { runtime -> + val a = runtime.startThread(ThreadOptions(threadId = SESSION_A)) + val b = runtime.startThread(ThreadOptions(threadId = SESSION_B)) + val waiting = async { b.runStreamed(RUN_B1, TurnOptions(turnId = RUN_B1)).toList() } + b.awaitApproval(RUN_B1) + val active = async { a.runStreamed(RUN_A1, TurnOptions(turnId = RUN_A1)).toList() } + enteredA.await() + val queued = async { a.runStreamed(RUN_A2, TurnOptions(turnId = RUN_A2)).toList() } + runtime.awaitQueued(1) + val executions = listOf(SESSION_A to RUN_A1, SESSION_B to RUN_B1).map { + checkNotNull(runtime.diagnostics.getRunState(it.first, it.second)).runId + } + runtime.close() + for (events in listOf(active.await(), waiting.await())) { + assertTurnEvents(events) + assertEquals(TurnStatus.INTERRUPTED, (events.last() as ThreadEvent.TurnCompleted).result.status) + } + val rejected = queued.await() + assertTurnEvents(rejected) + assertEquals("RUNTIME_CLOSED", (rejected.last() as ThreadEvent.TurnFailed).error.code) + executions.forEach { assertEquals(1, observer.counts[it]) } + assertEquals(2, observer.counts.size) + assertNull(runtime.diagnostics.getRunState(SESSION_A, RUN_A2)) + assertTrue(runCatching { a.run("after close") }.exceptionOrNull() is IllegalStateException) + assertIdle((runtime as DefaultThreadRuntime).engine) + } } @Test diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingIntegrationTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingIntegrationTest.kt index 016723b..773ad8f 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingIntegrationTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingIntegrationTest.kt @@ -1,6 +1,10 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime +import cc.noharry.agent.ThreadEvent +import cc.noharry.agent.TurnOptions +import cc.noharry.agent.TurnStatus +import cc.noharry.agent.RespondResult import cc.noharry.agent.spi.AgentEvent import cc.noharry.agent.spi.RuntimeEvidenceConfig import cc.noharry.agent.spi.SessionEventType @@ -16,6 +20,7 @@ import cc.noharry.agent.vfs.VfsFileSystem import java.nio.file.Files import java.util.concurrent.CopyOnWriteArrayList import kotlinx.coroutines.CancellationException +import kotlinx.coroutines.async import kotlinx.coroutines.CompletableDeferred import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.cancelAndJoin @@ -141,42 +146,24 @@ class SessionSchedulingIntegrationTest { } @Test - fun missingResumeQueueAndCancelReplacePolicies() = runSchedulingTest { - val runtime = confirmationRuntime() - try { - runtime.run(request(RUN_A1, SESSION_A)).toList() - - val missing = runtime.run(request(RUN_A2, SESSION_A)).toList() - val missingBlocker = missing.filterIsInstance().single().blocker - assertEquals(RuntimeErrorCode.ADMISSION_POLICY_REQUIRED.wireCode, missingBlocker.code) - assertEquals(RUN_A1, missingBlocker.runId) - assertNull(runtime.getRunState(RUN_A2)) - assertTrue(missing.none { it is AgentEvent.Started }) - - val resume = runtime.run( - request(RUN_A3, SESSION_A, SessionRunConflictPolicy.RESUME_CURRENT), - ).toList() - val resumeBlocker = resume.filterIsInstance().single().blocker - assertEquals(RuntimeErrorCode.PENDING_CONFIRMATION_EXISTS.wireCode, resumeBlocker.code) - assertNull(runtime.getRunState(RUN_A3)) - - val queued = launch { - runtime.run(request(RUN_A4, SESSION_A, SessionRunConflictPolicy.QUEUE_NEW)).toList() - } - awaitQueued(runtime, RUN_A4) + fun threadConflictPoliciesRejectQueueAndReplaceWithoutCreatingAnotherOwner() = runSchedulingTest { + threadApprovalRuntime().use { runtime -> + val thread = runtime.startThread() + val active = async { thread.run("original", TurnOptions(turnId = RUN_A1)) } + val pending = thread.awaitApproval(RUN_A1) + val busy = thread.run("busy", TurnOptions(turnId = RUN_A2, onConflict = SessionRunConflictPolicy.RESUME_CURRENT)) + assertEquals("THREAD_BUSY", busy.error?.code) + assertNull(runtime.diagnostics.getRunState(thread.id, RUN_A2)) + val queued = async { thread.run("queued", TurnOptions(turnId = RUN_A3)) } + runtime.awaitQueued(1) queued.cancelAndJoin() - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState(RUN_A4)?.status) - - val replaced = runtime.run( - request(RUN_A5, SESSION_A, SessionRunConflictPolicy.CANCEL_AND_REPLACE), - ).toList() - assertTrue(replaced.any { it is AgentEvent.Started }) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState(RUN_A1)?.status) - assertEquals(RuntimeErrorCode.RUN_REPLACED.wireCode, runtime.getRuntimeResult(RUN_A1)?.errorCode) - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState(RUN_A5)?.status) - assertIdleOwnersExcept(runtime, SESSION_A to RUN_A5) - } finally { - runtime.close() + runtime.awaitQueued(0) + val replacement = thread.collectApproving("replacement", TurnOptions(turnId = RUN_A5, + onConflict = SessionRunConflictPolicy.CANCEL_AND_REPLACE)) + assertEquals(TurnStatus.INTERRUPTED, active.await().status) + assertEquals(RespondResult.NOT_FOUND, pending.approve()) + assertEquals(TurnStatus.COMPLETED, (replacement.last() as ThreadEvent.TurnCompleted).result.status) + assertIdle(runtime.engine) } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingIntegrationTestSupport.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingIntegrationTestSupport.kt index 13466e2..a57bdba 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingIntegrationTestSupport.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingIntegrationTestSupport.kt @@ -89,16 +89,6 @@ internal fun countProbeTerminals(root: File, runId: String): Int { return probes.readLines().count { it.contains("\"stageId\":\"run.terminal\"") } } -internal suspend fun assertIdleOwnersExcept( - runtime: DefaultAgentRuntime, - vararg owners: Pair, -) { - val snap = runtime.sessionSchedulerSnapshotForTest() - assertEquals(owners.toMap(), snap.owners) - assertEquals(0, snap.activeExecutionCount) - assertEquals(owners.map { it.second }.toSet(), snap.waitingOwnerRunIds.toSet()) -} - internal fun runtime( model: ModelClient, maxActive: Int = 4, @@ -124,21 +114,6 @@ internal fun runtime( return builder.buildEngine() as DefaultAgentRuntime } -internal fun planConfirmationRuntime(provider: GatedMcpProvider): DefaultAgentRuntime = - AgentRuntimeBuilder.create() - .workspaceRoot(java.nio.file.Files.createTempDirectory("sched-confirm-").toFile()) - .toolProvider(provider) - .policyRule(confirmUnlessApprovedPolicy()) - .modelClient(directBackendCallModel()) - .sessionConcurrency(maxActiveSessions = 2) - .buildEngine() as DefaultAgentRuntime - -internal fun confirmationRuntime(): DefaultAgentRuntime = - AgentRuntimeBuilder.create() - .confirmationOnRun() - .sessionConcurrency(maxActiveSessions = 2) - .buildEngine() as DefaultAgentRuntime - internal fun request( runId: String, sessionId: String, @@ -186,18 +161,6 @@ internal fun directBackendCallModel(): ModelClient = ), ) -internal fun askThenConfirmModel(): ModelClient = - FakeModelClient( - eventsByRound = listOf( - listOf(schemaRead("set_temperature"), ModelEvent.Completed), - listOf( - ModelEvent.ToolCall("backend-1", qualifiedMcpTool("set_temperature"), directBackendCallJson()), - ModelEvent.Completed, - ), - listOf(ModelEvent.ToolCall("finish-1", "finish", """{"response":"done"}"""), ModelEvent.Completed), - ), - ) - internal fun confirmUnlessApprovedPolicy(): PolicyRule = PolicyRule { action, context: PolicyContext -> val source = (action as? PolicyAction.Call)?.source if (source != "BACKEND" || context.approvedConfirmation) { diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingRestartIntegrationTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingRestartIntegrationTest.kt index 0b636d1..f76ff6d 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingRestartIntegrationTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingRestartIntegrationTest.kt @@ -1,100 +1,42 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime -import cc.noharry.agent.spi.AgentEvent -import cc.noharry.agent.spi.ConfirmationChoice -import cc.noharry.agent.spi.ConfirmationDecision -import cc.noharry.agent.spi.ConfirmationResumeResult -import cc.noharry.agent.spi.reliability.RuntimeCompletionOutcome -import cc.noharry.agent.spi.reliability.RuntimeErrorCode -import cc.noharry.agent.spi.reliability.RuntimeRunStatus -import kotlinx.coroutines.CompletableDeferred -import kotlinx.coroutines.CoroutineScope -import kotlinx.coroutines.flow.toList -import kotlinx.coroutines.launch -import org.junit.Assert.assertEquals -import org.junit.Assert.assertTrue + +import cc.noharry.agent.* +import cc.noharry.agent.spi.reliability.* +import cc.noharry.agent.runtime.reliability.FileBackedReliabilityStorage +import cc.noharry.agent.runtime.thread.ThreadStore +import java.io.File +import org.junit.Assert.* import org.junit.Test -import java.nio.file.Files class SessionSchedulingRestartIntegrationTest { - @Test - fun processRestartStaleWaitingAndQueuedAreTerminalizedWithoutQueueRecovery() = runSchedulingTest { - assertStaleWaitingTerminalizedWithoutQueueRecovery() - assertStaleQueuedTerminalizedWithoutQueueRecovery() - } -} - -private suspend fun assertStaleWaitingTerminalizedWithoutQueueRecovery() { - val storageRoot = Files.createTempDirectory("runtime-restart-honesty-").toFile() - val first = AgentRuntimeBuilder.create() - .reliabilityStorageRoot(storageRoot) - .confirmationOnRun() - .sessionConcurrency(maxActiveSessions = 1) - .buildEngine() as DefaultAgentRuntime - first.run(request(RUN_A1, SESSION_A)).toList() - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, first.getRunState(RUN_A1)?.status) - - val restored = AgentRuntimeBuilder.create() - .reliabilityStorageRoot(storageRoot) - .confirmationOnRun() - .sessionConcurrency(maxActiveSessions = 1) - .buildEngine() as DefaultAgentRuntime - try { - val resumed = restored.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-1", ConfirmationChoice.APPROVE), - ) - assertTrue(resumed is ConfirmationResumeResult.Rejected || resumed is ConfirmationResumeResult.NotFound) - - val replacement = restored.run(request(RUN_A2, SESSION_A)).toList() - assertTrue(replacement.any { it is AgentEvent.ConfirmationRequired }) - assertEquals(RuntimeRunStatus.CANCELLED, restored.getRunState(RUN_A1)?.status) - assertEquals( - RuntimeErrorCode.PROCESS_RESTART_ADMISSION_UNSUPPORTED.wireCode, - restored.getRuntimeResult(RUN_A1)?.errorCode, - ) - assertEquals( - RuntimeCompletionOutcome.UNKNOWN, - restored.getRuntimeResult(RUN_A1)?.completion?.outcome, - ) - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, restored.getRunState(RUN_A2)?.status) - } finally { - restored.close() - } -} - -private suspend fun CoroutineScope.assertStaleQueuedTerminalizedWithoutQueueRecovery() { - val hold = CompletableDeferred() - val entered = CompletableDeferred() - val queuedRoot = Files.createTempDirectory("runtime-restart-queued-").toFile() - val parked = AgentRuntimeBuilder.create() - .reliabilityStorageRoot(queuedRoot) - .modelClient(SingleGateFinishModel(hold, entered)) - .sessionConcurrency(maxActiveSessions = 1) - .buildEngine() as DefaultAgentRuntime - val active = launch { parked.run(request(RUN_A1, SESSION_A)).toList() } - entered.await() - val queued = launch { parked.run(request(RUN_A2, SESSION_A)).toList() } - awaitQueued(parked, RUN_A2) - - val afterCrash = AgentRuntimeBuilder.create() - .reliabilityStorageRoot(queuedRoot) - .modelClient(SingleGateFinishModel(CompletableDeferred(), CompletableDeferred())) - .sessionConcurrency(maxActiveSessions = 1) - .confirmationOnRun() - .buildEngine() as DefaultAgentRuntime - try { - afterCrash.run(request(RUN_A3, SESSION_A)).toList() - assertEquals(RuntimeRunStatus.CANCELLED, afterCrash.getRunState(RUN_A2)?.status) - assertEquals( - RuntimeErrorCode.PROCESS_RESTART_ADMISSION_UNSUPPORTED.wireCode, - afterCrash.getRuntimeResult(RUN_A2)?.errorCode, - ) - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, afterCrash.getRunState(RUN_A3)?.status) - } finally { - afterCrash.close() - hold.complete(Unit) - active.cancel() - queued.cancel() + @Test fun abandonedWaitingAndQueuedAttemptsAreCancelledWithoutReplayingTheirWork() = runSchedulingTest { + val root = threadRoot() + val storage = File(root, "storage") + val store = ThreadStore(storage) + store.create(SESSION_A, ThreadOptions(threadId = SESSION_A)) + val reliability = FileBackedReliabilityStorage(File(storage, "runtime")) + val stale = listOf(RuntimeRunStatus.WAITING_CONFIRMATION, RuntimeRunStatus.QUEUED) + stale.forEachIndexed { index, status -> + val execution = "abandoned-$index" + store.attempts.begin(SESSION_A, "old-$index", execution) + val phase = if (status == RuntimeRunStatus.QUEUED) RuntimeRunPhase.QUEUED else RuntimeRunPhase.WAITING_CONFIRMATION + reliability.saveRun(RuntimeRunSnapshot(execution, SESSION_A, status, 1), + RuntimeRunEnvelope(execution, "old-$index", SESSION_A, status, phase, 1, 1)) + } + val model = ThreadScriptModel(listOf(finishEvents("fresh"))) + threadBuilder(model, root).build().use { runtime -> + val thread = runtime.resumeThread(SESSION_A) + assertTrue(thread.pendingRequests().isEmpty()) + assertEquals("fresh", thread.run("fresh request", TurnOptions(turnId = "new")).finalResponse) + assertEquals(1, model.requests.size) + assertEquals(listOf("fresh request"), model.requests.single().messages.filter { it.role == "user" }.map { it.content }) + stale.indices.forEach { index -> + assertEquals(RuntimeRunStatus.CANCELLED, reliability.readSnapshot("abandoned-$index")?.status) + assertEquals("INTERRUPTED", reliability.readResult("abandoned-$index")?.errorCode) + assertFalse(checkNotNull(store.attempts.latest(SESSION_A, "old-$index")).active) + } + } } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingResumeIntegrationTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingResumeIntegrationTest.kt index 94d7f5b..aa5a364 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingResumeIntegrationTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/SessionSchedulingResumeIntegrationTest.kt @@ -1,244 +1,173 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.runtime -import cc.noharry.agent.spi.AgentRequest -import cc.noharry.agent.spi.CancelPendingConfirmationRequest -import cc.noharry.agent.spi.ConfirmationChoice -import cc.noharry.agent.spi.ConfirmationDecision -import cc.noharry.agent.spi.ConfirmationResumeResult + +import cc.noharry.agent.* +import cc.noharry.agent.runtime.thread.DefaultThreadRuntime +import cc.noharry.agent.spi.ProviderConcurrencyDeclaration import cc.noharry.agent.spi.SessionRunConflictPolicy -import cc.noharry.agent.spi.reliability.RuntimeErrorCode +import cc.noharry.agent.spi.model.* import cc.noharry.agent.spi.reliability.RuntimeRunPhase import cc.noharry.agent.spi.reliability.RuntimeRunStatus -import kotlinx.coroutines.CompletableDeferred -import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.Flow +import kotlinx.coroutines.flow.flow import kotlinx.coroutines.flow.toList -import kotlinx.coroutines.launch -import org.junit.Assert.assertEquals -import org.junit.Assert.assertFalse -import org.junit.Assert.assertNull -import org.junit.Assert.assertTrue +import org.junit.Assert.* import org.junit.Test class SessionSchedulingResumeIntegrationTest { - @Test - fun waitingReleasesExecutionAndKeepsSameSessionQueued() = runSchedulingTest { - val runtime = confirmationRuntime() - try { - runtime.run(request(RUN_A1, SESSION_A)).toList() - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState(RUN_A1)?.status) - assertEquals(0, runtime.sessionSchedulerSnapshotForTest().activeExecutionCount) - assertEquals(RUN_A1, runtime.sessionSchedulerSnapshotForTest().owners[SESSION_A]) - - runtime.run(request(RUN_B1, SESSION_B)).toList() - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState(RUN_B1)?.status) - assertEquals(setOf(SESSION_A, SESSION_B), runtime.sessionSchedulerSnapshotForTest().owners.keys) - assertEquals(0, runtime.sessionSchedulerSnapshotForTest().activeExecutionCount) - - val a2 = launch { - runtime.run(request(RUN_A2, SESSION_A, SessionRunConflictPolicy.QUEUE_NEW)).toList() - } - awaitQueued(runtime, RUN_A2) - assertEquals(RUN_A1, runtime.sessionSchedulerSnapshotForTest().owners[SESSION_A]) - - runtime.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-1", ConfirmationChoice.APPROVE), - ) - a2.join() - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRunState(RUN_A1)?.status) - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState(RUN_A2)?.status) - assertIdleOwnersExcept(runtime, SESSION_A to RUN_A2, SESSION_B to RUN_B1) - } finally { - runtime.close() + @Test fun approvalRetainsTheSameOwnerAndQueuesTheNextTurnOfThatThread() = runSchedulingTest { + threadApprovalRuntime().use { runtime -> + val a = runtime.startThread(ThreadOptions(threadId = SESSION_A)) + val b = runtime.startThread(ThreadOptions(threadId = SESSION_B)) + val a1 = async { a.run("first", TurnOptions(turnId = RUN_A1)) } + val pa = a.awaitApproval(RUN_A1) + val b1 = async { b.run("other", TurnOptions(turnId = RUN_B1)) } + b.awaitApproval(RUN_B1) + val original = runtime.engine.sessionSchedulerSnapshotForTest().owners + assertEquals(2, runtime.engine.sessionSchedulerSnapshotForTest().activeExecutionCount) + val a2 = async { a.run("second", TurnOptions(turnId = RUN_A2)) } + runtime.awaitQueued(1) + assertEquals(original, runtime.engine.sessionSchedulerSnapshotForTest().owners) + pa.approve() + assertEquals(TurnStatus.COMPLETED, a1.await().status) + a.awaitApproval(RUN_A2) + val advanced = runtime.engine.sessionSchedulerSnapshotForTest().owners + assertNotEquals(original[SESSION_A], advanced[SESSION_A]) + assertEquals(original[SESSION_B], advanced[SESSION_B]) + a.interrupt(); b.interrupt() + a2.await(); b1.await() + assertIdle(runtime.engine) } } - @Test - fun resumeUsesExactLeaseAndDoesNotCreateSecondOwner() = runSchedulingTest { - val runtime = confirmationRuntime() - try { - runtime.run(request(RUN_A1, SESSION_A)).toList() - assertEquals(RUN_A1, runtime.sessionSchedulerSnapshotForTest().owners[SESSION_A]) - val accepted = runtime.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-1", ConfirmationChoice.APPROVE), - ) - assertEquals(ConfirmationResumeResult.Accepted, accepted) - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRunState(RUN_A1)?.status) - assertIdle(runtime) - val duplicate = runtime.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-1", ConfirmationChoice.APPROVE), - ) - assertEquals(ConfirmationResumeResult.AlreadyConsumed, duplicate) - assertIdle(runtime) - } finally { - runtime.close() - } - } - - @Test - fun confirmationResumePersistsRunningBeforeResumedLoopWork() = runSchedulingTest { + @Test fun approvalUsesTheExistingExecutionAndRunningStateBeforeToolWork() = runSchedulingTest { val gate = CompletableDeferred() val entered = CompletableDeferred() - val runtime = planConfirmationRuntime(GatedMcpProvider(gate, entered)) - try { - runtime.run(request(RUN_A1, SESSION_A)).toList() - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState(RUN_A1)?.status) - - val resume = launch { - runtime.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-1", ConfirmationChoice.APPROVE), - ) - } + val provider = GatedMcpProvider(gate, entered) + threadApprovalRuntime(provider).use { runtime -> + val thread = runtime.startThread() + val running = async { thread.run("action", TurnOptions(turnId = RUN_A1)) } + val pending = thread.awaitApproval(RUN_A1) + val execution = checkNotNull(runtime.diagnostics.getRunState(thread.id, RUN_A1)).runId + assertEquals(RespondResult.ACCEPTED, pending.approve()) entered.await() - assertEquals(RuntimeRunStatus.RUNNING, runtime.getRunState(RUN_A1)?.status) - assertEquals(RuntimeRunPhase.MODEL_RUNNING, runtime.getRunEnvelope(RUN_A1)?.phase) - assertEquals(1, runtime.sessionSchedulerSnapshotForTest().activeExecutionCount) - assertEquals(RUN_A1, runtime.sessionSchedulerSnapshotForTest().owners[SESSION_A]) - + assertEquals(RuntimeRunStatus.RUNNING, runtime.engine.getRunState(execution)?.status) + assertEquals(RuntimeRunPhase.MODEL_RUNNING, runtime.engine.getRunEnvelope(execution)?.phase) + assertEquals(execution, runtime.engine.sessionSchedulerSnapshotForTest().owners[thread.id]) + assertEquals(1, runtime.engine.sessionSchedulerSnapshotForTest().activeExecutionCount) + assertEquals(RespondResult.ALREADY_ANSWERED, pending.approve()) + assertEquals(1, provider.callCount) gate.complete(Unit) - resume.join() - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRunState(RUN_A1)?.status) - assertIdle(runtime) - } finally { - runtime.close() + assertEquals(TurnStatus.COMPLETED, running.await().status) + assertIdle(runtime.engine) } } - @Test - fun confirmationResumeVsCancelAndReplaceDoesNotUseStaleWaiting() = runSchedulingTest { + @Test fun concurrentApprovalResponsesCannotStartASecondExecution() = runSchedulingTest { val gate = CompletableDeferred() val entered = CompletableDeferred() - val runtime = planConfirmationRuntime(GatedMcpProvider(gate, entered)) - try { - runtime.run(request(RUN_A1, SESSION_A)).toList() - val resume = launch { - runtime.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-1", ConfirmationChoice.APPROVE), - ) - } + val provider = GatedMcpProvider(gate, entered) + threadApprovalRuntime(provider).use { runtime -> + val thread = runtime.startThread() + val running = async { thread.run("action") } + val pending = thread.awaitApproval() + val replies = listOf(async(Dispatchers.Default) { pending.approve() }, async(Dispatchers.Default) { pending.approve() }).awaitAll() + assertEquals(setOf(RespondResult.ACCEPTED, RespondResult.ALREADY_ANSWERED), replies.toSet()) entered.await() - awaitState(runtime, RUN_A1, RuntimeRunStatus.RUNNING) + assertEquals(1, provider.callCount) + gate.complete(Unit) + assertEquals(TurnStatus.COMPLETED, running.await().status) + assertIdle(runtime.engine) + } + } - val replaced = launch { - runtime.run( - request(RUN_A5, SESSION_A, SessionRunConflictPolicy.CANCEL_AND_REPLACE), - ).toList() + @Test fun interruptAfterApprovalBeforeExecutionCannotReviveTheTurn() = runSchedulingTest { + val provider = GatedMcpProvider(CompletableDeferred(Unit), CompletableDeferred()) + threadApprovalRuntime(provider).use { runtime -> + val thread = runtime.startThread() + val events = mutableListOf() + thread.runStreamed("action", TurnOptions(turnId = RUN_A1)).collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) (event.item as Approval).approve() + if (event is ThreadEvent.ItemCompleted && event.item is Approval) thread.interrupt() } - awaitQueued(runtime, RUN_A5) - assertEquals(RuntimeRunStatus.RUNNING, runtime.getRunState(RUN_A1)?.status) - assertTrue(runtime.getRuntimeResult(RUN_A1)?.errorCode != RuntimeErrorCode.RUN_REPLACED.wireCode) - assertFalse(replaced.isCompleted) - gate.complete(Unit) - resume.join() - replaced.join() - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRunState(RUN_A1)?.status) - assertTrue(runtime.getRuntimeResult(RUN_A1)?.errorCode != RuntimeErrorCode.RUN_REPLACED.wireCode) - } finally { - runtime.close() + assertTurnEvents(events) + assertEquals(TurnStatus.INTERRUPTED, (events.last() as ThreadEvent.TurnCompleted).result.status) + assertEquals(0, provider.callCount) + assertEquals(RuntimeRunStatus.CANCELLED, runtime.diagnostics.getRunState(thread.id, RUN_A1)?.status) + assertIdle(runtime.engine) } } - @Test - fun duplicateConcurrentResumeFailClosedWithoutSecondExecution() = runSchedulingTest { + @Test fun cancelAndReplaceInterruptsTheApprovedExecutionBeforeStartingItsReplacement() = runSchedulingTest { val gate = CompletableDeferred() val entered = CompletableDeferred() val provider = GatedMcpProvider(gate, entered) - val runtime = planConfirmationRuntime(provider) - try { - runtime.run(request(RUN_A1, SESSION_A)).toList() - val first = CompletableDeferred() - val second = CompletableDeferred() - launch { - first.complete( - runtime.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-1", ConfirmationChoice.APPROVE), - ), - ) - } + threadApprovalRuntime(provider).use { runtime -> + val thread = runtime.startThread() + val original = async { thread.run("original") } + thread.awaitApproval().approve() entered.await() - launch { - second.complete( - runtime.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-2", ConfirmationChoice.APPROVE), - ), - ) - } - val late = second.await() - assertTrue(late is ConfirmationResumeResult.Rejected || late is ConfirmationResumeResult.AlreadyConsumed) - assertEquals(1, provider.callCount) - assertEquals(RuntimeRunStatus.RUNNING, runtime.getRunState(RUN_A1)?.status) - gate.complete(Unit) - assertEquals(ConfirmationResumeResult.Accepted, first.await()) - assertEquals(RuntimeRunStatus.COMPLETED, runtime.getRunState(RUN_A1)?.status) - assertEquals(1, provider.callCount) - } finally { - runtime.close() + val replacement = thread.collectApproving("replacement", + TurnOptions(onConflict = SessionRunConflictPolicy.CANCEL_AND_REPLACE)) { gate.complete(Unit) } + assertEquals(TurnStatus.INTERRUPTED, original.await().status) + assertEquals(TurnStatus.COMPLETED, (replacement.last() as ThreadEvent.TurnCompleted).result.status) + assertEquals(2, provider.callCount) + assertIdle(runtime.engine) } } - @Test - fun resumeGrantBeforePersistLosesToCancelWithoutRevivingRunning() = runSchedulingTest { - val gate = CompletableDeferred() - val entered = CompletableDeferred() - val provider = GatedMcpProvider(gate, entered) - val runtime = planConfirmationRuntime(provider) - val attached = CompletableDeferred() - val releasePersist = CompletableDeferred() - try { - runtime.run(request(RUN_A1, SESSION_A)).toList() - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState(RUN_A1)?.status) - runtime.sessionRunSchedulerForTest().afterAttachJobForTest = { - attached.complete(Unit) - releasePersist.await() + @Test fun aBlockingQuestionReleasesExecutionBeforeItsAnswerCanReachApproval() = runSchedulingTest { + val model = ThreadScriptModel(listOf( + listOf(ModelEvent.ToolCall("ask", "ask", """{"question":"Which temperature?"}"""), ModelEvent.Completed), + listOf(schemaRead("set_temperature"), ModelEvent.Completed), + listOf(setTemperatureBackendCall(), ModelEvent.Completed), finishEvents("done"), + )) + threadBuilder(model).tools(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) + .hook(confirmUntilApproved()).sessionConcurrency(maxActiveSessions = 1).build().use { runtime -> + val thread = runtime.startThread() + val first = thread.run("set temperature") + assertEquals(TurnStatus.WAITING_FOR_ANSWER, first.status) + assertIdle((runtime as DefaultThreadRuntime).engine) + val events = mutableListOf() + thread.runStreamed(TurnInput(listOf(InputPart.Text("18")), answering = first.pending!!.id)).collect { event -> + events += event + if (event is ThreadEvent.ItemStarted && event.item is Approval) (event.item as Approval).approve() + } + assertTurnEvents(events) + val result = (events.last() as ThreadEvent.TurnCompleted).result + assertNotEquals(first.turnId, result.turnId) + assertEquals(TurnStatus.COMPLETED, result.status) + assertEquals(1, events.filterIsInstance().count { it.item is Approval }) + assertIdle(runtime.engine) } - val resume = CompletableDeferred() - launch(Dispatchers.Default) { - resume.complete( - runtime.resumeConfirmation( - ConfirmationDecision("$RUN_A1:confirmation", "resume-1", ConfirmationChoice.APPROVE), - ), - ) - } - attached.await() - val cancelled = runtime.cancelPendingConfirmation( - CancelPendingConfirmationRequest("$RUN_A1:confirmation", "cancel-race"), - ) - assertTrue(cancelled is cc.noharry.agent.spi.CancelPendingResult.Cancelled) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState(RUN_A1)?.status) - releasePersist.complete(Unit) - val resumeResult = resume.await() - assertTrue( - resumeResult is ConfirmationResumeResult.Rejected || - resumeResult is ConfirmationResumeResult.AlreadyConsumed, - ) - assertEquals(0, provider.callCount) - assertEquals(RuntimeRunStatus.CANCELLED, runtime.getRunState(RUN_A1)?.status) - assertTrue(runtime.getRunState(RUN_A1)?.status != RuntimeRunStatus.RUNNING) - assertIdle(runtime) - } finally { - runtime.sessionRunSchedulerForTest().afterAttachJobForTest = null - gate.complete(Unit) - runtime.close() - } } +} + +internal suspend fun AgentThread.awaitApproval(turnId: String? = null): Approval = withTimeout(5000) { + while (true) { + pendingRequests().filterIsInstance().firstOrNull { turnId == null || it.turnId == turnId }?.let { return@withTimeout it } + yield() + } + error("Unreachable") +} + +internal fun threadApprovalRuntime( + provider: cc.noharry.agent.spi.ToolProvider = LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature"))), +): DefaultThreadRuntime = threadBuilder(ApprovalPerTurnModel()).tools(provider).hook(confirmUntilApproved()) + .sessionConcurrency(maxActiveSessions = 2).build() as DefaultThreadRuntime - @Test - fun userInputThenConfirmationReleasesExecutionPermit() = runSchedulingTest { - val runtime = AgentRuntimeBuilder.create() - .workspaceRoot(java.nio.file.Files.createTempDirectory("sched-resume-").toFile()) - .toolProvider(LoopMcpProvider(exposedTools = listOf(mcpTool("set_temperature")))) - .policyRule(confirmUnlessApprovedPolicy()) - .modelClient(askThenConfirmModel()) - .sessionConcurrency(maxActiveSessions = 1) - .buildEngine() as DefaultAgentRuntime - try { - runtime.run(request(RUN_A1, SESSION_A)).toList() - assertEquals(RuntimeRunStatus.WAITING_CONFIRMATION, runtime.getRunState(RUN_A1)?.status) - assertEquals(0, runtime.sessionSchedulerSnapshotForTest().activeExecutionCount) - assertEquals(RUN_A1, runtime.sessionSchedulerSnapshotForTest().owners[SESSION_A]) - assertTrue(runtime.sessionSchedulerSnapshotForTest().waitingOwnerRunIds.contains(RUN_A1)) - } finally { - runtime.close() +private class ApprovalPerTurnModel : ModelClient { + override val providerConcurrency = ProviderConcurrencyDeclaration.threadSafe() + override fun complete(request: ModelRequest): Flow = flow { + val current = request.messages.drop(request.messages.indexOfLast { it.role == "user" } + 1) + val event = when { + current.none { it.role == "tool" && it.toolName == "read_file" } -> schemaRead("set_temperature") + current.none { it.role == "tool" && it.toolName == qualifiedMcpTool("set_temperature") } -> setTemperatureBackendCall() + else -> ModelEvent.ToolCall("finish", "finish", """{"response":"done"}""") } + emit(event); emit(ModelEvent.Completed) } } From 176a1e5cc6ed191af0849a0ff5f8d171c5369d75 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:32:24 -0800 Subject: [PATCH 30/40] fix(runtime): resuming a thread without changes does not rewrite it resumeThread wrote the thread's metadata file on every call. It now writes only when the merged options differ from the saved ones, and startThread/resumeThread say in their KDoc that they do this small I/O before returning. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 ++ .../main/kotlin/cc/noharry/agent/AgentRuntime.kt | 8 +++++++- .../agent/runtime/thread/DefaultAgentThread.kt | 4 ++-- .../agent/runtime/thread/DefaultThreadRuntime.kt | 2 +- .../noharry/agent/runtime/ThreadOptionPatchTest.kt | 14 ++++++++++++++ 5 files changed, 26 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b23569..0450edd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -86,6 +86,8 @@ called out; a patch release does not break it. `ThreadOptions.reset` clears selected model, workspace, scene or instruction overrides. New threads still use ASK. A policy given to `resumeThread` while a turn runs applies to that turn at once: an approval it is waiting for is decided by the new policy (`APPROVE_ALL` approves, `DENY_ALL` denies, `REMEMBER` approves a remembered area). + `startThread` and `resumeThread` do their small metadata I/O before returning (call them off the main thread on + Android); a resume that changes nothing no longer rewrites the saved thread. - **Independent budgets survive settings changes.** `LoopSettings.limits` defaults to null, so a settings call does not reset limits configured through `limits(...)`. An explicit settings budget still replaces them. diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt b/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt index 712fe75..2eb55d3 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/AgentRuntime.kt @@ -8,10 +8,16 @@ package cc.noharry.agent * `cc.noharry.agent.builder`); Java hosts use `AgentRuntimeBuilder.create()` from that artifact. */ interface AgentRuntime : AutoCloseable { + /** + * Starts a conversation. With storage configured this writes the thread's small metadata file before returning, + * so an Android host calls it off the main thread. + */ fun startThread(options: ThreadOptions = ThreadOptions()): AgentThread /** * Reopens saved model history and visible items when storage is configured. Without storage, history lives only - * in this runtime. Non-default options update the saved defaults used by future turns. + * in this runtime. Non-default options update the saved defaults used by future turns. With storage configured + * this reads the thread's small metadata file, and writes it only when the options change, before returning; an + * Android host calls it off the main thread. */ fun resumeThread(threadId: String, options: ThreadOptions = ThreadOptions()): AgentThread suspend fun listThreads(): List diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 8aac9cb..842bae9 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -26,8 +26,8 @@ internal class DefaultAgentThread( internal fun isCurrent(): Boolean = runtime.store.isCurrent(id, generation) private fun checkCurrent() { check(isCurrent()) { "Thread was deleted" } } - internal fun configure(options: ThreadOptions, explicitPolicy: ApprovalPolicy? = null) { - runtime.store.updateOptions(id, options, generation) + internal fun configure(options: ThreadOptions, explicitPolicy: ApprovalPolicy? = null, persist: Boolean = true) { + if (persist) runtime.store.updateOptions(id, options, generation) defaults = options if (explicitPolicy != null) active?.let { turn -> turn.approvalState.policy = explicitPolicy diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt index fb207ef..edde7f4 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultThreadRuntime.kt @@ -50,7 +50,7 @@ internal class DefaultThreadRuntime( require(options.threadId == null || options.threadId == threadId) { "Thread id does not match options" } val saved = store.load(threadId) ?: store.create(threadId, newThreadOptions(threadId, options)) val merged = mergeThreadOptions(saved.options, options) - return handle(saved.copy(options = merged)).also { it.configure(merged, options.approvalPolicy) } + return handle(saved.copy(options = merged)).also { it.configure(merged, options.approvalPolicy, persist = merged != saved.options) } } private fun newThreadOptions(threadId: String, options: ThreadOptions): ThreadOptions = diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadOptionPatchTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadOptionPatchTest.kt index 2d717d1..fd7e040 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadOptionPatchTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadOptionPatchTest.kt @@ -62,4 +62,18 @@ class ThreadOptionPatchTest { assertEquals(ApprovalPolicy.ASK, (runtime as DefaultThreadRuntime).store.load("replace")!!.options.approvalPolicy) } } + + @Test fun resumingWithoutChangesLeavesTheSavedThreadUntouched() = runBlocking { + val root = threadRoot() + approvalBuilder(root).build().use { it.startThread(ThreadOptions(threadId = "quiet", scene = "kept")) } + val file = root.walkTopDown().single { it.name.endsWith(".thread.json") } + check(file.setLastModified(0L)) + approvalBuilder(root).build().use { runtime -> + runtime.resumeThread("quiet") + runtime.resumeThread("quiet", ThreadOptions(scene = "kept")) + assertEquals(0L, file.lastModified()) + runtime.resumeThread("quiet", ThreadOptions(scene = "changed")) + assertNotEquals(0L, file.lastModified()) + } + } } From 40018784a07b99bb1e190716a96b5bf89795f928 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 01:34:20 -0800 Subject: [PATCH 31/40] fix(runtime): a call left waiting for approval by an earlier run reaches the model as cancelled A turn's history is saved with the call shown as waiting before the approval wait starts. When the process died during that wait, or a newer turn of the same thread replaced it (whose start makes the older run's own record a no-op), the next turn's model still saw the call as waiting. A run now closes such calls in the history it starts with: no earlier run of the same session can still be waiting then. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 ++ .../core/context/SessionHistoryStore.kt | 13 +++++++ .../kernel/core/loop/NativeToolMessages.kt | 6 +++- .../core/context/SessionHistoryStoreTest.kt | 35 +++++++++++++++++++ 4 files changed, 55 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0450edd..c7b9225 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,6 +45,8 @@ called out; a patch release does not break it. host parser; invalid targets are never remembered. MCP approvals cover one tool, with separate namespaces for web, MCP and other tools. `ToolCall.approvedBy` now uses `ApprovalSource.USER`, `REMEMBERED` or `AUTOMATIC`; a denied call has no approval source. Older snapshots with an ambiguous REMEMBER policy leave the source unset. + A call an earlier turn left waiting for approval (the process died, or a newer turn replaced it) reaches the next + turn's model as cancelled instead of still waiting. - **Damaged history does not block unrelated conversations.** Thread listing skips unreadable or unsupported metadata. Invalid provider history is renamed to a `.corrupt` file and the conversation resumes with empty model diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt index 8879466..97e8750 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt @@ -1,6 +1,8 @@ @file:OptIn(cc.noharry.agent.spi.ExperimentalAgentRuntimeApi::class) package cc.noharry.agent.kernel.core.context +import cc.noharry.agent.kernel.core.loop.AWAITING_CONFIRMATION_RESULT +import cc.noharry.agent.kernel.core.loop.INTERRUPTED_CONFIRMATION_RESULT import cc.noharry.agent.spi.model.ModelMessage /** @@ -56,6 +58,7 @@ internal class SessionHistoryStore @JvmOverloads constructor( session.runs = trimmed(saved?.runs.orEmpty()) session.lastInputTokens = saved?.lastInputTokens } + session.runs = session.runs.withStaleConfirmationsClosed() session.latestStarted += 1 RunStart(sessionId, session.latestStarted, session.runs) } @@ -185,6 +188,16 @@ private fun List.historyBytes(): Long = sumOf { message -> private fun String.utf8Size(): Long = toByteArray(Charsets.UTF_8).size.toLong() +/** + * A new run of a session starts only when no earlier run of it still waits for a confirmation, so a call an earlier run + * left shown as waiting (the process died, or a newer run replaced it, while the user had not answered) never ran. + */ +private fun List>.withStaleConfirmationsClosed(): List> = + if (none { run -> run.any(ModelMessage::isAwaitingConfirmation) }) this + else map { run -> run.map { if (it.isAwaitingConfirmation()) it.copy(content = INTERRUPTED_CONFIRMATION_RESULT) else it } } + +private fun ModelMessage.isAwaitingConfirmation(): Boolean = role == "tool" && content == AWAITING_CONFIRMATION_RESULT + /** Each unanswered call gets its result right after it: providers such as DeepSeek reject a result that comes later. */ private fun List.withClosedToolCalls(): List { val answered = filter { it.role == "tool" }.mapNotNullTo(hashSetOf()) { it.toolCallId } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolMessages.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolMessages.kt index 49117f0..3874065 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolMessages.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolMessages.kt @@ -69,9 +69,13 @@ internal fun PendingNativeToolUse.awaitingConfirmationMessages(): List) : SessionHistoryPersistence { + override fun load(sessionId: String) = saved[sessionId] + override fun save(sessionId: String, history: StoredSessionHistory) { saved[sessionId] = history } + override fun delete(sessionId: String) { saved.remove(sessionId) } + override fun clear() = saved.clear() +} From e6e15d40f73eeda6fda507c0da1f531ce78e4545 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 02:27:24 -0800 Subject: [PATCH 32/40] fix(runtime): a turn with large images no longer empties the model history Counting images toward the history guard made trimming drop every run, the one just finished included, once a turn carried more than half the guard in images (about 2 MB by default): the next turn's model had no context. Earlier runs now lose their images first, then the oldest runs go, and the newest run always stays. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 +++- .../core/context/SessionHistoryStore.kt | 16 +++++++++---- .../core/context/SessionHistoryStoreTest.kt | 23 ++++++++++++++++--- 3 files changed, 35 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7b9225..443a6fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,9 @@ called out; a patch release does not break it. ## Unreleased (0.5.0) - **Model-history byte guards include multimodal and reasoning data.** Images, reasoning, thinking signatures, - assistant text and deferred-tool metadata count alongside message text when old runs are trimmed. + assistant text and deferred-tool metadata count alongside message text when old runs are trimmed. Past the guard, + earlier runs lose their images before whole runs are dropped, and the newest run always stays, so one turn with + large images does not leave the next turn without the conversation. - **Conversation snapshots are stored once per turn.** A small metadata file serves thread listing; each result has its own file, and visible snapshots and provider history share content-addressed image blobs. Disk-backed threads diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt index 97e8750..73e0b20 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt @@ -155,12 +155,18 @@ internal class SessionHistoryStore @JvmOverloads constructor( } } + /** + * Past [maxBytes], earlier runs lose their images first and then the oldest runs go, down to half of it. The newest + * run always stays whole, so one turn with large images does not leave the next turn without the conversation. + */ private fun trimmed(runs: List>): List> { - var bytes = runs.sumOf { it.historyBytes() } - if (bytes <= maxBytes) return runs + if (runs.sumOf { it.historyBytes() } <= maxBytes) return runs + val kept = runs.mapIndexed { index, run -> if (index == runs.lastIndex) run else run.withoutImages() } + var bytes = kept.sumOf { it.historyBytes() } + if (bytes <= maxBytes) return kept var removed = 0 - while (removed < runs.size && bytes > maxBytes / 2) { bytes -= runs[removed].historyBytes(); removed += 1 } - return runs.drop(removed) + while (removed < kept.lastIndex && bytes > maxBytes / 2) { bytes -= kept[removed].historyBytes(); removed += 1 } + return kept.drop(removed) } private class SessionRuns { @@ -186,6 +192,8 @@ private fun List.historyBytes(): Long = sumOf { message -> } } +private fun List.withoutImages(): List = map { if (it.images.isEmpty()) it else it.copy(images = emptyList()) } + private fun String.utf8Size(): Long = toByteArray(Charsets.UTF_8).size.toLong() /** diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt index 7b252f4..b92e151 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt @@ -110,12 +110,29 @@ class SessionHistoryStoreTest { ) messages.forEach { message -> val store = SessionHistoryStore(maxBytes = 80) - store.start("run", "session") - store.record("run", listOf(message)) - assertTrue(store.messages("session").isEmpty()) + store.start("heavy", "session") + store.record("heavy", listOf(message)) + store.start("next", "session") + store.record("next", listOf(user("next"))) + val kept = store.messages("session") + assertTrue(kept.none { it.images.isNotEmpty() }) + if (message.images.isEmpty()) assertEquals(listOf(user("next")), kept) + else assertEquals(listOf(message.copy(images = emptyList()), user("next")), kept) } } + @Test + fun theNewestRunStaysWholeEvenWhenItAloneIsPastTheGuard() { + val store = SessionHistoryStore(maxBytes = 80) + store.start("older", "session") + store.record("older", listOf(user("看看这张图"))) + val photo = ModelMessage("user", "photo", images = listOf(ModelImage(ByteArray(500), "image/png", "photo"))) + store.start("photo", "session") + store.record("photo", listOf(photo, assistant("是一只猫"))) + + assertEquals(listOf(photo, assistant("是一只猫")), store.messages("session")) + } + @Test fun clearingASessionAlsoStopsARunInFlightFromWritingItBack() { val store = SessionHistoryStore() From 1c0c5d45e4d8abcd4340a8bf58bbd06a49097289 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 02:28:10 -0800 Subject: [PATCH 33/40] fix(storage): one unreadable run record or a failed log write no longer blocks deleting threads Deleting a thread read every other run's record to learn its owner and refused when one could not be read (a record cut short by a killed process, or one from an older version), so no thread could be deleted again. Such a record now belongs to nobody and is left to retention. Once an event-log writer's writes had failed, every later deletion refused too, often when disk was full and deletion was what the user needed; a writer that failed has stopped writing, so deletion goes ahead. Co-Authored-By: Claude Opus 5.5 --- .../runtime/eventlog/AsyncSessionEventLog.kt | 3 ++- .../reliability/FileBackedReliabilityStorage.kt | 5 +++-- .../runtime/eventlog/SessionEventDeletionTest.kt | 16 ++++++++++++++++ .../reliability/SessionArtifactDeletionTest.kt | 12 ++++++++++++ 4 files changed, 33 insertions(+), 3 deletions(-) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt index 85b4331..621fb42 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt @@ -243,7 +243,8 @@ internal class AsyncSessionEventLog( val gate = ROOT_GATES.computeIfAbsent(identity) { ReentrantLock() } return gate.withLock { val writers = synchronized(INSTANCES) { INSTANCES.keys.filter { it.rootGate === gate } } - writers.forEach { check(it.flush()) { "Cannot delete data while event-log writes have failed" } } + // A writer whose writes failed has stopped writing, so nothing it holds can land after the deletion. + writers.forEach { it.flush() } delete().also { deleted -> if (deleted) writers.forEach { it.forgetThread(threadId) } } } } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/reliability/FileBackedReliabilityStorage.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/reliability/FileBackedReliabilityStorage.kt index b0cf23e..de69188 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/reliability/FileBackedReliabilityStorage.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/reliability/FileBackedReliabilityStorage.kt @@ -86,9 +86,10 @@ internal class FileBackedReliabilityStorage( val known = knownRunIds.associateBy(::encodeFileName) return children.filter(File::isDirectory).mapNotNull { child -> known[child.name]?.let { return@mapNotNull storedRunRecord(child).copy(runId = it) } + // A record cut short by a killed process, or written by an older version, names no owner: leave it to + // retention rather than refuse every deletion. val snapshot = File(child, RUN_FILE).decodeOrNull(ReliabilityJsonCodecs::decodeSnapshot) - checkNotNull(snapshot) { "Cannot determine ownership of run artifacts: ${child.name}" } - if (snapshot.sessionId == sessionId) storedRunRecord(child) else null + if (snapshot?.sessionId == sessionId) storedRunRecord(child) else null } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletionTest.kt index e223e44..4cd5c49 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletionTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/eventlog/SessionEventDeletionTest.kt @@ -72,6 +72,22 @@ class SessionEventDeletionTest { } finally { release.countDown(); log.close(); pool.shutdownNow() } } + @Test fun aWriterWhoseWritesFailedDoesNotBlockDeletion() { + val root = Files.createTempDirectory("event-delete-failed-writer-").toFile() + val durable = FileBackedSessionEventLog(root) + durable.append(event("removed")) + val failing = AsyncSessionEventLog(durable, persistBatch = { error("disk full") }) + try { + failing.append(event("removed")) + assertFalse(failing.flush()) + assertTrue(failing.deleteThread("removed")) + assertTrue(durable.query(SessionEventQuery("removed")).isEmpty()) + } finally { + failing.close() + root.deleteRecursively() + } + } + @Test fun subscriberDropsAnOldPageAndReceivesEventsFromTheRecreatedThread() { val root = Files.createTempDirectory("event-delete-subscriber-").toFile() val log = AsyncSessionEventLog(FileBackedSessionEventLog(root)) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/reliability/SessionArtifactDeletionTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/reliability/SessionArtifactDeletionTest.kt index 48de48e..1a10410 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/reliability/SessionArtifactDeletionTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/reliability/SessionArtifactDeletionTest.kt @@ -39,6 +39,18 @@ class SessionArtifactDeletionTest { assertNull(storage.readEvidence("evidence-one")) } + @Test fun anotherRunWhoseRecordCannotBeReadDoesNotBlockDeletion() { + val root = Files.createTempDirectory("delete-unreadable-other-").toFile() + val storage = FileBackedReliabilityStorage(root) + saveRun(storage, "removed", "one") + saveRun(storage, "kept", "torn") + File(root, "runs/${encodeFileName("torn")}/run.json").writeText("{\"runId\":") + File(root, "runs/orphan").mkdirs() + assertEquals(setOf("one"), storage.deleteSession("removed")) + assertNull(storage.readSnapshot("one")) + assertTrue(File(root, "runs/${encodeFileName("torn")}").isDirectory) + } + @Test fun failedDeletesAreReportedAndCanBeRetried() { val root = Files.createTempDirectory("delete-failing-run-").toFile() val storage = FileBackedReliabilityStorage(root) From 1bbcf64a683ecffe77c57c09fc7cea92f9ad61d7 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 02:30:07 -0800 Subject: [PATCH 34/40] fix(runtime): an approval nobody answers in time lets the turn go on Steering accepted while an approval waited was lost when the approval expired: the turn ended, the input was never consumed and the next turn's model never saw it. A voice host that talks instead of tapping the card hit this often. Expiry now works like a denial: the call does not run, the model gets a CONFIRMATION_EXPIRED result and the queued input, and the tool item is DECLINED. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 +++- .../kotlin/cc/noharry/agent/TurnErrorCodes.kt | 2 +- .../kernel/core/loop/NativeToolResumeSupport.kt | 3 ++- .../agent/runtime/ThreadApprovalContinuation.kt | 2 ++ .../agent/runtime/run/NativeLoopFactory.kt | 8 ++++++-- .../agent/runtime/thread/ThreadToolProjection.kt | 2 +- .../agent/runtime/ConfirmationCloseLoopTest.kt | 6 ++++-- .../agent/runtime/ThreadApprovalFlowTest.kt | 15 ++++++++++++--- 8 files changed, 31 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 443a6fa..5696e7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,7 +29,9 @@ called out; a patch release does not break it. after approval or denial resumes their loop. - **Denied approvals continue the same turn.** Both explicit denial and `DENY_ALL` return a - `CONFIRMATION_DENIED` tool result to the model without executing the tool, so it can explain the outcome. + `CONFIRMATION_DENIED` tool result to the model without executing the tool, so it can explain the outcome. An + approval nobody answers in time does the same with `CONFIRMATION_EXPIRED`, so what the user said while it waited + reaches the model instead of being lost with the turn. Cancelling or interrupting a pending approval records `CONFIRMATION_CANCELLED` in provider history. - **Session storage backends support complete deletion.** SQLite removes the session's seven conversation tables diff --git a/agent-api/src/main/kotlin/cc/noharry/agent/TurnErrorCodes.kt b/agent-api/src/main/kotlin/cc/noharry/agent/TurnErrorCodes.kt index d0686f0..2b6b1f9 100644 --- a/agent-api/src/main/kotlin/cc/noharry/agent/TurnErrorCodes.kt +++ b/agent-api/src/main/kotlin/cc/noharry/agent/TurnErrorCodes.kt @@ -33,7 +33,7 @@ object TurnErrorCodes { const val RUNTIME_BUSY = "RUNTIME_BUSY" /** The runtime was closed before the queued turn could execute. */ const val RUNTIME_CLOSED = "RUNTIME_CLOSED" - /** A required approval was not received before its deadline. */ + /** A required approval was not received before its deadline; a tool result carries this code while the turn continues. */ const val CONFIRMATION_EXPIRED = "CONFIRMATION_EXPIRED" /** A tool's approval was denied; a tool result can carry this code while the turn continues. */ const val CONFIRMATION_DENIED = "CONFIRMATION_DENIED" diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolResumeSupport.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolResumeSupport.kt index bdca348..b377f70 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolResumeSupport.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/loop/NativeToolResumeSupport.kt @@ -15,7 +15,8 @@ internal suspend fun declinedToolResult( events: NativePublicEventBuffer, recorder: LoopSessionRecorder, ): ConfirmedToolUseResult { - val result = """{"ok":false,"code":"$code","message":"The user declined this action; the tool was not run."}""" + val why = if (code == CONFIRMATION_EXPIRED_CODE) "The user did not confirm this action in time" else "The user declined this action" + val result = """{"ok":false,"code":"$code","message":"$why; the tool was not run."}""" events.recordStarted(pending.toolCallId, pending.toolUse.toolName, pending.toolUse.argumentsJson) events.recordFinished(pending.toolCallId, pending.toolUse.toolName, result) recorder.recordToolFinished(pending.context, pending.toToolCallEvent(), pending.toolUse.source.toDynamicToolSource(), result) diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuation.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuation.kt index f29ad4d..5ad3f0a 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuation.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ThreadApprovalContinuation.kt @@ -40,7 +40,9 @@ internal suspend fun continueThreadApproval( } if (paused != null) { if (decision == ApprovalState.APPROVED) return loops.resumeConfirmedToolUse(paused, emit) + // Unanswered is like declined: the call does not run and the model goes on, reading what was said meanwhile. if (decision == ApprovalState.DENIED) return loops.resumeDeniedToolUse(paused, emit) + if (decision == ApprovalState.EXPIRED) return loops.resumeDeniedToolUse(paused, emit, "CONFIRMATION_EXPIRED") } val code = when (decision) { ApprovalState.EXPIRED -> "CONFIRMATION_EXPIRED" diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt index 277fa39..a1f6501 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/run/NativeLoopFactory.kt @@ -164,12 +164,16 @@ internal class NativeLoopFactory( ).resumeConfirmedToolUse(pending, emitPublicEvent) } - suspend fun resumeDeniedToolUse(pending: PendingNativeToolUse, emitPublicEvent: suspend (AgentEvent) -> Unit): NativeLoopOutcome { + suspend fun resumeDeniedToolUse( + pending: PendingNativeToolUse, + emitPublicEvent: suspend (AgentEvent) -> Unit, + code: String = "CONFIRMATION_DENIED", + ): NativeLoopOutcome { val runId = pending.context.runId return loop(runId, workspaceFileSystem = workspaces[runId], probeAttachment = probeAttachments[runId] ?: ProbeRunAttachment.disabled(runId), childRun = subagents?.isSubagentSession(pending.context.sessionId) == true) - .resumeAfterApproval(pending, "CONFIRMATION_DENIED", emitPublicEvent) + .resumeAfterApproval(pending, code, emitPublicEvent) } suspend fun resumeUserInput( diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt index c9b6342..5e50fba 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadToolProjection.kt @@ -77,7 +77,7 @@ internal class ThreadToolProjection( private fun resultStatus(output: String): ItemStatus { val root = try { Json.parseToJsonElement(output) as? JsonObject } catch (_: IllegalArgumentException) { null } val code = (root?.get("code") as? JsonPrimitive)?.content - if (code in setOf("CONFIRMATION_DENIED", "POLICY_DENIED", "HOOK_DENIED")) return ItemStatus.DECLINED + if (code in setOf("CONFIRMATION_DENIED", "CONFIRMATION_EXPIRED", "POLICY_DENIED", "HOOK_DENIED")) return ItemStatus.DECLINED val ok = (root?.get("ok") as? JsonPrimitive)?.content return if (ok == "false") ItemStatus.FAILED else ItemStatus.COMPLETED } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationCloseLoopTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationCloseLoopTest.kt index e522e81..e99593a 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationCloseLoopTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ConfirmationCloseLoopTest.kt @@ -106,7 +106,7 @@ class ConfirmationCloseLoopTest { } } - @Test fun anExpiredApprovalRefusesLateResponsesAndClosesTheTurn() = runBlocking { + @Test fun anExpiredApprovalRefusesLateResponsesAndTheTurnGoesOn() = runBlocking { var now = 1_000L approvalBuilder().nowEpochMillis { now }.build().use { runtime -> val thread = runtime.startThread() @@ -120,7 +120,9 @@ class ConfirmationCloseLoopTest { } } assertTurnEvents(events) - assertEquals(TurnErrorCodes.CONFIRMATION_EXPIRED, (events.last() as ThreadEvent.TurnFailed).error.code) + assertTrue(events.last() is ThreadEvent.TurnCompleted) + assertEquals(ItemStatus.DECLINED, events.filterIsInstance().map { it.item } + .filterIsInstance().single { it.tool == "mcp__default__set_temperature" }.status) assertTrue(thread.pendingRequests().isEmpty()) } } diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt index b25263e..f853a2e 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalFlowTest.kt @@ -76,14 +76,18 @@ class ThreadApprovalFlowTest { } } - @Test fun expiryRejectsLateResponses() = runBlocking { + @Test fun expiryRejectsLateResponsesAndTheTurnGoesOnWithoutTheCall() = runBlocking { val built = approvalBuilder().build() as DefaultThreadRuntime DefaultThreadRuntime(built.engine, built.store, confirmationTimeoutMillis = 20).use { runtime -> val events = runtime.startThread().runStreamed("set temperature").toList() assertTurnEvents(events) val pending = events.filterIsInstance().map { it.item }.filterIsInstance().single() assertEquals(RespondResult.EXPIRED, pending.approve()) - assertEquals("CONFIRMATION_EXPIRED", (events.last() as ThreadEvent.TurnFailed).error.code) + assertTrue(events.last() is ThreadEvent.TurnCompleted) + val call = events.filterIsInstance().map { it.item } + .filterIsInstance().single { it.tool == "mcp__default__set_temperature" } + assertEquals(ItemStatus.DECLINED, call.status) + assertTrue(call.output.orEmpty().contains("CONFIRMATION_EXPIRED")) } } @@ -117,7 +121,8 @@ class ThreadApprovalFlowTest { } private suspend fun acceptedInputSurvivesApprovalEnd(action: String) { - val built = approvalBuilder().build() as DefaultThreadRuntime + val requests = mutableListOf() + val built = approvalBuilder(requests = requests).build() as DefaultThreadRuntime DefaultThreadRuntime(built.engine, built.store, confirmationTimeoutMillis = 100).use { runtime -> val thread = runtime.startThread() val events = mutableListOf() @@ -137,6 +142,10 @@ class ThreadApprovalFlowTest { assertEquals("approval-end", inputs.single().requestId) assertEquals("Remember this input", (inputs.single().input.single() as InputPart.Text).text) assertEquals(inputs, thread.items().filterIsInstance().filter { it.steer }) + if (action != "interrupt") { + assertTrue("the model reads what was said while the approval waited", + requests.last().messages.any { it.role == "user" && it.content.contains("Remember this input") }) + } } } } From dd69df5f4e0efe0a1cb6474a7c9d25be942facc0 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 02:31:05 -0800 Subject: [PATCH 35/40] fix(runtime): a web host approved in a turn is not asked again in that turn Giving thread turns a single owner for remembered areas also dropped the network backend's per-run memory, so under ASK every fetch from the same host in one turn asked again. The thread now remembers, for the rest of the turn, the web hosts the person approved; other areas are still asked each time. The policy decisions moved into one function so they can be tested on their own. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + .../runtime/thread/DefaultAgentThread.kt | 13 +++------ .../agent/runtime/thread/ThreadApproval.kt | 27 ++++++++++++++++++- .../agent/runtime/thread/ThreadExecution.kt | 2 ++ .../agent/runtime/ThreadApprovalPolicyTest.kt | 17 ++++++++++++ 5 files changed, 50 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5696e7f..05c7553 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,6 +49,7 @@ called out; a patch release does not break it. host parser; invalid targets are never remembered. MCP approvals cover one tool, with separate namespaces for web, MCP and other tools. `ToolCall.approvedBy` now uses `ApprovalSource.USER`, `REMEMBERED` or `AUTOMATIC`; a denied call has no approval source. Older snapshots with an ambiguous REMEMBER policy leave the source unset. + Within one turn, a web host the person approved is not asked again for later fetches. A call an earlier turn left waiting for approval (the process died, or a newer turn replaced it) reaches the next turn's model as cancelled instead of still waiting. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 842bae9..812c02b 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -214,16 +214,10 @@ internal class DefaultAgentThread( val projection = checkNotNull(turn.projection) val policy = turn.approvalState.policy val domain = approvalDomain(pending.toolName.orEmpty(), pending.argumentsJson.orEmpty()) - val automatic = when (policy) { - ApprovalPolicy.APPROVE_ALL -> ApprovalState.APPROVED - ApprovalPolicy.DENY_ALL -> ApprovalState.DENIED - ApprovalPolicy.REMEMBER -> if (domain != null && domain in runtime.store.rememberedDomains(id)) ApprovalState.APPROVED else null - ApprovalPolicy.ASK -> null - } + val automatic = automaticApproval(policy, domain, { runtime.store.rememberedDomains(id) }, turn.approvedThisTurn) if (automatic != null) { - if (automatic == ApprovalState.APPROVED) projection.toolDecision(pending.idempotencyKey, - if (policy == ApprovalPolicy.REMEMBER) ApprovalSource.REMEMBERED else ApprovalSource.AUTOMATIC) - return automatic + automatic.source?.let { projection.toolDecision(pending.idempotencyKey, it) } + return automatic.state } if (runtime.engine.childApprovalPolicy(id) != null) return ApprovalState.DENIED val approval = ThreadApproval(pending.copy(runId = turn.id), runtime.nowEpochMillis() + runtime.confirmationTimeoutMillis, runtime.nowEpochMillis) @@ -239,6 +233,7 @@ internal class DefaultAgentThread( if (domain != null && decision == ApprovalState.APPROVED && (turn.approvalState.policy == ApprovalPolicy.REMEMBER || approval.scope == ApprovalScope.THREAD)) { withContext(Dispatchers.IO) { runtime.store.rememberDomain(id, domain, generation) } } + if (decision == ApprovalState.APPROVED && isTurnRememberedArea(domain)) turn.approvedThisTurn += checkNotNull(domain) if (decision == ApprovalState.APPROVED) projection.toolDecision(pending.idempotencyKey, approval.approvedBy ?: ApprovalSource.USER) projection.resolveApproval(approval.snapshot()) return decision diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt index 6a6a804..f7d34f0 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadApproval.kt @@ -77,12 +77,37 @@ internal class ThreadApproval( } } +/** A decision a policy makes without asking, and who made it (null for a denial). */ +internal data class AutomaticApproval(val state: ApprovalState, val source: ApprovalSource?) + +/** + * What [policy] decides without asking the person, or null to ask. Besides the thread's remembered areas, a web host + * the person approved earlier in the same turn is not asked again, as before turns waited for approvals themselves. + */ +internal fun automaticApproval( + policy: ApprovalPolicy, + domain: String?, + remembered: () -> Set, + approvedThisTurn: Set, +): AutomaticApproval? = when { + policy == ApprovalPolicy.APPROVE_ALL -> AutomaticApproval(ApprovalState.APPROVED, ApprovalSource.AUTOMATIC) + policy == ApprovalPolicy.DENY_ALL -> AutomaticApproval(ApprovalState.DENIED, null) + domain == null -> null + policy == ApprovalPolicy.REMEMBER && domain in remembered() -> AutomaticApproval(ApprovalState.APPROVED, ApprovalSource.REMEMBERED) + domain.startsWith(WEB_FETCH_AREA) && domain in approvedThisTurn -> AutomaticApproval(ApprovalState.APPROVED, ApprovalSource.USER) + else -> null +} + +internal fun isTurnRememberedArea(domain: String?): Boolean = domain?.startsWith(WEB_FETCH_AREA) == true + +private const val WEB_FETCH_AREA = "web_fetch:" + /** Invalid network targets cannot create a remembered approval for a broader area. */ internal fun approvalDomain(tool: String, arguments: String): String? { if (tool.startsWith("mcp__")) { val qualified = tool.removePrefix("mcp__") return "mcp:${qualified.substringBefore("__")}:${qualified.substringAfter("__", "")}" } - if (tool == "web_fetch") return webFetchApprovalHost(arguments)?.let { "web_fetch:$it" } + if (tool == "web_fetch") return webFetchApprovalHost(arguments)?.let { "$WEB_FETCH_AREA$it" } return "tool:$tool" } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt index ea2ebbe..4ec1709 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/ThreadExecution.kt @@ -37,6 +37,8 @@ internal class ActiveThreadTurn(val id: String, val options: ThreadOptions, val var job: Job? = null var projection: ThreadEventProjection? = null @Volatile var approval: ThreadApproval? = null + /** Web hosts the person approved in this turn; see [automaticApproval]. */ + val approvedThisTurn: MutableSet = java.util.concurrent.ConcurrentHashMap.newKeySet() @Volatile var items: List = emptyList() @Volatile var finalizing = false @Volatile var cancellation: TurnError? = null diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalPolicyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalPolicyTest.kt index 0ba1e46..78b81dc 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalPolicyTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadApprovalPolicyTest.kt @@ -6,7 +6,9 @@ import cc.noharry.agent.* import cc.noharry.agent.spi.* import cc.noharry.agent.spi.model.ModelEvent import cc.noharry.agent.kernel.core.tools.NetworkToolPolicyDecision +import cc.noharry.agent.runtime.thread.AutomaticApproval import cc.noharry.agent.runtime.thread.approvalDomain +import cc.noharry.agent.runtime.thread.automaticApproval import cc.noharry.agent.runtime.thread.ThreadItemCodec import kotlinx.coroutines.runBlocking import kotlinx.serialization.json.JsonObject @@ -88,6 +90,21 @@ class ThreadApprovalPolicyTest { assertNotEquals(approvalDomain("mcp__server_one__first", "{}"), approvalDomain("mcp__server_one__second", "{}")) } + @Test fun aWebHostApprovedEarlierInTheTurnIsNotAskedAgainButOtherAreasAre() { + val host = checkNotNull(approvalDomain("web_fetch", """{"url":"https://example.com/a"}""")) + val tool = checkNotNull(approvalDomain("mcp__cabin__unlock", "{}")) + val turn = setOf(host, tool) + val samePage = approvalDomain("web_fetch", """{"url":"https://example.com/b"}""") + assertEquals(AutomaticApproval(ApprovalState.APPROVED, ApprovalSource.USER), + automaticApproval(ApprovalPolicy.ASK, samePage, { emptySet() }, turn)) + assertNull(automaticApproval(ApprovalPolicy.ASK, tool, { emptySet() }, turn)) + assertNull(automaticApproval(ApprovalPolicy.ASK, approvalDomain("web_fetch", """{"url":"https://other.example/"}"""), { emptySet() }, turn)) + assertNull(automaticApproval(ApprovalPolicy.ASK, samePage, { emptySet() }, emptySet())) + assertEquals(ApprovalState.DENIED, automaticApproval(ApprovalPolicy.DENY_ALL, samePage, { emptySet() }, turn)?.state) + assertEquals(AutomaticApproval(ApprovalState.APPROVED, ApprovalSource.REMEMBERED), + automaticApproval(ApprovalPolicy.REMEMBER, tool, { setOf(tool) }, emptySet())) + } + @Test fun invalidNetworkTargetsNeverGetARememberableCatchAllArea() { for (arguments in listOf("{}", "not-json", """{"url":"invalid"}""", """{"url":"https://user:password@example.com"}""", """{"url":"https://example.com","max_bytes":0}""", """{"url":"http://127.0.0.1"}""")) { From 78c8db6a47241b4760ea19976fa9b97823ef6fc3 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 02:31:47 -0800 Subject: [PATCH 36/40] fix(storage): a JSON document inside a stored tool string stays valid JSON MCP text content often carries a JSON document as a string. Filtering that string as text let the secret pattern take a key's closing quote and value but leave its opening quote, so a host that parsed the text after a restart got invalid JSON. Such a string is now parsed and filtered structurally, then written back. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 ++- .../noharry/agent/runtime/ToolPayloadRedaction.kt | 13 ++++++++++++- .../agent/runtime/ThreadStoragePrivacyTest.kt | 14 ++++++++++++++ 3 files changed, 28 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 05c7553..73605e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,7 +59,8 @@ called out; a patch release does not break it. - **Conversation storage preserves display text and valid tool JSON.** User input and final answers are stored verbatim. Tool payloads retain JSON numeric/boolean/null types while sensitive fields and Bearer credentials are - removed; phone and location filtering follows the configured redactor. Provider model history intentionally + removed; a JSON document carried inside a string (as MCP text content often is) is filtered the same way and stays + valid. Phone and location filtering follows the configured redactor. Provider model history intentionally preserves original messages, reasoning and images, including secrets, for accurate replay. - **Configured event-log locations survive `storage(...)`.** Android continues using its existing `event-log` directory. A storage directory must be used by only one process; multiple runtimes in that process coordinate. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt index 0c99ef7..a4dc112 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt @@ -18,7 +18,18 @@ private fun JsonElement.redactedToolValue(redactor: TraceRedactor): JsonElement if (key.isCredentialField()) JsonPrimitive("[REDACTED_SECRET]") else value.redactedToolValue(redactor) }) is JsonArray -> JsonArray(map { it.redactedToolValue(redactor) }) - is JsonPrimitive -> if (isString) JsonPrimitive(redactor.redact(redactSecrets(content))) else this + is JsonPrimitive -> when { + !isString -> this + // MCP text content often carries a JSON document as a string: filtering it as text would break its syntax. + else -> nestedJson(content)?.let { JsonPrimitive(it.redactedToolValue(redactor).toString()) } + ?: JsonPrimitive(redactor.redact(redactSecrets(content))) + } +} + +private fun nestedJson(text: String): JsonElement? { + val trimmed = text.trim() + if (!(trimmed.startsWith("{") && trimmed.endsWith("}")) && !(trimmed.startsWith("[") && trimmed.endsWith("]"))) return null + return try { Json.parseToJsonElement(trimmed) } catch (_: IllegalArgumentException) { null } } private fun String.isCredentialField(): Boolean { diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt index 13f6822..86077de 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt @@ -27,6 +27,20 @@ class ThreadStoragePrivacyTest { assertFalse(root.walkTopDown().filter(File::isFile).joinToString { it.readText() }.contains("opaque-")) } + @Test fun aJsonDocumentInsideAStringStaysValidJson() { + val root = threadRoot() + val inner = """{"access_token":"opaque-token","n":1,"items":["Bearer opaque-bearer"]}""" + saveTool(root, buildJsonObject { + put("content", buildJsonArray { add(buildJsonObject { put("type", "text"); put("text", inner) }) }) + }.toString()) + val output = ThreadStore(root).items("privacy").filterIsInstance().single().output.orEmpty() + val text = Json.parseToJsonElement(output).jsonObject.getValue("content").jsonArray.single() + .jsonObject.getValue("text").jsonPrimitive.content + val nested = Json.parseToJsonElement(text).jsonObject + assertEquals(1, nested.getValue("n").jsonPrimitive.int) + assertFalse(text.contains("opaque-")) + } + @Test fun disabledPhoneAndLocationRulesStillRemoveCredentials() { val root = threadRoot() saveTool(root, """{"phone":"13800138000","text":"lat=31.2304 Bearer opaque-bearer","refresh_token":"opaque-refresh"}""", From b70b9b177350569a4cb150b20733685f622d2c9f Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 02:32:10 -0800 Subject: [PATCH 37/40] docs: state the measured size of the 0.5.0 public API Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 73605e2..f8fa73a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -138,6 +138,11 @@ called out; a patch release does not break it. Rebuild host code against 0.5.0. The module/package changes and constructor changes are binary breaks. Kotlin hosts import `cc.noharry.agent.builder`; Java hosts construct with `AgentRuntimeBuilder.create()`. +The public API dumps total 5,253 lines across the published modules, down from about 9,400: `agent-api` 2,658 +(the conversation API in `cc.noharry.agent` 770, extension interfaces the rest) and `agent-runtime` 1,514. +Most of what remains beyond the conversation API is the session event payload types and the workspace file system +that hosts implementing their own storage or workspaces need. + | 0.4.x runtime entry | 0.5.0 entry | |---|---| | `run(AgentRequest)` | `startThread` / `resumeThread`, then `run` / `runStreamed` | From be6f9ccefa2d4fe56ed7715171c24e5cad1b8974 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 02:49:09 -0800 Subject: [PATCH 38/40] docs: record the 0.5.0 wrap-up status for the next model Co-Authored-By: Claude Opus 5.5 --- docs/design/public-api-redesign-handoff.md | 2 +- docs/design/public-api-redesign-review.md | 38 ++++++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/design/public-api-redesign-handoff.md b/docs/design/public-api-redesign-handoff.md index 0ba1ab6..7a25973 100644 --- a/docs/design/public-api-redesign-handoff.md +++ b/docs/design/public-api-redesign-handoff.md @@ -5,7 +5,7 @@ > 接手更新(2026-11-06):owner 已在接手会话确认「全部按 9.3 推荐实施」。下文关于 9.2 / 9.3 等确认的记录是交接时的状态,不再是开工阻塞;Maven Central 发布仍需单独授权。实现使用 `codex/api-redesign` 分支和独立 worktree。 -> **2026-11-07 评审:先读 `public-api-redesign-review.md`。** 实现(SDK `dc90409`、Bothy `6713dd08`)经独立评审,发现一批发布前必须修的问题;0.5.0 不发,Bothy 不推,下一步是按那份文档修复。下面第 2 节是实现者自己记录的状态,评审结论以那份文档为准。 +> **2026-11-07 收尾:先读 `public-api-redesign-review.md` 第 0 节。** 评审列的问题和后来核对出的问题都已修好并带测试,SDK 和 Bothy 都已在本地验证;剩下的只有发布(要 owner 点头)、发布后的 Bothy 推送,以及那一节列的几个后续。下面第 2 节是实现者自己记录的状态,以第 0 节为准。 ## 1. 一句话 diff --git a/docs/design/public-api-redesign-review.md b/docs/design/public-api-redesign-review.md index 3cd3646..f73e8b4 100644 --- a/docs/design/public-api-redesign-review.md +++ b/docs/design/public-api-redesign-review.md @@ -5,6 +5,44 @@ > 评审方法:四路只读评审(公开 API、会话运行逻辑、持久化和隐私、Bothy 迁移),每条都按代码路径追过,没有运行。标了 ✔ 的几条又由我亲自读代码核对过。行号以 `dc90409` 和 `6713dd08` 为准,动手前请自己再看一遍。 > 和 owner 交流用中文。 +## 0. 收尾状态(2026-11-07,后写的,以这一节为准) + +下面第 1 到第 9 节是修复前写的评审,留作记录。修复轮之后又做了一轮独立核对,结论如下。 + +**SDK(分支 `codex/api-redesign`)** + +- 第 4.1、4.2、4.3 节列的问题都已修好,下面三条除外,作为后续: + - 4.2 第 6 条:旧的暂停/恢复代码已是 internal,公开 API 调不到,但代码还没删; + - 4.3 第 7 条:`resumeThread` 仍在调用线程上读写一个小的元数据文件,已写进 KDoc,选项没变时不再写盘; + - 4.3 第 8 条:进程在等批准时被杀,恢复后模型会看到这次调用已取消,但界面上不补一条提示。 +- 核对时发现修复轮自己又带进了几个问题,也已修好: + - 一轮里图片超过约 2 MB,整个模型历史会被清空。现在先去掉较早几轮的图片,最新一轮总是保留。 + - 一个读不了的运行记录,或者一次失败的日志写入,会让之后的删除全部失败。 + - 批准过期后,等待期间用户插的话会丢。现在过期和拒绝一样,接着跑。 + - 字符串里嵌着的 JSON,过滤后会变成非法 JSON。 + - 在「每次都问」下,同一轮里同一个网站会反复询问。现在同一轮里批准过的网站不再问。 +- 另外新增:宿主在一轮进行中通过 `resumeThread` 改批准策略,正在跑的那一轮和它正在等的批准立刻按新策略处理(Bothy 跑到一半切换模式要用)。 +- 每个修复都带了测试。2026-11-07 在这批修复上跑了完整的 `apiCheck` 和 `ciCheck`:1,848 个测试,0 失败,2 个跳过。Bothy 本地分支对着这个 SDK 分支跑 `scripts/validate.py` 也全部通过。 +- 搁置不做的:每个会话的存储上限(`ThreadStorageLimits`,本地分支 `codex/api-storage-repair` 上的 WIP 提交 `1b8fbeb`,还编不过)。这是新增功能,不破坏兼容,可以晚于 0.5.0;另外「回执满了就拒绝新轮次」这个设计对长期会话不友好,做之前要先定。 +- 早就存在、这次没修的:Android 上关闭运行时不会关闭 SQLite 数据库(`AndroidSqliteSessionStore` 不是 `AutoCloseable`),会等 GC 回收。 + +**Bothy(本地分支 `codex/api-redesign`,`~/project/bothy-api`,未推送)** + +- 第 5 节的问题都已修: + - 插话按请求 id 显示:用户说的话是插话气泡;计划提醒、委托报告只显示运行行。 + - 最终答案经过 `shownReply()`,不再出现「TTS:」开头的行。 + - 陪聊和计划提醒的上下文接回来了;超长时截短,不再让下一轮失败。 + - A2A 令牌在设置里能看到。 + - 「批准过的不再问」下批准一次会记住;卡片只显示网站名;跑到一半切换模式会同步给正在跑的那一轮。 + - 子 agent 用父会话的批准策略。 + - 一轮里有工具失败时,结束时写「Runtime result」行,手机靠它判断失败。 + - A2A 进度和看板恢复成 Bothy 自己的说法。 +- 修了两个测试问题: + - 一个会一直挂住的测试:它按旧的 id 订阅事件,永远等不到; + - 四个按执行 id 查事件的测试:事件日志里 `runId` 现在是执行 id,按轮次查要用 `requestId`。 +- 早就存在、这次没修的:`bothy-app` 的设备测试 `TrajectoryColdReadDeviceTest` 从 11-04 拆 server 起就编不过。它用到的类搬到了 agent-app-server 的包里,而且是 internal;同时它又要用 bothy-app 自己的东西。要修得把它挪到合适的模块并重写,validate 和 CI 都不编它。 +- 推送前还要做:把所有 checkpoint 提交合成一个,去掉 harness trace 文件,依赖改成 Maven 上的 0.5.0(发布之后)。 + ## 1. 结论 - 方向和主体结构是对的,设计稿的大部分内容都做出来了,CI 也是绿的。第 9 节列了确认没问题的部分,不要动。 From 40b311efae698398630226f90dc3f30231b96e79 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 02:57:12 -0800 Subject: [PATCH 39/40] fix(runtime): close the gaps the pre-push review found in the wrap-up fixes - Deleting a thread now waits until nothing an event-log writer accepted can still reach storage. A writer refusing new events because its queue was full keeps writing, so letting deletion go ahead on any failure (the previous commit) could write a deleted thread's events back. - A message that was only images keeps "[image omitted]" when an earlier run loses its images: Anthropic refuses empty content, which failed every later turn of the conversation. - Only the person's own yes to a web host carries over for the rest of the turn; one a policy gave ends with it. - Stored tool payloads nested past 64 levels are filtered as text instead of parsed, so a hostile document cannot exhaust the stack. - CHANGELOG: phone filtering applies to string values; numbers stay numbers. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 +- .../core/context/SessionHistoryStore.kt | 7 ++- .../agent/runtime/ToolPayloadRedaction.kt | 52 +++++++++++++++---- .../runtime/eventlog/AsyncSessionEventLog.kt | 18 ++++++- .../runtime/thread/DefaultAgentThread.kt | 4 +- .../core/context/SessionHistoryStoreTest.kt | 10 ++++ .../agent/runtime/ThreadStoragePrivacyTest.kt | 8 +++ 7 files changed, 86 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f8fa73a..a48dc4c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,7 +60,8 @@ called out; a patch release does not break it. - **Conversation storage preserves display text and valid tool JSON.** User input and final answers are stored verbatim. Tool payloads retain JSON numeric/boolean/null types while sensitive fields and Bearer credentials are removed; a JSON document carried inside a string (as MCP text content often is) is filtered the same way and stays - valid. Phone and location filtering follows the configured redactor. Provider model history intentionally + valid. Phone and location filtering follows the configured redactor for string values; numbers stay numbers + (timestamps and ids would otherwise read as phone numbers). Provider model history intentionally preserves original messages, reasoning and images, including secrets, for accurate replay. - **Configured event-log locations survive `storage(...)`.** Android continues using its existing `event-log` directory. A storage directory must be used by only one process; multiple runtimes in that process coordinate. diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt index 73e0b20..a5d3af2 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStore.kt @@ -192,7 +192,12 @@ private fun List.historyBytes(): Long = sumOf { message -> } } -private fun List.withoutImages(): List = map { if (it.images.isEmpty()) it else it.copy(images = emptyList()) } +/** A message that was only images keeps a word in their place: providers such as Anthropic refuse empty content. */ +private fun List.withoutImages(): List = map { + if (it.images.isEmpty()) it else it.copy(images = emptyList(), content = it.content.ifBlank { IMAGE_OMITTED }) +} + +private const val IMAGE_OMITTED = "[image omitted]" private fun String.utf8Size(): Long = toByteArray(Charsets.UTF_8).size.toLong() diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt index a4dc112..fb4f667 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/ToolPayloadRedaction.kt @@ -9,26 +9,56 @@ import kotlinx.serialization.json.JsonPrimitive /** Preserve JSON types and syntax while removing credentials and applying the host's text policy. */ internal fun redactToolPayload(value: String, redactor: TraceRedactor): String { - val parsed = try { Json.parseToJsonElement(value) } catch (_: IllegalArgumentException) { null } - return parsed?.redactedToolValue(redactor)?.toString() ?: redactor.redact(redactSecrets(value)) + val parsed = if (nestingDepth(value) > MAX_JSON_DEPTH) null + else try { Json.parseToJsonElement(value) } catch (_: IllegalArgumentException) { null } + return parsed?.redactedToolValue(redactor, 0)?.toString() ?: redactor.redact(redactSecrets(value)) } -private fun JsonElement.redactedToolValue(redactor: TraceRedactor): JsonElement = when (this) { - is JsonObject -> JsonObject(mapValues { (key, value) -> - if (key.isCredentialField()) JsonPrimitive("[REDACTED_SECRET]") else value.redactedToolValue(redactor) +/** Past [MAX_JSON_DEPTH] levels a value is filtered as text, so a hostile document cannot exhaust the stack. */ +private fun JsonElement.redactedToolValue(redactor: TraceRedactor, depth: Int): JsonElement = when { + depth >= MAX_JSON_DEPTH -> JsonPrimitive(redactor.redact(redactSecrets(toString()))) + this is JsonObject -> JsonObject(mapValues { (key, value) -> + if (key.isCredentialField()) JsonPrimitive("[REDACTED_SECRET]") else value.redactedToolValue(redactor, depth + 1) }) - is JsonArray -> JsonArray(map { it.redactedToolValue(redactor) }) - is JsonPrimitive -> when { - !isString -> this - // MCP text content often carries a JSON document as a string: filtering it as text would break its syntax. - else -> nestedJson(content)?.let { JsonPrimitive(it.redactedToolValue(redactor).toString()) } - ?: JsonPrimitive(redactor.redact(redactSecrets(content))) + this is JsonArray -> JsonArray(map { it.redactedToolValue(redactor, depth + 1) }) + this is JsonPrimitive && !isString -> this + // MCP text content often carries a JSON document as a string: filtering it as text would break its syntax. + else -> (this as JsonPrimitive).let { text -> + nestedJson(text.content)?.let { JsonPrimitive(it.redactedToolValue(redactor, depth + 1).toString()) } + ?: JsonPrimitive(redactor.redact(redactSecrets(text.content))) } } +private const val MAX_JSON_DEPTH = 64 + +/** How deep brackets nest outside string literals, read without parsing (which a hostile document could overflow). */ +private fun nestingDepth(text: String): Int { + var depth = 0 + var deepest = 0 + var inString = false + var escaped = false + for (c in text) { + if (inString) { + when { + escaped -> escaped = false + c == '\\' -> escaped = true + c == '"' -> inString = false + } + continue + } + when (c) { + '"' -> inString = true + '{', '[' -> { depth += 1; if (depth > deepest) deepest = depth } + '}', ']' -> depth -= 1 + } + } + return deepest +} + private fun nestedJson(text: String): JsonElement? { val trimmed = text.trim() if (!(trimmed.startsWith("{") && trimmed.endsWith("}")) && !(trimmed.startsWith("[") && trimmed.endsWith("]"))) return null + if (nestingDepth(trimmed) > MAX_JSON_DEPTH) return null return try { Json.parseToJsonElement(trimmed) } catch (_: IllegalArgumentException) { null } } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt index 621fb42..13deacb 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/eventlog/AsyncSessionEventLog.kt @@ -30,6 +30,8 @@ internal class AsyncSessionEventLog( private var pendingBytes = 0L private var closing = false private var failure: String? = null + /** The writer gave up after a failed write; a full acceptance queue alone leaves it writing. */ + private var writerStopped = false private val openedStreams = java.util.Collections.synchronizedSet(mutableSetOf()) init { rootGate.withLock { synchronized(INSTANCES) { INSTANCES[this] = true } } } @@ -110,6 +112,7 @@ internal class AsyncSessionEventLog( } catch (error: Exception) { lock.withLock { failure = safeFailureCode(error) + writerStopped = true changed.signalAll() } signalDeliveries() @@ -131,6 +134,16 @@ internal class AsyncSessionEventLog( return batch } + /** Waits until nothing accepted can still reach storage: all of it written, or the writer stopped on a failure. */ + internal fun awaitSettled(): Boolean = lock.withLock { + var remaining = TimeUnit.SECONDS.toNanos(FLUSH_TIMEOUT_SECONDS) + while (pending.isNotEmpty() && !writerStopped) { + if (remaining <= 0) return@withLock false + remaining = changed.awaitNanos(remaining) + } + true + } + /** Waits only for storage, never for UI callbacks. Failure stays visible in health. */ fun flush(): Boolean = lock.withLock { var remaining = TimeUnit.SECONDS.toNanos(FLUSH_TIMEOUT_SECONDS) @@ -243,8 +256,9 @@ internal class AsyncSessionEventLog( val gate = ROOT_GATES.computeIfAbsent(identity) { ReentrantLock() } return gate.withLock { val writers = synchronized(INSTANCES) { INSTANCES.keys.filter { it.rootGate === gate } } - // A writer whose writes failed has stopped writing, so nothing it holds can land after the deletion. - writers.forEach { it.flush() } + // Nothing a writer accepted may land after the deletion. A writer that stopped on a failed write holds + // nothing that can; one refusing new events because its queue is full is still writing, so wait. + writers.forEach { check(it.awaitSettled()) { "Cannot delete data while event-log writes are in flight" } } delete().also { deleted -> if (deleted) writers.forEach { it.forgetThread(threadId) } } } } diff --git a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt index 812c02b..2f158d1 100644 --- a/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt +++ b/agent-runtime/src/main/kotlin/cc/noharry/agent/runtime/thread/DefaultAgentThread.kt @@ -233,7 +233,9 @@ internal class DefaultAgentThread( if (domain != null && decision == ApprovalState.APPROVED && (turn.approvalState.policy == ApprovalPolicy.REMEMBER || approval.scope == ApprovalScope.THREAD)) { withContext(Dispatchers.IO) { runtime.store.rememberDomain(id, domain, generation) } } - if (decision == ApprovalState.APPROVED && isTurnRememberedArea(domain)) turn.approvedThisTurn += checkNotNull(domain) + // Only the person's own yes carries over; one a policy gave ends with the policy. + val byPerson = (approval.approvedBy ?: ApprovalSource.USER) == ApprovalSource.USER + if (decision == ApprovalState.APPROVED && byPerson && isTurnRememberedArea(domain)) turn.approvedThisTurn += checkNotNull(domain) if (decision == ApprovalState.APPROVED) projection.toolDecision(pending.idempotencyKey, approval.approvedBy ?: ApprovalSource.USER) projection.resolveApproval(approval.snapshot()) return decision diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt index b92e151..9acaa98 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/kernel/core/context/SessionHistoryStoreTest.kt @@ -121,6 +121,16 @@ class SessionHistoryStoreTest { } } + @Test + fun aMessageThatWasOnlyImagesKeepsAWordWhenItsImagesGo() { + val store = SessionHistoryStore(maxBytes = 80) + store.start("photo", "session") + store.record("photo", listOf(ModelMessage("user", "", images = listOf(ModelImage(ByteArray(200), "image/png", "p"))))) + store.start("next", "session") + store.record("next", listOf(user("next"))) + assertEquals(listOf("[image omitted]", "next"), store.messages("session").map { it.content }) + } + @Test fun theNewestRunStaysWholeEvenWhenItAloneIsPastTheGuard() { val store = SessionHistoryStore(maxBytes = 80) diff --git a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt index 86077de..39746da 100644 --- a/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt +++ b/agent-runtime/src/test/kotlin/cc/noharry/agent/runtime/ThreadStoragePrivacyTest.kt @@ -41,6 +41,14 @@ class ThreadStoragePrivacyTest { assertFalse(text.contains("opaque-")) } + @Test fun aDeeplyNestedDocumentIsFilteredWithoutExhaustingTheStack() { + val deep = "[".repeat(5_000) + "\"Bearer opaque-bearer\"" + "]".repeat(5_000) + val payload = buildJsonObject { put("text", deep) }.toString() + val redacted = redactToolPayload(payload, DefaultTraceRedactor) + assertFalse(redacted.contains("opaque-")) + Json.parseToJsonElement(redacted) + } + @Test fun disabledPhoneAndLocationRulesStillRemoveCredentials() { val root = threadRoot() saveTool(root, """{"phone":"13800138000","text":"lat=31.2304 Bearer opaque-bearer","refresh_token":"opaque-refresh"}""", From 3e9b2124bd449c2e66f257cdab8943635bba27c8 Mon Sep 17 00:00:00 2001 From: NoHarry Date: Sat, 7 Nov 2026 03:05:14 -0800 Subject: [PATCH 40/40] docs: record the verified 0.5.0 wrap-up, follow-ups and next steps Co-Authored-By: Claude Opus 5.5 --- docs/design/public-api-redesign-review.md | 83 +++++++++++++++-------- 1 file changed, 56 insertions(+), 27 deletions(-) diff --git a/docs/design/public-api-redesign-review.md b/docs/design/public-api-redesign-review.md index f73e8b4..5d5e63b 100644 --- a/docs/design/public-api-redesign-review.md +++ b/docs/design/public-api-redesign-review.md @@ -7,41 +7,70 @@ ## 0. 收尾状态(2026-11-07,后写的,以这一节为准) -下面第 1 到第 9 节是修复前写的评审,留作记录。修复轮之后又做了一轮独立核对,结论如下。 +下面第 1 到第 9 节是修复前写的评审,留作记录。修复轮之后又做了两轮独立核对,所有阻断问题都已修好。 -**SDK(分支 `codex/api-redesign`)** +### SDK(分支 `codex/api-redesign`,PR #1) -- 第 4.1、4.2、4.3 节列的问题都已修好,下面三条除外,作为后续: - - 4.2 第 6 条:旧的暂停/恢复代码已是 internal,公开 API 调不到,但代码还没删; - - 4.3 第 7 条:`resumeThread` 仍在调用线程上读写一个小的元数据文件,已写进 KDoc,选项没变时不再写盘; - - 4.3 第 8 条:进程在等批准时被杀,恢复后模型会看到这次调用已取消,但界面上不补一条提示。 -- 核对时发现修复轮自己又带进了几个问题,也已修好: - - 一轮里图片超过约 2 MB,整个模型历史会被清空。现在先去掉较早几轮的图片,最新一轮总是保留。 - - 一个读不了的运行记录,或者一次失败的日志写入,会让之后的删除全部失败。 +- 第 4.1、4.2、4.3 节的问题都已修好,下面「后续」里列的几条除外。 +- 核对时发现修复轮自己又带进了几个问题,也已修好,每个都带测试: + - 一轮里图片超过约 2 MB,整个模型历史会被清空。现在先去掉较早几轮的图片(只有图片的消息留下「[image omitted]」),最新一轮总是保留。 + - 一个读不了的运行记录,或者一次失败的日志写入,会让之后的删除全部失败。现在删除前会等写入线程把已经收下的事件写完,或者确认它已经因写失败停下。 - 批准过期后,等待期间用户插的话会丢。现在过期和拒绝一样,接着跑。 - - 字符串里嵌着的 JSON,过滤后会变成非法 JSON。 - - 在「每次都问」下,同一轮里同一个网站会反复询问。现在同一轮里批准过的网站不再问。 -- 另外新增:宿主在一轮进行中通过 `resumeThread` 改批准策略,正在跑的那一轮和它正在等的批准立刻按新策略处理(Bothy 跑到一半切换模式要用)。 -- 每个修复都带了测试。2026-11-07 在这批修复上跑了完整的 `apiCheck` 和 `ciCheck`:1,848 个测试,0 失败,2 个跳过。Bothy 本地分支对着这个 SDK 分支跑 `scripts/validate.py` 也全部通过。 -- 搁置不做的:每个会话的存储上限(`ThreadStorageLimits`,本地分支 `codex/api-storage-repair` 上的 WIP 提交 `1b8fbeb`,还编不过)。这是新增功能,不破坏兼容,可以晚于 0.5.0;另外「回执满了就拒绝新轮次」这个设计对长期会话不友好,做之前要先定。 -- 早就存在、这次没修的:Android 上关闭运行时不会关闭 SQLite 数据库(`AndroidSqliteSessionStore` 不是 `AutoCloseable`),会等 GC 回收。 - -**Bothy(本地分支 `codex/api-redesign`,`~/project/bothy-api`,未推送)** - -- 第 5 节的问题都已修: - - 插话按请求 id 显示:用户说的话是插话气泡;计划提醒、委托报告只显示运行行。 - - 最终答案经过 `shownReply()`,不再出现「TTS:」开头的行。 + - 字符串里嵌着的 JSON,过滤后会变成非法 JSON。现在按结构过滤;嵌套超过 64 层的,按文本过滤。 + - 在「每次都问」下,同一轮里同一个网站会反复询问。现在同一轮里人批准过的网站不再问;策略自动批准的不算。 +- 新增:宿主在一轮进行中通过 `resumeThread` 改批准策略,正在跑的那一轮和它正在等的批准,立刻按新策略处理。 +- 验证: + - 在 `40b311e` 之前跑过完整的 `apiCheck` 和 `ciCheck`,1,848 个测试,0 失败,2 个跳过。 + - `40b311e` 跑了相关测试,完整检查交给 PR #1 的 CI。 + +### Bothy(本地分支 `codex/api-redesign`,`~/project/bothy-api`,提交 `af07701a`,未推送) + +- 第 5 节的问题都已修好: + - 插话按请求 id 显示:用户说的话是插话气泡;计划提醒、委托报告只显示运行行。登记表全进程共用,切换会话也不会显示错。 + - 最终答案不再带「TTS:」开头的行,实时显示和重启后读回的历史都一样。 - 陪聊和计划提醒的上下文接回来了;超长时截短,不再让下一轮失败。 - - A2A 令牌在设置里能看到。 + - A2A 令牌能在设置里看到。 - 「批准过的不再问」下批准一次会记住;卡片只显示网站名;跑到一半切换模式会同步给正在跑的那一轮。 - 子 agent 用父会话的批准策略。 - 一轮里有工具失败时,结束时写「Runtime result」行,手机靠它判断失败。 - A2A 进度和看板恢复成 Bothy 自己的说法。 -- 修了两个测试问题: - - 一个会一直挂住的测试:它按旧的 id 订阅事件,永远等不到; - - 四个按执行 id 查事件的测试:事件日志里 `runId` 现在是执行 id,按轮次查要用 `requestId`。 -- 早就存在、这次没修的:`bothy-app` 的设备测试 `TrajectoryColdReadDeviceTest` 从 11-04 拆 server 起就编不过。它用到的类搬到了 agent-app-server 的包里,而且是 internal;同时它又要用 bothy-app 自己的东西。要修得把它挪到合适的模块并重写,validate 和 CI 都不编它。 -- 推送前还要做:把所有 checkpoint 提交合成一个,去掉 harness trace 文件,依赖改成 Maven 上的 0.5.0(发布之后)。 +- 设备检查发现并修好的: + - 一个问题显示两遍:现在只显示一条,并作为这一轮的回答; + - 停下来提问的那一轮被标成「replay failed」,现在算正常结束。 +- 测试问题: + - 一个会一直挂住的测试,以及四个按执行 id 查事件的测试,都已修正; + - `TrajectoryClearAdmissionRaceTest` 在机器负载高时偶尔超时,单独跑都能通过。 +- 验证:`scripts/validate.py` 全部通过。 +- 设备检查: + - 模拟器:普通一轮;拒绝后接着跑,卡片显示网站名;等批准时切到全部允许,批准立刻生效;插话显示成插话气泡,没有另开一轮;杀进程重启后,历史还在、模型记得前面的内容;提问后下一句话回答能接上;A2A 不带令牌 401、带令牌 completed。 + - 平板 HA2H3Y7F(装的是 `dev.116+af07701a`):普通一轮;重启后历史和记忆;A2A 401 和 completed。测试会话已删除,无障碍服务和录音权限已恢复。 + +### 后续(不影响 0.5.0) + +- **SDK**: + - 每个会话的存储上限(`ThreadStorageLimits`):本地分支 `codex/api-storage-repair` 上的 WIP 提交 `1b8fbeb`,还编不过。这是新增功能,不破坏兼容;而且「回执满了就拒绝新轮次」这个设计对长期会话不友好,要先定。 + - 旧的暂停/恢复代码已经是 internal,但还没删。 + - `resumeThread` 仍会读写一个小的元数据文件(已写进 KDoc)。 + - 进程在等批准时被杀,恢复后界面上不补一条提示(模型那边已经看到「已取消」)。 + - 一轮刚开始的那一刻改策略,可能不生效。 + - Android 关闭运行时不会关闭 SQLite 数据库(早就存在)。 +- **Bothy**: + - `TrajectoryColdReadDeviceTest` 从 11-04 拆 server 起就编不过,要挪到合适的模块重写;validate 和 CI 都不编它。 + - Bothy 和示例 App 都默认用 8766 端口,两个都装时,后启动的那个起不来 A2A 服务。 + - 插话气泡重启后不显示(会话存储只记每轮的问答,迁移前也一样)。 + - 只有批准网页抓取时卡片才显示网站;其他工具的批准卡片沿用旧的「要联网」文字。 + +### 接下来 + +1. PR #1 的 CI 绿了以后,把 SDK 的 main 快进到这个分支并推送。 +2. 等 owner 点头,发布 0.5.0。 +3. Bothy: + 1. 把所有 checkpoint 提交合成一个,按 Bothy 的格式写说明; + 2. 去掉 `harness/trace/2026-11-06-sdk-thread-api-migration.md`; + 3. `agentRuntimeVersion` 改成 0.5.0; + 4. 从零编一遍,跑 validate,评审后推送; + 5. 在平板上再验一遍。 +4. 更新知识体系文章:重新固定链接,并按新 API 改写正文。 ## 1. 结论