actoviq-agent-sdk 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -0,0 +1,219 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, with automated updates from GitHub Releases.
+
+## v0.4.8 - 2026-07-27
+
+### Runtime / prompt cache
+
+- Keep conversation history **append-only** on the wire and in session compact: no sliding-window rewrite of historical `tool_result` content between ReAct turns or auto session compact (aligns with Claude Code third-party behavior).
+- Context pressure is handled by **full summary compact** (in-loop + session), not by nibbling earlier tool results. Default `apiMicrocompactClearToolResults` is now `false`.
+- Map DeepSeek `prompt_cache_hit_tokens` → `cache_read_input_tokens` for local usage / GUI reporting. DeepSeek Context Caching remains automatic on their side; Anthropic hosts still receive explicit `cache_control` breakpoints.
+
+### GUI / docs
+
+- Document that the desktop **Agent graph** orchestration UI remains **under active iteration and optimization** (not a stable product surface). Prefer `/team`, saved team definitions, and SDK `createTeam()` / graph runtime for production workflows.
+
+### Notes
+
+- This release stays on the **0.4.x** line. **1.0.0 is not published yet.**
+
+## v0.4.7 - 2026-07-12
+
+### GUI
+
+- Hide incomplete Settings panels (**Profile**, **Browser**, **Computer control**, dedicated **Worktrees**) from the sidebar; markup and handlers remain in the codebase for a later release.
+- Hide the main **Agent** region nav entry (team graph UI) the same way — code retained, not deleted.
+- Settings sidebar notes which surfaces are still under development in this release.
+
+### Still under development (not product-ready in 0.4.7)
+
+- Main **Agent** / team-graph / **Agent graph orchestration UI** — still being iterated and optimized; do not treat as finished
+- Settings: **Profile**, **Browser**, **Computer control**, dedicated **Worktrees** tab
+- Keyboard shortcut remapping (reference list only)
+- Full 1.0 runtime/package surface (tracked as unreleased below)
+
+### Notes
+
+- This release stays on the **0.4.x** line. **1.0.0 is not published yet.**
+
+## Unreleased — v1.0.0 (not published)
+
+> Draft notes for a future 1.0.0. Do not treat this section as shipped.
+
+### Stable SDK contracts
+
+### Stable SDK contracts
+
+- Added responsibility-based public subpaths: `/core`, `/providers`, `/runtime`, `/events`, `/surfaces`, `/orchestration`, `/workflow`, `/profiles`, `/node`, and `/compat`.
+- Added provider-neutral canonical items, immutable `AgentSpec`, structured output, guardrails, aggregate usage, and versioned run errors.
+- Added `ModelProvider`, capability preflight, registry/transport contracts, and OpenAI Responses, OpenAI Chat compatibility, and Anthropic adapters.
+- Added `AgentRuntime`, fixed-stage middleware, lazy `RuntimeServices`, bounded streaming, unified cancellation/deadlines, tool policy, interruption, checkpoint, and resume contracts.
+- Reserved model/tool terminals now fail closed when middleware omits `next()`; model rewrites are post-validated, while ToolRunner parses once, freezes the validated result, and rejects wrapper replacement so capability/policy/schema invariants cannot be bypassed.
+- Added a fair, abort-aware top-level runtime concurrency gate; acceptance now covers 100 same-session turns and 1000 independent sessions without exceeding the configured provider concurrency.
+- GUI issue dispatch now persists a durable child/checkpoint before executing the legacy session adapter, with SQLite query/resume across coordinator restart and no second SDK/runtime instance.
+
+### Durable state and orchestration
+
+- Added tenant-scoped SQLite session, checkpoint, memory, artifact, and durable child stores with CAS and append-only item journals.
+- Added backup-first JSON v1 migration with canonical message conversion, migration ledger/idempotency, transaction rollback, legacy run filtering, and runtime cutover coverage.
+- Added agent-as-tool, handoff, durable background spawn, run-tree cancellation, inherited budget/policy/workspace/trace scope, workflow graph/reducer, and team/router/reviewer/swarm presets.
+- Explicit handoff now invokes the source runtime's `beforeHandoff` stage before child execution and ownership transfer; model-produced handoff items are not implicitly dispatched.
+- Split trusted compatibility workflow execution from fail-closed untrusted process/sandbox execution.
+
+### Agent profiles and product surfaces
+
+- Added chat, coding, research, workflow, supervisor, and background profiles sharing one runtime contract.
+- Added versioned `RunEvent` processing, redaction, trace propagation, OpenTelemetry-compatible export, and shared CLI/TUI/GUI/Bridge semantics.
+- Added `AgentRuntimeBridgeAdapter`, a thin Bridge projection over an existing runtime that owns no duplicate provider or service container.
+- Retained the 0.x root API and `createAgentSdk` as the 1.x compatibility façade, with provider adapters and local opt-in migration diagnostics.
+
+### Reliability, security, and release gates
+
+- Fixed same-session concurrency, bounded queue cancellation, side-effect retry safety, MCP configuration identity/catalog caching, team permission inheritance, work directory persistence, and usage aggregation.
+- Windows provider detection no longer executes `.cmd`/`.bat` shims for best-effort version display, preventing descendant leaks when the host denies process-tree termination; availability remains detectable and version is reported as unknown.
+- Added Node.js 22.13+/24 support policy, exact minimum-version CI gates, `SECURITY.md`, threat/failure policy, ten ADRs, migration/cutover/rollback guidance, and a 1.0 migration guide. The 22.13 floor reflects when `node:sqlite` became available without a host process flag.
+- Added runtime performance benchmarks, public API snapshots, package subpath clean-import verification, package dry-run, SDK layer coverage gates, and Node/OS CI matrices.
+
+### Compatibility notes
+
+- Node.js 18/20 and Node.js 22.0–22.4 are no longer supported.
+- Unknown legacy provider blocks remain durable for audit but are not replayed into a different provider's active transcript.
+- Local process workflow isolation is not an adversarial multi-tenant sandbox.
+
+## v0.4.0 - 2026-06-15
+
+### Features
+
+- **Subagent infrastructure**: `Agent`/`Task` tool with Task compatibility alias, persistent sessions, and `SendMessage` continuation
+- **Background agents**: automatic completion notifications, progress tracking, cancellation, and lifecycle reconciliation
+- **Markdown agent definitions**: user-level (`~/.actoviq/agents/`) and project-level (`.actoviq/agents/`) `.md` files with tool/skill/permission/MCP/effort controls
+- **Worktree isolation**: `isolation: "worktree"` for parallel agents editing overlapping files; dirty worktrees retained, clean ones auto-removed
+- **Nested delegation controls**: configurable depth limit (`maxSubagentDepth`), fanout limit (`maxSubagentFanout`), and per-definition allowed agents
+- **Built-in agent definitions**: Explore, Plan, and general-purpose agents with Claude Code-compatible profiles
+- **Windows Bash tool**: now uses Git Bash for POSIX commands on Windows
+- **TUI**: full-screen terminal UI (`actoviq-tui`) with session management, permission mode switching, and provider configuration
+- **Model tiers**: `min`/`medium`/`max` tier resolution with `ACTVIQ_DEFAULT_{TIER}_MODEL` env vars
+- **Enhanced Agent tool prompt**: Claude Code-level subagent guidance (foreground/background, parallel delegation, "never delegate understanding")
+
+### Bug Fixes
+
+- `close()` now tolerates individual cleanup failures instead of bailing on first error
+- `isGitWorkspaceDirty`: added 10s timeout, returns false on error to prevent worktree leaks
+- Background task `cancel()`: re-reads store after abort to prevent TOCTOU race with terminal state
+- `forwardStreamResult`: captures both pump and result errors instead of silently losing one
+- Agent definition loader: logs a warning for malformed `.md` files instead of silently skipping them
+- `encodeActoviqProjectPath` test made platform-aware (was hardcoded to Windows paths)
+
+### Benchmark
+
+- New cases: `workflow-agent-continuation` (SendMessage + background), `workflow-multi-module-parallel` (3-way parallel subagents)
+- Complex suite: 10/10 all three runtimes pass (Clean 0.993, Bridge 0.992, Official 0.960)
+- Long suite: 4/5 Clean and Bridge, 5/5 Official (`release-train-reconciliation` remains systemic weak point)
+- Multi-module-parallel: Clean 1.000 (3 parallel background subagents), Bridge 0.996, Official 0.953
+
+### TUI Branding
+
+- Display name changed from `Actoviq TUI` to `Hadamard Agent` (3 visible strings; all internal names, env vars, and config paths unchanged)
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.3.1...v0.4.0
+
+## v0.3.1 - 2026-06-11
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.3.0...v0.3.1
+
+## v0.3.0 - 2026-05-11
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/commits/v0.3.0
+
+## v0.2.0 - 2026-05-08
+
+### Breaking Changes
+
+- **`WorkflowBuilder.step()`** signature changed from 5 params `(id, name, description, prompt, opts?)` to 4 params `(id, description, prompt, opts?)`. The `name` field is removed — `description` now serves as the display name.
+- **`WorkflowStepDefinition`** removed `name` field. Use `description` for human-readable display names.
+
+### Features
+
+- **Workflow orchestration engine** with DAG execution, topological sort, and parallel step execution
+- **Builder DSL** (`sdk.workflow.define(...).step(...).run()`) and **JSON API** dual design paths
+- **Agent-orchestrated workflows**: Agent designs and executes workflow JSON via a `run_workflow` custom tool
+- **Tool registry pattern** (`sdk.getTool(name)`) enabling JSON-defined workflows to reference tools by name
+- **Step mode**: `'react'` (default, full tool loop) or `'single'` (no tool use, `tool_choice: none`)
+- **Variable interpolation** in step prompts: `$steps.<id>.text`, `$steps.<id>.toolCalls`, `$PARAM_NAME`
+- **`parallel()`** and **`race()`** primitives for concurrent task execution
+- **`SessionManager`** with idle timeout, auto-prune, stats, and lifecycle management
+- **Session checkpoints**: `saveCheckpoint()`, `restoreCheckpoint()`, `listCheckpoints()`, `deleteCheckpoint()`
+- **OpenAI protocol compatibility**: new `provider: 'openai'` option in `createAgentSdk()`. Use OpenAI, DeepSeek, or any OpenAI-compatible API with the same SDK surface. Automatic Anthropic ↔ OpenAI format translation.
+- **Alignment with Claude Code architecture**: tool self-declaration (isReadOnly/isDestructive/checkPermissions), canUseTool callback, compaction layered defense + circuit breaker, post-compaction context restoration, stop hooks system
+- Session lifecycle management: idle timeout, prune by age/status, close idle
+
+### Docs
+
+- Added agent-orchestrated workflow section (1.2) to EN and ZH tutorial docs
+- Documented OpenAI protocol configuration in setup/quickstart (EN + ZH)
+
+### Examples
+
+- Added `workflow-annotated.ts` — annotated walkthrough of every API parameter
+- Added `workflow-agent-orchestration.ts` — Agent autonomously designs and executes workflows
+- Added `actoviq-platform.ts` — consolidated workspaces + swarm + session memory + dream
+- Removed 8 redundant examples (buddy, computer-use, dream, memory, session-memory, skills, swarm, workspaces)
+- 12 focused examples remaining
+
+### Fixes
+
+- 18 bugs across provider layer, runtime, and workflow engine
+- Missing public API exports (trackRecentFile, resolveActoviqStopHooks, etc.)
+
+### Internal
+
+- Fixed regex for hyphenated step IDs in variable interpolation (`\w+` → `[\w-]+`)
+- Defensive `?.` checks on optional `dependsOn` and `steps` fields across workflow engine
+- `getTool()` public method on `ActoviqAgentClient` for tool registry lookup
+
+## v0.1.12 - 2026-05-06
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.11...v0.1.12
+
+## v0.1.11 - 2026-04-04
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.9...v0.1.11
+
+## v0.1.10 - 2026-04-03
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.9...v0.1.10
+
+## v0.1.9 - 2026-04-03
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.8...v0.1.9
+
+## v0.1.8 - 2026-04-03
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.7...v0.1.8
+
+## v0.1.7 - 2026-04-02
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.6...v0.1.7
+
+## v0.1.6 - 2026-04-02
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.5...v0.1.6
+
+## v0.1.5 - 2026-04-02
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.4...v0.1.5
+
+## v0.1.4 - 2026-04-02
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.3...v0.1.4
+
+## v0.1.3 - 2026-04-01
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.2...v0.1.3
+
+## v0.1.2 - 2026-04-01
+
+**Full Changelog**: https://github.com/DeconBear/actoviq-agent-sdk/compare/v0.1.1...v0.1.2

package/README-zh.md

@@ -9,29 +9,41 @@
 
 文档站地址：https://deconbear.github.io/actoviq-agent-sdk/
 
-**Actoviq** 是一个 agent team 平台 —— 一个 TypeScript 框架，用于将多个 AI agent、运行时和提供商组合成协作的多 agent 系统。它起源于可编程 agent SDK，但现在的目标是解决 **多 agent、多运行时状态管理** 和 **model team 协作**：协调多个专用模型、跨提供商路由、以及使用共享上下文编排 agent 集群。
+**Actoviq**（`0.4.x`）是 TypeScript agent SDK 与 agent-team 平台，含 TUI、GUI、Bridge 与多 agent 协作。未来的 **1.0** 线将稳定 package subpath 契约；该表面**尚未发布**。
+
+> **说明：** 桌面端 **Agent graph** 编排 UI（可视化团队 / 图编辑器）**仍在持续迭代与优化中**，交互与行为可能变化。生产工作流请优先使用 `/team`、已保存的 team 定义，以及 SDK 的 `createTeam()` / graph runtime。详见 `CHANGELOG.md`。
 
 受 Claude Code、Codex、Deepagents 等项目启发。Actoviq 保持独立，拥有自己的公开 API 与文档。
 
 ## 愿景
 
 - **多 agent**：子代理委派（Task 工具）、panel-analysis 团队、reviewer-auditor 对、动态 workflow —— agent 之间协作，而非单一的 ReAct 循环。
-- **多运行时状态管理**：bridge config 支持预配置多个后端（anthropic / openai / 任意兼容）的 apiKey + baseURL + model，命名切换，对话上下文在切换中保留（同一个 session 对象、同一份 transcript）。
+- **多运行时状态管理**：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`（只报告可验证问题的审计者）。集中化运行时（`src/team/teamRuntime.ts`），每个成员有稳定身份，流式 `TeamEvent`，每成员独立 provider 配置，全局 AgentPool。
+- **Model Team** — `panel-analysis`（并行调查 + 收敛）和 `reviewer`（只报告可验证问题的审计者）。runtime-owned 成员池、流式 `TeamEvent`、成员 provider 配置，以及继承的权限/重试边界。
 - **Model Router / Leader-Dispatch** — 每轮由 leader 分派到最佳 specialist（任意模型/提供商），执行者自身也可召集 team。Profile 位于 `~/.actoviq/routers/`。
-- **Dynamic Workflows** — JS 脚本多 agent 编排：`agent()`/`parallel()`/`pipeline()` 原语，沙箱运行时，Schema 强制。
-- **Bridge（命名连接配置）** — 进程内运行时切换：预配置 `anthropic`/`openai` 后端，命名 + apiKey + baseURL + model，命名切换，多轮上下文保留。`/bridge config` 单页编辑器；`/bridge` 列出已保存配置；`/cost` 中按配置展示用量。
-- **桌面 GUI (`actoviq-gui`)** — Electron 聊天 UI：流式 transcript、对话历史、命令面板、设置、每工具权限提示。安全增强。
+- **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 (`actoviq-gui`)** — Electron 聊天 UI：流式 transcript、对话历史、命令面板、设置、每工具权限提示。安全增强。可视化 **Agent graph** 编排 UI 仍在迭代中，暂勿当作稳定产品面。
 - **TUI (`actoviq-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
 
 - **Swarm 协作** — 基于邮箱的 agent 间通信、任务队列、共享知识图谱。
@@ -41,6 +53,9 @@
 
 ## 安装
 
+要求 Node.js 22.13+ 或 Node.js 24。Node 22.5–22.12 的 `node:sqlite` 仍要求宿主进程 flag，
+因此不属于默认 Runtime 支持范围。
+
 ```bash
 npm install actoviq-agent-sdk zod
 ```
@@ -53,36 +68,41 @@ npm install actoviq-agent-sdk zod
 
 也可以使用 `loadJsonConfigFile(...)` 预加载自定义 JSON 文件。
 
-## 快速开始
+## 快速开始（1.0 runtime）
 
 ```ts
-import { createAgentSdk, loadDefaultActoviqSettings } from 'actoviq-agent-sdk';
-
-await loadDefaultActoviqSettings();
-
-// 默认 Anthropic 协议
-const sdk = await createAgentSdk();
-
-// 或使用 OpenAI / OpenAI 兼容 API
-const sdk = await createAgentSdk({
-  provider: 'openai',
-  baseURL: 'https://api.deepseek.com',
-  model: 'deepseek-chat',
+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 sdk.run('简要介绍一下你自己。');
-  console.log(result.text);
+  const result = await runtime.run(agent, '什么是 CAS？');
+  console.log(result.output, result.usage.totalTokens);
 } finally {
-  await sdk.close();
+  await runtime.close();
 }
 ```
 
+0.x 应用可继续从 package root 或 `/compat` 导入 `createAgentSdk`。新应用应使用上述职责 subpath；迁移步骤见 [1.0 迁移指南](./docs/zh/09-sdk-v2-migration-guide.md)。
+
 运行仓库示例：
 
 ```bash
 npm run example:actoviq-quickstart
 npm run example:actoviq-agent-helpers
+npm run example:profiles
 ```
 
 ## CLI REPL
@@ -108,7 +128,7 @@ npx actoviq-tui [工作目录] [选项]
 #   --continue                 继续最近更新的会话
 ```
 
-特性与英文 README 一致，包括上下文管理、bridge config、计划模式、hooks、MCP、诊断等。
+特性与英文 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 的协议与版本。
 
 ## 桌面 GUI (`actoviq-gui`)
 
@@ -116,6 +136,14 @@ npx actoviq-tui [工作目录] [选项]
 npx actoviq-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`，也可切换到受保护的工作区文件 `.actoviq/issues.json`。
+- Settings → General 可将完整数据根目录迁移到空目录：复制并校验数据、写入 bootstrap 指针、重建 SDK/session store，并保留旧目录供手动清理。
+
+数据根目录解析优先级为：显式 SDK `homeDir` → `ACTOVIQ_HOME` → `~/.actoviq/data-root.json` → `~/.actoviq`。
+
 ## 开发者笔记
 
 - **启动 CLI/GUI 前构建：** `npm run build`（clean + `tsc`）。仅类型检查用 `npm run typecheck`；运行测试套件用 `npm test -- --run`。
@@ -133,6 +161,16 @@ npx actoviq-gui [工作目录] [选项]
 - [examples/actoviq-quickstart.ts](./examples/actoviq-quickstart.ts)
 - [examples/actoviq-workflow.ts](./examples/actoviq-workflow.ts)
 - [examples/actoviq-agent-helpers.ts](./examples/actoviq-agent-helpers.ts)
+- [examples/profiles/all-profiles.ts](./examples/profiles/all-profiles.ts)
+
+架构与运维文档：
+
+- [架构审计与实施规划](./docs/zh/08-sdk-architecture-audit-and-optimization-plan.md)
+- [1.0 迁移指南](./docs/zh/09-sdk-v2-migration-guide.md)
+- [支持、安全、SemVer 与 failure model](./docs/zh/10-support-security-semver-and-failure-model.md)
+- [JSON v1 → SQLite 迁移 Runbook](./docs/zh/11-json-v1-to-sqlite-migration-runbook.md)
+- [1.0 实施与端到端验收报告](./docs/zh/12-sdk-1.0-implementation-and-verification-report.md)
+- [安全报告政策](./SECURITY.md)
 
 ## 参与贡献
 

package/README.md

@@ -9,29 +9,41 @@
 
 Documentation site: https://deconbear.github.io/actoviq-agent-sdk/
 
-**Actoviq** is an agent team platform — a TypeScript framework for composing multiple AI agents, runtimes, and providers into collaborative multi-agent systems. It grew out of a programmable agent SDK but now targets the **multi-agent, multi-runtime state management** and **model team collaboration** space: coordinating specialized models, routing turns across providers, and orchestrating agent swarms with shared context.
+**Actoviq** (`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**.
+
+> **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`.
 
 Inspired by Claude Code, Codex, Deepagents, and the broader agent ecosystem. Actoviq 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 let you pre-configure multiple backends (anthropic / openai / any-compatible) with apiKey + baseURL + model, switch by name mid-session, and the conversation context survives the switch (same session object, same transcript).
+- **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). Centralized runtime (`src/team/teamRuntime.ts`) per stable member identity, streamed `TeamEvent`s, per-member provider config, `$ENV_VAR` apiKey resolution, global AgentPool.
+- **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 `~/.actoviq/routers/`.
-- **Dynamic Workflows** — JS script-based multi-agent orchestration: `agent()`/`parallel()`/`pipeline()` primitives, sandboxed runtime, schema enforcement.
-- **Bridge (named connection configs)** — in-process runtime switching: pre-configure `anthropic`/`openai` backends with name + apiKey + baseURL + model, switch by name mid-session, multi-turn context survives (same session). `/bridge config` single-page editor; `/bridge` lists saved configs; per-config usage tracking in `/cost`.
-- **Desktop GUI (`actoviq-gui`)** — Electron chat UI: streamed transcript, conversation history, command palette, settings, per-tool permission prompts. Security-hardened.
+- **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 (`actoviq-gui`)** — Electron chat UI: streamed transcript, conversation history, command palette, settings, per-tool permission prompts. Security-hardened. The visual **Agent graph** orchestration UI is shipping in-progress and continues to be iterated (not a stable product surface yet).
 - **TUI (`actoviq-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; user-configurable `PreToolUse`/`PostToolUse`/`SessionStart` hooks from `settings.json`.
 - **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.
@@ -41,6 +53,10 @@ Inspired by Claude Code, Codex, Deepagents, and the broader agent ecosystem. Act
 
 ## 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.
+
 ```bash
 npm install actoviq-agent-sdk zod
 ```
@@ -53,36 +69,41 @@ For local examples, place your config at:
 
 You can also preload a custom JSON file with `loadJsonConfigFile(...)`.
 
-## Quick Start
+## Quick Start (1.0 runtime)
 
 ```ts
-import { createAgentSdk, loadDefaultActoviqSettings } from 'actoviq-agent-sdk';
-
-await loadDefaultActoviqSettings();
-
-// Default: Anthropic protocol
-const sdk = await createAgentSdk();
-
-// Or use OpenAI / OpenAI-compatible APIs (DeepSeek, vLLM, etc.)
-const sdk = await createAgentSdk({
-  provider: 'openai',
-  baseURL: 'https://api.deepseek.com',
-  model: 'deepseek-chat',
+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 sdk.run('Introduce yourself in one short sentence.');
-  console.log(result.text);
+  const result = await runtime.run(agent, 'What is compare-and-swap?');
+  console.log(result.output, result.usage.totalTokens);
 } finally {
-  await sdk.close();
+  await runtime.close();
 }
 ```
 
+Existing 0.x applications may keep importing `createAgentSdk` from the package root or `/compat`. See the [1.0 migration guide](./docs/zh/09-sdk-v2-migration-guide.md); new applications should use the responsibility subpaths above.
+
 Run the repository examples with:
 
 ```bash
 npm run example:actoviq-quickstart
 npm run example:actoviq-agent-helpers
+npm run example:profiles
 ```
 
 ## CLI REPL
@@ -127,9 +148,9 @@ Features:
 - **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); `PreToolUse`/`PostToolUse`/`SessionStart` hooks from settings.json; `/hooks` lists them.
-- **Bridge configs** — `/bridge config` manages named connection profiles (name + runtime + apiKey + baseURL + model); `/bridge` lists them; selecting one switches the active runtime in-process. Per-config usage in `/cost` and `/usage`.
+- **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 and reactively recovers when a provider rejects an oversized prompt; compactions surface as `∿ context compacted` notices.
+- **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 `~/.actoviq/mcp.json`.
 - **Image attachments** — `@<path>.png` tokens expand into image content blocks (in-process, read as base64).
 
@@ -161,9 +182,15 @@ It opens an Electron window backed by a localhost-only HTTP server. Features:
 - **Conversation history on resume** — opening or switching a chat replays its stored messages
 - **Command palette + 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 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 Actoviq 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.
 
 **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`.
 
+Actoviq resolves its data root in this order: an explicit SDK `homeDir`, `ACTOVIQ_HOME`, `~/.actoviq/data-root.json`, then `~/.actoviq`. Project issues default to `<data-root>/projects/<workspace-key>/issues.json`; a project can instead use the protected workspace file `.actoviq/issues.json`.
+
 > `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:** `ACTOVIQ_CLAUDE_PATH`, `ACTOVIQ_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`.
@@ -187,6 +214,16 @@ Start with these examples:
 - [examples/actoviq-quickstart.ts](./examples/actoviq-quickstart.ts)
 - [examples/actoviq-workflow.ts](./examples/actoviq-workflow.ts)
 - [examples/actoviq-agent-helpers.ts](./examples/actoviq-agent-helpers.ts)
+- [examples/profiles/all-profiles.ts](./examples/profiles/all-profiles.ts)
+
+Architecture and operations:
+
+- [Architecture audit and implementation plan](./docs/zh/08-sdk-architecture-audit-and-optimization-plan.md)
+- [1.0 migration guide](./docs/zh/09-sdk-v2-migration-guide.md)
+- [Support, security, SemVer, and failure model](./docs/zh/10-support-security-semver-and-failure-model.md)
+- [JSON v1 to SQLite migration runbook](./docs/zh/11-json-v1-to-sqlite-migration-runbook.md)
+- [1.0 implementation and verification report](./docs/zh/12-sdk-1.0-implementation-and-verification-report.md)
+- [Security policy](./SECURITY.md)
 
 ## Contributing
 

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest Actoviq Agent SDK 1.x minor release. The legacy root compatibility façade remains supported throughout 1.x. Node.js 22.5+ and Node.js 24 are the supported runtime lines.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use the repository's [private vulnerability reporting form](https://github.com/DeconBear/actoviq-agent-sdk/security/advisories/new). Include:
+
+- affected version/commit, Node version, and operating system;
+- the smallest reproducible scenario and required configuration;
+- security boundary crossed and likely impact;
+- whether credentials, tenant data, workspace files, or side effects are involved;
+- any known workaround or evidence that exploitation is active.
+
+Avoid including real credentials or private user data. If private reporting is unavailable, open a public issue containing no exploit details and ask a maintainer to establish a private channel.
+
+The maintainers will acknowledge receipt, validate severity, coordinate remediation and disclosure, and publish an advisory when appropriate. Response targets and the full threat/failure policy are documented in [docs/zh/10-support-security-semver-and-failure-model.md](docs/zh/10-support-security-semver-and-failure-model.md).
+
+## Security boundaries
+
+- `LocalIsolatedProcessWorkflowExecutor` reduces ambient access but is not an adversarial multi-tenant sandbox. Use a container or remote sandbox executor for untrusted workloads.
+- A timeout or transport error does not prove that a remote side effect did not occur. Reconcile `started` or `unknown` operations before retrying.
+- Provider raw responses and legacy unknown blocks may contain sensitive data. They are opt-in or retained for audit and are not replayed across providers by default.
+- Hosts remain responsible for provider credentials, exporter retention, tool permission policy, tenant identity, and workspace authorization.

package/bin/actoviq-gui.js

@@ -1,15 +1,40 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
-const electron = require('electron');
+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));
+
+function resolveElectronExecutable() {
+  const electronExe = require('electron');
+  if (process.platform === 'win32') {
+    const brandedLauncher = join(dirname(electronExe), 'Actoviq.exe');
+    if (!existsSync(brandedLauncher)) {
+      const prep = spawnSync(process.execPath, [prepareLauncher], { stdio: 'inherit' });
+      if (prep.status !== 0) {
+        process.stderr.write(
+          'Actoviq: branded launcher unavailable; taskbar may show the Electron icon.\n',
+        );
+      }
+    }
+    if (existsSync(brandedLauncher)) return brandedLauncher;
+  }
+  return electronExe;
+}
+
+const electron = resolveElectronExecutable();
 
 const child = spawn(electron, [main, ...process.argv.slice(2)], {
   stdio: 'inherit',
-  env: process.env,
+  env: {
+    ...process.env,
+    ACTOVIQ_GUI_ROOT: rootDir,
+  },
   windowsHide: false,
 });