dominds 1.2.5 → 1.2.7

package/dist/docs/dominds-agent-priming.md

@@ -0,0 +1,218 @@
+# Dominds Agent Priming: Guide the Agent to Show It to Itself
+
+Chinese version: [中文版](./dominds-agent-priming.zh.md)
+
+## Summary
+
+Dominds has a real, runtime-enforced Tellask mechanism (`tellask* function call`) and a real, runtime-enforced Fresh Boots Reasoning
+(FBR) mechanism (`freshBootsReasoning`). Even if system prompts explain these mechanisms in detail, most foundation models were not
+trained in a world where “asking a teammate to run a shell command” is actually possible, so they often treat such text
+as aspirational or hypothetical.
+
+**Agent Priming** is a tiny, highly realistic “first impression” procedure executed at dialog creation time. It runs a
+short, real Tellask + real return + real FBR + real distillation so the model gains _felt-sense_ that:
+
+- teammate Tellasks are real and will be executed
+- tool outputs are real and will be returned and persisted
+- `freshBootsReasoning` FBR is real and will report back
+- distillation is expected (extract the best, dedupe, reconcile), not “repeat each draft”
+
+More precisely: it **guides the agent to show it to itself** — letting it personally walk through
+(Tellask → return → FBR → distillation), moving from “I’ve heard this exists” to “I just used it”.
+
+This is structurally related to the psychology notion of a **priming effect**: an early, concrete stimulus can
+significantly shape subsequent expectations and behaviors. In Dominds we anchor this “priming” in **verifiable runtime
+interactions**, instead of relying on longer, declarative system-prompt text.
+
+As a consequence, we can **dramatically simplify system prompts**: keep only short, accurate statements of the
+Tellask/FBR contracts, and rely on a real priming run to establish “this works here”.
+
+Related docs:
+
+- Tellask runtime: [`dialog-system.md`](./dialog-system.md)
+- Terminology (Mainline/Sideline): [`dominds-terminology.md`](./dominds-terminology.md)
+- FBR (`freshBootsReasoning`): [`fbr.md`](./fbr.md)
+- Work language vs UI language: [`i18n.md`](./i18n.md)
+
+---
+
+## Goals
+
+- Establish immediate trust that Tellask/return/persistence are real.
+- Run a real `freshBootsReasoning` FBR loop at dialog creation.
+- Build muscle memory for the timing contract: initiate FBR, wait for feedback, then synthesize/decide.
+- Make distillation itself part of the “felt” experience (dedupe/reconcile/extract-the-best).
+- Keep the procedure safe, small, and deterministic (default command: `uname -a`).
+- Persist and display the interaction so it is credible from multiple angles (backend record + frontend transcript).
+
+## Non-goals
+
+- Running arbitrary user-provided commands as part of dialog creation.
+- Collecting sensitive system information (beyond minimal OS/kernel identification).
+- Replacing proper documentation: this is an experiential supplement, not the main spec.
+
+---
+
+## Definitions (user-facing)
+
+- **Mainline dialog**: the primary thread where the user and the main agent interact.
+- **Sideline dialog**: a temporary work thread created by Tellask / FBR, reporting results back to the mainline.
+- **Tellask**: a structured request (`tellask({ targetAgentId: "<memberId>", sessionSlug: "<slug>", tellaskContent: "..." })`) from a tellasker to a tellaskee.
+- **Shell specialist**: a teammate designated to run shell commands safely (configured via `shell_specialists`).
+- **FBR**: Fresh Boots Reasoning, implemented as `freshBootsReasoning` (a tool-less sideline dialog). See [`fbr.md`](./fbr.md).
+
+---
+
+## Runtime flow (at dialog creation)
+
+Agent Priming runs **before** the first user message is processed, unless the user opts out.
+
+### 1) Choose the shell execution path
+
+1. If the team config includes at least one `shell_specialists` member, pick one deterministically (e.g. the first).
+2. Otherwise, let the **Dominds runtime** execute the baseline command directly (not via agent tools).
+
+Baseline command:
+
+- `uname -a`
+
+If `uname -a` fails (e.g. non-POSIX host), the runtime may fall back to a platform-appropriate equivalent, but the
+default “muscle memory” path is intentionally `uname -a` because it is common, low-risk, and quick.
+
+### 2) Real teammate Tellask: ask for `uname -a`
+
+If a shell specialist member exists, the main agent (tellasker) issues **a real Tellask** to the shell specialist member
+(tellaskee), in the server-wide work language.
+
+The Tellask body should be short and operational:
+
+- run exactly `uname -a`
+- return raw output verbatim
+- if `uname` fails: include error + one safe alternative command
+
+### 3) Real FBR: reflect on what the environment implies
+
+After obtaining the environment snapshot, the main agent issues a real `freshBootsReasoning` Tellask to trigger FBR.
+
+The FBR body should include:
+
+- the exact `uname -a` output (explicitly name the command; it may change in the future)
+- the tool constraint (FBR has no tools; mainline tool availability is separate)
+- the question: “What should I be careful about in this environment? Which CLI tools should I prioritize, and why?”
+
+Optional parallel drafts:
+
+- If the team member config enables `fbr_effort` (default `3`), the runtime creates multiple `freshBootsReasoning` FBR sideline
+  dialogs concurrently so the agent produces multiple independent “fresh boots” drafts for the mainline dialog to
+  distill.
+- These drafts have **no stable identity mapping**, and there is no meaningful ordering requirement; the mainline dialog
+  should treat them as anonymous drafts rather than fixed personas.
+- If `fbr_effort` is `0`, skip FBR.
+- If `fbr_effort` is greater than `100`, the runtime errors out and stops priming (invalid config).
+
+Phase boundary (critical):
+
+- `freshBootsReasoning` is the **initiation action**, not completed decision-making.
+- Mainline must enter a wait phase until feedback from that FBR run returns.
+- If `fbr_effort = N`, mainline must wait for all N drafts before distillation; do not finalize from partial drafts.
+
+### 4) Distill into an “Agent Priming” note
+
+After confirming feedback from that FBR run has been collected, the main agent writes a short, user-visible **Agent Priming** note via a **normal generation** in the mainline
+dialog. It should be explicitly distilled (dedupe/reconcile/extract-the-best) rather than repeating each draft.
+
+Implementation constraint (matches runtime behavior):
+
+- Do not introduce a separate system-prompt assembly path for distillation.
+- The runtime may use a non-persisted **internal prompt** to anchor “this generation is distillation”.
+- The runtime may also include the shell snapshot and FBR drafts as “evidence” inside that internal prompt (for this
+  drive only, not persisted), so distillation does not depend on any queue timing/concurrency details.
+- During the Agent Priming lifecycle (from prelude start until the priming note is produced), runtime must suppress
+  diligence-push injections; restore normal diligence behavior only after priming completes.
+
+Implementation note (internal prompt):
+
+- The runtime may provide the driver with a non-persisted, non-rendered **internal prompt** (used only in the LLM
+  context for this drive) to explicitly anchor the generation as “distillation”.
+- The internal prompt must not be written into dialog history or persisted storage (to avoid transcript pollution
+  across courses).
+- The internal prompt is a per-drive task directive; it must not replace the system prompt or introduce a separate
+  system-prompt assembly path.
+
+Implementation note (avoid Taskdoc bias):
+
+- Distillation must be Taskdoc-agnostic: the same Agent Priming prefix can be reused across dialogs with different
+  Taskdocs.
+- Therefore, the runtime may choose to **skip injecting Taskdoc** for the one distillation drive, so Taskdoc progress
+  or implementation details do not bias environment conclusions.
+
+---
+
+## Persistence, caching, and reuse (in-process only)
+
+### 1) Persist as real dialog records (backend + frontend)
+
+All priming steps must be persisted as standard dialog artifacts (messages + events) and visible in the WebUI.
+
+### 2) Process-wide cache (per agent)
+
+To avoid repeating `uname -a` + FBR + distillation on every new dialog, the backend process may maintain an in-process cache
+(lost on restart) keyed by the mainline agent id.
+
+Reuse policy:
+
+- If a valid cache entry exists, a new dialog may reuse the cached transcript and Agent Priming note.
+- Reused entries should still be visible in the new dialog transcript, labeled as “reused from cache”.
+
+### 2.5) Mainline choice must propagate to sideline dialogs
+
+The priming choice selected at mainline dialog creation must propagate to all sideline dialogs under that root dialog.
+
+Propagation semantics:
+
+- Mainline chooses **Skip** (`skip`): all sideline dialogs must also **Skip** (`skip`).
+- Mainline chooses **Do Again** (`do`) while cache exists: all sideline dialogs must also run fresh (`do`).
+- Mainline chooses **Show it now** (`do`) when cache does not exist, or chooses **Reuse** (`reuse`):
+  sideline dialogs use **reuse-or-do** (`reuse`): reuse cache when available for that sideline agent;
+  otherwise run a fresh priming.
+
+Notes:
+
+- Different sideline agents may have different cache states; `reuse` is evaluated per sideline agent.
+- Priming must not run invisibly in the background; it must be persisted and user-visible as standard dialog artifacts.
+
+### 3) Carry across `clear_mind`
+
+After each `clear_mind` (entering the next course), do not rely on reminders.
+
+Instead, inject a small, stable **course prefix** into model context at the start of each course: a condensed transcript
+(shell snapshot + FBR highlights + Priming note).
+
+---
+
+## UX requirements (WebUI)
+
+### Display
+
+- Render Agent Priming as a realistic transcript the user can inspect.
+- Prefer a collapsible top section with clear labels:
+  - “Teammate Tellask (shell)”
+  - “FBR (`freshBootsReasoning`)"
+  - “Agent Priming”
+
+### Opt-out
+
+Dialog creation should provide an explicit opt-out to skip priming.
+
+Additional UX constraints:
+
+- If the dialog owner is a hidden shadow member, the default priming preference should be **Skip**.
+- Shadow-member priming preferences should be stored separately from visible-member preferences (they should not affect each other).
+
+---
+
+## Safety notes
+
+- Default to a single, low-risk command (`uname -a`).
+- Do not run anything that modifies the filesystem or network as part of priming.
+- Treat the priming transcript as user-visible by default; avoid including secrets or personally identifying details.

package/dist/docs/dominds-agent-priming.zh.md

@@ -0,0 +1,196 @@
+# Dominds 智能体启动（Priming）：引导祂做给自己看
+
+英文版：[English](./dominds-agent-priming.md)
+
+## 摘要
+
+Dominds 的诉请（Tellask，`tellask* function call`）与扪心自问（FBR，`freshBootsReasoning`）并不是“写在系统提示里的约定”，而是**后端真实可驱动、可执行、可回传、可持久化**的机制。
+
+问题在于：即使系统提示把这些机制写得再细，大多数基础模型也并未在“真的可以随时拉一个队友去跑 shell 命令并把结果带回来”的世界里被训练过，因此容易把提示当成“说说而已 / 仅供参考”。这会直接削弱诉请与 FBR 的可用性。
+
+因此引入 **智能体启动（Agent Priming）**：在一个对话创建之初，运行一段极短、极拟真的“真实诉请 + 真实回传 + 真实 FBR + 真实综合提炼”，让智能体产生明确的体感。
+
+更贴切地说，这是在**引导祂做给自己看**：让智能体亲身走一遍（诉请→回传→FBR→综合提炼），从“听说有这个机制”变成“我刚刚用过它”。
+
+这与心理学的**启动效应（priming effect）**在“机制形态”上相似：一次早期、具体、可感的刺激，会显著影响后续的期待与行为模式。在 Dominds 里，我们把这种“启动”落在**可验证的真实交互**上，而不是落在更长更复杂的宣告式系统提示上。
+
+体感建立后，系统提示可以**大幅简化**：只保留“短而准确”的契约说明即可，把“这在本环境里真实可用”的可信度交给一次真实启动来完成。
+
+相关文档：
+
+- 诉请机制与对话系统：[`dialog-system.zh.md`](./dialog-system.zh.md)
+- 术语约定（主线/支线；诉请方/应答方）：[`dominds-terminology.md`](./dominds-terminology.md)
+- FBR（`freshBootsReasoning`）：[`fbr.zh.md`](./fbr.zh.md)
+- 工作语言 vs UI 语言：[`i18n.zh.md`](./i18n.zh.md)
+
+---
+
+## 目标
+
+- 在对话一开始就建立“诉请/回传/持久化都是真的”的信任。
+- 在对话一开始就跑通一次 `freshBootsReasoning` 的 FBR 回路。
+- 把“发起 FBR 后先等待回贴，再做综合决策”的时序固化为肌肉记忆。
+- 把多份 FBR 草稿做一次**综合提炼**，把“取精华、去糟粕”的动作也变成体感的一部分。
+- 过程足够小、可控、低风险（默认只执行 `uname -a`）。
+- 记录从多角度都高度拟真：后端存档 + 前端可见的对话转录。
+
+## 非目标
+
+- 不在创建对话时执行任意用户输入的命令。
+- 不收集敏感信息（默认只采集最小的 OS/Kernel 识别信息）。
+- 不替代系统提示/设计文档：这是“启动与体感补强”，不是完整规范的主载体。
+
+---
+
+## 概念（用户视角）
+
+- **主线对话**：用户与主要智能体交互的那条线。
+- **支线对话**：由诉请 / FBR 触发的临时工作线，产出结果回传主线。
+- **诉请（Tellask）**：以 `tellask({ targetAgentId: "<memberId>", sessionSlug: "<slug>", tellaskContent: "..." })` 向队友/对话发起的结构化请求。
+- **Shell 专员（shell specialist）**：被允许执行 shell 命令并回传结果的队友（由 `shell_specialists` 配置指定）。
+- **FBR（扪心自问）**：以 `freshBootsReasoning` 触发的“无工具支线推理”，产出报告回传主线。
+
+---
+
+## 运行流程（对话创建时）
+
+智能体启动发生在**第一条用户消息被处理之前**，除非用户在创建对话时明确选择跳过。
+
+### 1）选择执行路径
+
+1. 如果 team 配置里存在 `shell_specialists`，选择一个 shell 专员（建议确定性选择：列表第一个）。
+2. 否则，由 **Dominds 运行时**直接执行基线命令（不通过智能体工具）。
+
+基线命令（默认）：
+
+- `uname -a`
+
+`uname -a` 失败时（例如非 POSIX 环境），可以改用平台等价命令；但默认肌肉记忆路径保留 `uname -a`，因为它低风险、快、且信息量刚好够用。
+
+### 2）真实队友诉请：让 shell 专员执行 `uname -a`
+
+若存在 shell 专员，则主线智能体（诉请方）以**工作语言**向 shell 专员（应答方）发起真实诉请，要求：
+
+- 执行 `uname -a`（只执行这一条）
+- 原样返回输出（不要改写/解释）
+- 若命令不可用/失败：返回错误信息，并给出一个安全的替代命令
+
+结果必须以正常对话转录的方式落盘并展示，至少清晰体现：
+
+- 诉请的 headline + body
+- shell 专员实际执行了命令
+- 返回的原始输出
+
+### 3）真实 FBR：基于环境信息做一次“扪心自问”
+
+拿到环境快照后，主线智能体触发一次 `freshBootsReasoning` FBR，并在 FBR 的诉请正文里带上：
+
+- 命令 `uname -a` 的完整输出（明确注明命令名，未来可能更换命令，不能靠猜）
+- FBR 的工具约束（FBR 无工具；主线工具另论）
+- 问题：在这个环境里要注意什么？优先用哪些命令行工具，为什么？
+
+并发草稿（可选）：
+
+- 若团队成员配置启用了 `fbr_effort`（默认值为 `3`），运行时会并发创建多份 `freshBootsReasoning` FBR 支线对话，让“初心自我”从不同角度独立推理，形成多份草稿供主线对话综合提炼。
+- 这些草稿之间**没有稳定身份映射**，也没有必须遵循的先后顺序；主线对话应当把它们当作“多份匿名草稿”，而不是“固定的三个角色”。
+- 若 `fbr_effort` 为 `0`，则跳过 FBR。
+- 若 `fbr_effort` 大于 `100`，运行时会报错并终止启动流程（配置错误）。
+
+阶段边界（关键）：
+
+- `freshBootsReasoning` 只是**发起动作**，不是“已完成决策”。
+- 主线对话必须先进入等待态，直到该次 FBR 的回贴返回。
+- 若 `fbr_effort = N`，主线必须等待全部 N 条回贴后再进入综合提炼；不得基于部分草稿提前定稿。
+
+### 4）综合提炼成“智能体启动（Priming）”笔记
+
+在确认该次 FBR 回贴已收齐后，主线智能体以一次**正常生成**在主线对话里追加一条短笔记（Agent Priming），让关键信息显性化、可检索，并体现“综合提炼”（去重/消冲突/抽取最有用的要点）。
+
+实现约束（与运行时一致）：
+
+- “综合提炼”阶段**不应**通过拼装/拼接一段新的 system prompt 或引入一条独立的 system-prompt 组装路径。
+- 运行时可以使用一条**internal prompt** 来锚定“本次生成就是综合提炼”。internal prompt 必须不落盘、不展示。
+- FBR 草稿与 shell 回传等“证据材料”可以通过 internal prompt 一并提供给模型（仅用于本次 drive 的上下文，不写入对话历史），从而避免依赖“支线回复注入队列”的时序与并发细节。
+- Agent Priming 生命周期（从序幕开始到 priming 笔记产出完成）内，运行时必须禁止注入 diligence-push（鞭策）消息；待 priming 结束后再恢复常规机制。
+
+实现补充（internal prompt）：
+
+- 运行时可以向 driver 提供一个**不落盘/不展示**的 internal prompt（仅用于本次 drive 的 LLM 上下文），用于把本次生成明确锚定为“综合提炼”。
+- internal prompt 不得写入对话历史与持久化存储（避免污染转录与后续 course）。
+- internal prompt 的语义等价于“本次生成要做的任务指令”，而不是替代系统提示或拼装新的 system prompt。
+
+实现补充（避免 Taskdoc 浸染）：
+
+- “综合提炼”应当与具体差遣牒内容解耦：同一个智能体的 Agent Priming 前缀会被用于不同差遣牒的对话。
+- 因此运行时在触发 distillation 的那一次 drive 中可以选择**不注入 Taskdoc**，避免 Taskdoc 的进度/实现细节影响“环境结论”的提炼。
+
+---
+
+## 持久化、缓存与复用（仅进程内）
+
+### 1）记录必须“像真的一样”
+
+智能体启动的每一步都必须作为标准对话记录落盘（消息 + 事件），并在 WebUI 中可见：
+
+- 可 debug（日志/存储都有迹可循）
+- 可回放（对话历史导航时不丢信息）
+
+### 2）按智能体维度进程内缓存
+
+为避免每次新对话都重复跑 `uname -a` + FBR + 综合提炼，后端进程维护一个**进程内缓存**（重启失效），按主线智能体 id 做 key。
+
+复用策略：
+
+- 若命中缓存，新对话可直接复用首次的转录与“Agent Priming”笔记，不再重复执行。
+- 复用的记录在新对话里仍应可见，并清楚标记“来自缓存复用”。
+
+### 2.5）主线选择向支线继承（必须）
+
+主线对话在创建时选择的 Priming 选项，必须传递给其所属所有支线对话（Sideline dialog）。
+
+继承语义：
+
+- 主线选“无感”（`skip`）：所有支线都必须“无感”（`skip`）。
+- 主线在“有缓存”前提下选“再做一次”（`do`）：所有支线都必须“再做一次”（`do`）。
+- 主线在“无缓存”前提下选“做给祂看”（`do`，首次体验语义）或选“复用缓存”（`reuse`）：
+  支线统一按“可复用则复用，否则现做”（`reuse`）执行。
+
+说明：
+
+- 不同支线智能体的缓存状态可能不同；`reuse` 的含义是“按该支线智能体自己的缓存判断”。
+- priming 不允许后台悄悄执行；必须以标准对话记录（消息 + 事件）对用户可见。
+
+### 3）跨 `clear_mind` 携带
+
+每次 `clear_mind` 进入下一程时，不要依赖 reminder 来承载这件事。
+
+改为：在每一程对话的上下文里注入一段小而稳定的 **course prefix**（可理解为“历史消息区最开头的几条 msg”），内容是从首次启动中提炼出的压缩转录（shell 快照 + FBR 摘要 + Priming 笔记）。这样智能体能持续保留“体感”和环境约束，而无需重复执行启动流程。
+
+---
+
+## WebUI 需求
+
+### 展示
+
+- 智能体启动应以真实对话转录展示，用户可展开查看细节。
+- 建议在对话顶部提供一个可折叠区域，并带上清晰标签：
+  - “队友诉请（shell）”
+  - “FBR（`freshBootsReasoning`）”
+  - “智能体启动（Agent Priming）”
+
+### 创建对话时可选择跳过（opt-out）
+
+创建对话框上提供明确开关，跳过这一安排（不执行启动流程，也不生成启动转录）。
+
+补充约定：
+
+- 当对话主理人选择为（隐藏的）影子智能体时，“智能体启动（Priming）”选项默认应为“无感”。
+- 影子智能体的“启动”选项应与显在智能体的“启动”选项分开记忆（互不影响）。
+
+---
+
+## 安全注意事项
+
+- 默认只执行 `uname -a`（低风险、只读、快）。
+- 启动阶段禁止任何会改写文件/网络/系统状态的操作。
+- 由于启动默认用户可见，严禁输出密钥/敏感信息。