actoviq-agent-sdk 0.4.21 → 0.4.22

package/README-zh.md

@@ -1,4 +1,4 @@
-# Hadamard Agent SDK
+# Hadamard：让 Agent 像工程团队一样协作
 
 [![CI](https://github.com/DeconBear/hadamard/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DeconBear/hadamard/actions/workflows/ci.yml)
 [![Publish npm Package](https://github.com/DeconBear/hadamard/actions/workflows/publish-npm.yml/badge.svg?branch=main)](https://github.com/DeconBear/hadamard/actions/workflows/publish-npm.yml)
@@ -7,159 +7,96 @@
 
 [English](./README.md) | [中文](./README-zh.md)
 
-文档站地址：https://deconbear.github.io/hadamard/
+如今的 LLM harness 越来越强，但在真实的工程与科研任务上仍难以管理——交付软件、跑 AI4S 流程、训练神经网络与调参实验。上下文溢出、工具调用失控、运行偏离预期，而单个 agent 闭环永远缺少第二意见。
 
-**Hadamard**（`0.4.x`）是 TypeScript agent SDK 与 agent-team 平台，含 TUI、GUI、Bridge 与多 agent 协作。未来的 **1.0** 线将稳定 package subpath 契约；该表面**尚未发布**。
-
-> **包名说明：** npm 发布名仍为 [`actoviq-agent-sdk`](https://www.npmjs.com/package/actoviq-agent-sdk)。产品、仓库、CLI 与配置路径统一为 **Hadamard**（`hadamard-*`、`~/.hadamard`、`.hadamard/`）。
-
-> **说明：** 桌面端 **Agent graph** 编排 UI（可视化团队 / 图编辑器）**仍在持续迭代与优化中**，交互与行为可能变化。生产工作流请优先使用 `/team`、已保存的 team 定义，以及 SDK 的 `createTeam()` / graph runtime。详见 `CHANGELOG.md`。
+**Hadamard** 的目标是让 Agent 的工程与科研变得可控：引入不同 provider 的多个 agent 相互交流，并行调查、评审与分派，把问题考虑得更加周全。同一套 TypeScript runtime 提供工具、skills、持久会话、记忆与 MCP，并能通过 bridge 把已安装的 agent CLI（Claude Code、Codex、Cursor、Pi、CodeWhale、Reasonix、Crush）作为子进程管理；终端 UI 与桌面 GUI 也构建在这套 runtime 之上。
 
 受 Claude Code、Codex、Deepagents 等项目启发。Hadamard 保持独立，拥有自己的公开 API 与文档。
 
-## 愿景
-
-- **多 agent**：子代理委派（Task 工具）、panel-analysis 团队、reviewer-auditor 对、动态 workflow —— agent 之间协作，而非单一的 ReAct 循环。
-- **多运行时状态管理**：bridge config 明确区分两种模式。`Direct API` 在进程内调用 Anthropic/OpenAI 兼容接口；`External CLI` 则把已安装的 Claude Code、Codex、Pi、CodeWhale、Reasonix 或 Crush 作为子进程托管，并在 CLI 协议提供会话 ID 时保留原生 session 身份。
-- **model team 协作**：leader 将每轮分派给最佳 specialist（`/model router`），panel 成员并行调查并收敛，reviewer 只报告可验证的问题 —— team 是 agent 可调用的一等工具。
-
-## 亮点
-
-- **Model Team** — `panel-analysis`（并行调查 + 收敛）和 `reviewer`（只报告可验证问题的审计者）。runtime-owned 成员池、流式 `TeamEvent`、成员 provider 配置，以及继承的权限/重试边界。
-- **Model Router / Leader-Dispatch** — 每轮由 leader 分派到最佳 specialist（任意模型/提供商），执行者自身也可召集 team。Profile 位于 `~/.hadamard/routers/`。
-- **Dynamic Workflows** — 显式信任等级的 JS 编排：trusted 兼容执行、隔离 local-process，或由 host 提供的远程/container 强 sandbox；local process 不宣传为对抗性多租户沙箱。
-- **Bridge（命名运行时配置）** — 可选 `Direct API` 做 provider/API 级复用，也可选 `External CLI` 直接启动已安装的 Claude Code、Codex、Pi、CodeWhale、Reasonix 或 Crush，继承各 CLI 的原生登录和配置、流式显示规范化后的工具与回答事件、终止后台任务，并浏览/恢复受支持的原生会话。单独填写的 key 只注入子进程，不写入 CLI 的凭据库；Pi、CodeWhale、Reasonix 与 Crush 会使用按配置隔离的持久会话目录，因此 key 模式重启后仍可读取历史，同时不会读取原生登录凭据。
-- **桌面 GUI (`hadamard-gui`)** — Electron 聊天 UI：流式 transcript、对话历史、命令面板、设置、每工具权限提示。安全增强。全局 **Assistant** FAB（Global/Project 作用域）。可视化 **Agent graph** 编排 UI 仍在迭代中，暂勿当作稳定产品面。
-- **TUI (`hadamard-tui`)** — 终端 UI，25+ 斜杠命令，Claude Code 风格 UX：`/team`、`/bridge`、`/plan`、`/hooks`、`/mcp`、`/review`、`/context`、`/cost`、`/doctor` 等。实时状态旋转器、滚动 transcript、todo 面板、项目/用户级权限对话框、子命令自动补全。
-- **计划模式 + hooks** — `EnterPlanMode`/`ExitPlanMode` 工具 + 计划文件；`settings.json` 中的 `PreToolUse`/`PostToolUse`/`SessionStart` hooks。
-- **Worktree 工具** — `EnterWorktree`/`ExitWorktree`，栈式 cwd，`.worktreeinclude`，PR checkout。
-- **TavilySearch** — AI 优化网络搜索，纯 TypeScript。
-- **Standard Benchmark** — 自包含框架，DeepSeek judge，HTML dashboard，4-agent 对比。
-
-## 1.0 SDK 架构
-
-- `core`：不可变 `AgentSpec`、canonical items、structured output、guardrail、usage 与 run error。
-- `providers`：统一 `ModelProvider` contract，以及 capability-checked OpenAI Responses、OpenAI Chat-compatible、Anthropic adapter。
-- `runtime`：单一 `AgentRuntime`、lazy `RuntimeServices`、固定阶段 middleware、tool/policy、有界 stream、checkpoint、interruption/resume。
-- `node`：tenant-scoped SQLite session/checkpoint/memory/artifact store 与 backup-first JSON v1 migration。
-- `events` / `surfaces`：版本化、可 trace 的 `RunEvent`，以及统一 CLI/TUI/GUI/Bridge 语义和 redaction。
-- `orchestration` / `workflow` / `profiles`：agent-as-tool、handoff、durable spawn、graph/preset、workflow trust 与六类 profile。
-- `compat`：0.x root façade 与迁移 adapter，在整个 1.x 保留。
-
-## 路线图 — 迈向 agent team
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/gui-home.png" alt="Hadamard 桌面 GUI——项目总览" width="49%">
+  <img src="https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/gui-chat.png" alt="Hadamard 桌面 GUI——模型对话" width="49%">
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/tui-home.png" alt="Hadamard TUI——终端启动界面" width="90%">
+</p>
+<p align="center"><em>桌面 GUI（上：项目总览与对话界面）和终端 UI（下）。</em></p>
 
-- **Swarm 协作** — 基于邮箱的 agent 间通信、任务队列、共享知识图谱。
-- **持久 team 记忆** — team 级上下文，跨会话和成员变更保留。
-- **跨运行时会话延续** — 恢复 bridge 运行时会话时保留精确位置。
-- **Model team IDE** — 可视化团队构建器、成员角色编辑器、团队健康仪表板。
+> **包名说明：** npm 发布名为 [`actoviq-agent-sdk`](https://www.npmjs.com/package/actoviq-agent-sdk)。产品、仓库、CLI 与配置路径统一为 **Hadamard**（`hadamard-*`、`~/.hadamard`、`.hadamard/`）。
 
 ## 安装
 
-要求 Node.js 22.13+ 或 Node.js 24。Node 22.5–22.12 的 `node:sqlite` 仍要求宿主进程 flag，
-因此不属于默认 Runtime 支持范围。
+要求 Node.js 22.13+ 或 Node.js 24。
 
 ```bash
 npm install actoviq-agent-sdk zod
 ```
 
-本地使用，请将配置放在：
+上面的 `npm install` 面向 SDK 用法（`import 'actoviq-agent-sdk'`），命令行需通过 `npx` 调用（如 `npx hadamard-tui`）。若想让 `hadamard-tui` / `hadamard-gui` / `hadamard` / `actoviq` 直接出现在 PATH 上，请改用全局安装：
 
-```text
-~/.hadamard/settings.json
+```bash
+npm install -g actoviq-agent-sdk
 ```
 
-也可以使用 `loadJsonConfigFile(...)` 预加载自定义 JSON 文件。
+将提供商配置放在 `~/.hadamard/settings.json` —— 任意 Anthropic 兼容或 OpenAI 兼容的提供商均可。
+
+## 快速开始
 
-## 快速开始（1.0 runtime）
+### SDK
 
 ```ts
-import type { AgentSpec } from 'actoviq-agent-sdk/core';
-import { ModelRegistry, OpenAIResponsesProvider } from 'actoviq-agent-sdk/providers';
-import { AgentRuntime } from 'actoviq-agent-sdk/runtime';
-
-const runtime = new AgentRuntime({
-  models: new ModelRegistry([
-    new OpenAIResponsesProvider({ apiKey: process.env.OPENAI_API_KEY }),
-  ]),
-});
-const agent: AgentSpec = {
-  id: 'concise-chat',
-  name: 'Concise chat',
-  instructions: '请用一句话回答。',
-  model: 'openai-responses:gpt-4.1-mini',
-};
-
-try {
-  const result = await runtime.run(agent, '什么是 CAS？');
-  console.log(result.output, result.usage.totalTokens);
-} finally {
-  await runtime.close();
-}
-```
+import { createAgentSdk, loadDefaultHadamardSettings } from 'actoviq-agent-sdk';
 
-0.x 应用可继续从 package root 或 `/compat` 导入 `createAgentSdk`；新应用应使用上述职责 subpath。
+await loadDefaultHadamardSettings();   // 读取 ~/.hadamard/settings.json
+const sdk = await createAgentSdk();
 
-运行仓库示例：
+const result = await sdk.run('什么是 CAS？');
+console.log(result.text);
 
-```bash
-npm run example:hadamard-quickstart
-npm run example:hadamard-agent-helpers
-npm run example:profiles
+await sdk.close();
 ```
 
-## 终端 UI (TUI)
+在仓库内可用 `npm run example:hadamard-quickstart` 运行同样的示例。
 
-`hadamard-tui` 是唯一的交互式终端 Agent 入口，也是全功能终端 UI：
+### 终端 UI（`hadamard-tui`）
 
 ```bash
-npx hadamard-tui [工作目录] [选项]
-
-# 选项
-#   --config <路径>            加载指定的 Hadamard 设置 JSON 文件
-#   --permission-mode <模式>   default | acceptEdits | plan | bypassPermissions (默认)
-#   --model <模型>             覆盖已配置的模型
-#   --resume <会话ID>          恢复已存储的 Hadamard SDK 会话
-#   --continue                 继续最近更新的会话
+npx hadamard-tui [工作目录]
 ```
 
-特性与英文 README 一致，包括上下文管理（append-only 前缀以利于 DeepSeek 等自动缓存；超阈值走整段摘要 compact）、bridge config、计划模式、hooks、MCP、诊断等。六种 External CLI 都可使用 `/bridge status`、`/bridge background`、`/bridge runs` 和 `/bridge stop`；`/bridge history` 与 `/bridge resume` 在 TUI 和 GUI 中共享同一套校验逻辑，但原生历史/恢复能力仍取决于已安装 CLI 的协议与版本。
+输入消息并回车，即可在 Claude Code 风格的终端 REPL 中与 agent 对话。输入 `/` 打开斜杠命令菜单（`/team`、`/bridge`、`/plan`、`/mcp`、`/doctor`……）。常用参数：`--model`、`--permission-mode`、`--resume <会话ID>`、`--continue`。
 
-## 桌面 GUI (`hadamard-gui`)
+### 桌面 GUI（`hadamard-gui`）
 
 ```bash
-npx hadamard-gui [工作目录] [选项]
+npx hadamard-gui [工作目录]
 ```
 
-- Project 详情提供 `Document` / `Issues` 双 Tab。Issue 支持优先级、标签、验收标准、评论，以及受守卫保护的 `backlog → todo → in_progress → in_review/blocked → done` 生命周期。
-- **Agent graph 编排 UI**（GUI **Agent** 区域的可视化团队/图编辑器）**仍在持续迭代和优化中**，请勿当作已定稿产品面；稳定工作流请用已保存 team + `/team` / SDK API。
-- Settings → Models & routing 可创建 Agent Profile，将 bridge config 与模型绑定。`/issues start <id> [agent-profile]` 会先让 Project Manager 生成任务书，再创建关联会话；执行 agent 通过 `IssueReport` 汇报待审或阻塞状态。
-- Issue 与会话可双向跳转。Issue 默认保存在 `<data-root>/projects/<workspace-key>/issues.json`，也可切换到受保护的工作区文件 `.hadamard/issues.json`。
-- Settings → General 可将完整数据根目录迁移到空目录：复制并校验数据、写入 bootstrap 指针、重建 SDK/session store，并保留旧目录供手动清理。
+打开 Electron 聊天窗口（仅绑定 localhost 服务）—— 发送一条消息即可开始第一次对话。可视化 Agent graph 编辑器仍在迭代中；生产工作流请优先使用已保存的 team 与 `/team`。
 
-数据根目录解析优先级为：显式 SDK `homeDir` → `HADAMARD_HOME` → `~/.hadamard/data-root.json` → `~/.hadamard`。
+## 演示
 
-## 开发者笔记
+50 秒走一遍桌面 GUI：打开会话视图、新建对话、发送问题，观看流式回复、思考指示器与代码渲染。（[高清 MP4](https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/gui-demo.mp4)）
 
-- **启动 CLI/GUI 前构建：** `npm run build`（clean + `tsc`）。仅类型检查用 `npm run typecheck`；运行测试套件用 `npm test -- --run`。
-- **Team 行为集中化：** 通过 `src/team/teamRuntime.ts` 扩展团队，而非在每个模式中重复逻辑。
-- **Router profile 是 leader/dispatch 配置：** 内置 `dispatch` profile；用户同名文件会覆盖内置。
-- **`CLAUDE.md` 在此仓库中默认 git-ignore**。
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/gui-demo.gif" alt="Hadamard 桌面 GUI 演示——从新建对话到流式回复与代码块" width="90%">
+</p>
 
-## 教程
+## 文档
 
-- 英文教程：[docs/en/README.md](./docs/en/README.md)
-- 中文教程：[docs/zh/README.md](./docs/zh/README.md)
-- GitHub Pages 文档站：https://deconbear.github.io/hadamard/
+- 文档站：https://deconbear.github.io/hadamard/
+- 英文教程：[docs/en/README.md](./docs/en/README.md) · 中文教程：[docs/zh/README.md](./docs/zh/README.md)
+- External CLI bridge 指南（provider 参数、凭证、`HADAMARD_<PROVIDER>_PATH`）：[docs/en/05-bridge-runtime.md](./docs/en/05-bridge-runtime.md)
+- 示例：[hadamard-quickstart.ts](./examples/hadamard-quickstart.ts)、[hadamard-workflow.ts](./examples/hadamard-workflow.ts)、[hadamard-agent-helpers.ts](./examples/hadamard-agent-helpers.ts)
+- 安全政策：[SECURITY.md](./SECURITY.md)
 
-入口示例：
-- [examples/hadamard-quickstart.ts](./examples/hadamard-quickstart.ts)
-- [examples/hadamard-workflow.ts](./examples/hadamard-workflow.ts)
-- [examples/hadamard-agent-helpers.ts](./examples/hadamard-agent-helpers.ts)
-- [examples/profiles/all-profiles.ts](./examples/profiles/all-profiles.ts)
+## 开发
 
-架构与运维文档：
-
-- [安全报告政策](./SECURITY.md)
+```bash
+npm run typecheck   # TypeScript 检查
+npm test            # Vitest 测试
+npm run build       # 清理 + 编译
+```
 
 ## 参与贡献
 

package/README.md

@@ -1,4 +1,4 @@
-# Hadamard Agent SDK
+# Hadamard: Agents as an Engineering Team
 
 [![CI](https://github.com/DeconBear/hadamard/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DeconBear/hadamard/actions/workflows/ci.yml)
 [![Publish npm Package](https://github.com/DeconBear/hadamard/actions/workflows/publish-npm.yml/badge.svg?branch=main)](https://github.com/DeconBear/hadamard/actions/workflows/publish-npm.yml)
@@ -7,209 +7,96 @@
 
 [English](./README.md) | [Chinese](./README-zh.md)
 
-Documentation site: https://deconbear.github.io/hadamard/
+LLM harnesses are powerful but hard to manage on real engineering and research work — shipping software, running AI-for-Science (AI4S) pipelines, training neural networks and steering experiments. Contexts overflow, tool calls sprawl, runs drift from the plan, and a single agent loop never gets a second opinion.
 
-**Hadamard** (`0.4.x`) is a TypeScript agent SDK and agent-team platform with TUI, GUI, Bridge, and multi-agent collaboration. A future **1.0** line will stabilize package subpath contracts; that surface is **not published yet**.
+**Hadamard** exists to make agent engineering and research controllable. Multiple agents on different providers talk to each other — investigating, reviewing, and dispatching in parallel — so problems get considered more thoroughly. One TypeScript runtime provides tools, skills, durable sessions, memory, and MCP, plus a bridge that manages installed agent CLIs (Claude Code, Codex, Cursor, Pi, CodeWhale, Reasonix, Crush) as child processes; the same runtime ships with a terminal UI and a desktop GUI.
 
-> **Package name:** the published npm package remains [`actoviq-agent-sdk`](https://www.npmjs.com/package/actoviq-agent-sdk). Product, repo, CLI, and config paths use **Hadamard** (`hadamard-*`, `~/.hadamard`, `.hadamard/`).
+Inspired by Claude Code, Codex, Deepagents, and the broader agent ecosystem. Hadamard remains independent with its own public API and documentation.
 
-> **Note:** The desktop **Agent graph** orchestration UI (visual team / graph editor) is **still under active iteration and optimization** — expect UX and API changes. Prefer `/team`, saved team definitions, and the SDK `createTeam()` / graph runtime for production workflows today. See `CHANGELOG.md`.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/gui-home.png" alt="Hadamard desktop GUI — projects overview" width="49%">
+  <img src="https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/gui-chat.png" alt="Hadamard desktop GUI — chat with a model" width="49%">
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/tui-home.png" alt="Hadamard TUI — terminal startup screen" width="90%">
+</p>
+<p align="center"><em>The desktop GUI (top: projects overview and a chat session) and the terminal UI (bottom).</em></p>
 
-Inspired by Claude Code, Codex, Deepagents, and the broader agent ecosystem. Hadamard remains independent with its own public surface and documentation.
-
-## Vision
-
-- **Multi-agent**: subagent delegation (Task tool), panel-analysis teams, reviewer-auditor pairs, dynamic workflows — agents collaborating, not just a single loop.
-- **Multi-runtime state management**: bridge configs have two explicit modes. `Direct API` calls Anthropic/OpenAI-compatible providers in-process; `External CLI` manages installed Claude Code, Codex, Pi, CodeWhale, Reasonix, or Crush runtimes as child processes and preserves native session identities when the CLI protocol exposes them.
-- **Model team collaboration**: leaders dispatch to specialists (`/model router`), panel members investigate in parallel with structured convergence, reviewers report only verifiable issues — teams as first-class tools the agent invokes.
-
-## Highlights
-
-- **Model Team** — `panel-analysis` (parallel investigation + convergence) and `reviewer` (verifiable-issues-only auditor). Runtime-owned member pooling, streamed `TeamEvent`s, per-member provider config, and inherited permission/retry boundaries.
-- **Model Router / Leader-Dispatch** — a leader classifies each turn and dispatches it to the best specialist route (any model/provider), runs normally, and the executor may itself convene a team. Profiles in `~/.hadamard/routers/`.
-- **Dynamic Workflows** — JS script-based orchestration with explicit trust levels: trusted compatibility execution, isolated local-process execution, or a host-supplied remote/container sandbox for adversarial inputs.
-- **Bridge (named runtime configs)** — choose `Direct API` for provider-level reuse, or `External CLI` to launch installed Claude Code, Codex, Pi, CodeWhale, Reasonix, or Crush; reuse each CLI's native login/config, stream normalized tool and assistant events, stop background work, and browse/resume supported native conversations. An explicit key override is injected only into the child and is not written to the CLI's credential store; Pi, CodeWhale, Reasonix, and Crush keep isolated per-config session profiles so that key-mode history survives restarts without reading the native login store.
-- **Desktop GUI (`hadamard-gui`)** — Electron chat UI: streamed transcript, conversation history, command palette, settings, per-tool permission prompts. Security-hardened. Global **Assistant** FAB (Global/Project scope). The visual **Agent graph** orchestration UI is shipping in-progress and continues to be iterated (not a stable product surface yet).
-- **TUI (`hadamard-tui`)** — Terminal UI with 25+ slash commands, Claude Code-style UX: `/team`, `/bridge`, `/plan`, `/hooks`, `/mcp`, `/review`, `/context`, `/cost`, `/doctor`, and more. Live status spinner, scrollback transcript, todo panel, permission dialogs with project/user scope, sub-command autocomplete.
-- **Plan mode + hooks** — `EnterPlanMode`/`ExitPlanMode` tools with plan file; typed command, prompt, or HTTPS lifecycle hooks for session, turn, model, tool, permission, compact, stop, and worktree events. The GUI edits them directly; legacy `PreToolUse`/`PostToolUse`/`SessionStart` shell hooks remain compatible.
-- **Worktree Tools** — `EnterWorktree`/`ExitWorktree` with stack-based cwd, `.worktreeinclude`, PR checkout.
-- **TavilySearch** — AI-optimized web search, pure TypeScript.
-- **Standard Benchmark** — Self-contained framework with DeepSeek judge, HTML dashboard, 4-agent comparison.
-
-## 1.0 SDK architecture
-
-- `core`: immutable `AgentSpec`, canonical input/output items, structured output, guardrails, usage, and run errors.
-- `providers`: capability-checked OpenAI Responses, OpenAI Chat-compatible, and Anthropic adapters behind one `ModelProvider` contract.
-- `runtime`: one `AgentRuntime`, lazy `RuntimeServices`, fixed-stage middleware, tools/policy, bounded streams, checkpoints, interruption, and resume.
-- `node`: tenant-scoped SQLite session/checkpoint/memory/artifact stores and backup-first JSON v1 migration.
-- `events` and `surfaces`: versioned traceable `RunEvent`s plus shared CLI/TUI/GUI/Bridge semantics and redaction.
-- `orchestration`, `workflow`, and `profiles`: agent-as-tool, handoff, durable spawn, graphs/presets, explicit workflow trust, and six composable agent profiles.
-- `compat`: the 0.x root façade and migration adapters, retained throughout the 1.x line.
-
-## Roadmap — toward agent teams
-
-- **Swarm coordination** — mailbox-based inter-agent communication, task queues, shared knowledge graph.
-- **Persistent team memory** — team-scoped context that survives across sessions and member changes.
-- **Cross-runtime session continuity** — resume a bridge runtime's session exactly where you left it, regardless of which config was active.
-- **Model team IDE** — visual team builder, member role editor, team health dashboard.
+> **Package name:** the published npm package is [`actoviq-agent-sdk`](https://www.npmjs.com/package/actoviq-agent-sdk). Product, repo, CLI, and config paths use **Hadamard** (`hadamard-*`, `~/.hadamard`, `.hadamard/`).
 
 ## Install
 
-Node.js 22.13+ or Node.js 24 is required. Node 22.5–22.12 exposes
-`node:sqlite` only behind a process flag and is therefore outside the default
-runtime support contract.
+Node.js 22.13+ or Node.js 24 is required.
 
 ```bash
 npm install actoviq-agent-sdk zod
 ```
 
-For local examples, place your config at:
+The `npm install` above is for SDK usage (import from `'actoviq-agent-sdk'`); the CLIs are then available through `npx` (for example `npx hadamard-tui`). To run `hadamard-tui` / `hadamard-gui` / `hadamard` / `actoviq` directly on your PATH, install globally instead:
 
-```text
-~/.hadamard/settings.json
+```bash
+npm install -g actoviq-agent-sdk
 ```
 
-You can also preload a custom JSON file with `loadJsonConfigFile(...)`.
+Put your provider settings at `~/.hadamard/settings.json` — any Anthropic-compatible or OpenAI-compatible provider works.
 
-## Quick Start (1.0 runtime)
+## Quick Start
 
-```ts
-import type { AgentSpec } from 'actoviq-agent-sdk/core';
-import { ModelRegistry, OpenAIResponsesProvider } from 'actoviq-agent-sdk/providers';
-import { AgentRuntime } from 'actoviq-agent-sdk/runtime';
-
-const runtime = new AgentRuntime({
-  models: new ModelRegistry([
-    new OpenAIResponsesProvider({ apiKey: process.env.OPENAI_API_KEY }),
-  ]),
-});
-const agent: AgentSpec = {
-  id: 'concise-chat',
-  name: 'Concise chat',
-  instructions: 'Answer in one short sentence.',
-  model: 'openai-responses:gpt-4.1-mini',
-};
-
-try {
-  const result = await runtime.run(agent, 'What is compare-and-swap?');
-  console.log(result.output, result.usage.totalTokens);
-} finally {
-  await runtime.close();
-}
-```
+### SDK
 
-Existing 0.x applications may keep importing `createAgentSdk` from the package root or `/compat`; new applications should use the responsibility subpaths above.
+```ts
+import { createAgentSdk, loadDefaultHadamardSettings } from 'actoviq-agent-sdk';
 
-The supported differences between the SDK, `hadamard-tui`, and the desktop GUI are defined by the [three-layer product surface policy](./docs/en/08-product-surfaces.md) ([中文](./docs/zh/08-product-surfaces.md)). SDK-only developer parameters are intentional; shared TUI/GUI commands and runtime semantics are parity requirements.
+await loadDefaultHadamardSettings();   // reads ~/.hadamard/settings.json
+const sdk = await createAgentSdk();
 
-Run the repository examples with:
+const result = await sdk.run('What is compare-and-swap?');
+console.log(result.text);
 
-```bash
-npm run example:hadamard-quickstart
-npm run example:hadamard-agent-helpers
-npm run example:profiles
+await sdk.close();
 ```
 
-## CLI / Terminal UI
+Run the same example from the repository with `npm run example:hadamard-quickstart`.
 
-`hadamard-tui` is the full terminal UI, modeled on Claude Code's REPL design: the transcript prints into native scrollback while a redrawable bottom region hosts the status line, a Claude-style prompt bar, the slash-command menu, and permission dialogs.
+### Terminal UI (`hadamard-tui`)
 
 ```bash
-npx hadamard-tui [work-dir] [options]
-
-# Options
-#   --config <path>            Load a specific Hadamard settings JSON file
-#   --permission-mode <mode>   default | acceptEdits | plan | bypassPermissions (default)
-#   --model <model>            Override the configured model
-#   --resume <session-id>      Resume a stored Hadamard SDK session
-#   --continue                 Continue the most recently updated session
+npx hadamard-tui [work-dir]
 ```
 
-Features:
+Type a message and press Enter — you are chatting with the agent in a Claude Code-style terminal REPL. `/` opens the slash-command menu (`/team`, `/bridge`, `/plan`, `/mcp`, `/doctor`, …). Common flags: `--model`, `--permission-mode`, `--resume <session-id>`, `--continue`.
 
-- **Streaming transcript in native scrollback** — assistant text, `⏺ Tool(args)` calls, and `⎿ ✓/✗` result lines flush into the normal terminal buffer; scrollback and copy/paste work as usual.
-- **Live status line** — spinner, elapsed time, tool count, and the active tool while the agent works, over an always-visible mode line (model · permission · effort · team · bridge · context%) that shows context usage as a percentage of the window and turns yellow then red as it fills.
-- **Claude-style prompt bar** — type `\` then `Enter` (or `Ctrl+J`) for a newline; `↑`/`↓` walk input history; the caret renders inline.
-- **Slash-command menu** — type `/` to open a filtered menu (`↑↓` select, `Tab` complete, `Enter` run). `/resume` opens a searchable project-session picker.
-- **`@` file completion** — type `@` to open a git-aware workspace file picker filtered by the partial path; subsequence fuzzy matching.
-- **Team / workflow / worktree pickers** — `/team` activates a saved Model Team; `/workflows` runs a saved dynamic workflow; `/worktree` enters, exits, or lists git worktrees.
-- **Permission presets + per-tool scope** — `/permissions` switches between read-only/workspace/full/plan presets; always-allow rules persist with project or user scope.
-- **Mid-run steering** — keep typing while the agent works and press `Enter`: the message is queued and injected into the very next model request (shown as `⧗ queued`).
-- **Plan mode + hooks** — `/plan` enters plan mode (`EnterPlanMode`/`ExitPlanMode` tools, plan file); typed lifecycle hooks are configured in the GUI or `settings.json`, while `/hooks` continues to list compatible legacy shell hooks.
-- **Bridge configs** — `/bridge config` manages named API or External CLI profiles for all six managed CLIs. `/bridge status`, `/bridge background`, `/bridge runs`, `/bridge stop`, `/bridge history`, and `/bridge resume` expose the same runtime lifecycle in the TUI and GUI; native history/resume remains subject to each installed CLI's protocol/version support.
-- **Diagnostics + inspection** — `/doctor` checks config health; `/context` inspects the context window; `/cost`/`/usage` track token + spend (per-config breakdown); `/review` reviews the git diff; `/stats` shows session stats.
-- **Context management built in** — the Hadamard SDK auto-compacts long sessions mid-run (full summary compact) and reactively recovers when a provider rejects an oversized prompt; notices surface as ∿ context compacted. History stays **append-only** between turns so automatic prefix caches (e.g. DeepSeek Context Caching) stay hot; Anthropic hosts still get explicit cache_control breakpoints. Oversized tool outputs are artifacted at write time rather than rewriting earlier messages.
-- **MCP management** — `/mcp add`/`/mcp remove` manage stdio + remote HTTP MCP servers, persisted to `~/.hadamard/mcp.json`.
-- **Image attachments** — `@<path>.png` tokens expand into image content blocks (in-process, read as base64).
-
-The TUI uses the Hadamard SDK runtime defaults (Hadamard settings from `~/.hadamard/settings.json`, core tools, `bypassPermissions`, uncapped tool iterations) and runs against any Anthropic-compatible or OpenAI-compatible provider. `hadamard-tui` is the only interactive terminal agent entry point; the former `hadamard-react` and `hadamard-interactive-agent` entry points were retired after their capabilities were consolidated here.
-
-By default, Hadamard SDK sessions are scoped to the current workspace under `~/.hadamard/projects/<workspace-key>`. Explicit `sessionDirectory` settings still take precedence.
-
-Model tiers are provider-neutral aliases. Configure them with `HADAMARD_DEFAULT_MIN_MODEL`, `HADAMARD_DEFAULT_MEDIUM_MODEL`, and `HADAMARD_DEFAULT_MAX_MODEL`, then use `min`, `medium`, or `max` anywhere a model can be selected.
-
-## Desktop GUI (`hadamard-gui`)
-
-A local Electron desktop chat UI for the Hadamard SDK.
+### Desktop GUI (`hadamard-gui`)
 
 ```bash
-npx hadamard-gui [work-dir] [options]
-
-# Options
-#   --port <port>              Internal port to bind (default: 4174, auto-fallback if busy)
-#   --config <path>            Load a specific Hadamard settings JSON file
-#   --permission-mode <mode>   default | acceptEdits | plan | bypassPermissions (default)
-#   --model <model>            Override the configured model
-#   --resume <session-id>      Resume a stored session
-#   --continue                 Resume the most recent stored session
+npx hadamard-gui [work-dir]
 ```
 
-It opens an Electron window backed by a localhost-only HTTP server. Features:
-
-- **Streamed transcript** with markdown rendering and copyable code blocks, plus live tool-call cards
-- **Conversation history on resume** — opening or switching a chat replays its stored messages
-- **Shared slash commands**, settings (provider / model / keys / appearance), workspace switching, and empty-chat cleanup
-- **Per-tool permission prompts** (queued so concurrent requests don't collide) and a token-usage readout
-- **Project Documents + Issues** — each Project detail page has `Document` and `Issues` tabs. Issues use the guarded `backlog → todo → in_progress → in_review/blocked → done` lifecycle, support priorities, labels, acceptance criteria, comments, and links back to their worker sessions.
-- **Agent graph orchestration UI** — visual team/graph editor lives in the GUI **Agent** region; **it is still being iterated and optimized** and should not be treated as a finished product surface. Prefer saved teams + `/team` / SDK APIs for stable workflows.
-- **Agent Workflow + Automation** — the Agent region edits validated sequential, branch, and parallel Workflow trees. New Automation tasks select those saved Workflows; historical dynamic-script tasks remain compatible without being reinterpreted.
-- **Custom shortcuts + desktop screenshots** — Settings remaps supported actions, including a cross-platform screenshot action available to the user and agent runtime.
-- **Lifecycle hook editor** — Settings manages typed session, turn, model, tool, permission, compact, stop, and worktree hooks while retaining legacy hook compatibility.
-- **Agent Profiles for issue dispatch** — Settings → Models & routing can bind a named profile to a saved bridge config and model. `/issues start <id> [agent-profile]` asks the Project Manager for a worker brief, starts a linked session without changing the globally active runtime, and requires the worker to report through `IssueReport`.
-- **Movable data root** — Settings → General can copy the complete Hadamard data root to an empty directory, validate it, write the bootstrap pointer, rebuild the SDK/session store, and retain the previous directory for manual cleanup.
+Opens an Electron chat window backed by a localhost-only server — send a message to start your first conversation. The visual Agent graph editor is still iterating; prefer saved teams and `/team` for production workflows.
 
-**Security model:** the internal API is reachable only from loopback (Host + Origin allowlist, which defeats DNS-rebinding / CSRF) and requires a per-process token; the page ships a strict Content-Security-Policy. Electron runs with `sandbox`, `contextIsolation`, and no `nodeIntegration`.
+## Demo
 
-Hadamard resolves its data root in this order: an explicit SDK `homeDir`, `HADAMARD_HOME`, `~/.hadamard/data-root.json`, then `~/.hadamard`. Project issues default to `<data-root>/projects/<workspace-key>/issues.json`; a project can instead use the protected workspace file `.hadamard/issues.json`.
+A 50-second walkthrough of the desktop GUI: open the Chats view, start a new conversation, ask a question, and watch the streamed reply with the thinking indicator and code rendering. ([Full-resolution MP4](https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/gui-demo.mp4))
 
-> `electron` and `bun` are **optional** dependencies — installed only if you use the GUI / bridge runtime. The core SDK does not require them.
->
-> **Bridge env overrides:** `HADAMARD_CLAUDE_PATH`, `HADAMARD_PI_PATH`, … (one per provider) to point the bridge at a specific runtime binary when it's not on `PATH`. See `docs/en/05-bridge-runtime.md`.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DeconBear/hadamard/main/docs/assets/screenshots/gui-demo.gif" alt="Hadamard desktop GUI demo — a chat from New chat to a streamed reply with a code block" width="90%">
+</p>
 
-## Developer notes
+## Documentation
 
-- **Build before launching the CLIs/GUI:** `npm run build` (clean + `tsc`). Type-check only with `npm run typecheck`; run the suite with `npm test -- --run`.
-- **Team behavior is centralized:** extend teams through `src/team/teamRuntime.ts` (`runMemberAgent` / `buildMemberIdentities` / `preflightMember`) rather than duplicating per-mode logic. Observe a run via `team.ask(prompt, signal, { onEvent })` and inspect `result.memberStatuses` / `result.incompleteReason`.
-- **Router profiles are leader/dispatch configs:** a `RouterProfile` is a leader (`routerModel`) + a roster of specialist `routes` (each with `when` and optional `role` / `description`). `BUILT_IN_ROUTER_PROFILES` ships a ready-made `dispatch` profile; a user file of the same name in `.hadamard/routers/` shadows it.
-- **`CLAUDE.md` is intentionally git-ignored** in this repo — keep contributor-facing docs here in the README (or under `docs/`), not in `CLAUDE.md`.
+- Docs site: https://deconbear.github.io/hadamard/
+- English tutorial: [docs/en/README.md](./docs/en/README.md) · Chinese tutorial: [docs/zh/README.md](./docs/zh/README.md)
+- External CLI bridge guide (provider flags, credentials, `HADAMARD_<PROVIDER>_PATH`): [docs/en/05-bridge-runtime.md](./docs/en/05-bridge-runtime.md)
+- Examples: [hadamard-quickstart.ts](./examples/hadamard-quickstart.ts), [hadamard-workflow.ts](./examples/hadamard-workflow.ts), [hadamard-agent-helpers.ts](./examples/hadamard-agent-helpers.ts)
+- Security policy: [SECURITY.md](./SECURITY.md)
 
-## Tutorials
+## Development
 
-- English tutorial: [docs/en/README.md](./docs/en/README.md)
-- Chinese tutorial: [docs/zh/README.md](./docs/zh/README.md)
-- GitHub Pages docs site:
-  - https://deconbear.github.io/hadamard/
-
-Start with these examples:
-
-- [examples/hadamard-quickstart.ts](./examples/hadamard-quickstart.ts)
-- [examples/hadamard-workflow.ts](./examples/hadamard-workflow.ts)
-- [examples/hadamard-agent-helpers.ts](./examples/hadamard-agent-helpers.ts)
-- [examples/profiles/all-profiles.ts](./examples/profiles/all-profiles.ts)
-
-Architecture and operations:
-
-- [Security policy](./SECURITY.md)
+```bash
+npm run typecheck   # TypeScript checks
+npm test            # Vitest suite
+npm run build       # clean + compile
+```
 
 ## Contributing
 

package/bin/hadamard-gui.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
@@ -9,21 +10,36 @@ const require = createRequire(import.meta.url);
 const rootDir = fileURLToPath(new URL('..', import.meta.url));
 const main = fileURLToPath(new URL('../dist/src/gui/electronMain.js', import.meta.url));
 const prepareLauncher = fileURLToPath(new URL('../scripts/prepare-gui-launcher.mjs', import.meta.url));
+const iconIco = fileURLToPath(new URL('../assets/hadamard-icon.ico', import.meta.url));
+
+function resolveDevelopmentIdentity() {
+  if (!existsSync(iconIco)) {
+    return {
+      launcherName: 'Hadamard.exe',
+      appUserModelId: 'com.hadamard.desktop.dev',
+    };
+  }
+  const iconFingerprint = createHash('sha256').update(readFileSync(iconIco)).digest('hex').slice(0, 12);
+  return {
+    launcherName: `Hadamard-${iconFingerprint}.exe`,
+    appUserModelId: `com.hadamard.desktop.dev.${iconFingerprint}`,
+  };
+}
+
+const developmentIdentity = resolveDevelopmentIdentity();
 
 function resolveElectronExecutable() {
   const electronExe = require('electron');
   if (process.platform === 'win32') {
-    const brandedLauncher = join(dirname(electronExe), 'Hadamard.exe');
-    if (!existsSync(brandedLauncher)) {
-      const prep = spawnSync(process.execPath, [prepareLauncher], {
-        stdio: process.platform === 'win32' ? 'ignore' : 'inherit',
-        windowsHide: process.platform === 'win32',
-      });
-      if (prep.status !== 0) {
-        process.stderr.write(
-          'Hadamard: branded launcher unavailable; taskbar may show the Electron icon.\n',
-        );
-      }
+    const brandedLauncher = join(dirname(electronExe), developmentIdentity.launcherName);
+    const prep = spawnSync(process.execPath, [prepareLauncher], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    if (prep.status !== 0) {
+      process.stderr.write(
+        'Hadamard: branded launcher could not be refreshed; taskbar may show a stale or Electron icon.\n',
+      );
     }
     if (existsSync(brandedLauncher)) return brandedLauncher;
   }
@@ -38,6 +54,9 @@ const child = spawn(electron, [main, ...process.argv.slice(2)], {
   env: {
     ...process.env,
     HADAMARD_GUI_ROOT: rootDir,
+    HADAMARD_GUI_DEVELOPMENT: '1',
+    HADAMARD_GUI_APP_USER_MODEL_ID: developmentIdentity.appUserModelId,
+    HADAMARD_GUI_NODE: process.execPath,
   },
   windowsHide: windowsGuiLaunch,
   detached: windowsGuiLaunch,

package/dist/src/codeIntel/codeIntelligenceService.d.ts

@@ -5,6 +5,14 @@ export interface CodeIntelligenceServiceOptions {
     registry: LanguageServerRegistry;
     timeoutMs?: number;
 }
+/** Snapshot of one language server for the /lsp status command. */
+export interface LanguageServerStatus {
+    id: string;
+    languages: string[];
+    available: boolean;
+    reason?: string;
+    running: boolean;
+}
 export declare class CodeIntelligenceService {
     private readonly options;
     private readonly workDir;
@@ -14,10 +22,18 @@ export declare class CodeIntelligenceService {
     workspaceSymbols(query: string): Promise<WorkspaceSymbol[]>;
     definition(filePath: string, line: number, character: number): Promise<CodeLocation[]>;
     references(filePath: string, line: number, character: number): Promise<CodeLocation[]>;
+    hover(filePath: string, line: number, character: number): Promise<string>;
     diagnostics(filePath?: string): Promise<CodeDiagnostic[]>;
+    /**
+     * Registry capabilities plus live server state for the /lsp command. Running
+     * is reported conservatively (a server entry exists once spawned); a hung
+     * initialize handshake must not block this status call.
+     */
+    serverStatus(): Promise<LanguageServerStatus[]>;
     close(): Promise<void>;
     private locationRequest;
     private openDocument;
+    private syncDocument;
     private assertWorkspacePath;
     private allAvailableServers;
     private server;

package/dist/src/codeIntel/codeIntelligenceService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codeIntelligenceService.d.ts","sourceRoot":"","sources":["../../../src/codeIntel/codeIntelligenceService.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EAEZ,eAAe,EAChB,MAAM,YAAY,CAAC;AAUpB,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,sBAAsB,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,uBAAuB;IAKtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;gBAE3C,OAAO,EAAE,8BAA8B;IAI9D,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAW3D,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAItF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAMtF,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAQzD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAKd,eAAe;YAoBf,YAAY;YAqBZ,mBAAmB;YA0BnB,mBAAmB;YAUnB,MAAM;IAmCpB,OAAO,CAAC,kBAAkB;CAiB3B"}
+{"version":3,"file":"codeIntelligenceService.d.ts","sourceRoot":"","sources":["../../../src/codeIntel/codeIntelligenceService.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EAEZ,eAAe,EAChB,MAAM,YAAY,CAAC;AAgBpB,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,sBAAsB,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,uBAAuB;IAKtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;gBAE3C,OAAO,EAAE,8BAA8B;IAI9D,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAW3D,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAItF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAMtF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYzE,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAQ/D;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAW/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAgBd,eAAe;YAoBf,YAAY;YA0BZ,YAAY;YAoBZ,mBAAmB;YA0BnB,mBAAmB;YAUnB,MAAM;IAmCpB,OAAO,CAAC,kBAAkB;CAiB3B"}