@orion-agents/orion-code 0.1.9 → 0.2.2

package/docs/migration/v0.1.9-to-v0.2.0.md

@@ -0,0 +1,98 @@
+# Orion Code v0.1.9 → v0.2.0 migration and rollback
+
+Status: release-candidate guidance. A source commit, tag, npm version, and npm dist-tag are separate
+delivery receipts; do not treat this document as proof that `0.2.0` has been published.
+
+## Why this is a major runtime migration
+
+v0.2.0 replaces the legacy Brain/Agent/Harness/query ownership graph with one product runtime built
+around `Thread → Turn → Step → Item`. It is an intentional breaking cut rather than a compatibility
+wrapper:
+
+- one Agent Loop owns root and child model/tool recursion;
+- one ToolGateway owns Capability, Policy, Approval, Sandbox, execution, and durable receipts;
+- every model request uses a digest-bound Step Snapshot, so visible schemas and dispatch cannot
+  drift during a step;
+- Skills and MCP servers stay descriptor-only until selected; unselected definitions, resources,
+  connections, processes, and sockets remain dormant;
+- Goal lifecycle and completion state are committed with the same durable TurnCommit as history and
+  TaskContext evidence;
+- Plan produces a durable PlanReceipt, exits automatically, restores BUILD/AUTO, and schedules
+  implementation as a new logical turn;
+- Compact is a non-steerable maintenance transaction with source CAS, checkpoint, pointer, and
+  crash recovery.
+
+The package root no longer exports legacy Agent, Brain, Harness, SDK query/session helpers, internal
+runtime services, Step Snapshot internals, or plugin-container surfaces.
+
+## Command changes
+
+- `/goal <objective>` creates a Goal. `/goal status`, `pause`, `resume`, and `clear` are the only
+  lifecycle controls.
+- `/target` is removed. `/goal exit`, `edit`, `replace`, `confirm`, `budget`, and `clear --yes` are
+  removed rather than silently reinterpreted.
+- `/plan <task>` is the task entry. A successful planning turn saves a PlanReceipt and exits Plan
+  automatically; there is no `exit_plan_mode` tool.
+- `Shift+Tab` cycles BUILD → PLAN → AUTO. Mode selects workflow behavior; Authority and tool policy
+  remain separate.
+- Compatibility-only roots such as `/task`, `/run`, `/chat`, `/sessions`, and `/models` are removed.
+  Use `/help` from the installed candidate for the authoritative command inventory.
+
+## Before upgrading
+
+1. Stop all Orion processes for the target project.
+2. Record `orion --version` and run `orion doctor` with the old executable.
+3. Make a recoverable copy or filesystem snapshot of `~/.orion-code`; preserve permissions and do
+   not commit it.
+4. Keep the project worktree recoverable. The migration does not require deleting sessions, lock
+   files, databases, or project data.
+5. Install only an immutable version after its npm receipt exists:
+
+```bash
+npm install -g @orion-agents/orion-code@0.2.0
+orion --version
+orion doctor
+```
+
+## First start and resume
+
+On first use of an existing session, Orion materializes legacy transcript, trace, Harness, Compact,
+and Goal facts into a side-by-side v2 Thread store. The legacy bytes remain unchanged. Facts and a
+verified projection are written before the project index switches; until that final index commit,
+the legacy source remains authoritative.
+
+Migration is fail closed:
+
+- corrupt records or missing/unknown tool pairs become explicit indeterminate Items rather than a
+  guessed successful turn;
+- a changed source, digest mismatch, partial event prefix, or conflicting index aborts cutover;
+- after a successful index switch, replay and projection digests must match before resume;
+- a crash before the index switch resolves to legacy; a crash after it resolves to the v2 Thread.
+
+Resume a non-critical session first, inspect `/status`, `/context explain`, `/tools`, `/skills`, and
+`/mcp`, then run a small read/edit/test turn. Do not manually remove `.lock`, `.recovery`, v2 Thread,
+compact transaction, or index files while any Orion process may own them.
+
+## Configuration boundary
+
+Existing model/provider configuration remains supported. `skills.paths` becomes filesystem Skill
+provider roots. `mcpServers` become dormant descriptors and are not connected merely because Orion
+starts or `/mcp` is inspected. BUILD/PLAN/AUTO do not grant additional Authority.
+
+Do not add plugin package paths or executable JavaScript loaders: v0.2.0 deliberately keeps Model,
+Skills, and MCP as the only user extension boundaries.
+
+## Rollback
+
+The executable can be rolled back without deleting data:
+
+```bash
+npm install -g @orion-agents/orion-code@0.1.9
+orion --version
+```
+
+v0.1.9 cannot safely write a project after its session has cut over to the v2 Thread index. Stop all
+Orion processes and restore the pre-upgrade `~/.orion-code` snapshot before resuming with v0.1.9.
+Never splice a legacy transcript together with a v2 index, projection, TurnCommit, Goal, or compact
+pointer. Preserve the failed v2 directory and diagnostics for audit rather than repeatedly retrying
+or deleting recovery evidence.

package/docs/orion.example.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 1,
+  "providers": [
+    {
+      "id": "my-provider",
+      "displayName": "My OpenAI-compatible Provider",
+      "baseUrl": "https://your-endpoint.example/v1",
+      "apiKey": "sk-REPLACE_WITH_YOUR_KEY",
+      "protocol": "openai-completions"
+    }
+  ],
+  "models": [
+    {
+      "id": "my-model",
+      "displayName": "My Model",
+      "provider": "my-provider",
+      "model": "model-name",
+      "contextWindow": 200000,
+      "maxOutputTokens": 8192,
+      "reasoningCapability": {
+        "kind": "effort-level",
+        "supportedLevels": ["low", "medium", "high"],
+        "defaultLevel": "medium",
+        "adapter": "openai-chat-reasoning-effort",
+        "source": "config"
+      }
+    },
+    {
+      "id": "my-fallback",
+      "displayName": "My Fallback Model",
+      "provider": "my-provider",
+      "model": "fallback-model-name",
+      "contextWindow": 200000,
+      "maxOutputTokens": 8192
+    }
+  ],
+  "defaultModel": "my-model",
+  "fallbackModel": "my-fallback",
+  "defaultEffort": "auto",
+  "toolConfirmation": "allow",
+  "allowedTools": [],
+  "projects": {
+    "/absolute/path/to/project": {
+      "compactInstructions": "Retain architecture decisions, failed verification, and release receipts."
+    }
+  },
+  "ui": {
+    "confirmations": "config",
+    "theme": "orion-pixel",
+    "motion": "reduced",
+    "mascot": true,
+    "statusLine": ["mode", "goal", "model", "context", "permission", "queue", "activity"],
+    "keymap": {
+      "queue": ["tab"],
+      "history-search": ["ctrl+r"],
+      "external-editor": ["ctrl+e"]
+    }
+  },
+  "subagents": {
+    "mode": "auto",
+    "maxParallel": 4
+  },
+  "webSearch": {
+    "provider": "auto",
+    "apiKey": "REPLACE_WITH_WEB_SEARCH_KEY"
+  },
+  "skills": {
+    "paths": []
+  },
+  "agentLoop": {
+    "budget": {
+      "maxLlmRequestsPerUserTurn": 200,
+      "maxToolCallsPerUserTurn": 400
+    }
+  },
+  "sandbox": {
+    "profile": "none"
+  }
+}