soturail 1.0.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +60 -13
- package/dist/cli.js +6 -0
- package/dist/cli.js.map +1 -1
- package/dist/commands/agents.js +37 -7
- package/dist/commands/agents.js.map +1 -1
- package/dist/commands/feature.d.ts +2 -0
- package/dist/commands/feature.js +28 -0
- package/dist/commands/feature.js.map +1 -0
- package/dist/commands/handoff.d.ts +2 -0
- package/dist/commands/handoff.js +14 -0
- package/dist/commands/handoff.js.map +1 -0
- package/dist/commands/harness.js +20 -0
- package/dist/commands/harness.js.map +1 -1
- package/dist/commands/mcp.js +10 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/commands/report.js +14 -3
- package/dist/commands/report.js.map +1 -1
- package/dist/commands/session.d.ts +2 -0
- package/dist/commands/session.js +17 -0
- package/dist/commands/session.js.map +1 -0
- package/dist/core/agent-exporter.d.ts +39 -2
- package/dist/core/agent-exporter.js +290 -24
- package/dist/core/agent-exporter.js.map +1 -1
- package/dist/core/agent-profile.d.ts +1 -1
- package/dist/core/agent-registry.js +12 -0
- package/dist/core/agent-registry.js.map +1 -1
- package/dist/core/agent-runtime.d.ts +15 -1
- package/dist/core/agent-runtime.js +120 -14
- package/dist/core/agent-runtime.js.map +1 -1
- package/dist/core/code-health.js +3 -0
- package/dist/core/code-health.js.map +1 -1
- package/dist/core/config.d.ts +7 -0
- package/dist/core/config.js +8 -0
- package/dist/core/config.js.map +1 -1
- package/dist/core/harness-lifecycle.d.ts +63 -0
- package/dist/core/harness-lifecycle.js +397 -0
- package/dist/core/harness-lifecycle.js.map +1 -0
- package/dist/core/harness-rail.js +1 -0
- package/dist/core/harness-rail.js.map +1 -1
- package/dist/core/mcp-resources.d.ts +27 -0
- package/dist/core/mcp-resources.js +104 -1
- package/dist/core/mcp-resources.js.map +1 -1
- package/dist/core/release-preflight.js +3 -0
- package/dist/core/release-preflight.js.map +1 -1
- package/dist/core/report-rail.d.ts +1 -1
- package/dist/core/report-rail.js +33 -8
- package/dist/core/report-rail.js.map +1 -1
- package/dist/core/schema-readiness.js +12 -1
- package/dist/core/schema-readiness.js.map +1 -1
- package/dist/core/skill-schema.d.ts +2 -2
- package/dist/core/version.d.ts +1 -1
- package/dist/core/version.js +1 -1
- package/docs/agent-export-contract.md +42 -0
- package/docs/agent-governance-rail.md +89 -0
- package/docs/agent-harness-synthesis-2026.md +101 -0
- package/docs/agent-hosts.md +24 -5
- package/docs/agent-qa-rail.md +92 -0
- package/docs/agents.md +31 -12
- package/docs/assets/demos/README.md +3 -0
- package/docs/assets/screenshots/agents-matrix.svg +35 -0
- package/docs/assets/screenshots/host-doctor.svg +21 -0
- package/docs/assets/screenshots/status-json.svg +30 -0
- package/docs/benchmarking.md +2 -2
- package/docs/conductor-mode.md +44 -0
- package/docs/context-packs.md +18 -0
- package/docs/dashboard-rail.md +6 -0
- package/docs/ecosystem-influences.md +65 -0
- package/docs/eval-datasets.md +40 -0
- package/docs/evaluation-suite.md +6 -0
- package/docs/evidence-provenance-rail.md +70 -0
- package/docs/external-projects-audit.md +29 -0
- package/docs/future-rails-index.md +75 -17
- package/docs/golden-agent-tests.md +44 -0
- package/docs/governance-cost-rail.md +10 -0
- package/docs/harness-lifecycle-rail.md +95 -0
- package/docs/harness-rail.md +27 -0
- package/docs/host-compatibility-rail.md +30 -6
- package/docs/host-matrix-schema.md +43 -0
- package/docs/host-router-rail.md +73 -0
- package/docs/knowledge-rail.md +76 -0
- package/docs/llm-as-judge-policy.md +45 -0
- package/docs/mcp-host-manifest.md +33 -0
- package/docs/mcp-report-resources.md +9 -0
- package/docs/mcp.md +4 -0
- package/docs/media-guide.md +27 -0
- package/docs/multi-agent-workflow-templates.md +63 -0
- package/docs/observability-rail.md +36 -0
- package/docs/quickstart.md +1 -1
- package/docs/rate-limit-and-fallback-policy.md +45 -0
- package/docs/release-workflow.md +12 -1
- package/docs/releases/README.md +3 -0
- package/docs/releases/RELEASE_NOTES_v1.1.0.md +55 -0
- package/docs/releases/RELEASE_NOTES_v1.2.0.md +43 -0
- package/docs/repo-docs-audit-2026-06-05.md +55 -0
- package/docs/report-rail.md +12 -0
- package/docs/resilience-rail.md +48 -0
- package/docs/schema-contracts.md +20 -0
- package/docs/security-boundaries.md +34 -0
- package/docs/skill-rail-2.md +11 -0
- package/docs/stable-command-surface.md +16 -1
- package/docs/tasklet-rail.md +62 -0
- package/docs/tutorial-antigravity.md +7 -2
- package/docs/tutorial-deep-agents-role-packs.md +4 -0
- package/docs/tutorial-gemini-cli.md +4 -0
- package/docs/tutorial-opencode.md +37 -0
- package/docs/v1-contract.md +5 -3
- package/docs/workflow-rail.md +12 -0
- package/examples/agents/README.md +6 -1
- package/examples/agents/opencode.md +26 -0
- package/package.json +2 -2
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
# Host Compatibility Rail
|
|
2
2
|
|
|
3
|
-
Host Compatibility Rail is the
|
|
3
|
+
Host Compatibility Rail is the v1.1.0 direction for making SotuRail outputs useful across coding-agent hosts without becoming an agent host itself.
|
|
4
|
+
|
|
5
|
+
## Host Fit
|
|
6
|
+
|
|
7
|
+
`soturail agents matrix`, `agents doctor --host <host>` and `agents doctor --all` form the current Host Fit Doctor surface. They report compatibility, export support, limitations and safe next commands without model serving or runtime installation.
|
|
8
|
+
|
|
9
|
+
Hermes and Odysseus are ecosystem influences, not direct stable host integrations. Hermes is an agent runtime and Odysseus is a broader workspace/runtime stack. Generic-compatible exports remain the safe fallback until a host-specific path is implemented and tested.
|
|
4
10
|
|
|
5
11
|
## Goal
|
|
6
12
|
|
|
@@ -17,22 +23,25 @@ Supported host families should be treated as runtime surfaces with different cap
|
|
|
17
23
|
| --- | --- |
|
|
18
24
|
| Claude / Claude Code-style | short `CLAUDE.md`, referenced docs, MCP/resource notes, report agent brief |
|
|
19
25
|
| Codex-style | `AGENTS.md`-friendly Markdown, safe commands, report/status summaries |
|
|
20
|
-
| OpenCode |
|
|
26
|
+
| OpenCode | generic-compatible `AGENTS.md`, context packs and report briefs |
|
|
21
27
|
| Cursor | rules/context docs, dashboard/report references and safe workflow notes |
|
|
22
|
-
| Antigravity-style |
|
|
23
|
-
|
|
|
24
|
-
|
|
|
28
|
+
| Antigravity-style | high-priority experimental `AGENTS.md`, context pack and Gemini-to-Antigravity migration notes |
|
|
29
|
+
| Gemini legacy/compatible | AGENTS/GEMINI Markdown handoff for mixed host behavior |
|
|
30
|
+
| Deep Agents-style | role packs, subagent notes, filesystem evidence and human approval notes |
|
|
31
|
+
| Generic MCP host | read-only report/status/brain/bench/baseline/host manifests and exposure reports |
|
|
25
32
|
|
|
26
33
|
## Planned Commands
|
|
27
34
|
|
|
28
35
|
```bash
|
|
29
36
|
soturail agents matrix
|
|
37
|
+
soturail agents matrix --json
|
|
30
38
|
soturail agents doctor --host opencode
|
|
39
|
+
soturail agents doctor --all --json
|
|
31
40
|
soturail agents export --agent opencode
|
|
32
41
|
soturail agents export --agent antigravity
|
|
33
42
|
soturail agents export --agent deepagents
|
|
34
43
|
soturail agents export --agent generic
|
|
35
|
-
soturail mcp resources host-manifest
|
|
44
|
+
soturail mcp resources host-manifest --host opencode
|
|
36
45
|
```
|
|
37
46
|
|
|
38
47
|
## Capability Matrix Fields
|
|
@@ -49,6 +58,7 @@ Each host entry should eventually report:
|
|
|
49
58
|
- report/status format preference;
|
|
50
59
|
- known limitations;
|
|
51
60
|
- required human review.
|
|
61
|
+
- mutation allowed by default, which must remain `false`.
|
|
52
62
|
|
|
53
63
|
## Safety Defaults
|
|
54
64
|
|
|
@@ -58,6 +68,8 @@ Each host entry should eventually report:
|
|
|
58
68
|
- Do not expose destructive MCP tools by default.
|
|
59
69
|
- Do not claim first-class support until the export path has tests and docs.
|
|
60
70
|
- Always keep a generic Markdown fallback.
|
|
71
|
+
- Keep `.soturail/raw` out of agent handoff files.
|
|
72
|
+
- Use `soturail agents doctor --host <host>` before copying exports into host-visible locations.
|
|
61
73
|
|
|
62
74
|
## Relationship To Existing Rails
|
|
63
75
|
|
|
@@ -70,3 +82,15 @@ Each host entry should eventually report:
|
|
|
70
82
|
| Policy Rail | config write, hook and tool exposure checks |
|
|
71
83
|
| Skill Rail | host-aware skill export without always loading every skill |
|
|
72
84
|
| Workflow Rail | phase-specific host handoff |
|
|
85
|
+
|
|
86
|
+
## Host Router Expansion
|
|
87
|
+
|
|
88
|
+
Future host work is tracked in [`host-router-rail.md`](host-router-rail.md).
|
|
89
|
+
|
|
90
|
+
The host-router idea means context-format routing, not model-request routing:
|
|
91
|
+
|
|
92
|
+
```txt
|
|
93
|
+
one SotuRail context source -> Claude/Codex/Cursor/OpenCode/Gemini/generic exports
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
SotuRail must not intercept IDE traffic, proxy provider requests, manage browser tokens or bypass quotas.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Host Matrix Schema
|
|
2
|
+
|
|
3
|
+
SotuRail v1.1.0 keeps the v1 matrix artifact compatible with `soturail.agents.matrix.v1` and adds the v1.1 contract id:
|
|
4
|
+
|
|
5
|
+
```json
|
|
6
|
+
{
|
|
7
|
+
"schemaVersion": "soturail.agents.matrix.v1",
|
|
8
|
+
"contractId": "soturail.agent-host-matrix.v1",
|
|
9
|
+
"createdAt": "ISO-8601",
|
|
10
|
+
"version": "1.1.0",
|
|
11
|
+
"status": "passed|warning|failed|unknown",
|
|
12
|
+
"hosts": []
|
|
13
|
+
}
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Each host row preserves the v1 fields (`host`, `id`, `status`, `exportSupport`, `reportAgentSupport`, `contextPackSupport`, `mcpResourcesSupport`, `installDryRunSupport`, `knownLimitations`, `recommendedCommand`) and adds host-compatibility fields:
|
|
17
|
+
|
|
18
|
+
- `displayName`
|
|
19
|
+
- `priority`
|
|
20
|
+
- `instructionFiles`
|
|
21
|
+
- `contextFormats`
|
|
22
|
+
- `reportFormats`
|
|
23
|
+
- `mcpSupport`
|
|
24
|
+
- `skillsSupport`
|
|
25
|
+
- `hooksSupport`
|
|
26
|
+
- `installSupport`
|
|
27
|
+
- `mutationAllowedByDefault`
|
|
28
|
+
- `recommendedCommands`
|
|
29
|
+
- `limitations`
|
|
30
|
+
- `policyNotes`
|
|
31
|
+
|
|
32
|
+
## Statuses
|
|
33
|
+
|
|
34
|
+
- `stable`: covered by the local v1/v1.1 surface.
|
|
35
|
+
- `generic-compatible`: safe generic Markdown/context handoff, but not host-native integration.
|
|
36
|
+
- `legacy`: prompt/context compatibility for older or mixed host behavior.
|
|
37
|
+
- `experimental`: prompt-only, docs-only or role-pack-only until promoted.
|
|
38
|
+
- `planned`: documented future surface.
|
|
39
|
+
- `unknown`: not enough evidence.
|
|
40
|
+
|
|
41
|
+
## Safety
|
|
42
|
+
|
|
43
|
+
`mutationAllowedByDefault` must be `false` for every host. The matrix must not claim destructive MCP tools, shell execution through MCP, cloud telemetry or autonomous editing behavior.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Host Router Rail
|
|
2
|
+
|
|
3
|
+
Host Router Rail is a planned host/export layer inspired by router products, but it routes context formats, not model traffic.
|
|
4
|
+
|
|
5
|
+
```txt
|
|
6
|
+
One SotuRail context source -> many host-specific exports.
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Goal
|
|
10
|
+
|
|
11
|
+
Generate the best safe local artifact for each host:
|
|
12
|
+
|
|
13
|
+
| Host | Example export |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| Claude Code | `CLAUDE.md`, skills guidance, MCP read-only manifest |
|
|
16
|
+
| Codex | `AGENTS.md`, instructions and safe command handoff |
|
|
17
|
+
| Cursor | `.cursor/rules` style prompt/rule files |
|
|
18
|
+
| OpenCode | OpenCode-compatible instructions and role packs |
|
|
19
|
+
| Gemini | `GEMINI.md` style guidance |
|
|
20
|
+
| generic | Markdown context pack and report bundle |
|
|
21
|
+
|
|
22
|
+
## Proposed Commands
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
soturail export all
|
|
26
|
+
soturail translate --to claude
|
|
27
|
+
soturail translate --to codex
|
|
28
|
+
soturail translate --to cursor
|
|
29
|
+
soturail hosts status
|
|
30
|
+
soturail doctor --hosts
|
|
31
|
+
soturail export --fallback
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Context Optimization
|
|
35
|
+
|
|
36
|
+
Host Router Rail should connect to context budgeting:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
soturail context optimize
|
|
40
|
+
soturail context budget
|
|
41
|
+
soturail context compact
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Potential outputs:
|
|
45
|
+
|
|
46
|
+
```txt
|
|
47
|
+
.soturail/context/full.md
|
|
48
|
+
.soturail/context/compact.md
|
|
49
|
+
.soturail/context/ultra.md
|
|
50
|
+
.soturail/exports/claude/
|
|
51
|
+
.soturail/exports/codex/
|
|
52
|
+
.soturail/exports/cursor/
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Fallbacks
|
|
56
|
+
|
|
57
|
+
Fallback should mean safe format fallback, not provider or quota bypass:
|
|
58
|
+
|
|
59
|
+
- MCP unsupported -> static Markdown/resources;
|
|
60
|
+
- skills unsupported -> prompt-only instructions;
|
|
61
|
+
- huge context -> compact role pack;
|
|
62
|
+
- host unknown -> generic export.
|
|
63
|
+
|
|
64
|
+
## Hard Boundary
|
|
65
|
+
|
|
66
|
+
SotuRail must not:
|
|
67
|
+
|
|
68
|
+
- intercept IDE traffic;
|
|
69
|
+
- proxy model requests;
|
|
70
|
+
- manage or rotate provider accounts;
|
|
71
|
+
- use browser cookies or session tokens;
|
|
72
|
+
- bypass quotas;
|
|
73
|
+
- promise unlimited free model access.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Knowledge Rail
|
|
2
|
+
|
|
3
|
+
Knowledge Rail is a planned future surface for compiling project documentation into small, on-demand knowledge packs for coding agents.
|
|
4
|
+
|
|
5
|
+
It is inspired by document-to-skill workflows: extract structure, not a giant summary.
|
|
6
|
+
|
|
7
|
+
## Goal
|
|
8
|
+
|
|
9
|
+
Turn docs, specs, READMEs, ADRs, notes and technical references into local agent-usable knowledge:
|
|
10
|
+
|
|
11
|
+
```txt
|
|
12
|
+
source docs -> topic index -> SKILL.md -> topics -> glossary -> patterns -> cheatsheet -> provenance
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Proposed Commands
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
soturail knowledge ingest ./docs ./README.md ./architecture.md
|
|
19
|
+
soturail knowledge estimate ./docs
|
|
20
|
+
soturail knowledge compile --mode on-demand
|
|
21
|
+
soturail knowledge update project-brain ./new-docs
|
|
22
|
+
soturail knowledge verify
|
|
23
|
+
soturail skill build ./docs --name project-architecture
|
|
24
|
+
soturail skill fold-in project-architecture ./ADR-004.md
|
|
25
|
+
soturail skill export --target claude
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Local Layout
|
|
29
|
+
|
|
30
|
+
```txt
|
|
31
|
+
.soturail/knowledge/<name>/
|
|
32
|
+
SKILL.md
|
|
33
|
+
topics/
|
|
34
|
+
architecture.md
|
|
35
|
+
testing.md
|
|
36
|
+
release.md
|
|
37
|
+
glossary.md
|
|
38
|
+
patterns.md
|
|
39
|
+
cheatsheet.md
|
|
40
|
+
source-map.json
|
|
41
|
+
metadata.json
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## On-Demand Context
|
|
45
|
+
|
|
46
|
+
Instead of loading all docs into every prompt, an export can say:
|
|
47
|
+
|
|
48
|
+
```txt
|
|
49
|
+
Read .soturail/knowledge/project/SKILL.md first.
|
|
50
|
+
For release tasks, read topics/release.md.
|
|
51
|
+
For testing tasks, read topics/testing.md.
|
|
52
|
+
Do not load unrelated topics unless needed.
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Metadata
|
|
56
|
+
|
|
57
|
+
A knowledge pack should record:
|
|
58
|
+
|
|
59
|
+
- source paths;
|
|
60
|
+
- extraction date;
|
|
61
|
+
- token estimate;
|
|
62
|
+
- topic list;
|
|
63
|
+
- source map;
|
|
64
|
+
- verification status;
|
|
65
|
+
- update/fold-in history.
|
|
66
|
+
|
|
67
|
+
## Copyright And Sharing Boundary
|
|
68
|
+
|
|
69
|
+
Knowledge packs generated from private or copyrighted material should stay local unless the user has rights to redistribute them. SotuRail should prefer synthesized structure and references over copying large source text.
|
|
70
|
+
|
|
71
|
+
## Non-Goals
|
|
72
|
+
|
|
73
|
+
- no vector database required;
|
|
74
|
+
- no cloud embeddings required;
|
|
75
|
+
- no publishing third-party book content by default;
|
|
76
|
+
- no replacing Project Brain or Knowledge Graph Rail. Knowledge Rail feeds them with organized source material.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# LLM-As-Judge Policy
|
|
2
|
+
|
|
3
|
+
SotuRail may eventually support optional LLM-as-judge evaluations for hallucination, clarity and evidence quality. This document defines the boundary before that feature exists.
|
|
4
|
+
|
|
5
|
+
## Default Policy
|
|
6
|
+
|
|
7
|
+
```txt
|
|
8
|
+
No LLM-as-judge call is required for normal SotuRail development, testing or release.
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Default gates should be deterministic:
|
|
12
|
+
|
|
13
|
+
- schema validation;
|
|
14
|
+
- JSON parsing;
|
|
15
|
+
- keyword and section checks;
|
|
16
|
+
- file existence checks;
|
|
17
|
+
- redaction checks;
|
|
18
|
+
- golden output checks;
|
|
19
|
+
- snapshot diff checks;
|
|
20
|
+
- link/path checks where local.
|
|
21
|
+
|
|
22
|
+
## Optional Judge Mode
|
|
23
|
+
|
|
24
|
+
A future optional command could look like:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
soturail eval judge --provider openai
|
|
28
|
+
soturail eval judge --provider groq
|
|
29
|
+
soturail eval judge --provider local
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Required behavior:
|
|
33
|
+
|
|
34
|
+
- opt-in only;
|
|
35
|
+
- never uploads repo data without clear user action;
|
|
36
|
+
- stores provider, model, prompt hash, timestamp and result;
|
|
37
|
+
- separates judge results from deterministic release evidence;
|
|
38
|
+
- marks results as subjective/heuristic, not proof.
|
|
39
|
+
|
|
40
|
+
## Non-Goals
|
|
41
|
+
|
|
42
|
+
- no mandatory provider keys;
|
|
43
|
+
- no hidden telemetry;
|
|
44
|
+
- no judge score as the only release gate;
|
|
45
|
+
- no claim that a judge result proves correctness.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# MCP Host Manifest
|
|
2
|
+
|
|
3
|
+
SotuRail v1.1.0 adds a read-only host manifest for agent hosts that can inspect local MCP-style resources.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
soturail mcp resources host-manifest --host codex
|
|
7
|
+
soturail mcp resources host-manifest --host codex --json
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Generated files:
|
|
11
|
+
|
|
12
|
+
```txt
|
|
13
|
+
.soturail/mcp/host-manifest.json
|
|
14
|
+
.soturail/mcp/host-manifests/<host>.json
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Schema:
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"schemaVersion": "soturail.mcp.host-manifest.v1",
|
|
22
|
+
"version": "1.1.0",
|
|
23
|
+
"host": "codex",
|
|
24
|
+
"mode": "read-only",
|
|
25
|
+
"mutationAllowed": false,
|
|
26
|
+
"arbitraryShellExecutionExposed": false,
|
|
27
|
+
"resources": []
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Resources include status, report, agent report, Project Brain brief, schema check, v1 readiness, benchmark, native candidates, baseline, dashboard, host export and host doctor artifacts when present.
|
|
32
|
+
|
|
33
|
+
The manifest does not expose `.soturail/raw`, shell execution, write tools or destructive MCP tools. Missing artifacts are warnings with next commands, not crashes.
|
|
@@ -4,6 +4,8 @@ v0.10.0 exposes report artifacts as read-only MCP resource metadata.
|
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
soturail mcp resources report
|
|
7
|
+
soturail mcp resources host-manifest --host codex
|
|
8
|
+
soturail mcp resources host-manifest --host codex --json
|
|
7
9
|
soturail mcp exposure
|
|
8
10
|
```
|
|
9
11
|
|
|
@@ -11,6 +13,8 @@ Generated manifest:
|
|
|
11
13
|
|
|
12
14
|
```txt
|
|
13
15
|
.soturail/mcp/report-resources.json
|
|
16
|
+
.soturail/mcp/host-manifest.json
|
|
17
|
+
.soturail/mcp/host-manifests/<host>.json
|
|
14
18
|
```
|
|
15
19
|
|
|
16
20
|
Seed resource URIs:
|
|
@@ -24,8 +28,13 @@ soturail://bench/latest
|
|
|
24
28
|
soturail://native/candidates
|
|
25
29
|
soturail://baseline/latest
|
|
26
30
|
soturail://observability/timeline
|
|
31
|
+
soturail://agents/host-manifest
|
|
27
32
|
```
|
|
28
33
|
|
|
29
34
|
These resources are read-only. They do not expose destructive tools, shell execution or report mutation. Content is sanitized and redaction-aware where possible.
|
|
30
35
|
|
|
31
36
|
If a host does not consume MCP resources directly, the manifest still documents the safe local report artifacts an agent can inspect.
|
|
37
|
+
|
|
38
|
+
Host manifests use `soturail.mcp.host-manifest.v1` and include `mutationAllowed: false` and `arbitraryShellExecutionExposed: false`. They reference status, reports, agent reports, Project Brain exports, schemas, readiness, benchmarks, native candidates, baselines, dashboard, host export and host doctor artifacts when available.
|
|
39
|
+
|
|
40
|
+
See [mcp-host-manifest.md](mcp-host-manifest.md).
|
package/docs/mcp.md
CHANGED
|
@@ -9,6 +9,8 @@ soturail mcp config --agent generic
|
|
|
9
9
|
soturail mcp smoke
|
|
10
10
|
soturail mcp exposure
|
|
11
11
|
soturail mcp exposure --json
|
|
12
|
+
soturail mcp resources report
|
|
13
|
+
soturail mcp resources host-manifest --host codex
|
|
12
14
|
soturail mcp serve --transport stdio
|
|
13
15
|
```
|
|
14
16
|
|
|
@@ -75,6 +77,8 @@ soturail mcp serve --transport stdio
|
|
|
75
77
|
|
|
76
78
|
It does not assume a global application config path. Review it before adding it to an agent host.
|
|
77
79
|
|
|
80
|
+
`soturail mcp resources host-manifest --host <host>` writes `.soturail/mcp/host-manifest.json` and `.soturail/mcp/host-manifests/<host>.json`. The manifest lists local status, report, brain, schema, readiness, benchmark, native, baseline, dashboard, host export and host doctor artifacts. It sets `mutationAllowed: false` and `arbitraryShellExecutionExposed: false`.
|
|
81
|
+
|
|
78
82
|
For v0.6.0 agent-runtime setup, prefer host-aware dry-runs before copying MCP snippets into a host:
|
|
79
83
|
|
|
80
84
|
```bash
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Media Guide
|
|
2
|
+
|
|
3
|
+
SotuRail media assets are local documentation artifacts. They should show the CLI, reports, dashboard and host exports without exposing private paths, secrets or live tokens.
|
|
4
|
+
|
|
5
|
+
## Folders
|
|
6
|
+
|
|
7
|
+
```txt
|
|
8
|
+
docs/assets/screenshots/
|
|
9
|
+
docs/assets/demos/
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Rules
|
|
13
|
+
|
|
14
|
+
- Use generated or sanitized screenshots.
|
|
15
|
+
- Do not include real tokens, emails, private paths or `.env` data.
|
|
16
|
+
- Do not show `.soturail/raw` evidence.
|
|
17
|
+
- Prefer small SVG or PNG assets that can be committed safely.
|
|
18
|
+
- Keep animated demos short and local; do not rely on external CDNs.
|
|
19
|
+
|
|
20
|
+
## Suggested Shots
|
|
21
|
+
|
|
22
|
+
- `status-json.svg`: valid JSON status output.
|
|
23
|
+
- `agents-matrix.svg`: host compatibility matrix summary.
|
|
24
|
+
- `host-doctor.svg`: per-host doctor result.
|
|
25
|
+
- `dashboard.svg`: static dashboard overview.
|
|
26
|
+
|
|
27
|
+
Media is illustrative evidence, not a replacement for tests or release checks.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Multi-Agent Workflow Templates
|
|
2
|
+
|
|
3
|
+
SotuRail should support multi-agent ideas as templates and context packs, not as a required CrewAI/LangGraph runtime.
|
|
4
|
+
|
|
5
|
+
## Purpose
|
|
6
|
+
|
|
7
|
+
A multi-agent workflow template defines roles, inputs, outputs, evidence and verification criteria for external agents.
|
|
8
|
+
|
|
9
|
+
SotuRail can generate:
|
|
10
|
+
|
|
11
|
+
- role-specific context packs;
|
|
12
|
+
- role boundaries;
|
|
13
|
+
- definition of done per role;
|
|
14
|
+
- handoff files between roles;
|
|
15
|
+
- evidence requirements;
|
|
16
|
+
- a final report skeleton.
|
|
17
|
+
|
|
18
|
+
## Example Roles
|
|
19
|
+
|
|
20
|
+
```txt
|
|
21
|
+
Lead Agent
|
|
22
|
+
├── Researcher: collects local evidence and docs
|
|
23
|
+
├── Analyst: compares options and risks
|
|
24
|
+
├── Writer: produces user-facing docs/reports
|
|
25
|
+
└── Verifier: checks claims, tests, links and provenance
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Proposed Commands
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
soturail workflow template research-report
|
|
32
|
+
soturail workflow template validate-fix-verify-report
|
|
33
|
+
soturail context pack --role researcher
|
|
34
|
+
soturail context pack --role analyst
|
|
35
|
+
soturail context pack --role verifier
|
|
36
|
+
soturail agents export --role reviewer
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Template: Validate -> Fix -> Verify -> Report
|
|
40
|
+
|
|
41
|
+
Inspired by agent pipelines that validate input, repair issues, revalidate and then produce a report.
|
|
42
|
+
|
|
43
|
+
```txt
|
|
44
|
+
validate
|
|
45
|
+
input: selected files, schema, policy
|
|
46
|
+
output: findings.json
|
|
47
|
+
fix
|
|
48
|
+
input: findings.json and allowed files
|
|
49
|
+
output: patch proposal or instructions
|
|
50
|
+
verify
|
|
51
|
+
input: patch proposal and test/report commands
|
|
52
|
+
output: verification.md
|
|
53
|
+
report
|
|
54
|
+
input: all prior artifacts
|
|
55
|
+
output: report.md + provenance.md
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Non-Goals
|
|
59
|
+
|
|
60
|
+
- no mandatory CrewAI, LangGraph or LangChain dependency;
|
|
61
|
+
- no hidden subagent execution;
|
|
62
|
+
- no external web search by default;
|
|
63
|
+
- no autonomous edits without host/human approval.
|
|
@@ -36,3 +36,39 @@ The timeline is sorted deterministically, and the summary includes:
|
|
|
36
36
|
- safe next commands.
|
|
37
37
|
|
|
38
38
|
Observability still does not collect private shell history and does not upload telemetry.
|
|
39
|
+
|
|
40
|
+
## Pipeline Recorder Expansion
|
|
41
|
+
|
|
42
|
+
Future observability work can add a pipeline recorder inspired by validate/fix/verify/report agent flows:
|
|
43
|
+
|
|
44
|
+
```txt
|
|
45
|
+
agent_started
|
|
46
|
+
agent_finished
|
|
47
|
+
agent_failed
|
|
48
|
+
file_read
|
|
49
|
+
schema_validated
|
|
50
|
+
repair_applied
|
|
51
|
+
report_generated
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The first implementation can remain local artifacts and dashboard cards. A live SSE/server mode is optional and should not become required.
|
|
55
|
+
|
|
56
|
+
## Related 2026 Harness Rails
|
|
57
|
+
|
|
58
|
+
Observability Rail is the local timeline layer that feeds several planned rails:
|
|
59
|
+
|
|
60
|
+
- [`agent-qa-rail.md`](agent-qa-rail.md) defines eval runs, scores and regression artifacts that can become observability events.
|
|
61
|
+
- [`evidence-provenance-rail.md`](evidence-provenance-rail.md) defines verification status and provenance sidecars that reports and timelines should surface.
|
|
62
|
+
- [`agent-governance-rail.md`](agent-governance-rail.md) extends observability into trace, ledger, experiment and approval records.
|
|
63
|
+
- [`resilience-rail.md`](resilience-rail.md) adds rate-limit/fallback/provider-risk warnings as local events, not cloud telemetry.
|
|
64
|
+
|
|
65
|
+
This keeps the boundary clear: SotuRail observes local artifacts and user-approved records; it does not upload traces or become a hosted LangFuse/OpenTelemetry replacement by default.
|
|
66
|
+
|
|
67
|
+
## Ecosystem Direction
|
|
68
|
+
|
|
69
|
+
Hermes-style trajectory compression and Odysseus-style visual workspaces reinforce two SotuRail rules:
|
|
70
|
+
|
|
71
|
+
- keep observability as local, recoverable evidence rather than uploaded telemetry;
|
|
72
|
+
- present Context Packs, Memory, Reports, Evidence, Workflows, Host Compatibility, Skills, lifecycle state and Handoffs as bounded dashboard/report sections.
|
|
73
|
+
|
|
74
|
+
SotuRail does not add a required server, chat workspace or central shell interface. See [Security Boundaries](security-boundaries.md).
|
package/docs/quickstart.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Quickstart
|
|
2
2
|
|
|
3
|
-
SotuRail is a local-first Context OS for AI coding agents. v1.0.0
|
|
3
|
+
SotuRail is a local-first Context OS for AI coding agents. v1.0.0 froze the first stable command surface for local status, reports, dashboard artifacts, Project Brain checks, benchmarks, release readiness and agent handoff. v1.1.0 adds host-compatible exports, host doctors and read-only MCP host manifests.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Rate Limit And Fallback Policy
|
|
2
|
+
|
|
3
|
+
This document describes the future SotuRail policy model for rate-limit and fallback guidance. It is documentation-first and local-first.
|
|
4
|
+
|
|
5
|
+
## Policy Fields
|
|
6
|
+
|
|
7
|
+
A future policy file could live at:
|
|
8
|
+
|
|
9
|
+
```txt
|
|
10
|
+
.soturail/policies/rate-limit-and-fallback.yaml
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Example:
|
|
14
|
+
|
|
15
|
+
```yaml
|
|
16
|
+
hosts:
|
|
17
|
+
claude:
|
|
18
|
+
fallback: codex
|
|
19
|
+
contextFallback: markdown
|
|
20
|
+
cursor:
|
|
21
|
+
fallback: generic
|
|
22
|
+
contextFallback: cursor-rules-lite
|
|
23
|
+
workflows:
|
|
24
|
+
default:
|
|
25
|
+
maxAgentTurns: 20
|
|
26
|
+
requireHandoffAfterMinutes: 30
|
|
27
|
+
requireApprovalForExternalCalls: true
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Fallback Types
|
|
31
|
+
|
|
32
|
+
| Fallback | Meaning |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| host fallback | export the same SotuRail context to a different agent host |
|
|
35
|
+
| format fallback | use Markdown/static files when MCP or skills are unsupported |
|
|
36
|
+
| role fallback | reduce full workflow context to planner/executor/reviewer packs |
|
|
37
|
+
| offline fallback | keep local docs/reports usable when no provider is available |
|
|
38
|
+
|
|
39
|
+
## Non-Goals
|
|
40
|
+
|
|
41
|
+
- no live billing control;
|
|
42
|
+
- no provider account automation;
|
|
43
|
+
- no quota bypass;
|
|
44
|
+
- no traffic interception;
|
|
45
|
+
- no promise that fallback preserves model behavior.
|
package/docs/release-workflow.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Release Workflow
|
|
2
2
|
|
|
3
|
-
v1.
|
|
3
|
+
v1.x uses strict local release gates:
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
soturail self schemas --check --strict
|
|
@@ -86,6 +86,17 @@ soturail release check
|
|
|
86
86
|
|
|
87
87
|
`report_safety` is a release gate. If report artifacts contain obvious tokens or private keys, run `soturail report redact` and inspect the source artifact before publishing.
|
|
88
88
|
|
|
89
|
+
For v1.1.0 host compatibility evidence, run:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
soturail agents matrix --json
|
|
93
|
+
soturail agents doctor --all --json
|
|
94
|
+
soturail mcp resources host-manifest --host codex
|
|
95
|
+
soturail report agent --agent opencode
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Host evidence must stay local, read-only and redaction-aware. It must not claim destructive MCP, shell execution through MCP, cloud telemetry or full host-native runtime support for experimental targets.
|
|
99
|
+
|
|
89
100
|
You can run only the package verification gate with:
|
|
90
101
|
|
|
91
102
|
```bash
|
package/docs/releases/README.md
CHANGED
|
@@ -31,3 +31,6 @@ docs/releases/RELEASE_NOTES_vX.Y.Z.md
|
|
|
31
31
|
- [v0.10.0](RELEASE_NOTES_v0.10.0.md)
|
|
32
32
|
- [v0.10.1](RELEASE_NOTES_v0.10.1.md)
|
|
33
33
|
- [v1.0.0](RELEASE_NOTES_v1.0.0.md)
|
|
34
|
+
- [v1.0.1](RELEASE_NOTES_v1.0.1.md)
|
|
35
|
+
- [v1.1.0](RELEASE_NOTES_v1.1.0.md)
|
|
36
|
+
- [v1.2.0](RELEASE_NOTES_v1.2.0.md)
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# SotuRail v1.1.0
|
|
2
|
+
|
|
3
|
+
SotuRail v1.1.0 adds Host Compatibility Rail 1.0: host-aware exports, a richer compatibility matrix, per-host doctor reports, read-only MCP host manifests and practical docs for OpenCode, Antigravity, Gemini-compatible and DeepAgents-style handoffs.
|
|
4
|
+
|
|
5
|
+
## Added
|
|
6
|
+
|
|
7
|
+
- `soturail agents matrix --json` now preserves `soturail.agents.matrix.v1` and adds `contractId: soturail.agent-host-matrix.v1`.
|
|
8
|
+
- `soturail agents doctor --host <host>` writes `.soturail/agents/<host>/doctor.json` and `.md`.
|
|
9
|
+
- `soturail agents doctor --all --json` writes `.soturail/agents/doctor-summary.json` and `.md`.
|
|
10
|
+
- `soturail mcp resources host-manifest --host <host> [--json]` writes read-only host manifests.
|
|
11
|
+
- `soturail agents export --agent gemini-legacy` supports Gemini legacy/compatible handoffs.
|
|
12
|
+
- OpenCode exports include `AGENTS.md` and context packs.
|
|
13
|
+
- Antigravity exports include high-priority experimental transition guidance.
|
|
14
|
+
- DeepAgents/deepagents-js exports include `role-pack.md` and `subagents.md`.
|
|
15
|
+
|
|
16
|
+
## Changed
|
|
17
|
+
|
|
18
|
+
- Default agent exports are mirrored to `.soturail/agents/<host>/` and `.soturail/exports/agents/<host>/`.
|
|
19
|
+
- Agent reports support OpenCode, Antigravity, Cursor, Gemini legacy and DeepAgents-style targets.
|
|
20
|
+
- Docs now include host matrix schema, export contract, MCP host manifest, OpenCode tutorial and media guidance.
|
|
21
|
+
- README and ROADMAP now mark v1.1.0 Host Compatibility Rail as delivered.
|
|
22
|
+
|
|
23
|
+
## Safety
|
|
24
|
+
|
|
25
|
+
- No cloud telemetry.
|
|
26
|
+
- No server requirement.
|
|
27
|
+
- No destructive MCP tools.
|
|
28
|
+
- No shell execution through MCP.
|
|
29
|
+
- No provider lock-in.
|
|
30
|
+
- TypeScript fallback remains mandatory.
|
|
31
|
+
- Experimental hosts are labeled honestly; OpenCode is generic-compatible, Antigravity is experimental, and DeepAgents exports are role/context artifacts only.
|
|
32
|
+
|
|
33
|
+
## Verification
|
|
34
|
+
|
|
35
|
+
Run before publishing:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm run typecheck
|
|
39
|
+
npm run build
|
|
40
|
+
npx vitest run tests/v110.test.ts
|
|
41
|
+
npx vitest run tests/v100.test.ts
|
|
42
|
+
npm test
|
|
43
|
+
npm run release:check
|
|
44
|
+
node dist/cli.js agents matrix --json
|
|
45
|
+
node dist/cli.js agents doctor --all --json
|
|
46
|
+
node dist/cli.js mcp resources host-manifest --host codex --json
|
|
47
|
+
node dist/cli.js report agent --agent opencode
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Known Limitations
|
|
51
|
+
|
|
52
|
+
- Host compatibility remains export/report/manifest oriented; SotuRail does not become a host runtime.
|
|
53
|
+
- Antigravity support remains prompt/context only until a stable Google-local project config surface is documented.
|
|
54
|
+
- OpenCode support is generic-compatible and does not claim full host-native integration.
|
|
55
|
+
- DeepAgents exports are role packs and subagent notes only; no runtime dependency is installed.
|