amiru 0.1.0 → 0.2.0

package/README.md

@@ -1,149 +1,175 @@
-# Amiru
-
-**Amiru** 是一个运行在 DeepSeek Harness 上的 QQ AI 陪伴运行时。角色由人设卡决定，而不是写死在代码里；它不自己连接 QQ，也不复制 QQ 插件，而是复用官方 QQ 机器人插件的会话与出站能力。
-
-它只做四件事：
-
-1. **收/发官方 QQ 消息**：复用 [`@tencent-connect/dsh-qqbot`](https://www.npmjs.com/package/@tencent-connect/dsh-qqbot) 的 session、preset、出站与主动投递。
-2. **按用户隔离的长期记忆**：以 `account_id + chat_key` 为边界，不按昵称、不跨用户共享。
-3. **可直接编辑的人设卡**：Markdown 文件放在本地，改完下一轮生效，不是黑盒。
-4. **克制的主动对话**：静默时长、免打扰、每日上限、连续未回退避；触发后走一轮正常 Agent 回合。
-
-> Amiru 是“陪伴运行时”，不是“恋爱模拟器”。默认人设卡只是一个示例，你可以把它换成任何角色：朋友、搭档、树洞、虚构人物，或完全自定义的存在。
-
-## 状态
-
-当前是 **可运行的原型**：已在 DSH + 官方 QQ 机器人上跑通私聊收发、首轮人设注入与记忆写入。主动回合已实现，仍需要更多 live 验证。
-
-主动消息需要 QQ 插件包含 `proactiveDelivery.externalTurns`。仓库市面上的 `dsh-qqbot` v0.5.5 旧构建没有这个能力；请使用带该能力的源码版本（见下文）。
-
-## 架构
-
-```text
-QQ 用户
-  ↕  QQ WebSocket
-@tencent-connect/dsh-qqbot
-  ↕  DSH Agent / session / outbound
-Amiru
-  ├─ binding：哪个 QQ 会话用哪张人设卡
-  ├─ prompt：静态人设、关系状态、记忆上下文
-  ├─ memory：本地 JSON / JSONL，按 binding 隔离
-  └─ proactive：定时评估，通过 Agent.followup() 发起正常回合
-```
-
-Amiru **不新开第二条 QQ 连接**，也不绕过 QQ 插件的发送链路。
-
-## 环境要求
-
-- DeepSeek Harness（DSH）
-- 已安装并启用的官方 QQ 机器人插件 `@tencent-connect/dsh-qqbot`
-- QQ 开放平台机器人 `appId` / `appSecret`
-- Node.js 20+
-- 可选的源码版 QQ 插件，用于主动消息投递
-
-## 安装
-
-### 从源码安装（当前推荐）
-
-先安装带 `externalTurns` 的 QQ 插件源码版：
-
-```text
-plugin_manager install_bundle target="/absolute/path/to/dsh-qqbot"
-```
-
-如果该源码包是 `link:` 安装，`plugin_manager` 不会替它安装依赖。先在其目录执行：
-
-```bash
-pnpm install --prod --ignore-scripts
-```
-
-再安装 Amiru：
-
-```text
-plugin_manager install_bundle target="/absolute/path/to/amiru"
-```
-
-安装后重启 DSH，确认插件列表出现 `Amiru`。
-
-### 从 npm 安装（发布后）
-
-```text
-plugin_manager install_bundle target="amiru@0.1.0"
-```
-
-## QQ 插件配置
-
-在 QQ 机器人插件的配置中确认：
-
-- `appId` / `appSecret` 已填写；
-- 私聊访问模式允许你的账号；
-- `proactiveDelivery.externalTurns` 为 `c2c`（只私聊）或 `all`（私聊和群聊）；
-- 建议给陪伴会话单独设置一个 Agent preset，避免和编码助手共用同一套工具与提示词。
-
-如果 DSH 通过系统代理启动，而代理不可用或不代理 QQ，请在启动 DSH 前设置：
-
-```text
-NO_PROXY=localhost,127.0.0.1,api.sgroup.qq.com,bots.qq.com,q.qq.com
-```
-
-Windows 可以用：
-
-```powershell
-setx NO_PROXY "localhost,127.0.0.1,api.sgroup.qq.com,bots.qq.com,q.qq.com"
-```
-
-然后**完全退出并重新打开 DSH**。QQ 的 token 域名是 `bots.qq.com`，OpenAPI 是 `api.sgroup.qq.com`；漏掉前者会一直报 `ECONNREFUSED 127.0.0.1:7890`。
-
-## 人设卡
-
-首次启动会自动生成：
-
-```text
-~/.amiru/personas/default.md
-```
-
-直接编辑这个 Markdown。标题就是段落名；`〔私聊〕` 只注入私聊，`〔群聊〕` 只注入群聊，不写标记则两边都用。
-
-```markdown
-# 名字
-阿梨
-
-# 年龄与身份
-24 岁，在城市里做独立插画师。
-
-# 性格
-温柔，有自己的边界；会吐槽，但不刻薄。
-
-# 说话方式
-短句，口语化。不用客服腔，不列清单，不主动说“我可以帮你……”。
-
-# 〔私聊〕关系边界
-亲密但不低俗；不查岗，不要求秒回。
-
-# 禁止
-不要自称 AI 助手、心理咨询师或客服。
-```
-
-改完下一轮生效，不需要重启。也可以新增 `~/.amiru/personas/another.md`，把 binding 的 `personaId` 改成 `another`。
-
-**选卡提示**：从 SillyTavern / Chub / JanitorAI 等社区拿到的角色卡不能直接导入，需要改写成 Markdown；删掉 `{{char}}` / `{{user}}` 等模板语法，控制在 6000 字符以内。
-
-## 记忆
-
-```text
-~/.amiru/
-  bindings.json      # 每个 QQ 私聊/群聊的 binding
-  memories.json      # 结构化长期记忆
-  messages.jsonl     # 最近对话，最多 5000 条
-  personas/          # 人设卡
-```
-
-- 以 `account_id + chat_key` 隔离，不用昵称做 key，避免同名串记忆。
-- 每轮确定性写入用户/助手消息；`amiru_remember` 工具让模型在明确事实、偏好、承诺、日期、边界时主动记一条。
-- 规则扫描会兜底记录“我叫… / 我喜欢… / 我答应… / 记住…”这类句子。
-- 注入预算默认 1400 字，只放关系状态、长期记忆、上一次会话的最近几条，避免和当前对话重复。
-- 所有数据都在本机，没有遥测，也不会上传到第三方。
-
+# Amiru
+
+**Amiru** 是一个运行在 DeepSeek Harness 上的 QQ AI 陪伴运行时。角色由人设卡决定，而不是写死在代码里；它不自己连接 QQ，也不复制 QQ 插件，而是复用官方 QQ 机器人插件的会话与出站能力。
+
+它只做四件事：
+
+1. **收/发官方 QQ 消息**：复用 [`@tencent-connect/dsh-qqbot`](https://www.npmjs.com/package/@tencent-connect/dsh-qqbot) 的 session、preset、出站与主动投递。
+2. **按用户隔离的长期记忆**：以 `account_id + chat_key` 为边界，不按昵称、不跨用户共享。
+3. **可直接编辑的人设卡**：Markdown 文件放在本地，改完下一轮生效，不是黑盒。
+4. **克制的主动对话**：静默时长、免打扰、每日上限、连续未回退避；触发后走一轮正常 Agent 回合。
+
+> Amiru 是“陪伴运行时”，不是“恋爱模拟器”。默认人设卡只是一个示例，你可以把它换成任何角色：朋友、搭档、树洞、虚构人物，或完全自定义的存在。
+
+## 状态
+
+当前是 **可运行的原型**：已在 DSH + 官方 QQ 机器人上跑通私聊收发、首轮人设注入与记忆写入。主动回合已实现，仍需要更多 live 验证。
+
+主动消息需要 QQ 插件包含 `proactiveDelivery.externalTurns`。仓库市面上的 `dsh-qqbot` v0.5.5 旧构建没有这个能力；请使用带该能力的源码版本（见下文）。
+
+## 架构
+
+```text
+QQ 用户
+  ↕  QQ WebSocket
+@tencent-connect/dsh-qqbot
+  ↕  DSH Agent / session / outbound
+Amiru
+  ├─ binding：哪个 QQ 会话用哪张人设卡
+  ├─ prompt：静态人设、关系状态、记忆上下文
+  ├─ memory：本地 JSON / JSONL，按 binding 隔离
+  └─ proactive：定时评估，通过 Agent.followup() 发起正常回合
+```
+
+Amiru **不新开第二条 QQ 连接**，也不绕过 QQ 插件的发送链路。
+
+## 环境要求
+
+- DeepSeek Harness（DSH）
+- 已安装并启用的官方 QQ 机器人插件 `@tencent-connect/dsh-qqbot`
+- QQ 开放平台机器人 `appId` / `appSecret`
+- Node.js 20+
+- 可选的源码版 QQ 插件，用于主动消息投递
+
+## 安装
+
+### 从源码安装（当前推荐）
+
+先安装带 `externalTurns` 的 QQ 插件源码版：
+
+```text
+plugin_manager install_bundle target="/absolute/path/to/dsh-qqbot"
+```
+
+如果该源码包是 `link:` 安装，`plugin_manager` 不会替它安装依赖。先在其目录执行：
+
+```bash
+pnpm install --prod --ignore-scripts
+```
+
+再安装 Amiru：
+
+```text
+plugin_manager install_bundle target="/absolute/path/to/amiru"
+```
+
+安装后重启 DSH，确认插件列表出现 `Amiru`。
+
+### 从 npm 安装（发布后）
+
+```text
+plugin_manager install_bundle target="amiru@0.1.0"
+```
+
+## QQ 插件配置
+
+在 QQ 机器人插件的配置中确认：
+
+- `appId` / `appSecret` 已填写；
+- 私聊访问模式允许你的账号；
+- `proactiveDelivery.externalTurns` 为 `c2c`（只私聊）或 `all`（私聊和群聊）；
+- 建议给陪伴会话单独设置一个 Agent preset，避免和编码助手共用同一套工具与提示词。
+
+如果 DSH 通过系统代理启动，而代理不可用或不代理 QQ，请在启动 DSH 前设置：
+
+```text
+NO_PROXY=localhost,127.0.0.1,api.sgroup.qq.com,bots.qq.com,q.qq.com
+```
+
+Windows 可以用：
+
+```powershell
+setx NO_PROXY "localhost,127.0.0.1,api.sgroup.qq.com,bots.qq.com,q.qq.com"
+```
+
+然后**完全退出并重新打开 DSH**。QQ 的 token 域名是 `bots.qq.com`，OpenAPI 是 `api.sgroup.qq.com`；漏掉前者会一直报 `ECONNREFUSED 127.0.0.1:7890`。
+
+## 人设卡
+
+卡就是一份 Markdown 文件，默认放在：
+
+```text
+~/.amiru/personas/default.md
+```
+
+`~/.amiru` 是插件的 `dataDir`。**插件不会替你生成这张卡**——没有卡时，它会告诉 agent「还没有人设卡」，由 agent 和你商量怎么建。
+
+想直接看效果，可以用自带的示例卡（文件不存在时才写入，不会覆盖你已有的卡）：
+
+```text
+~/.amiru/personas/samples/ali.md
+```
+
+把它复制成 `default.md` 就是一张能用的卡。
+
+### 卡长什么样
+
+`#` 标题就是段落名；标题里可以带 `〔私聊〕` 或 `〔群聊〕`，只在那类会话注入，不写标记则两边都用。
+
+```markdown
+# 名字
+阿梨
+
+# 年龄与身份
+24 岁，在城市里做独立插画师。
+
+# 性格
+温柔，有自己的边界；会吐槽，但不刻薄。
+
+# 说话方式
+短句，口语化。不用客服腔，不列清单，不主动说“我可以帮你……”。
+
+# 〔私聊〕关系边界
+亲密但不低俗；不查岗，不要求秒回。
+
+# 禁止
+不要自称 AI 助手、心理咨询师或客服。
+```
+
+注入上限默认 6000 字（`maxPersonaChars`）。超过上限的部分**不会**进入上下文——保存时 agent 会看到实际字数，剩下的内容仍在文件里，不会丢。
+
+### 怎么写
+
+- **想自己写**：用 SillyTavern / 酒馆这类写卡工具写好，把卡（内容或文件）交给 agent，它会改写成上面的格式再保存。
+- **不想写**：直接跟 agent 说想要什么样的角色，聊几轮让它帮你写一张。
+- **拿现成的卡**：社区卡（SillyTavern / Chub / JanitorAI 等）不能直接导入，需要改写成 Markdown、去掉 `{{char}}` / `{{user}}` 之类的模板语法。
+
+agent 通过 `amiru_persona_save` 工具把卡存进 `~/.amiru/personas/`。
+
+### 什么时候生效
+
+卡是每轮实时读取的，改文件下一轮就生效，不用重启。
+
+但**旧对话仍然在上下文里**，带着旧人设说过的话。所以换卡之后请开一个新会话：QQ 里发 `/new`，桌面端点侧边栏的「新会话」。
+
+也可以新增 `~/.amiru/personas/another.md`，把 binding 的 `personaId` 改成 `another`。
+
+## 记忆
+
+```text
+~/.amiru/
+  bindings.json      # 每个 QQ 私聊/群聊的 binding
+  memories.json      # 结构化长期记忆
+  messages.jsonl     # 最近对话，最多 5000 条
+  personas/          # 人设卡
+```
+
+- 以 `account_id + chat_key` 隔离，不用昵称做 key，避免同名串记忆。
+- 每轮确定性写入用户/助手消息；`amiru_remember` 工具让模型在明确事实、偏好、承诺、日期、边界时主动记一条。
+- 规则扫描会兜底记录“我叫… / 我喜欢… / 我答应… / 记住…”这类句子。
+- 注入预算默认 1400 字，只放关系状态、长期记忆、上一次会话的最近几条，避免和当前对话重复。
+- 所有数据都在本机，没有遥测，也不会上传到第三方。
+
 ### 从旧版迁移
 
 0.1.0 之前这个项目先后叫过 **AIGirl** 和 **Ami**，两个旧数据目录都可以直接搬过来：
@@ -156,64 +182,64 @@ cp -a ~/.aigirl ~/.amiru  # 或从更早的 AIGirl 版本升级
 然后重新安装 Amiru，并把 binding 的 `personaId` 指向 `~/.amiru/personas/` 下的文件。
 
 
-## 主动对话
-
-默认策略：
-
-| 项 | 默认 |
-|---|---|
-| 静默多久才考虑 | 120 分钟 |
-| 两次主动最小间隔 | 120 分钟 |
-| 每天上限 | 2 条 |
-| 至少聊过 | 3 条用户消息 |
-| 免打扰 | 23:30–08:00 |
-| 连续未回 | 2 次后 48 小时不再发 |
-
-触发优先级：连续未回后的轻接话 → 长时间沉默 → 日常想起。提示词要求给出具体由头，并直接输出一句自然、简短、可以立刻发出去的话。
-
-> **为什么没有 `<SKIP>`**：`agent.followup()` 产生的 assistant 文本会由 QQ 插件直接出站，出站层无法可靠拦截占位符。因此主动回合在硬门通过后才生成，提示词不再提供“跳过”选项，避免把 `<SKIP>` 原样发给用户。
-
-## 配置
-
-`cordis.patch.yml` 里的 `config` 可改：
-
-```yaml
-enabled: true
-defaultPersona: default
-dataDir: ~/.amiru
-proactive:
-  enabled: true
-  idleMinutes: 120
-  minIntervalMinutes: 120
-  dailyCap: 2
-  minUserMessages: 3
-  quietStart: '23:30'
-  quietEnd: '08:00'
-  maxUnanswered: 2
-  backoffHours: 48
-```
-
-`qqPrefsPath` 默认读 `~/.dsh-qqbot/model-prefs.json`，也可用环境变量 `QQBOT_DATA_DIR`。
-
-## 开发
-
-```bash
-node --test test/*.test.js
-npm run check
-```
-
-代码结构：
-
-- `index.js`：事件接线、QQ session 识别、主动 tick。
-- `src/persona.js`：Markdown 人设卡解析与 scope 过滤。
-- `src/qq.js`：`qqbot:<appId>:<scope>:<peerId>` 解析与 prefs 反查。
-- `src/store.js`：binding / message / memory 持久化。
-- `src/memory.js`：关系摘要、记忆注入、规则兜底。
-- `src/proactive.js`：硬门、评分、主动提示词。
-- `src/prompt.js`：`amiru:*` system prompt 段与 `amiru_remember` 工具。
-
-详细设计见 [`docs/plugin-design.md`](docs/plugin-design.md) 与 [`docs/runtime-spec.md`](docs/runtime-spec.md)。
-
-## 许可
-
-MIT
+## 主动对话
+
+默认策略：
+
+| 项 | 默认 |
+|---|---|
+| 静默多久才考虑 | 120 分钟 |
+| 两次主动最小间隔 | 120 分钟 |
+| 每天上限 | 2 条 |
+| 至少聊过 | 3 条用户消息 |
+| 免打扰 | 23:30–08:00 |
+| 连续未回 | 2 次后 48 小时不再发 |
+
+触发优先级：连续未回后的轻接话 → 长时间沉默 → 日常想起。提示词要求给出具体由头，并直接输出一句自然、简短、可以立刻发出去的话。
+
+> **为什么没有 `<SKIP>`**：`agent.followup()` 产生的 assistant 文本会由 QQ 插件直接出站，出站层无法可靠拦截占位符。因此主动回合在硬门通过后才生成，提示词不再提供“跳过”选项，避免把 `<SKIP>` 原样发给用户。
+
+## 配置
+
+`cordis.patch.yml` 里的 `config` 可改：
+
+```yaml
+enabled: true
+defaultPersona: default
+dataDir: ~/.amiru
+proactive:
+  enabled: true
+  idleMinutes: 120
+  minIntervalMinutes: 120
+  dailyCap: 2
+  minUserMessages: 3
+  quietStart: '23:30'
+  quietEnd: '08:00'
+  maxUnanswered: 2
+  backoffHours: 48
+```
+
+`qqPrefsPath` 默认读 `~/.dsh-qqbot/model-prefs.json`，也可用环境变量 `QQBOT_DATA_DIR`。
+
+## 开发
+
+```bash
+node --test test/*.test.js
+npm run check
+```
+
+代码结构：
+
+- `index.js`：事件接线、QQ session 识别、主动 tick。
+- `src/persona.js`：Markdown 人设卡解析与 scope 过滤。
+- `src/qq.js`：`qqbot:<appId>:<scope>:<peerId>` 解析与 prefs 反查。
+- `src/store.js`：binding / message / memory 持久化。
+- `src/memory.js`：关系摘要、记忆注入、规则兜底。
+- `src/proactive.js`：硬门、评分、主动提示词。
+- `src/prompt.js`：`amiru:*` system prompt 段与 `amiru_remember` 工具。
+
+详细设计见 [`docs/plugin-design.md`](docs/plugin-design.md) 与 [`docs/runtime-spec.md`](docs/runtime-spec.md)。
+
+## 许可
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amiru",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "Persona-driven AI companion runtime for the official QQ bot plugin in DeepSeek Harness",

package/src/persona.js

@@ -95,7 +95,7 @@ export class PersonaStore {
     this.defaultPersona = safeId(defaultPersona) || 'default'
     this.maxChars = maxChars
     mkdirSync(this.dir, { recursive: true })
-    this.ensureDefault()
+    this.ensureSamples()
   }
 
   pathFor(id) {
@@ -103,10 +103,16 @@ export class PersonaStore {
     return safe ? join(this.dir, `${safe}.md`) : null
   }
 
-  ensureDefault() {
-    const path = this.pathFor(this.defaultPersona)
-    if (!path) return
-    if (!existsSync(path)) this.save(this.defaultPersona, PERSONA_TEMPLATE)
+  ensureSamples() {
+    const dir = join(this.dir, 'samples')
+    const path = join(dir, 'ali.md')
+    mkdirSync(dir, { recursive: true })
+    if (!existsSync(path)) writeFileSync(path, PERSONA_TEMPLATE, 'utf8')
+  }
+
+  exists(id) {
+    const path = this.pathFor(id)
+    return Boolean(path) && existsSync(path)
   }
 
   list() {
@@ -139,7 +145,7 @@ export class PersonaStore {
     if (!path) throw new Error(`invalid persona id: ${id}`)
     mkdirSync(this.dir, { recursive: true })
     const tmp = `${path}.${process.pid}.tmp`
-    writeFileSync(tmp, String(content ?? '').slice(0, this.maxChars), 'utf8')
+    writeFileSync(tmp, String(content ?? ''), 'utf8')
     renameSync(tmp, path)
     return path
   }

package/src/prompt.js

@@ -2,6 +2,10 @@ import { buildMemoryContext } from './memory.js'
 
 const attached = new WeakSet()
 
+const PERSONA_MISSING_TEXT = `当前还没有人设卡，不要自行扮演某个固定角色。
+可以请用户选一条路：① 直接用示例卡（personas/samples/ali.md，复制成卡即可）；② 把自己用写卡工具做好的卡发过来，改写成上面的格式再存；③ 现在简单聊几句，帮他写一张。
+写好用 amiru_persona_save 保存。保存后提醒开新会话（QQ 用 /new，桌面点侧边栏「新会话」）。`
+
 function getService(agentCtx, name) {
   if (agentCtx && typeof agentCtx.get === 'function') {
     const service = agentCtx.get(name)
@@ -22,6 +26,13 @@ export function attachPrompt(agentCtx, { binding, resolveBinding, store, persona
   // Resolve at render time so the first turn still gets the persona.
   const currentBinding = typeof resolveBinding === 'function' ? resolveBinding : () => binding
 
+  const personaId = () => currentBinding()?.personaId ?? config.defaultPersona ?? 'default'
+  const contractLine = () => {
+    const id = personaStore.resolveId?.(personaId()) ?? personaId()
+    const path = personaStore.pathFor?.(id) ?? ''
+    return `卡文件：${path}｜# 分段，标题可带〔私聊〕〔群聊〕｜≤${config.maxPersonaChars} 字｜保存用 amiru_persona_save`
+  }
+
   systemPrompt.section({
     name: 'amiru:rules',
     order: 430,
@@ -33,7 +44,13 @@ export function attachPrompt(agentCtx, { binding, resolveBinding, store, persona
     order: 441,
     text: () => {
       const current = currentBinding()
-      return current ? personaStore.get(current.personaId, current.scope || 'c2c') : ''
+      const id = personaId()
+      if (!current) return contractLine()
+      const exists = personaStore.exists?.(id) ?? false
+      const body = personaStore.get(id, current.scope || 'c2c')
+      if (!exists) return `${contractLine()}\n\n${PERSONA_MISSING_TEXT}`
+      if (!body) return `${contractLine()}\n\n（这张卡没有适用于当前场景的段落）`
+      return `${contractLine()}\n\n${body}`
     },
   })
 
@@ -87,6 +104,58 @@ export function attachPrompt(agentCtx, { binding, resolveBinding, store, persona
         return item ? { ok: true, saved: item.text } : { ok: false }
       },
     })
+
+    tools.register({
+      name: 'amiru_persona_save',
+      description: '把人设卡 markdown 存进插件的人设目录。用户给出一张卡（自己写的或用写卡工具导出的）后，把它改写成我们的格式再调用本工具保存。',
+      parameters: {
+        type: 'object',
+        properties: {
+          markdown: { type: 'string', description: '完整的人设卡 markdown。' },
+          id: { type: 'string', description: '卡的文件名（不含扩展名），默认存成当前使用的卡。' },
+        },
+        required: ['markdown'],
+      },
+      output: {
+        schema: {
+          type: 'object',
+          properties: {
+            ok: { type: 'boolean' },
+            id: { type: 'string' },
+            path: { type: 'string' },
+            chars: { type: 'number' },
+            limit: { type: 'number' },
+            truncated: { type: 'boolean' },
+            active: { type: 'boolean' },
+            reason: { type: 'string' },
+          },
+          required: ['ok'],
+        },
+        render(args, value) {
+          if (!value?.ok) return '没有保存。'
+          const head = value.truncated
+            ? `已保存到 ${value.path}（${value.chars} 字，超过 ${value.limit} 字注入上限，超出部分不会进入上下文）。`
+            : `已保存到 ${value.path}（${value.chars} 字）。`
+          return `${head}要让这张卡生效，请开新会话：QQ 用 /new，桌面点侧边栏「新会话」。`
+        },
+      },
+      execute(args) {
+        const text = String(args?.markdown ?? '').trim()
+        if (!text) return { ok: false, reason: 'empty' }
+        const target = args?.id === undefined ? personaId() : (personaStore.resolveId?.(args.id) ?? args.id)
+        if (!personaStore.pathFor?.(target)) return { ok: false, reason: 'invalid-id' }
+        const path = personaStore.save(target, text)
+        return {
+          ok: true,
+          id: target,
+          path,
+          chars: text.length,
+          limit: config.maxPersonaChars,
+          truncated: text.length > config.maxPersonaChars,
+          active: Boolean(currentBinding()) && target === personaId(),
+        }
+      },
+    })
   }
 
   attached.add(agentCtx)