stable-harness 0.0.7 → 0.0.9

package/README.md

@@ -206,6 +206,16 @@ This is constrained repair, not silent magic:
 - LangGraph-compatible facade: [docs/protocols/langgraph-compatible.md](docs/protocols/langgraph-compatible.md)
 - HTTP runtime protocol: [docs/protocols/http-runtime.md](docs/protocols/http-runtime.md)
 
+## Documentation
+
+- [Documentation index](docs/guides/index.md)
+- [Getting started](docs/guides/getting-started.md)
+- [Workspace authoring](docs/guides/workspace-authoring.md)
+- [Integration guide](docs/guides/integration-guide.md)
+- [Operator runbook](docs/guides/operator-runbook.md)
+- [Adoption playbook](docs/product/adoption-playbook.md)
+- [Market positioning](docs/product/market-positioning.md)
+
 ## Product Boundary
 
 Read these before adding public runtime behavior:

package/docs/0.1.0-p0-runtime-control-plane-plan.zh.md

@@ -0,0 +1,171 @@
+# stable-harness P0 Runtime Control Plane Plan
+
+## Goal
+
+`stable-harness` must become the product runtime and operator control plane for
+agent workspaces. It must not recreate upstream agent execution semantics.
+
+This plan closes the highest-priority gaps against `agent-harness` by adding
+typed stable runtime capabilities that are independently pluggable, testable,
+and replaceable.
+
+## Non-Goals
+
+- Do not copy `agent-harness` internal module layout.
+- Do not add EasyNet-specific routing, prompt, ticker, news, Kubernetes, QA, or
+  release heuristics to core runtime.
+- Do not parse TODO text to create tool calls.
+- Do not recreate DeepAgents planning, delegation, virtual filesystem, or
+  upstream tool-call semantics.
+- Do not make compatibility code the native design target.
+
+## Capability Classification
+
+Useful `agent-harness` behavior must be reclassified before implementation:
+
+- Upstream execution semantics: expose through backend adapter passthrough.
+- Runtime/control-plane semantics: implement as stable typed capability.
+- Downstream application logic: keep in workspace config, tools, or prompts.
+- Historical workaround: keep in explicit compat path or delete.
+
+## Milestone P0-1: Durable Runtime Stores
+
+### Scope
+
+Add the minimal stable persistence boundary for runtime records:
+
+- `RuntimeStore` interface.
+- In-memory implementation.
+- JSON file implementation for local durable development.
+- Runtime integration through dependency injection.
+- Store-backed run, event, artifact, and state updates.
+
+### Acceptance
+
+- Existing runtime behavior is unchanged when no store is provided.
+- A file-backed runtime can survive runtime recreation.
+- Events are appended through the store.
+- Artifacts remain request-scoped.
+- No source file exceeds project size limits.
+
+### Tests
+
+- Unit tests for in-memory store.
+- Unit tests for JSON file store reload.
+- Runtime request test with injected file store.
+- `npm run check`.
+- `npm run check:rules`.
+- `npm test`.
+
+## Milestone P0-2: Operator Inspection Contract
+
+### Scope
+
+Extend native inspection without copying legacy structures:
+
+- Session summary.
+- Request summary.
+- Request detail.
+- Runtime snapshot for workspace/agent/model/tool binding.
+- Event timeline projection.
+- Artifact listing projection.
+
+### Acceptance
+
+- Operators can inspect a request without reading raw run internals.
+- Protocol client can fetch request/session projections.
+- Existing `inspect()` remains backward-compatible.
+
+### Tests
+
+- Runtime inspection unit tests.
+- HTTP/in-process protocol tests.
+- Existing runtime and trace tests.
+
+## Milestone P0-3: Queue and Recovery Core
+
+### Scope
+
+Add request lifecycle primitives:
+
+- Durable queue record.
+- Priority and queue key.
+- Claim/lease/heartbeat.
+- Cancel intent.
+- Stuck request detection.
+- Recovery intent record.
+
+### Acceptance
+
+- Queue logic is typed and domain-neutral.
+- Recovery decisions come from runtime state, not prompt text.
+- Running requests can be inspected and reconciled after restart.
+
+### Tests
+
+- Queue lease and expiration tests.
+- Heartbeat/stuck detection tests.
+- Cancel intent tests.
+- Recovery intent persistence tests.
+
+## Milestone P0-4: Artifacts, Evidence, and Replay Bundles
+
+### Scope
+
+Make evidence first-class:
+
+- Durable artifact content store.
+- Artifact listing and read APIs.
+- Evaluation bundle export.
+- Replay bundle validation.
+- Hash/metadata checks for stored artifacts.
+
+### Acceptance
+
+- Request evidence can be exported from runtime records alone.
+- Replay bundle contains runs, events, artifacts, and runtime metadata.
+- Artifact APIs are independent from backend adapters.
+
+### Tests
+
+- Artifact create/list/read tests.
+- Evaluation bundle export tests.
+- Replay validation tests.
+- Existing EasyNet native stable tests.
+
+## Milestone P0-5: Native NL Migration Gate
+
+### Scope
+
+Move natural-language execution toward native stable runtime:
+
+- Keep DeepAgents as upstream execution source of truth.
+- Preserve trace/evidence visibility through stable events.
+- Keep compatibility facade explicit.
+- Remove native dependence on compatibility runner when upstream behavior is
+  stable enough.
+
+### Acceptance
+
+- EasyNet typed native gates pass.
+- EasyNet natural-language matrix has a native stable path or documented
+  upstream blocker.
+- No downstream-specific runtime heuristics are added.
+
+### Tests
+
+- Stable native CLI tests.
+- EasyNet native stable tests.
+- EasyNet full matrix as migration gate.
+
+## Execution Rules
+
+Each milestone must follow this loop:
+
+1. Inspect existing code and tests.
+2. Implement the smallest typed stable capability.
+3. Add focused tests.
+4. Run `npm run check`.
+5. Run `npm run check:rules`.
+6. Run `npm test`.
+7. Only then continue to the next milestone.

package/docs/0.1.0-retry-policy.zh.md

@@ -0,0 +1,87 @@
+# Retry Policy
+
+`stable-harness` 的 retry 只覆盖生产稳定性，不接管 DeepAgents 的执行语义。
+
+## 边界
+
+| 场景 | 归属 | 行为 |
+| --- | --- | --- |
+| 模型 API timeout、rate limit、5xx | runtime policy | 通过 LangChain `modelRetryMiddleware` 重试同一次 model call |
+| 工具后端 timeout、临时网络失败 | runtime policy | 通过 LangChain `toolRetryMiddleware` 重试同一次 tool call |
+| tool 参数类型错、枚举错、语义错 | tool gateway guard | 返回 `ToolMessage(status="error")`，让模型下一轮自我修复 |
+| 模型看到 ToolMessage 后是否重新调用 tool | DeepAgents/LangChain agent loop | 不做确定性保证，需要 benchmark |
+
+## YAML
+
+```yaml
+apiVersion: stable-harness.dev/v1
+kind: Runtime
+metadata:
+  name: production
+spec:
+  routing:
+    defaultAgentId: orchestra
+  retry:
+    model:
+      enabled: true
+      maxRetries: 3
+      initialDelayMs: 1000
+      backoffFactor: 2
+      jitter: true
+      onFailure: continue
+    tools:
+      enabled: true
+      tools:
+        - web_search
+        - fetch_url
+      retryOn:
+        - timeout
+        - network
+        - rateLimit
+        - serverError
+      maxRetries: 2
+      initialDelayMs: 500
+      backoffFactor: 2
+      jitter: true
+      onFailure: continue
+```
+
+`retryOn` 是稳定 runtime 的字符串白名单，不接收 JavaScript function。默认等价于 `timeout/network/rateLimit/serverError`。`tools` 建议只配置会遇到临时失败的外部 I/O 工具。不要把 schema/参数修复放到 retry policy 里；参数修复由 `ToolArgumentGuard` 生成可读错误并交回模型。
+
+## Sequence
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Runtime as stable-harness runtime
+  participant Adapter as DeepAgents adapter
+  participant LC as LangChain retry middleware
+  participant DA as DeepAgents agent loop
+  participant Tool as Tool gateway
+  participant Model as LLM
+
+  User->>Runtime: request
+  Runtime->>Adapter: run with retry policy
+  Adapter->>LC: install model/tool retry middleware
+  Adapter->>DA: createDeepAgent(params)
+  DA->>Model: model call
+  alt transient model failure
+    LC->>Model: retry model call
+  end
+  Model->>DA: tool call
+  DA->>Tool: invoke
+  alt transient tool failure
+    LC->>Tool: retry same tool call
+  else argument validation failure
+    Tool-->>DA: ToolMessage(status="error")
+    DA->>Model: feed error observation
+    Model->>DA: maybe corrected tool call
+  end
+  DA-->>Runtime: final result
+```
+
+## 当前测试
+
+- `DeepAgents retry policy is translated to upstream middleware`：确认 `Runtime.spec.retry` 被 adapter 翻译成 LangChain 官方 middleware。
+- `DeepAgents tool retry policy retries transient gateway failures`：真实 DeepAgents + fake tool-calling model，第一次 gateway tool 抛临时错误，第二次重试成功。
+- `npm run benchmark:retry-policy`：对比 retry policy on/off 的成功率、attempts 和耗时。

package/docs/0.1.0-stable-runtime-development-roadmap.zh.md

@@ -0,0 +1,393 @@
+# Stable Harness Runtime 改造路线图
+
+本文档定义 `stable-harness` 后续改造的逐步开发清单。目标是把 `stable-harness` 建成干净的 runtime / operator control plane，而不是复刻 `agent-harness` 或把 EasyNet 业务规则写入 runtime。
+
+## 硬性执行规则
+
+- 每完成一个开发步骤，必须运行 EasyNet 完整真实验证。
+- EasyNet 验证必须连接真实模型，运行真实 workspace、真实 tools、真实数据路径。
+- 每完成一个开发步骤，必须在 `docs/` 下新增一份中文报告。
+- 每份步骤报告必须包含：
+  - 改造目标
+  - 代码改动范围
+  - runtime boundary 判断
+  - EasyNet 真实测试命令和结果
+  - 失败、重试、风险和残留问题
+  - sequence diagram
+  - flow chart
+- 不允许为了通过 EasyNet case 把 EasyNet 业务规则写入 `stable-harness` runtime。
+- `runtime/compat` 和 `compat/*` 只能作为迁移路径，不能承载 native runtime 新能力。
+
+## 每步统一验证门槛
+
+在每个步骤结束前，至少运行：
+
+```bash
+npm run check
+npm run check:rules
+npm test
+```
+
+在 EasyNet 中运行：
+
+```bash
+npm test
+npm run test:botbotgo:full
+```
+
+必要时增加定向过滤重试：
+
+```bash
+EASYNET_FULL_MATRIX_FILTER=<case_id> npm run test:botbotgo:full
+```
+
+测试记录必须说明：
+
+- 使用的 workspace：`/Users/boqiangliang/project/easynet`
+- 使用的 runtime：`stable-harness -> file:../stable-harness`
+- 是否连接真实模型
+- 是否执行真实工具
+- 是否存在未跟踪文件、外部服务失败、模型波动或 Kubernetes 环境限制
+
+## 开发步骤清单
+
+### 1. RunStore / EventStore / ArtifactStore
+
+目标：
+
+- 把当前 core runtime 内部的 in-memory `Map` 拆成可替换 store interface。
+- runtime 只依赖 store contract，不直接绑定内存实现。
+
+交付：
+
+- `RunStore`
+- `EventStore`
+- `ArtifactStore`
+- in-memory store implementation
+- core runtime 使用 store
+- store-focused tests
+
+禁止：
+
+- 不引入 SQLite 作为第一步默认实现。
+- 不复制 `agent-harness` 的 persistence 结构。
+
+验收：
+
+- runtime inspection 仍可返回 run/event/artifact。
+- EasyNet 完整真实测试通过。
+
+### 2. Runtime Event Model 标准化
+
+目标：
+
+- 把工具事件、delegation 事件、approval 事件、artifact 事件统一成稳定 event envelope。
+- CLI 和 protocols 消费统一事件，不直接消费 compat runner 的临时 delta。
+
+交付：
+
+- `RuntimeEventEnvelope`
+- typed event payloads
+- event projection helpers
+- event store append/read tests
+
+禁止：
+
+- 不解析 TODO 文本生成事件。
+- 不写 EasyNet specialist 事件特例。
+
+验收：
+
+- EasyNet CLI trace 仍显示 delegation、tool start/result、TODO trace。
+- 完整真实测试通过。
+
+### 3. ToolGateway 接入 Runtime
+
+目标：
+
+- 把 native tool execution 从直接调用迁到 `@stable-harness/tool-gateway`。
+- compat runner 只在迁移阶段保留 direct invocation。
+
+交付：
+
+- runtime-level tool gateway injection
+- tool invocation context
+- tool start/result/error events
+- schema validation hook
+- focused gateway tests
+
+禁止：
+
+- 不在 gateway 内做自然语言工具选择。
+- 不把 finance/k8s/git/qa 等工具规则写入 gateway。
+
+验收：
+
+- EasyNet 所有 specialist tools 仍通过真实工具执行。
+- 完整真实测试通过。
+
+### 4. Governance / Approval Queue
+
+目标：
+
+- 把 approval、sandbox、resource limit 变成独立 runtime capability。
+- 工具执行前可基于 typed policy 进入 approval queue。
+
+交付：
+
+- `ApprovalQueue`
+- `GovernanceDecision`
+- policy evaluation events
+- allow/deny/resume lifecycle
+- tests for allow / require approval / deny
+
+禁止：
+
+- 不用 prompt 文本判断是否需要 approval。
+- 不让 adapter 自己实现 approval lifecycle。
+
+验收：
+
+- EasyNet 默认无 approval 阻塞，完整真实测试通过。
+- 新 approval tests 证明 capability 可关闭、可替换。
+
+### 5. DeepAgents Native Path 对齐
+
+目标：
+
+- 让 native DeepAgents adapter 成为默认设计目标。
+- `createDeepAgent` 参数尽量 passthrough upstream primitives。
+
+交付：
+
+- model config passthrough
+- tools passthrough or gateway bridge
+- subagents passthrough
+- memory / skills passthrough
+- upstream event normalization
+- DeepAgents capability audit report
+
+禁止：
+
+- 不重建 DeepAgents middleware stack。
+- 不实现第二套 subagent planning language。
+- 不 replay upstream custom tool calls。
+
+验收：
+
+- native path tests 通过。
+- EasyNet migration path 仍完整通过。
+
+### 6. Compat Runner 收缩
+
+目标：
+
+- 把 `runtime/compat` 保持为 migration-only。
+- 能迁出的能力迁到 native capability 或 upstream passthrough。
+
+交付：
+
+- compat usage inventory
+- migration blockers list
+- compat-only behavior tags
+- removal plan
+
+禁止：
+
+- 不在 compat runner 中新增 native runtime 功能。
+- 不把 compat API 扩展为产品 API。
+
+验收：
+
+- EasyNet 完整真实测试通过。
+- docs 中明确每个剩余 compat 行为的归宿。
+
+### 7. Protocol Surface
+
+目标：
+
+- HTTP / in-process / future ACP / A2A / AG-UI 都调用同一 runtime contract。
+
+交付：
+
+- request API
+- event stream API
+- run inspection API
+- approval API
+- artifact API
+- protocol tests
+
+禁止：
+
+- protocol 层不执行 agent。
+- protocol 层不包含 backend 或 workspace 业务逻辑。
+
+验收：
+
+- protocol tests 通过。
+- EasyNet 完整真实测试通过。
+
+### 8. Replay / Evaluation
+
+目标：
+
+- 基于 runtime events 和 artifacts 做 replay / eval，而不是重跑 prompt heuristics。
+
+交付：
+
+- replay manifest
+- evaluation fixture runner
+- trace export
+- artifact reference validation
+
+禁止：
+
+- 不从自然语言输出反推工具调用。
+- 不把某个 EasyNet case 的断言写成 runtime 规则。
+
+验收：
+
+- replay tests 通过。
+- EasyNet 完整真实测试通过。
+
+### 9. Memory Lifecycle
+
+目标：
+
+- runtime 管 memory lifecycle，不替代 backend-native memory semantics。
+
+交付：
+
+- memory namespace contract
+- recall coordination events
+- import/export hooks
+- compaction hooks
+- tests with in-memory store
+
+禁止：
+
+- 不伪造统一记忆语义覆盖 DeepAgents native memory。
+- 不在 memory capability 里做业务 routing。
+
+验收：
+
+- memory tests 通过。
+- EasyNet 完整真实测试通过。
+
+### 10. Native Stable Package Migration
+
+目标：
+
+- EasyNet 从 explicit compat facade 迁到 stable native API。
+
+交付：
+
+- EasyNet dependency migration plan
+- native API usage examples
+- compat fallback plan
+- final migration test report
+
+禁止：
+
+- 不为了迁移削弱 EasyNet contract tests。
+- 不隐藏 JSON contract / specialist ownership / tool boundary。
+
+验收：
+
+- EasyNet `npm test` 通过。
+- EasyNet `npm run test:botbotgo:full` 通过。
+- EasyNet 不再依赖 compat-only API，或明确列出最后 blockers。
+
+## 总体 Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant Dev as Developer
+  participant SH as stable-harness
+  participant EN as EasyNet
+  participant Model as Real Model
+  participant Tools as Real Tools/Data
+  participant Docs as docs/
+
+  Dev->>SH: Implement one runtime capability
+  SH->>SH: npm run check
+  SH->>SH: npm run check:rules
+  SH->>SH: npm test
+  Dev->>EN: npm test
+  EN->>Model: Real model calls
+  EN->>Tools: Real tool/data execution
+  Dev->>EN: npm run test:botbotgo:full
+  EN->>Model: Full matrix real model calls
+  EN->>Tools: Full matrix real tools/data
+  Dev->>Docs: Write Chinese step report
+  Docs->>Docs: Include sequence diagram and flow chart
+  Dev->>SH: Commit only after all gates pass
+```
+
+## 总体 Flow Chart
+
+```mermaid
+flowchart TD
+  A["Pick next runtime capability"] --> B["Classify boundary"]
+  B --> C{"Who owns the behavior?"}
+  C -->|Upstream framework| D["Adapter passthrough"]
+  C -->|Runtime/control plane| E["Typed stable capability"]
+  C -->|Downstream app| F["Workspace config/tool/test"]
+  C -->|Historical workaround| G["Compat only or delete"]
+  D --> H["Implement narrow change"]
+  E --> H
+  F --> H
+  G --> H
+  H --> I["Run stable-harness checks/tests"]
+  I --> J["Run EasyNet npm test"]
+  J --> K["Run EasyNet full botbotgo matrix"]
+  K --> L{"All real gates pass?"}
+  L -->|No| M["Fix at correct boundary"]
+  M --> B
+  L -->|Yes| N["Write Chinese docs report"]
+  N --> O["Commit and push"]
+```
+
+## 每步报告模板
+
+每个步骤完成后，在 `docs/` 新增：
+
+```text
+0.1.0-step-<number>-<short-name>.zh.md
+```
+
+模板：
+
+```markdown
+# Step <number>: <name>
+
+## 目标
+
+## 改动范围
+
+## Runtime Boundary 判断
+
+## 实现细节
+
+## EasyNet 真实测试
+
+### 命令
+
+### 结果
+
+### 模型和数据说明
+
+## 风险和残留问题
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+```
+
+## Flow Chart
+
+```mermaid
+flowchart TD
+```
+```

package/docs/0.1.0-tool-guard-benchmark.zh.md

@@ -0,0 +1,42 @@
+# 0.1.0 Tool Guard Benchmark
+
+生成时间：2026-05-07T00:40:17.180Z
+
+## 测试设置
+
+- 远端 Ollama：`https://ollama-rtx-4070.easynet.world`
+- 每个模型自然用例轮数：`10`，总自然用例数为 `50`
+- 注入错误矩阵覆盖：未知工具、错误工具名、缺必填、类型错、enum 错、extra arg、绝对路径、语义 ticker 错、不可解析参数
+- 该 benchmark 是产品级 fault-injection 与本地 BFCL-style 子集，不是 BFCL 官方成绩。
+
+## 自然工具调用
+
+| 模型 | Repair | 自然用例数 | Exact | Baseline Accepted | Bad Exec 无 Guard | Bad Exec 有 Guard | Final Accepted |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| qwen3:0.6b | off | 50 | 80% | 80% | 20% | 0% | 80% |
+| qwen3:0.6b | on | 50 | 80% | 80% | 20% | 0% | 80% |
+| qwen3.5:0.8b | off | 50 | 100% | 100% | 0% | 0% | 100% |
+| qwen3.5:0.8b | on | 50 | 100% | 100% | 0% | 0% | 100% |
+| qwen3.5:2b | off | 50 | 100% | 100% | 0% | 0% | 100% |
+| qwen3.5:2b | on | 50 | 100% | 100% | 0% | 0% | 100% |
+| granite4.1:3b | off | 50 | 100% | 100% | 0% | 0% | 100% |
+| granite4.1:3b | on | 50 | 100% | 100% | 0% | 0% | 100% |
+| qwen3.5:4b | off | 50 | 100% | 100% | 0% | 0% | 100% |
+| qwen3.5:4b | on | 50 | 100% | 100% | 0% | 0% | 100% |
+
+## 注入错误矩阵
+
+| 模型 | 注入错误 Guard 拦截 | 注入错误 Repair 成功 | 覆盖错误类型 |
+| --- | --- | --- | --- |
+| qwen3:0.6b | 100% | 66.7% | name, schema, type, semantic |
+| qwen3.5:0.8b | 100% | 66.7% | name, schema, type, semantic |
+| qwen3.5:2b | 100% | 100% | name, schema, type, semantic |
+| granite4.1:3b | 100% | 100% | name, schema, type, semantic |
+| qwen3.5:4b | 100% | 100% | name, schema, type, semantic |
+
+## 结论
+
+- Guard 的核心收益是阻止错误 tool call 进入真实执行层；在本轮测试里，所有注入错误都被 100% 拦截。
+- `qwen3:0.6b` 的自然输出存在 20% 原本会错误执行的 registered tool call，开启 Guard 后 bad execution 从 20% 降到 0%。
+- `qwen3.5:2b`、`granite4.1:3b`、`qwen3.5:4b` 对注入错误的一轮 repair 成功率为 100%。这个结论只适用于本 benchmark 的注入错误矩阵。
+- `qwen3.5:0.8b` 及以上在本轮自然用例里 baseline 已经是 100%，所以自然场景没有可观察的 accepted-rate uplift。