salmon-loop 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 salmonloop
+
+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,144 @@
+# Salmon-Loop
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+SalmonLoop is a chat-first coding agent CLI for repositories that care about safety, auditability, and clean diffs.
+Open `s8p`, describe the job, and let the loop stay disciplined about verification, rollback, and protecting user data.
+
+## Why SalmonLoop
+
+- **Agent, with guardrails**: SalmonLoop can plan, patch, verify, and serve through ACP/A2A, but it does not get a free pass to mutate your repo however it wants.
+- **Chat-first UX**: `s8p` drops straight into the main experience.
+- **Patch-first under the hood**: Changes are generated as diffs, not mystery rewrites.
+- **Verify before success**: A run is only successful if your verification command passes.
+- **Built for messy real repos**: The worktree strategy keeps dirty workspaces safer by isolating execution and applying changes back carefully.
+- **Observable**: Sessions, audit events, snapshots, and structured outputs make it easier to inspect what happened.
+
+## The Vibe
+
+SalmonLoop is not trying to be an always-on autopilot that wanders around your codebase.
+It is a disciplined engineering agent: focused instructions in, reviewable patches out.
+
+The execution model stays pragmatic:
+
+1. **Deterministic tools** for cheap, reliable operations.
+2. **Microtasks** for small logic bridges and context assembly.
+3. **Sub-agents** for multi-step tasks that actually need agent behavior.
+
+## Quickstart
+
+### 1. Install
+
+```bash
+npm install -g salmon-loop
+# or
+bun install -g salmon-loop
+```
+
+Requires `bun >= 1.3.9` if you use Bun as your package manager.
+
+### 2. Configure an LLM
+
+Create a local `.env` and set the preferred environment variables:
+
+```bash
+SALMONLOOP_API_KEY=your-key
+SALMONLOOP_BASE_URL=https://api.openai.com/v1
+SALMONLOOP_MODEL=gpt-4.1-mini
+```
+
+Legacy `S8P_*` aliases still work, but new setups should prefer `SALMONLOOP_*`.
+
+### 3. Start chat mode
+
+```bash
+s8p
+```
+
+That is the primary product surface. Open it inside the repository you want to work on, then give it a task and a verification command in chat.
+
+Example prompt:
+
+```bash
+Fix the null handling in src/user.ts and verify with bun run test
+```
+
+### 4. Use `run` when you want one-shot automation
+
+```bash
+s8p run \
+  --repo /path/to/your/repo \
+  --instruction "Fix the null handling in src/user.ts" \
+  --verify "bun run test" \
+  --checkpoint-strategy worktree
+```
+
+### 5. Serve it as an agent
+
+```bash
+s8p serve
+```
+
+This starts the built-in agent server stack for A2A and local sidecar integration.
+
+## What Users Usually Care About
+
+- **Chat mode**: `s8p`
+- **Single run**: `s8p run --instruction "..." --verify "..."` when chat is not the right fit
+- **Context only**: `s8p context -i "..."`
+- **Snapshots**: `s8p snap ls`, `s8p snap show <hash>`, `s8p checkout <hash>`
+- **Headless / CI**: `--output-format json` or `--output-format stream-json`
+
+More detail lives in [docs/user/cli.md](docs/user/cli.md), [docs/user/config.md](docs/user/config.md), and [docs/reference/headless.md](docs/reference/headless.md).
+
+## Safety Model
+
+SalmonLoop is opinionated here, on purpose.
+
+- **User data safety comes first**: the execution contract is designed to avoid unintended writes to the main workspace and Git index.
+- **Dirty workspace support is explicit**: use `worktree` when you need isolation and safer apply-back behavior.
+- **Rollback is part of the design**: failed verification is not a soft warning; it is a failed run.
+- **Read-only phases stay read-only**: exploration, planning, and validation do not get casual write access.
+
+If you want the exact contract, start with [docs/design/execution-contract.md](docs/design/execution-contract.md).
+
+## Extensibility
+
+- **Language plugins**: add support under `.salmonloop/languages/<lang>/index.js`
+- **External tools and MCP**: configure extensions under `.salmonloop/config/`
+See [docs/user/plugins.md](docs/user/plugins.md) and [docs/user/extensions.md](docs/user/extensions.md).
+
+## Contributing
+
+For contributors, the short version is:
+
+```bash
+bun run setup:hooks
+bun run verify
+```
+
+`bun run verify` is the delivery bar for code changes in this repository.
+
+Useful docs:
+
+- [docs/contributing/contributing.md](docs/contributing/contributing.md)
+- [docs/contributing/testing.md](docs/contributing/testing.md)
+- [docs/contributing/coding-standards.md](docs/contributing/coding-standards.md)
+- [docs/contributing/release.md](docs/contributing/release.md)
+- [docs/contributing/security.md](docs/contributing/security.md)
+
+## Docs Map
+
+The documentation hub is [docs/README.md](docs/README.md).
+
+Good starting points:
+
+- [docs/getting-started/overview.md](docs/getting-started/overview.md)
+- [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)
+- [docs/user/execution-safety.md](docs/user/execution-safety.md)
+- [docs/design/execution-limits.md](docs/design/execution-limits.md)
+- [docs/reference/changelog.md](docs/reference/changelog.md)
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,144 @@
+# Salmon-Loop
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+SalmonLoop 是一个以对话为主入口的 coding agent CLI，适合对安全性、可审计性和干净 diff 有要求的代码仓库。
+直接运行 `s8p` 就会进入主体验，后面的执行仍然会严格受验证、回滚和用户数据保护约束。
+
+## 为什么用 SalmonLoop
+
+- **是 Agent，但有边界**：它可以规划、打补丁、验证，也能通过 ACP / A2A 对外提供 Agent 能力，但不会无约束地乱改仓库。
+- **对话优先**：`s8p` 直接进入主体验。
+- **补丁优先**：底层依然默认产出 diff，而不是神秘的大段重写。
+- **验证通过才算成功**：你的验证命令不过，任务就不算完成。
+- **适合真实仓库**：`worktree` 策略可以在脏工作区里隔离执行，再谨慎地 apply back。
+- **过程可追踪**：会话、审计事件、快照和结构化输出都方便排查问题。
+
+## 整体气质
+
+SalmonLoop 不是那种会一直在代码库里游荡的自动驾驶型 Agent。
+它更像一个纪律严格的工程 Agent：输入明确指令，输出可审查的补丁。
+
+它的执行模型也比较务实：
+
+1. **确定性工具** 处理便宜、可靠的操作。
+2. **微任务** 负责小范围逻辑拼装和上下文补全。
+3. **子代理** 只在确实需要多步推理时出场。
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+npm install -g salmon-loop
+# 或
+bun install -g salmon-loop
+```
+
+如果你用 Bun 作为包管理器，要求 `bun >= 1.3.9`。
+
+### 2. 配置 LLM
+
+新建本地 `.env`，优先使用这些环境变量：
+
+```bash
+SALMONLOOP_API_KEY=your-key
+SALMONLOOP_BASE_URL=https://api.openai.com/v1
+SALMONLOOP_MODEL=gpt-4.1-mini
+```
+
+旧的 `S8P_*` 别名仍然兼容，但新配置建议统一用 `SALMONLOOP_*`。
+
+### 3. 进入对话模式
+
+```bash
+s8p
+```
+
+这是主推入口。进入目标仓库后，直接在对话里给它任务和验证命令即可。
+
+例如：
+
+```bash
+Fix the null handling in src/user.ts and verify with bun run test
+```
+
+### 4. 需要一次性执行时再用 `run`
+
+```bash
+s8p run \
+  --repo /path/to/your/repo \
+  --instruction "Fix the null handling in src/user.ts" \
+  --verify "bun run test" \
+  --checkpoint-strategy worktree
+```
+
+### 5. 作为 Agent 服务运行
+
+```bash
+s8p serve
+```
+
+这会启动内置的 Agent 服务栈，用于 A2A 和本地 sidecar 集成。
+
+## 用户最常用的能力
+
+- **对话模式**：`s8p`
+- **单次执行**：`s8p run --instruction "..." --verify "..."`，适合非交互场景
+- **只构建上下文**：`s8p context -i "..."`
+- **快照管理**：`s8p snap ls`、`s8p snap show <hash>`、`s8p checkout <hash>`
+- **Headless / CI**：`--output-format json` 或 `--output-format stream-json`
+
+更完整的用法可以看 [docs/user/cli.md](docs/user/cli.md)、[docs/user/config.md](docs/user/config.md)、[docs/reference/headless.md](docs/reference/headless.md)。
+
+## 安全模型
+
+SalmonLoop 在这里是故意严格的。
+
+- **用户数据安全优先**：执行契约明确限制对主工作区和 Git index 的非预期写入。
+- **脏工作区支持是显式设计**：需要隔离执行和更安全的 apply-back 时，就用 `worktree`。
+- **回滚不是附属功能**：验证失败就是失败，不会含糊带过。
+- **只读阶段必须只读**：探索、规划、验证阶段不会随便获得写权限。
+
+如果你想看完整契约，先从 [docs/design/execution-contract.md](docs/design/execution-contract.md) 开始。
+
+## 扩展能力
+
+- **语言插件**：放到 `.salmonloop/languages/<lang>/index.js`
+- **外部工具和 MCP**：通过 `.salmonloop/config/` 配置
+相关文档见 [docs/user/plugins.md](docs/user/plugins.md) 和 [docs/user/extensions.md](docs/user/extensions.md)。
+
+## 参与贡献
+
+对贡献者来说，最短路径是：
+
+```bash
+bun run setup:hooks
+bun run verify
+```
+
+这个仓库里，`bun run verify` 就是代码交付线。
+
+建议先看：
+
+- [docs/contributing/contributing.md](docs/contributing/contributing.md)
+- [docs/contributing/testing.md](docs/contributing/testing.md)
+- [docs/contributing/coding-standards.md](docs/contributing/coding-standards.md)
+- [docs/contributing/release.md](docs/contributing/release.md)
+- [docs/contributing/security.md](docs/contributing/security.md)
+
+## 文档入口
+
+完整文档目录在 [docs/README.md](docs/README.md)。
+
+推荐先读这些：
+
+- [docs/getting-started/overview.md](docs/getting-started/overview.md)
+- [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)
+- [docs/user/execution-safety.md](docs/user/execution-safety.md)
+- [docs/design/execution-limits.md](docs/design/execution-limits.md)
+- [docs/reference/changelog.md](docs/reference/changelog.md)
+
+## License
+
+MIT

package/dist/cli/argv/headless-detection.js

@@ -0,0 +1,60 @@
+function readFlagValue(tokens, index) {
+    const token = tokens[index];
+    const eq = token.indexOf('=');
+    if (eq !== -1)
+        return { value: token.slice(eq + 1), nextIndex: index };
+    const next = tokens[index + 1];
+    if (typeof next === 'string')
+        return { value: next, nextIndex: index + 1 };
+    return { value: undefined, nextIndex: index };
+}
+export function detectHeadlessOutputFromArgv(argv) {
+    const tokens = argv.slice(2);
+    let repoPath;
+    let instruction;
+    let resumeSessionId;
+    let outputFormat;
+    let outputProfile;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token === '-r' || token === '--repo' || token.startsWith('--repo=')) {
+            const { value, nextIndex } = readFlagValue(tokens, i);
+            repoPath = value;
+            i = nextIndex;
+            continue;
+        }
+        if (token === '-p' || token === '--print' || token.startsWith('--print=')) {
+            const { value, nextIndex } = readFlagValue(tokens, i);
+            instruction = value;
+            i = nextIndex;
+            continue;
+        }
+        if (token === '--resume' || token.startsWith('--resume=')) {
+            const { value, nextIndex } = readFlagValue(tokens, i);
+            resumeSessionId = value;
+            i = nextIndex;
+            continue;
+        }
+        if (token === '--output-format' || token.startsWith('--output-format=')) {
+            const { value, nextIndex } = readFlagValue(tokens, i);
+            outputFormat = value;
+            i = nextIndex;
+            continue;
+        }
+        if (token === '--output-profile' || token.startsWith('--output-profile=')) {
+            const { value, nextIndex } = readFlagValue(tokens, i);
+            outputProfile = value;
+            i = nextIndex;
+            continue;
+        }
+    }
+    const normalized = outputFormat === 'json' || outputFormat === 'stream-json' ? outputFormat : null;
+    return {
+        repoPath,
+        instruction,
+        resumeSessionId,
+        outputFormat: normalized,
+        outputProfile,
+    };
+}
+//# sourceMappingURL=headless-detection.js.map

package/dist/cli/argv/print-mode.js

@@ -0,0 +1,60 @@
+export const CLI_ROOT_COMMANDS = new Set([
+    'run',
+    'serve',
+    'chat',
+    'context',
+    'restore',
+    'checkout',
+    'snapshot',
+    'snap',
+]);
+const PRINT_MODE_FLAGS_WITH_VALUES = new Set([
+    '-p',
+    '--print',
+    '-r',
+    '--repo',
+    '--resume',
+    '-v',
+    '--verify',
+    '-cs',
+    '--checkpoint-strategy',
+    '--llm-output',
+]);
+function startsWithAny(value, prefixes) {
+    for (const prefix of prefixes) {
+        if (value.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+export function rewriteArgvForPrintMode(argv) {
+    const tokens = argv.slice(2);
+    const hasPrint = tokens.some((t) => t === '-p' || t === '--print' || t.startsWith('--print='));
+    if (!hasPrint)
+        return argv;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token === '--')
+            break;
+        if (PRINT_MODE_FLAGS_WITH_VALUES.has(token)) {
+            i += 1;
+            continue;
+        }
+        if (startsWithAny(token, [
+            '--print=',
+            '--repo=',
+            '--resume=',
+            '--verify=',
+            '--checkpoint-strategy=',
+            '--llm-output=',
+        ])) {
+            continue;
+        }
+        if (token.startsWith('-'))
+            continue;
+        if (CLI_ROOT_COMMANDS.has(token))
+            return argv;
+    }
+    return [...argv.slice(0, 2), 'run', ...tokens];
+}
+//# sourceMappingURL=print-mode.js.map