dsh-working-activity 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/activity/working-activity/README.md
+README.md: bf0787caac11a292882ba1a35963878e373e7db8
+README.zh.md: de09a7945dbe42c85d359fd256cdac0264d4b6cd

package/README.md

@@ -0,0 +1,109 @@
+# dsh-working-activity
+
+A live "working line" for DeepSeek Harness: the model's real-time activity — playful thinking copy, the tool actually running, elapsed time, and a turn-end summary — shown while the agent works.
+
+## What it does
+
+Folds the durable session stream (`turn/start`, `assistant/chunk`, `tool/call`, `tool/result`, `turn/end`) plus `agent/status` into one status line, refreshed on a render tick:
+
+- **Thinking**: short colloquial copy rotates every few seconds (`嗯…让我捋捋`, `盘一下盘一下`, `大脑转起来了`, deadpan `lol` / `hm` / `ok`), tiered when thinking runs long (30s / 1min / 5min), night-owl copy mixed in between 00:00–06:00 local time.
+- **Tool activity**: the running tool renders as `俏皮动词 + 参数细节 + 已耗时` (`跑个命令 npm test · 12s`); failed tools show `翻车了`-style copy in the done line.
+- **Turn summary**: on `turn/end` the line becomes `搞定 ✓ · N 工具 · 想Xs 干Ys` (thinking/tool split), with the last tool's fragment pinned for a few seconds.
+- **Minimal mode**: `phrases: false` renders plain functional labels (`思考中 · 总1m23s`, `bash npm test · 12s`).
+
+Two optional sinks, both off by default only when their seam is absent:
+
+1. **TUI prompt slot** — registers the `${activity}` template value on `ctx.tuiPrompt` when the TUI is composed. Add `${activity}` to `theme.leftPrompt` to see it next to `cwd`/`model`/`context`.
+2. **Session events** — appends log-only `activity/status` events (never surface events: the model never sees them) for Web and other UI consumers; replay ignores them.
+
+## Installation
+
+```yaml
+# cordis.yml
+plugins:
+  - id: working-activity
+    name: 'dsh-working-activity'
+```
+
+## TUI usage
+
+Enable the plugin alongside `dsh-tui` and add the slot to the left prompt template:
+
+```yaml
+plugins:
+  - id: tui
+    name: '@deepseek-ai/dsh-tui'
+    config:
+      theme:
+        leftPrompt: '${cwd}${git/worktree}${activity}${model}${token_meter/cache_hit_rate}${context}'
+  - id: working-activity
+    name: 'dsh-working-activity'
+```
+
+While a turn runs, the prompt line shows e.g. `dsh main 跑个命令 npm test · 12s deepseek-chat …`; while thinking, `嗯…让我捋捋 · 总1m23s`; after the turn, `搞定 ✓ · 4 工具 · 想12s 干11s` briefly. Without `${activity}` in the template, the plugin is inert in the TUI (the slot is unregistered values are omitted by the template renderer).
+
+## Web usage
+
+The Web client renders the live line two ways, both fed by the `activity/status` events:
+
+- The turn-level status label (`TurnStatus`, formerly the static "Deep diving...") shows the live line while a turn runs, keeping its sweep animation.
+- A working-line dock entry (`WorkingLine` on `conversation.input.dock`) renders the turn-end statistics (token/elapsed/tool summary) above the composer after a turn settles; live phases stay on the turn label.
+
+Both fall back to the previous static label while the plugin is absent, so the Web UI is unaffected by disabling it.
+
+## Configuration
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `phrases` | `boolean` | `true` | Playful copy pool; `false` renders plain functional labels |
+| `publish` | `boolean` | `true` | Append `activity/status` session events for UI consumers |
+| `tickMs` | `number` | `500` | Status render tick interval (50–5000) |
+| `publishIntervalMs` | `number` | `2000` | Minimum interval between published events while the line is stable (500–30000) |
+| `detailLimit` | `number` | `40` | Max displayed detail length (paths/commands/patterns), 8–120 |
+| `customActions` | `object` | `{}` | Exact tool-name → action-copy pools, e.g. `{"my_deploy": ["部署一下", "上线中"]}` |
+| `narrate` | `boolean` | `true` | Inject the `⏵` self-narration contract into the system prompt; the line is surfaced live and stripped from the chat body |
+
+## Event contract
+
+`activity/status` is a log-only session event (merge-extensible `SessionEventMap` member, no `surfaceOp`):
+
+```ts
+{
+  phase: 'idle' | 'waiting' | 'thinking' | 'tool' | 'done'
+  line: string            // plain-text status line, no ANSI
+  label?: string          // current work label (tool action / stage)
+  detail?: string         // path / command / pattern fragment
+  phrase?: string         // current playful phrase
+  toolCount: number       // tools completed this turn
+  turnElapsedMs: number   // ms since turn start
+  phaseStartedAt: number  // epoch ms the phase started (animation anchor)
+}
+```
+
+Publishing rules: line changes publish immediately; a stable line republishes at most every `publishIntervalMs` so a long tool's elapsed time stays live without flooding the log. All data is lossless JSON; optional fields are omitted when absent.
+
+## Export shape
+
+A function/namespace plugin: `name` / `Config` / `apply`, no default export. The state machine (`ActivityTracker`) and copy pools live in `./status` and `./phrases` (pure, clock-injected, unit-tested). The invariant companion registers under `./invariant`.
+
+## Model Experience
+
+### Prompt and tool surface
+
+Nothing. The plugin injects no prompt sections, registers no tools, and appends no surface events. `activity/status` is UI state only: it never enters derived model history, so the model cannot see its own working line.
+
+### Token effect
+
+Zero per request.
+
+### KV Cache effect
+
+No system-prompt contribution, so no cache-stability effect.
+
+## Known Limitations and Deferred Work
+
+- **Single active line**: the plugin keeps one status line per session; the TUI slot shows the most recently active session.
+- **Narration is opt-in**: the `⏵` self-narration contract (model writes a short status line at the top of each reply) is injected by default (`narrate: true`); set `narrate: false` for a purely event-derived line.
+- **No progress percentages**: DSH has no tool progress events; a long tool shows elapsed time only.
+- **No animated frames**: the TUI slot renders a static text fragment; frame animation (moon/comet/braille presets) is deferred until the prompt-slot contract supports a frame callback.
+- **Web dock entry duplicates the turn label**: the input-dock `WorkingLine` and the chat `TurnStatus` show the same snapshot; the dock entry exists for session views where the turn label is not visible.

package/README.zh.md

@@ -0,0 +1,111 @@
+# @deepseek-ai/dsh-working-activity
+
+[English](README.md) | 中文
+
+为 DeepSeek Harness 打造的一条实时 "工作状态行"：模型的实时活动——俏皮思考文案、真正在跑的工具、已耗时、收尾摘要——在 agent 干活时展示出来。
+
+## 功能
+
+把持久会话流（`turn/start`、`assistant/chunk`、`tool/call`、`tool/result`、`turn/end`）和 `agent/status` 折叠成一条状态行，按渲染 tick 刷新：
+
+- **思考中**：每隔几秒轮换一句短俏皮文案（`嗯…让我捋捋`、`盘一下盘一下`、`大脑转起来了`，穿插面无表情的 `lol` / `hm` / `ok`）；想久了自动分档（30 秒 / 1 分钟 / 5 分钟）；本地时间 00:00–06:00 混入深夜专属文案。
+- **工具活动**：正在运行的工具渲染为 `俏皮动词 + 参数细节 + 已耗时`（`跑个命令 npm test · 12s`）；失败工具在收尾行显示 `翻车了` 风格文案。
+- **收尾摘要**：`turn/end` 后状态行变为 `搞定 ✓ · N 工具 · 想Xs 干Ys`（思考/干活耗时拆分），并短暂钉住最后一个工具的片段。
+- **极简模式**：`phrases: false` 时渲染朴素功能标签（`思考中 · 总1m23s`、`bash npm test · 12s`）。
+
+两个可选出口，只有对应接缝存在时才会生效：
+
+1. **TUI prompt 槽位** —— TUI 组合存在时，在 `ctx.tuiPrompt` 上注册 `${activity}` 模板值。把 `${activity}` 加进 `theme.leftPrompt` 即可在 `cwd`/`model`/`context` 旁边看到它。
+2. **会话事件** —— 追加只记日志的 `activity/status` 事件（绝不是 surface 事件：模型永远看不到），供 Web 与其他 UI 消费；回放时忽略它们。
+
+## 安装
+
+```yaml
+# cordis.yml
+plugins:
+  - id: working-activity
+    name: '@deepseek-ai/dsh-working-activity'
+```
+
+## TUI 用法
+
+与 `dsh-tui` 一起启用插件，并把槽位加进左侧 prompt 模板：
+
+```yaml
+plugins:
+  - id: tui
+    name: '@deepseek-ai/dsh-tui'
+    config:
+      theme:
+        leftPrompt: '${cwd}${git/worktree}${activity}${model}${token_meter/cache_hit_rate}${context}'
+  - id: working-activity
+    name: '@deepseek-ai/dsh-working-activity'
+```
+
+一轮进行中时，提示行显示例如 `dsh main 跑个命令 npm test · 12s deepseek-chat …`；思考时显示 `嗯…让我捋捋 · 总1m23s`；收尾后短暂显示 `搞定 ✓ · 4 工具 · 想12s 干11s`。模板里没有 `${activity}` 时，插件在 TUI 中不产生任何效果（槽位未注册的值会被模板渲染器省略）。
+
+## Web 用法
+
+Web 客户端通过 `activity/status` 事件以两种方式渲染实时状态行：
+
+- 回合级状态标签（`TurnStatus`，原先是静态的 "Deep diving..."）：回合进行中显示实时状态行，保留原有的流光扫过特效。
+- 输入区上方的状态行条目（`WorkingLine`，挂在 `conversation.input.dock`）：回合结束后渲染收工统计（token/耗时/工具摘要）；活动阶段只在轮辑标签上显示。
+
+插件缺席时两者都回退到原来的静态标签，禁用插件不影响 Web UI。
+
+## 配置
+
+| 键 | 类型 | 默认值 | 含义 |
+|---|---|---|---|
+| `phrases` | `boolean` | `true` | 俏皮文案池；`false` 渲染朴素功能标签 |
+| `publish` | `boolean` | `true` | 为 UI 消费者追加 `activity/status` 会话事件 |
+| `tickMs` | `number` | `500` | 状态渲染 tick 间隔（50–5000） |
+| `publishIntervalMs` | `number` | `2000` | 状态行稳定时两次发布事件的最小间隔（500–30000） |
+| `detailLimit` | `number` | `40` | 详情最大展示长度（路径/命令/模式），8–120 |
+| `customActions` | `object` | `{}` | 工具名精确匹配 → 动作文案池，如 `{"my_deploy": ["部署一下", "上线中"]}` |
+| `narrate` | `boolean` | `true` | 向 system prompt 注入 `⏵` 自述约定；该行实时展示并从聊天正文中过滤 |
+
+## 事件契约
+
+`activity/status` 是只记日志的会话事件（merge 可扩展的 `SessionEventMap` 成员，无 `surfaceOp`）：
+
+```ts
+{
+  phase: 'idle' | 'waiting' | 'thinking' | 'tool' | 'done'
+  line: string            // 纯文本状态行，无 ANSI
+  label?: string          // 当前工作标签（工具动作/阶段）
+  detail?: string         // 路径 / 命令 / 模式片段
+  phrase?: string         // 当前俏皮文案
+  toolCount: number       // 本轮已完成的工具数
+  turnElapsedMs: number   // 距本轮开始毫秒数
+  phaseStartedAt: number  // 相位开始的 epoch 毫秒（动画锚点）
+}
+```
+
+发布规则：状态行变化立即发布；稳定行最多每 `publishIntervalMs` 重发一次，让长工具的已耗时保持实时而不刷爆日志。所有数据都是无损 JSON；可选字段缺省时省略。
+
+## 导出形状
+
+函数/命名空间插件：`name` / `Config` / `apply`，无默认导出。状态机（`ActivityTracker`）与文案池在 `./status` 和 `./phrases`（纯逻辑、时钟注入、有单测）。不变量伴生插件在 `./invariant` 注册。
+
+## Model Experience
+
+### 提示词与工具面
+
+没有。插件不注入任何提示词段、不注册任何工具、不追加任何 surface 事件。`activity/status` 只是 UI 状态：永不进入派生模型历史，模型看不到自己的工作状态行。
+
+### Token 影响
+
+每次请求为零。
+
+### KV 缓存影响
+
+不贡献 system prompt，因此无缓存稳定性影响。
+
+## Known Limitations and Deferred Work
+
+- **单条活跃状态行**：插件按会话维护一条状态行；TUI 槽位显示最近活跃会话。
+- **自述可选**：`⏵` 模型自述约定（每次回复顶部写一行短状态文案）默认注入（`narrate: true`）；设 `narrate: false` 则只由事件推导。
+- **无进度百分比**：DSH 没有工具进度事件；长工具只显示已耗时。
+- **无动画帧**：TUI 槽位渲染静态文本片段；帧动画（moon/comet/braille 预设）要等 prompt 槽位契约支持帧回调后再做。
+- **Web 双入口重复显示**：输入区 `WorkingLine` 与聊天区 `TurnStatus` 显示同一快照；dock 条目用于回合标签不可见的会话视图。

package/lib/types/events.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `activity/status` session event — a log-only, non-surface snapshot of the
+ * model's current working activity, published by this plugin for any UI
+ * consumer (Web client, telemetry, …). It never enters derived model history
+ * (no `surfaceOp`), so it cannot leak into prompts; UIs render it like
+ * `todo/write` or `plan/mode`.
+ * @module @deepseek-ai/dsh-working-activity/events
+ */
+import type { ActivityPhase } from './status.js';
+/** Durable payload of one `activity/status` snapshot. */
+export interface ActivityStatusEvent {
+    /** Which activity phase the model is in. */
+    readonly phase: ActivityPhase;
+    /** Human-readable status line (plain text, no ANSI). */
+    readonly line: string;
+    /** Short label of the current work, when any. */
+    readonly label?: string;
+    /** Detail fragment (path / command / pattern), when any. */
+    readonly detail?: string;
+    /** The playful phrase currently shown, when the copy pool is on. */
+    readonly phrase?: string;
+    /** Tools completed in the current turn. */
+    readonly toolCount: number;
+    /** Milliseconds since the current turn started (0 when idle). */
+    readonly turnElapsedMs: number;
+    /** Wall-clock time (epoch ms) the current phase started, for animations. */
+    readonly phaseStartedAt: number;
+}
+/** The `activity/status` phase vocabulary, exported for wire consumers. */
+export type { ActivityPhase };
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Log-only UI snapshot of the model's working activity (thinking copy,
+         * running tool, turn elapsed). Never a surface event: UIs render it, the
+         * model never sees it.
+         * @param data - The rendered status snapshot.
+         */
+        'activity/status': ActivityStatusEvent;
+    }
+}
+//# sourceMappingURL=events.d.ts.map

package/lib/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED,2EAA2E;AAC3E,YAAY,EAAE,aAAa,EAAE,CAAA;AAE7B,OAAO,QAAQ,gCAAgC,CAAC;IAC9C,UAAU,eAAe;QACvB;;;;;WAKG;QACH,iBAAiB,EAAE,mBAAmB,CAAA;KACvC;CACF"}

package/lib/types/events.js

@@ -0,0 +1,9 @@
+/**
+ * `activity/status` session event — a log-only, non-surface snapshot of the
+ * model's current working activity, published by this plugin for any UI
+ * consumer (Web client, telemetry, …). It never enters derived model history
+ * (no `surfaceOp`), so it cannot leak into prompts; UIs render it like
+ * `todo/write` or `plan/mode`.
+ * @module @deepseek-ai/dsh-working-activity/events
+ */
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * working-activity — a live "working line" for DeepSeek Harness agents.
+ *
+ * Folds the durable session stream (turn/step/tool/stream events) plus
+ * `agent/status` into a playful real-time status line, then publishes it two
+ * ways, both optional:
+ *
+ * - TUI: registers the `${activity}` prompt slot on `ctx.tuiPrompt` when the
+ *   TUI is composed; add `${activity}` to `theme.leftPrompt` to see it.
+ * - Session log: appends log-only `activity/status` events (never surface
+ *   events) for Web and other UI consumers; replay ignores them.
+ *
+ * The state machine itself lives in `./status.ts` (pure, clock-injected); this
+ * module only wires events, the render tick, and the two sinks.
+ * @module @deepseek-ai/dsh-working-activity
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export type * from './events.js';
+export declare const name = "working-activity";
+/** Configurable knobs; every key has a sane default. */
+export type Config = {
+    /** Playful copy pool; false renders plain functional labels. */
+    phrases?: boolean;
+    /** Append `activity/status` session events for UI consumers. */
+    publish?: boolean;
+    /** Status render tick interval in ms. */
+    tickMs?: number;
+    /** Minimum interval in ms between published events while the line is stable. */
+    publishIntervalMs?: number;
+    /** Maximum displayed detail length (paths/commands/patterns). */
+    detailLimit?: number;
+    /** Exact tool-name → action-copy pools (case-insensitive match). */
+    customActions?: Record<string, string[]>;
+    /** Inject the `⏵` self-narration contract into the system prompt and surface it. */
+    narrate?: boolean;
+};
+export declare const Config: z<Schemastery.ObjectS<{
+    phrases: z<boolean, boolean>;
+    publish: z<boolean, boolean>;
+    tickMs: z<number, number>;
+    publishIntervalMs: z<number, number>;
+    detailLimit: z<number, number>;
+    customActions: z<import("@deepseek-ai/cosmokit").Dict<string[], string>, import("@deepseek-ai/cosmokit").Dict<string[], string>>;
+    narrate: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    phrases: z<boolean, boolean>;
+    publish: z<boolean, boolean>;
+    tickMs: z<number, number>;
+    publishIntervalMs: z<number, number>;
+    detailLimit: z<number, number>;
+    customActions: z<import("@deepseek-ai/cosmokit").Dict<string[], string>, import("@deepseek-ai/cosmokit").Dict<string[], string>>;
+    narrate: z<boolean, boolean>;
+}>>;
+/**
+ * Wire the working-activity plugin.
+ * @param ctx - Cordis context (agent loop + session services composed).
+ * @param config - Validated plugin config (schema defaults applied).
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAWxC,mBAAmB,aAAa,CAAA;AAEhC,eAAO,MAAM,IAAI,qBAAqB,CAAA;AAEtC,wDAAwD;AACxD,MAAM,MAAM,MAAM,GAAG;IACnB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IACxC,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;GAQjB,CAAA;AAyBF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CAyH7D"}

package/lib/types/index.js

@@ -0,0 +1,151 @@
+/**
+ * working-activity — a live "working line" for DeepSeek Harness agents.
+ *
+ * Folds the durable session stream (turn/step/tool/stream events) plus
+ * `agent/status` into a playful real-time status line, then publishes it two
+ * ways, both optional:
+ *
+ * - TUI: registers the `${activity}` prompt slot on `ctx.tuiPrompt` when the
+ *   TUI is composed; add `${activity}` to `theme.leftPrompt` to see it.
+ * - Session log: appends log-only `activity/status` events (never surface
+ *   events) for Web and other UI consumers; replay ignores them.
+ *
+ * The state machine itself lives in `./status.ts` (pure, clock-injected); this
+ * module only wires events, the render tick, and the two sinks.
+ * @module @deepseek-ai/dsh-working-activity
+ */
+import z from '@deepseek-ai/schemastery';
+import { ActivityTracker } from './status.js';
+export const name = 'working-activity';
+export const Config = z.object({
+    phrases: z.boolean().default(true),
+    publish: z.boolean().default(true),
+    tickMs: z.number().step(50).min(100).max(5000).default(500),
+    publishIntervalMs: z.number().step(500).min(500).max(30_000).default(2000),
+    detailLimit: z.number().step(1).min(8).max(120).default(40),
+    customActions: z.dict(z.array(z.string())).default({}),
+    narrate: z.boolean().default(true),
+});
+/** The self-narration contract injected into the system prompt (narrate on). */
+const NARRATE_INSTRUCTION = '[状态栏] 你有一个状态栏展示给用户。【必须】在每个步骤/子任务开始时（不只是调用工具前），在回复正文的最前面单独写一行：⏵ 你在做的具体事情（不超过20字），然后换行继续正常回复。整轮回复只写一行 ⏵，不要重复。信息为主——让人一眼知道你在干什么，风格自然、可以带点俏皮。例：⏵ 修复登录页样式、⏵ 查一下报错原因、⏵ 给补丁跑个验证。切换任务时必须更新。';
+/**
+ * Wire the working-activity plugin.
+ * @param ctx - Cordis context (agent loop + session services composed).
+ * @param config - Validated plugin config (schema defaults applied).
+ */
+export function apply(ctx, config = {}) {
+    const resolved = {
+        phrases: config.phrases ?? true,
+        publish: config.publish ?? true,
+        tickMs: config.tickMs ?? 500,
+        publishIntervalMs: config.publishIntervalMs ?? 2000,
+        detailLimit: config.detailLimit ?? 40,
+        narrate: config.narrate ?? true,
+        customActions: config.customActions ?? {},
+    };
+    const trackers = new Map();
+    let activeSession;
+    let lastPublishedLine;
+    let lastPublishedPhase;
+    let lastPublishAt = 0;
+    // Optional TUI seam: no TUI composed -> no slot, no error. The register()
+    // call is itself effect-owned, so fiber disposal unregisters the slot.
+    const prompt = ctx.get('tuiPrompt', false);
+    const promptHandle = prompt?.register('activity', undefined);
+    // The `⏵` self-narration contract rides the stable system-prompt sections:
+    // injected when the systemPrompt service is composed (agent assemblies
+    // always mount it), removed with this fiber.
+    if (resolved.narrate) {
+        ctx.inject(['systemPrompt'], (promptCtx) => {
+            promptCtx.systemPrompt.section({
+                name: 'working-activity:narrate',
+                order: 60,
+                text: NARRATE_INSTRUCTION,
+            });
+        });
+    }
+    const trackerFor = (session) => {
+        let tracker = trackers.get(session);
+        if (tracker === undefined) {
+            tracker = new ActivityTracker({ phrases: resolved.phrases, detailLimit: resolved.detailLimit, showIdle: false }, Date.now, resolved.customActions);
+            trackers.set(session, tracker);
+        }
+        return tracker;
+    };
+    /**
+     * Publish one rendered snapshot: TUI slot update + throttled session event.
+     * Callers snapshot the tracker state at event time and hand it here, so a
+     * burst of fast events (e.g. a synchronous tool call+result) cannot lose an
+     * intermediate phase; the append itself runs inside a microtask because the
+     * session's appending guard is still set while session/event callbacks run.
+     */
+    const publish = (session, state) => {
+        queueMicrotask(() => {
+            const line = state.phase === 'idle' ? undefined : state.line;
+            promptHandle?.set(line);
+            if (!resolved.publish)
+                return;
+            const nowMs = Date.now();
+            const lineChanged = state.line !== lastPublishedLine;
+            const phaseChanged = state.phase !== lastPublishedPhase;
+            // Live phases republish on a throttle so elapsed times stay current;
+            // settled phases (idle/done) publish only when the line itself changes.
+            const liveThrottle = state.phase !== 'idle' && state.phase !== 'done'
+                && nowMs - lastPublishAt >= resolved.publishIntervalMs;
+            if (!lineChanged && !phaseChanged && !liveThrottle)
+                return;
+            // Optional fields must be omitted (not undefined): session append rejects
+            // data JSON would discard, and `activity/status` is a lossless-JSON event.
+            const payload = {
+                phase: state.phase,
+                line: state.line,
+                toolCount: state.toolCount,
+                turnElapsedMs: state.turnElapsedMs,
+                phaseStartedAt: state.phaseStartedAt,
+                ...(state.label === undefined ? {} : { label: state.label }),
+                ...(state.detail === undefined ? {} : { detail: state.detail }),
+                ...(state.phrase === undefined ? {} : { phrase: state.phrase }),
+            };
+            try {
+                session.append('activity/status', payload);
+                lastPublishedLine = state.line;
+                lastPublishedPhase = state.phase;
+                lastPublishAt = nowMs;
+            }
+            catch {
+                // Session closed or the append guard still held: drop this snapshot;
+                // the next tick retries the same line.
+            }
+        });
+    };
+    ctx.on('session/event', (session, event) => {
+        const tracker = trackerFor(session);
+        tracker.onSessionEvent(event);
+        activeSession = session;
+        publish(session, tracker.render());
+    });
+    ctx.on('session/disposed', (session) => {
+        trackers.delete(session);
+        if (activeSession === session)
+            activeSession = undefined;
+    });
+    ctx.on('agent/status', ({ agent, status }) => {
+        const session = agent.session;
+        const tracker = trackerFor(session);
+        tracker.onAgentStatus(status);
+        activeSession = session;
+        publish(session, tracker.render());
+    });
+    // Continuous tick: elapsed times and the phrase rotation move on their own.
+    // A manual timer keeps this plugin free of the @cordisjs/plugin-timer mixin;
+    // the effect disposer clears it when this fiber unloads.
+    const tickTimer = setInterval(() => {
+        if (activeSession === undefined)
+            return;
+        const tracker = trackers.get(activeSession);
+        if (tracker === undefined)
+            return;
+        publish(activeSession, tracker.render());
+    }, resolved.tickMs);
+    ctx.effect(() => () => { clearInterval(tickTimer); }, 'working-activity tick timer');
+}

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned `activity/status` snapshot invariants.
+ * @module dsh-working-activity/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "working-activity-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the working-activity invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,+BAA+B,CAAA;AAChD,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAkDpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/types/invariant.js

@@ -0,0 +1,61 @@
+/**
+ * Package-owned `activity/status` snapshot invariants.
+ * @module dsh-working-activity/invariant
+ */
+/** Cordis companion plugin name. */
+export const name = 'working-activity-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+const PACKAGE_NAME = 'dsh-working-activity';
+const PHASES = new Set(['idle', 'waiting', 'thinking', 'tool', 'done']);
+/** Validate one published activity snapshot before it reaches the durable log. */
+function validateStatus(data, fail) {
+    const record = data;
+    if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+        fail('activity/status data must be an object');
+        return;
+    }
+    if (typeof record.phase !== 'string' || !PHASES.has(record.phase)) {
+        fail(`activity/status carries unknown phase ${JSON.stringify(record.phase)}`);
+    }
+    if (typeof record.line !== 'string' || record.line.length === 0) {
+        fail('activity/status line must be a non-empty string');
+    }
+    for (const key of ['toolCount', 'turnElapsedMs', 'phaseStartedAt']) {
+        const value = record[key];
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+            fail(`activity/status ${key} must be a non-negative finite number`);
+        }
+    }
+    for (const key of ['label', 'detail', 'phrase']) {
+        if (record[key] !== undefined && typeof record[key] !== 'string') {
+            fail(`activity/status ${key} must be a string when present`);
+        }
+    }
+}
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Validate the package-owned event shape and ignore unrelated events. */
+function validateEvent(event, fail) {
+    if (event.type === 'activity/status')
+        validateStatus(event.data, fail);
+}
+/** Install validation for loaded and newly appended activity snapshots. */
+const install = Object.assign((ctx, fail) => {
+    for (const session of ctx.sessions.list()) {
+        for (const event of session.events)
+            validateEvent(event, fail);
+    }
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const event = args[1];
+        validateEvent(event, fail);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/* jscpd:ignore-end */
+/**
+ * Register the working-activity invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));

package/lib/types/phrases.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Copy pools for the working-activity status line: short, colloquial, playful
+ * Chinese fragments with deadpan English one-liners mixed in, matching the
+ * pi-working-activity tone. Everything here is pure data + pure pickers.
+ * @module @deepseek-ai/dsh-working-activity/phrases
+ */
+/** A pool of copy fragments. */
+export type PhrasePool = readonly string[];
+/** Pick one random entry; repeated draws avoid the previous entry when possible. */
+export declare function pickPhrase(entries: PhrasePool, previous?: string): string;
+/** Thinking phrases while the model works without a tool. */
+export declare const THINKING_PHRASES: readonly string[];
+/** Tiered phrases when thinking runs long (elapsed >= threshold). */
+export declare const THINKING_TIERS: readonly {
+    /** Minimum thinking ms for this tier. */
+    readonly atMs: number;
+    readonly pool: readonly string[];
+}[];
+/** Phrases shown while waiting for the first streamed token. */
+export declare const WAITING_PHRASES: readonly string[];
+/** Tool-name patterns mapped to playful action verbs. */
+export declare const ACTION_MAP: readonly {
+    readonly test: RegExp;
+    readonly actions: readonly string[];
+}[];
+/** Fallback verbs for unknown tools. */
+export declare const FALLBACK_ACTIONS: readonly string[];
+/** Tool failure phrases, replacing a bare ✗. */
+export declare const FAIL_PHRASES: readonly string[];
+/** Turn-completion phrases. */
+export declare const DONE_PHRASES: readonly string[];
+/** Night-owl phrases mixed in between 00:00 and 06:00 local time. */
+export declare const NIGHT_PHRASES: readonly string[];
+/** Common git tool names / bash commands containing `git `. */
+export declare const GIT_TOOL_RE: RegExp;
+/** Detect the 00:00–06:00 night window (local time). */
+export declare function isNight(hour: number): boolean;
+/**
+ * Pick a thinking phrase appropriate for the elapsed thinking time.
+ * @param elapsedMs - Milliseconds spent thinking in the current phase.
+ * @param previous - Previously shown phrase, to avoid repeats.
+ * @param night - Mix night-owl copy into the pool.
+ */
+export declare function thinkingPhrase(elapsedMs: number, previous?: string, night?: boolean): string;
+/**
+ * Map a tool name to a playful action verb.
+ * @param toolName - Registry tool name (unqualified).
+ * @param custom - Exact-name custom action pools, matched case-insensitively.
+ */
+export declare function actionFor(toolName: string, custom?: Readonly<Record<string, readonly string[]>>): string;
+/** Whether a tool is a git operation (name match, or a shell command containing `git `). */
+export declare function isGitTool(toolName: string, args?: Readonly<Record<string, unknown>>): boolean;
+/** Format milliseconds as a compact human duration (`1m23s`). */
+export declare function fmtDuration(ms: number): string;
+//# sourceMappingURL=phrases.d.ts.map

package/lib/types/phrases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phrases.d.ts","sourceRoot":"","sources":["../../src/phrases.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,gCAAgC;AAChC,MAAM,MAAM,UAAU,GAAG,SAAS,MAAM,EAAE,CAAA;AAE1C,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CASzE;AAED,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAiB7C,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,cAAc,EAAE,SAAS;IACpC,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC,EAIA,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAQ5C,CAAA;AAED,yDAAyD;AACzD,eAAO,MAAM,UAAU,EAAE,SAAS;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC,EAkBA,CAAA;AAED,wCAAwC;AACxC,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAAqD,CAAA;AAEnG,gDAAgD;AAChD,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAMzC,CAAA;AAED,+BAA+B;AAC/B,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAMzC,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAI1C,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,WAAW,QAA4G,CAAA;AAEpI,wDAAwD;AACxD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,MAAM,CAY1F;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GAAG,MAAM,CAQxG;AAED,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAO7F;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAS9C"}