opensober 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tt-a1i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# opensober
+
+> *Stay sober. Nothing is magic.*
+
+**English** | [简体中文](./README.zh-CN.md)
+
+An opencode plugin that doesn't try to be clever. Agent tools keep getting smarter, more magical, more opinionated. opensober goes the other way: every behavior is visible, disable-able, and fails loud.
+
+**Status:** v0.1.x, API not yet stable. Not yet published to npm.
+
+## Why
+
+- **No invisible automation.** No keyword-driven modes. No prompt-derived command execution. Every context injection is named in config.
+- **Readonly agents cannot escape their sandbox.** A readonly agent delegating to a writable agent is rejected at runtime — enforced by the `task` tool, not by documentation.
+- **Edits can't silently clobber stale state.** `read` annotates each line with a content hash; `edit` rejects the whole batch if any hash has changed.
+
+## Install
+
+Not yet published to npm. For local development:
+
+```bash
+git clone <this-repo>
+cd opensober
+bun install
+bun run build
+npm pack                    # produces opensober-0.1.0.tgz
+```
+
+Then install into your opencode config:
+
+```bash
+cd ~/.config/opencode
+bun add /path/to/opensober-0.1.0.tgz
+```
+
+Add to `~/.config/opencode/opencode.json`:
+
+```jsonc
+{
+  // Register opensober as a plugin (file URL to the built entry)
+  "plugin": ["file:///path/to/.config/opencode/node_modules/opensober/dist/index.js"],
+
+  // opensober's orchestrator must be declared as a static primary agent
+  // for it to appear in the opencode agent selector UI.
+  "agent": {
+    "orchestrator": {
+      "model": "your-provider/your-model",
+      "mode": "primary"
+    }
+    // ... your other agents
+  }
+}
+```
+
+> **Note:** opencode's UI agent list reads from static config, not solely from plugin
+> dynamic registration. The `orchestrator` entry above is the UI anchor; opensober's
+> `explore` and `reviewer` subagents are registered dynamically and accessible via
+> the `task` tool, but don't need static entries.
+
+Peer requirement: `@opencode-ai/plugin ^1.4.0`. Bun-only (>= 1.3.0); no Node fallback.
+
+## Quickstart
+
+Create `.opensober/config.jsonc` at your project root:
+
+```jsonc
+{
+  "version": 1,
+  "model": "anthropic/claude-opus-4-6",
+  "agents": {
+    "quick": {
+      "extends": "orchestrator",
+      "model": "openai/gpt-5-mini"
+    }
+  }
+}
+```
+
+Check it loads cleanly:
+
+```
+$ bunx opensober doctor
+
+== opensober doctor ==
+
+config
+  version:       1
+  global model:  anthropic/claude-opus-4-6
+  layers:
+    default       (built-in)
+    project       /repo/.opensober/config.jsonc
+
+agents
+  explore         anthropic/claude-opus-4-6      readonly, no-delegate
+  orchestrator    anthropic/claude-opus-4-6      writable, delegates
+  reviewer        anthropic/claude-opus-4-6      readonly, delegates (readonly-only)
+  quick           openai/gpt-5-mini              writable, delegates
+
+tools
+  edit, read, task
+
+warnings
+  (none)
+```
+
+Exit codes: `0` clean, `1` warnings, `2` config failed to load.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `bunx opensober doctor`  | Health check: config summary, agents, tools, warnings |
+| `bunx opensober run`     | Load config and print a session-ready summary |
+| `bunx opensober install` | *(not yet implemented)* |
+
+Both `doctor` and `run` take `--cwd <dir>` and `--config <path>`.
+
+## Config layering
+
+Four layers merge in order (later wins):
+
+1. **default** — built-in baselines
+2. **user** — `~/.config/opensober/config.jsonc`
+3. **project** — `<project-root>/.opensober/config.jsonc`
+4. **cli-override** — `--config <path>`
+
+Project root is the nearest ancestor directory containing `.git`. If none is found, the project layer is silently skipped — single-file or CI scratch directories just work.
+
+## Built-in agents
+
+Three agents ship in the box:
+
+- `orchestrator` — writable, may delegate to any agent
+- `explore` — readonly, cannot delegate
+- `reviewer` — readonly, may delegate only to other readonly agents
+
+User-defined agents extend these via `extends`. Permission flags (`readonly`, `can_delegate`) inherit from the parent chain; overriding them explicitly is allowed but the `task` tool still enforces that readonly callers cannot reach writable targets.
+
+## Learn more
+
+- [`v1-scope.md`](./v1-scope.md) — frozen v1 scope
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — the nine hard rules
+- [`round-7.5-memo.md`](./round-7.5-memo.md) — SDK investigation memo
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,144 @@
+# opensober
+
+> *Stay sober. Nothing is magic.*
+
+[English](./README.md) | **简体中文**
+
+一个不装聪明的 opencode 插件。Agent 工具越来越"聪明"、越来越"贴心"、越来越有主张——prompt 背着你被注入、关键字悄悄切模式、fallback 链在你睡觉时烧光 API 配额。opensober 走反方向：每个行为都可见、可关、错了就明摆着让你看见。
+
+**状态：** v0.1.x，API 尚未稳定，尚未发布到 npm。
+
+## 为什么
+
+- **没有隐形自动化。** 不做关键字切模式。不从 prompt 文本里自动执行命令。每一处上下文注入都在配置里明确命名。
+- **Readonly agent 逃不出沙盒。** Readonly agent 想把任务委派给 writable agent，会在运行时被拒——由 `task` 工具强制，不是靠文档约定。
+- **编辑不会悄悄覆盖过期状态。** `read` 给每一行标上内容哈希；`edit` 如果任何一行的哈希变了，整批拒绝。
+
+## 安装
+
+尚未发布到 npm。本地开发：
+
+```bash
+git clone <本仓库>
+cd opensober
+bun install
+bun run build
+npm pack                    # 生成 opensober-0.1.0.tgz
+```
+
+安装到 opencode：
+
+```bash
+cd ~/.config/opencode
+bun add /path/to/opensober-0.1.0.tgz
+```
+
+在 `~/.config/opencode/opencode.json` 中注册：
+
+```jsonc
+{
+  // 用 file URL 指向 opensober 的构建入口
+  "plugin": ["file:///path/to/.config/opencode/node_modules/opensober/dist/index.js"],
+
+  // orchestrator 必须作为静态 primary agent 声明，才会出现在 opencode 的 agent 选择器里
+  "agent": {
+    "orchestrator": {
+      "model": "your-provider/your-model",
+      "mode": "primary"
+    }
+  }
+}
+```
+
+> **注意**：opencode 的 UI agent 列表依赖静态配置，不仅仅来自插件动态注册。
+> 上面的 `orchestrator` 条目是 UI 锚点；opensober 的 `explore` 和 `reviewer`
+> 子 agent 由插件动态注册，通过 `task` 工具调用，不需要静态配置。
+
+Peer 依赖：`@opencode-ai/plugin ^1.4.0`。仅支持 Bun（>= 1.3.0），不提供 Node fallback。
+
+## 快速上手
+
+在项目根目录创建 `.opensober/config.jsonc`：
+
+```jsonc
+{
+  "version": 1,
+  "model": "anthropic/claude-opus-4-6",
+  "agents": {
+    "quick": {
+      "extends": "orchestrator",
+      "model": "openai/gpt-5-mini"
+    }
+  }
+}
+```
+
+检查配置是否加载成功：
+
+```
+$ bunx opensober doctor
+
+== opensober doctor ==
+
+config
+  version:       1
+  global model:  anthropic/claude-opus-4-6
+  layers:
+    default       (built-in)
+    project       /repo/.opensober/config.jsonc
+
+agents
+  explore         anthropic/claude-opus-4-6      readonly, no-delegate
+  orchestrator    anthropic/claude-opus-4-6      writable, delegates
+  reviewer        anthropic/claude-opus-4-6      readonly, delegates (readonly-only)
+  quick           openai/gpt-5-mini              writable, delegates
+
+tools
+  edit, read, task
+
+warnings
+  (none)
+```
+
+退出码：`0` 干净，`1` 有警告，`2` 配置加载失败。
+
+## 命令
+
+| 命令 | 用途 |
+|---|---|
+| `bunx opensober doctor`  | 健康检查：配置摘要、agents、工具、警告 |
+| `bunx opensober run`     | 加载配置并打印一份 session-ready 摘要 |
+| `bunx opensober install` | *（尚未实现）* |
+
+`doctor` 和 `run` 都接受 `--cwd <dir>` 和 `--config <path>`。
+
+## 配置分层
+
+四层按顺序合并，后面的覆盖前面的：
+
+1. **default** — 内置基线
+2. **user** — `~/.config/opensober/config.jsonc`
+3. **project** — `<项目根>/.opensober/config.jsonc`
+4. **cli-override** — `--config <path>`
+
+项目根是向上找最近一个含 `.git` 的目录。找不到时会静默跳过 project 层——单文件 / CI 临时目录也能正常工作。
+
+## 内置 agent
+
+三个开箱即用的 agent：
+
+- `orchestrator` — writable，可以委派给任意 agent
+- `explore` — readonly，不能委派
+- `reviewer` — readonly，只能委派给同样 readonly 的 agent
+
+用户自定义 agent 通过 `extends` 继承。权限标记（`readonly`、`can_delegate`）从 parent 链继承；显式覆盖也允许，但 `task` 工具仍会强制：readonly 调用方不能触及 writable 目标。
+
+## 延伸阅读
+
+- [`v1-scope.md`](./v1-scope.md) — v1 冻结范围
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — 九条硬规则
+- [`round-7.5-memo.md`](./round-7.5-memo.md) — SDK 调研备忘录
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/cli/doctor.d.ts

@@ -0,0 +1,11 @@
+import { type ErrorSink } from "./format-error";
+export type OutSink = (line: string) => void;
+export interface DoctorOptions {
+    readonly cwd?: string | undefined;
+    readonly configOverride?: string | undefined;
+    readonly userHome?: string | undefined;
+    readonly out?: OutSink | undefined;
+    readonly err?: ErrorSink | undefined;
+}
+export declare function doctorCommand(opts?: DoctorOptions): number;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,gBAAgB,CAAA;AAE5D,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAE5C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;CACrC;AAYD,wBAAgB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,MAAM,CA8B9D"}

package/dist/cli/format-error.d.ts

@@ -0,0 +1,3 @@
+export type ErrorSink = (line: string) => void;
+export declare function formatError(err: unknown, write?: ErrorSink): void;
+//# sourceMappingURL=format-error.d.ts.map

package/dist/cli/format-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-error.d.ts","sourceRoot":"","sources":["../../src/cli/format-error.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAM9C,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,GAAE,SAAwB,GAAG,IAAI,CA6B/E"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}