@ran-sh/dsh-crew 0.3.8 → 0.4.0

package/README.md

@@ -43,10 +43,25 @@ Use ds-reviewer to review the result.
 
 Legacy `ds-flash` and `ds-pro` aliases remain compatible.
 
+## Results and reviews
+
+Crew returns a compact, machine-readable Result Contract by default: status,
+tests, changed files, review verdict, model-selection trace, artifact references,
+and canonical lifecycle events. Raw agent prose and full patches are not copied
+through every hand-off. An automatic Reviewer receives a bounded evidence
+capsule and inspects the isolated workspace directly.
+
+MCP callers can request `detail: "full"` on `dsh_run_worker` or
+`dsh_worker_result` for explicit debugging and recovery. Contract details are in
+[Job contracts and information flow](./docs/job-contracts.md).
+
 ## Common commands
 
 ```bash
 dsh-crew status       # installation and integration health
+dsh-crew inspect      # machine-readable capabilities and readiness
+dsh-crew jobs list    # machine-readable jobs
+dsh-crew jobs watch <job-id> --after 0
 dsh-crew update       # update and repair enabled integrations
 dsh-crew integrate    # connect official 3080 UI to isolated 3210 Crew
 dsh-crew detach       # remove only the 3080 bridge
@@ -87,7 +102,8 @@ pnpm run build:client
 node scripts/setup.mjs uninstall
 ```
 
-More detail: [Changelog](./CHANGELOG.md) · [Readiness matrix](./docs/readiness-matrix.md)
+More detail: [Changelog](./CHANGELOG.md) · [Readiness matrix](./docs/readiness-matrix.md) · [Job contracts](./docs/job-contracts.md)
+· [GPT-first extension](./docs/gpt-relay-extension.md)
 
 ## License
 

package/README.zh.md

@@ -43,10 +43,24 @@ npx -y @deepseek-ai/dsh web --host 127.0.0.1 --port 3080
 
 旧的 `ds-flash`、`ds-pro` 别名仍可使用。
 
+## 结果与复审信息流
+
+Crew 默认返回紧凑、机器可读的 Result Contract：状态、测试、改动文件、
+Reviewer 结论、模型选择轨迹、候选引用和规范化生命周期事件。Worker 的
+整段原始回答和完整 patch 不会在每次交接时重复传递；自动 Reviewer 只接收
+有大小上限的证据胶囊，并直接检查隔离工作区。
+
+MCP 调用方如需排障或恢复，可以在 `dsh_run_worker` 或
+`dsh_worker_result` 中显式传入 `detail: "full"`。完整契约见
+[任务契约与信息流](./docs/job-contracts.md)。
+
 ## 常用命令
 
 ```bash
 dsh-crew status       # 查看安装与集成状态
+dsh-crew inspect      # 输出机器可读的能力与就绪度
+dsh-crew jobs list    # 输出机器可读的任务列表
+dsh-crew jobs watch <job-id> --after 0
 dsh-crew update       # 更新并自动修复已启用的集成
 dsh-crew integrate    # 将官方 3080 界面连接到隔离的 3210 Crew
 dsh-crew detach       # 只移除 3080 桥接
@@ -87,7 +101,8 @@ pnpm run build:client
 node scripts/setup.mjs uninstall
 ```
 
-更多资料：[Changelog](./CHANGELOG.md) · [Readiness Matrix](./docs/readiness-matrix.md)
+更多资料：[Changelog](./CHANGELOG.md) · [Readiness Matrix](./docs/readiness-matrix.md) · [任务契约](./docs/job-contracts.md)
+· [GPT-first 扩展接入](./docs/gpt-relay-extension.md)
 
 ## License
 

package/docs/gpt-relay-extension.md

@@ -0,0 +1,103 @@
+# GPT-first extension integration
+
+DSH Crew is an optional DeepSeek Harness capability extension for Codex,
+Claude Code, ZCode, or another top-level executor. It is not itself a top-level
+executor and does not choose the next project-wide step.
+
+## Discover
+
+With the isolated Hub running on 3210:
+
+```bash
+dsh-crew inspect
+```
+
+The same versioned JSON is available at:
+
+```text
+GET http://127.0.0.1:3210/_dsh/dsh-crew/extension
+```
+
+An orchestrator should check `capabilities.deepseek.worker` or
+`capabilities.deepseek.reviewer`, then inspect `readiness.status` and its
+components. `DEGRADED` is not `READY`; a model catalog proves discoverability,
+not successful authentication or execution.
+
+## Dispatch and observe
+
+Codex and Claude normally call the six MCP tools. `dsh_run_worker` and
+`dsh_spawn_worker` accept the backward-compatible fields plus:
+
+- `job_id`: optional caller id, echoed separately from Crew's internal id.
+- `profile`: a Worker/Reviewer profile id.
+- `workspace`: per-job `repo_root`, `branch`, and `worktree` policy.
+- `constraints`: per-job timeout and fallback override.
+- `workspace_id`: a registered Workspace Context id.
+- `context_refs`: extra workspace-relative instruction references.
+
+Poll `dsh_worker_result` with `after_sequence` to receive only newer canonical
+events. HTTP consumers can use:
+
+```text
+POST /_dsh/dsh-crew/jobs
+GET /_dsh/dsh-crew/jobs/:id/contract?after=0
+GET /_dsh/dsh-crew/jobs/:id/events?after=0
+```
+
+CLI consumers use `dsh-crew jobs list|get|watch|cancel|submit`; `submit`
+accepts a versioned JSON Job Request through `--request`.
+
+The compact Contract is the automation surface. Full prose and patches require
+an explicit `detail=full` recovery/debug request.
+
+## Profiles
+
+Profiles live in `~/.config/dsh-crew/profiles.json`:
+
+```json
+{
+  "schema_version": 1,
+  "profiles": {
+    "worker-fast": {
+      "role": "worker",
+      "routing": "priority",
+      "isolation": "worktree",
+      "fallback": false,
+      "timeout_seconds": 300,
+      "review_strictness": "standard"
+    }
+  }
+}
+```
+
+The built-ins are `worker-default` and `reviewer-default`. The registry can be
+read or atomically replaced through loopback-only `GET/POST
+/_dsh/dsh-crew/profiles`. Invalid documents are rejected before replacement.
+
+## Workspace Context
+
+Workspace facts live in `~/.config/dsh-crew/workspaces.json`:
+
+```json
+{
+  "schema_version": 1,
+  "workspaces": {
+    "dsh-crew": {
+      "repo_root": "D:/work/dsh-crew",
+      "default_branch": "main",
+      "instruction_files": ["AGENTS.md"],
+      "validation_hints": ["node --test test/*.test.mjs", "pnpm run build:client"]
+    }
+  }
+}
+```
+
+Only bounded path references and hints cross the hand-off. Crew never copies
+instruction-file contents into the registry. Use loopback-only `GET/POST
+/_dsh/dsh-crew/workspaces` to read or atomically replace it.
+
+## Failure handling
+
+Every structured failure includes a `family` and `disposition`. Dispositions
+are `retry`, `fallback`, `human`, or `terminal` (`none` for success), allowing
+the GPT-first controller to decide the next step without parsing logs.

package/docs/job-contracts.md

@@ -0,0 +1,107 @@
+# Job contracts and information flow
+
+DSH Crew is a narrow bridge and scheduler. Codex or Claude owns the main task;
+Crew owns one delegated Worker/Reviewer workflow and reports auditable evidence
+back to the caller.
+
+## Information flow
+
+```text
+caller objective
+  -> Worker in isolated workspace
+  -> structured outcome + candidate reference
+  -> optional Reviewer inspects the workspace directly
+  -> compact Result Contract + canonical job events
+  -> caller
+```
+
+The Worker receives the complete delegated objective. After it finishes, Crew
+does not copy the Worker's raw prose or full patch into the Reviewer prompt.
+The Reviewer receives a bounded capsule containing the objective, reported
+changes/tests/risks, changed-file names, base revision, and candidate
+fingerprint. It opens the relevant files and runs `git diff` in the isolated
+workspace when deeper inspection is needed.
+
+The Hub keeps only the latest assistant message needed as the final Delivery
+Report. It does not retain an ever-growing list of intermediate assistant
+messages.
+
+## Canonical events
+
+Every workflow result can expose a versioned, ordered `canonical_events` list.
+Each event has `schema_version`, `event_id`, `job_id`, `sequence`, `type`, `at`,
+`role`, `attempt`, and bounded structured `data`.
+
+Supported event types (the allow-list is versioned; `approval.required` is
+reserved for a future approval broker and is not emitted by the current
+runtime):
+
+- `job.created`, `job.started`
+- `model.selected`, `model.fallback`
+- `worker.started`, `worker.completed`
+- `review.started`, `review.completed`
+- `approval.required`
+- `job.completed`, `job.failed`, `job.cancelled`
+
+Events never carry a candidate patch, raw provider payload, credential, or full
+assistant response. `event_cursor` identifies the latest event in status views.
+
+## Result Contract
+
+`dsh_run_worker` and `dsh_worker_result` default to `detail: "compact"`. Their
+`evidence` object contains:
+
+- `status`: `PASS`, `FAIL`, `PARTIAL`, or `BLOCKED`
+- structured execution/test/delivery/review summary
+- bounded model-selection trace
+- changed files, reported changes, tests, risks, and unverified checks
+- reviewer verdict and evidence when review ran
+- candidate fingerprint/base revision and workspace recovery state
+- bounded machine error code/message when execution failed
+
+Raw worker prose and candidate patch text are excluded. For an explicit debug
+or recovery operation, pass `detail: "full"`; this preserves the previous rich
+workflow view and adds the same evidence envelope.
+
+## Profiles, Workspace Context, and watch
+
+Both blocking and asynchronous MCP dispatch accept optional `job_id`, `profile`,
+`workspace`, `constraints`, `workspace_id`, and `context_refs` fields. The
+caller id is echoed as `client_job_id`; it never replaces Crew's internal id.
+Profiles control role-compatible
+routing, isolation, timeout, fallback, and review strictness. Workspace Context
+adds bounded project facts by reference; instruction file contents are opened by
+the Agent in the workspace rather than copied through the hand-off.
+
+`dsh_worker_result` accepts `after_sequence`. The response includes only newer
+`canonical_events` plus the current numeric `event_cursor`, so callers can watch
+long jobs without replaying the entire event history.
+
+The isolated Hub also exposes `/extension`, `/profiles`, `/workspaces`,
+`/jobs/:id/contract`, and `/jobs/:id/events`. All remain loopback-only.
+
+Per-job precedence is request `constraints` > Profile > session defaults.
+`workspace.branch` pins the isolated base revision; `workspace.worktree` accepts
+`auto`, `existing`, or `none`. Workspace preflight reports `READY`, `CONFLICT`,
+`READ_ONLY`, or `UNAVAILABLE` before dispatch.
+
+The CLI is a JSON projection of the same local HTTP surface:
+
+```text
+dsh-crew jobs list
+dsh-crew jobs get <job-id> --detail compact
+dsh-crew jobs watch <job-id> --after <sequence>
+dsh-crew jobs cancel <job-id>
+dsh-crew jobs submit --request job.json
+```
+
+## Compatibility boundary
+
+The internal legacy phase events remain in the explicit full view for current
+debug consumers. Canonical events and the compact Result Contract are the
+stable integration surface for new Codex, Claude, CLI, and HTTP consumers.
+
+This design borrows the useful boundary from
+[OpenMausBot](https://github.com/milind-soni/OpenMausBot)—a small provider
+contract and one normalized event stream—without adopting its desktop chat,
+bot roster, persona, connector, or general-purpose agent-platform scope.

package/docs/readiness-matrix.md

@@ -0,0 +1,73 @@
+# DSH Crew Readiness Matrix
+
+The readiness matrix is a conservative diagnostic surface for release and environment confidence. Its primary rule is simple:
+
+> Missing evidence is never PASS.
+
+The matrix is emitted by `hubStatus()` and is therefore visible inside the existing `dsh_worker_config` response under `hub_compatibility.readiness_matrix`.
+
+## Statuses
+
+- `PASS` — direct evidence confirms the row.
+- `FAIL` — a check actually ran and produced an incompatible or failed result.
+- `BLOCKED` — the check could not run because required infrastructure or authorization was unavailable.
+- `SKIP` — the row is intentionally not applicable for the active policy/path.
+- `NOT_RUN` — no trusted evidence has been supplied for the row.
+
+`BLOCKED` and `SKIP` are not failures. `NOT_RUN` is not success.
+
+## Evidence classes
+
+The matrix separates three kinds of evidence:
+
+1. `live-runtime` — facts the current process can directly observe, such as Hub reachability and protocol compatibility.
+2. `ci` — platform validation such as Linux deterministic, Windows regressions, and future macOS smoke.
+3. `real-execution` — provider/model and workflow behavior that requires a genuine DSH execution.
+
+Only live checks are populated automatically by the current runtime. CI and real-execution rows remain `NOT_RUN` until a trusted higher layer supplies explicit evidence.
+
+## Target rows
+
+- `linux_deterministic`
+- `windows_regressions`
+- `macos_smoke`
+- `hub_compatibility`
+- `provider_catalog`
+- `deepseek_flash`
+- `deepseek_pro`
+- `opencode_go_mimo_qwen`
+- `reviewer_pipeline`
+- `cancellation_timeout_escalation`
+- `standalone_official`
+
+## Provider/catalog rule
+
+The Hub client does not know the active worker provider mode, so its embedded matrix leaves `provider_catalog` as `NOT_RUN` with `PROVIDER_MODE_UNKNOWN` rather than guessing.
+
+When a higher layer knows the provider mode and has actually read the Harness catalog, it may build a more specific matrix:
+
+- DeepSeek Official strict mode: catalog row may be `SKIP` / `PROVIDER_CATALOG_NOT_REQUIRED`.
+- Follow-DSH with successful catalog read: `PASS` / `PROVIDER_CATALOG_RESOLVED`.
+- Follow-DSH with an attempted but failed catalog read: `FAIL` / `PROVIDER_CATALOG_UNAVAILABLE`.
+- Hub unavailable/incompatible before catalog access: `BLOCKED`, not `FAIL`.
+
+## Credential safety
+
+The matrix never reads or returns credential values, provider configuration payloads, quota data, pricing, cookies, tokens, or raw exception dumps. The standalone row defaults to `NOT_RUN` / `CREDENTIAL_STATUS_NOT_PROBED` unless an authorized real-environment validation explicitly reports evidence.
+
+## Trusted evidence
+
+`buildReadinessMatrix()` accepts an optional evidence map so CI/report aggregation can be added later without changing row semantics. Evidence can set only the existing status vocabulary. Invalid statuses are ignored rather than broadening the contract.
+
+An evidence record may contain:
+
+```json
+{
+  "status": "PASS",
+  "reason_code": "CI_GREEN",
+  "evidence_source": "github-actions",
+  "evidence_ref": "run-123"
+}
+```
+
+The matrix does not fetch or trust arbitrary remote data by itself. Loading and authenticating an evidence source is the responsibility of the higher layer that calls the builder.