sloppatrol 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,7 @@
+Sloppatrol
+Copyright 2026 The Sloppatrol Authors
+
+This product includes software developed at the Sloppatrol project
+(https://github.com/agent-labs-dev/sloppatrol).
+
+Licensed under the Apache License, Version 2.0. See LICENSE.

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+# Sloppatrol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sloppatrol is a team of agents that patrols your repo all day and makes the code cleaner, one small pull request at a time. It never changes what the code does.
+
+It is the code-quality sibling of [Bugpatrol](https://github.com/agent-labs-dev/bugpatrol) and [Speedpatrol](https://github.com/agent-labs-dev/speedpatrol): one `.sloppatrol/` folder, agent roles on any agent runtime, a patrol loop, a live dashboard, and GitHub pull requests.
+
+- The **surveyor** reads the code and records **opportunities**: shallow modules, mixed concerns, hidden dependencies, deep imports, duplicated owners, dead code, tests that mock the team's own code.
+- The **refactorer** makes one opportunity real, in its own git worktree.
+- The **gate** is code, not a model. It decides what is kept: guards on the diff, then every check of your repo.
+- The **assessor** scores code against a rubric of seven quality metrics: for the repo's scorecard, and blind, before and after, for every refactor.
+- The **reviewer** reads a change that passed the gate. It can only reject.
+- Each verified refactor becomes a draft pull request.
+
+```bash
+npx sloppatrol init
+npx sloppatrol
+```
+
+## Why you can trust a refactor
+
+An agent proposes; code decides. A refactor is kept only when every step below passes, and no agent can overrule one.
+
+| Step | What it checks |
+| --- | --- |
+| One side | A **source** refactor changes no test file, so your existing tests prove the behaviour held. A **tests** refactor changes no source file, so the unchanged source proves the new tests right. |
+| Frozen files | No manifest, lockfile, tool config, CI file, snapshot or `.env` changes. No path in `ignore`. |
+| No suppression | No added `@ts-ignore`, `eslint-disable`, `# type: ignore`, `as any`, coverage exclusion, or skipped or focused test. A suppression that moves with its code is fine. |
+| Tests kept | The diff removes no test case, and changes no test file that no check runs (`uncheckedTests`). |
+| Size | At most `guards.maxFiles` files and `guards.maxLines` lines. |
+| Checks | Every command in `checks` passes, as it passes on `main`. Sloppatrol does no work while `main` is red. |
+| Review | A reviewer agent reads the diff against the playbook, and rejects when in doubt. |
+
+| Mutation | A **tests** refactor plants one bug in the unchanged source; a test check must turn red. A test that cannot fail proves nothing. |
+| Improvement | The assessor scores the changed files before and after, blind. The target metrics must go up; no other metric may drop. |
+
+So the stronger your tests, the more Sloppatrol can do. Each check must run the same work on `main` and on every refactor: a command that picks its tests from the diff (`--changed`, `affected`) runs less on `main`, so a failure on a refactor can be old. `sloppatrol doctor` warns about such a check. Where code has no tests, the surveyor proposes **characterization tests** first: tests that pin what the code does today. To move a test from a mocking library to a fake, it makes two refactors: `inject-dependency` (source: add a seam, with today's behaviour as the default), then `replace-mock` (tests: inject a fake through the seam).
+
+## The metrics
+
+An assessor agent scores each file against a fixed rubric, and cites the lines behind each score. For each metric it picks one of five anchored levels, and Sloppatrol shows the result as 0 (worst) to 100 (best): a level of 3 is 75. A scorecard also shows one **overall** score, the mean of all metrics. The rubric anchors every level in things a reader can point at, so scores stay consistent ([ADR 0004](docs/adr/0004-llm-judged-metrics.md)).
+
+| Metric | The question |
+| --- | --- |
+| Simplicity | Can a reader follow each function without holding much in their head? |
+| Modularity | Does the file own one concept, behind a small interface, apart from other concerns? |
+| Injection | Does the code receive what it depends on, or reach out for it? |
+| Purity | How much of the logic lives in pure functions (same input, same output, no side effects), with state and effects kept small and at the edge? |
+| Test quality | Do the tests prove behaviour through the interface, and would they fail if it broke? |
+| Clarity | Does every name, comment and abstraction earn its place? |
+| Agent-friendliness | How hard is it for an agent to change this file wrong, and is it a pattern worth copying? |
+
+The scorecard also checks the repo's own guardrails, from files alone: an agent guide, strict types, a linter, module boundary rules, a pre-commit hook, CI and tests. Each one turns a wrong edit into a failed check. Sloppatrol reports a missing one; it never adds one itself, because tool configs are frozen.
+
+Each commit gets a **scorecard** of the whole repo. A file keeps its scores while its content does not change, and each cycle scores up to `metrics.panel` more files: the most changed first, then the largest. So coverage grows each cycle until every file is scored, and the scorecard shows how much it covers. Every mean is weighted by lines. The surveyor starts from the worst scores, and each opportunity names the metrics it will raise. `sloppatrol score --files 200` scores more now; the dashboard shows the trend.
+
+## The proof
+
+Every pull request carries its proof, built by code and by a blind assessor, never by the agent that wrote the change:
+
+- **It breaks nothing:** the side it changed, the guards it passed, the same checks green on `main` and on the change (with the test counts), and for a tests refactor, the planted bug its tests caught.
+- **It makes the code better:** each metric before and after, the target marked, and the measured lines, nesting, comments, mocks and suppressions.
+- **It follows the repo's rules:** the rule files read, and the reviewer's account of each rule that applies.
+
+## Your repo's rules
+
+Every agent reads your repo's own rules before it acts, and they win over the playbook: `.sloppatrol/instructions.md`, every `AGENTS.md` and `CLAUDE.md` from the repo root down to the changed files (with their `@path` imports), `CONTRIBUTING.md`, `CODING_STANDARDS.md`, `GLOSSARY.md`, and the titles of your decision records. `sloppatrol doctor` lists what it found.
+
+## The playbook
+
+The agents follow a [playbook](playbook/) of top-tier engineering practice, written for agents:
+
+- [Principles](playbook/principles.md): deep modules, seams, ports and adapters, one owner per concept, separation of concerns, dependency injection, single responsibility, small files, no sediment. The vocabulary comes from Ousterhout, Feathers, Fowler, and [Matt Pocock's skills](https://github.com/mattpocock/skills).
+- [Testing](playbook/testing.md): test through the interface; fakes injected through a seam, never a mocking library for your own code.
+- [Smells](playbook/smells.md) and [Safety](playbook/safety.md): what to look for, and the behaviour a refactor must keep.
+- One page per stack, picked from what the census detects: [TypeScript](playbook/stacks/typescript.md), [React and React Native](playbook/stacks/react.md), [Node backends](playbook/stacks/node-backend.md), [Python](playbook/stacks/python.md), [Go](playbook/stacks/go.md), [Swift](playbook/stacks/swift.md), [Kotlin](playbook/stacks/kotlin.md), [Rust](playbook/stacks/rust.md).
+
+Your repo's own rules win over the playbook: `.sloppatrol/instructions.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `GLOSSARY.md`, and the decision records in `docs/adr/`.
+
+## Commands
+
+```text
+Start
+  sloppatrol init              Create .sloppatrol/ with a guess at your checks
+  sloppatrol doctor            Show the config, the agent each role runs on, and what is missing
+
+Run
+  sloppatrol                   Patrol all day: a cycle every patrol.intervalMinutes, with the dashboard
+  sloppatrol --once            One cycle, then stop
+  sloppatrol dashboard         Only the dashboard (http://127.0.0.1:4322)
+
+One step at a time
+  sloppatrol check             Run your checks on the patrolled commit (the oracle)
+  sloppatrol survey            Let the surveyor record opportunities now
+  sloppatrol refactor [id]     Attempt one opportunity now: the best open one, or <id>
+  sloppatrol score             Score the repo now: the metrics of the panel of files
+  sloppatrol publish           Open pull requests for verified refactors (--dry-run)
+
+Read
+  sloppatrol status            The opportunities, the refactors and the agents
+  sloppatrol census            What the surveyor sees: stack, large files, mocks, churn
+  sloppatrol dismiss <id>      Never propose this opportunity again (--reason "...")
+```
+
+## A cycle
+
+```mermaid
+flowchart TB
+  start(["sloppatrol"]) --> pull["Resolve origin/main, check it out"]
+  pull --> base{{"Checks on main<br/>(code)"}}
+  base -->|red| wait
+  base -->|green| survey["Survey, when the backlog is low<br/>LLM · surveyor"]
+  survey --> pick["Pick the strongest opportunity<br/>no file overlap with open PRs"]
+  pick --> refactor["Refactor in a worktree<br/>LLM · refactorer"]
+  refactor --> guards{{"Guards on the diff<br/>(code)"}}
+  guards -->|pass| checks{{"Your checks<br/>(code)"}}
+  checks -->|pass| review["Review<br/>LLM · reviewer, veto only"]
+  review -->|approve| pr["Draft pull request"]
+  guards -->|fail| reject["Rejected: worktree removed"]
+  checks -->|fail| reject
+  review -->|reject| reject
+  pr --> wait["Wait patrol.intervalMinutes"]
+  reject --> wait
+  wait --> pull
+
+  classDef llm fill:#312e81,stroke:#a5b4fc,color:#ffffff
+  classDef code fill:#1e293b,stroke:#64748b,color:#e2e8f0
+  class survey,refactor,review llm
+  class start,pull,base,pick,guards,checks,pr,reject,wait code
+```
+
+- A merged pull request finishes its opportunity. A closed one dismisses it for good.
+- At most `github.maxOpen` pull requests wait at once, and two never touch the same file.
+- An opportunity that fails the gate `maxAttempts` times is exhausted.
+
+## The dashboard
+
+`sloppatrol` serves a dashboard on `http://127.0.0.1:4322` while it patrols (`--no-dashboard` turns it off; `sloppatrol dashboard` serves it alone). It shows, live:
+
+- **Agents**: what the patrol, the surveyor, the refactorer, the gate and the reviewer do now.
+- **Refactors**: each attempt as a pipeline (refactorer → guards → checks → mutation → metrics → review → pull request), with its full proof.
+- **Scorecard**: each metric's score and trend over commits, and every file of the panel with the evidence behind its scores.
+- **Checks**: every check run on `main`, on each refactor, and each run the refactorer starts itself, with the output of each check.
+- **Backlog**: the opportunities by status, with the problem, the change and the files.
+- **Sessions**: every agent session as a timeline of its tool calls.
+
+## Any agent, any model
+
+By default every role runs on the agent CLI you have installed: `agent: auto` picks `claude`, then `codex`, then `opencode`, from your `PATH`. The surveyor and the reviewer get read-only access; the refactorer gets edit access in its own worktree. Every role reaches Sloppatrol through its tools over a local MCP server.
+
+```yaml
+agent: auto                       # or claude | codex | opencode
+agents:
+  reviewer: { use: codex }        # a second opinion from another agent
+  surveyor:
+    use: { runtime: model, via: openrouter, model: anthropic/claude-opus-5.5 }
+```
+
+`{ runtime: model, via: anthropic | openai | openrouter | custom, model }` runs Sloppatrol's own tool loop on an API key. `{ runtime: cli, command: "..." }` runs any command, with `{prompt}`, `{mcp}`, `{mcpUrl}` and `{workdir}` filled in.
+
+## Configuration
+
+```yaml
+# .sloppatrol/sloppatrol.yml
+agent: auto
+prepare: [pnpm install --frozen-lockfile]   # each fresh checkout and worktree
+checks:                                     # the oracle
+  - { name: typecheck, run: pnpm typecheck }
+  - { name: lint, run: pnpm lint }
+  - { name: test, run: pnpm test, tests: true }   # tests: true marks the checks a planted bug must turn red
+focus: [src/**]                             # where the surveyor looks (default: everywhere)
+ignore: [src/generated/**]                  # what no agent may change
+uncheckedTests: [tests/e2e/**]              # tests no check runs: no refactor may change them
+guards: { maxFiles: 12, maxLines: 600 }
+metrics: { enabled: true, panel: 100, tolerance: 0.5, judges: 3 }   # panel: files newly scored per cycle
+agents:
+  surveyor: { minBacklog: 3, maxPerSurvey: 8 }
+  refactorer: { maxPerCycle: 1, maxAttempts: 2 }
+  reviewer: { enabled: true }
+github: { enabled: true, draft: true, maxOpen: 3, labels: [sloppatrol] }
+patrol: { intervalMinutes: 60, pull: origin/main }
+```
+
+Every role also takes `maxSteps`, `timeoutMinutes` and `budgetUsd` (model runtime). Pull requests open with your `gh` login.
+
+`.sloppatrol/sloppatrol.yml` and `.sloppatrol/instructions.md` are committed. `.sloppatrol/runs/` holds local data (checkouts, worktrees, opportunities, refactors, check runs, sessions) as plain JSON, and git ignores it.
+
+## Docs
+
+- [Glossary](GLOSSARY.md)
+- [Decisions](docs/adr/): why it works this way.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm check      # Biome, module boundaries (dependency-cruiser), types
+pnpm knip
+```
+
+Sloppatrol follows its own playbook: each folder in `src/` is a deep module, other modules reach it only through its root files, the CLI is the only composition root, and the tests use real git repos, real processes, an in-memory GitHub and a scripted agent, with no mocking library.
+
+## License
+
+Apache-2.0

package/dist/agents/index.d.ts

@@ -0,0 +1,9 @@
+import type { RoleRuntime } from '../config/index.js';
+import type { Runtime } from './lib/types.js';
+export { editTools, repoTools } from './lib/repo-tools.js';
+export { finishTool, str, strList, tool } from './lib/schema.js';
+export { runRole } from './lib/session.js';
+export type { RoleOutcome } from './lib/types.js';
+/** Builds the runtime for a role. The CLI injects this; tests can inject their own. */
+export type RuntimeFactory = (use: RoleRuntime) => Runtime;
+export declare const createRuntime: RuntimeFactory;

package/dist/agents/index.js

@@ -0,0 +1,7 @@
+import { CliRuntime } from './lib/cli-runtime.js';
+import { ModelRuntime } from './lib/model-runtime.js';
+export { editTools, repoTools } from './lib/repo-tools.js';
+export { finishTool, str, strList, tool } from './lib/schema.js';
+export { runRole } from './lib/session.js';
+export const createRuntime = (use) => use.runtime === 'cli' ? new CliRuntime(use) : new ModelRuntime(use);
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAGtD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAM3C,MAAM,CAAC,MAAM,aAAa,GAAmB,CAAC,GAAG,EAAE,EAAE,CACnD,GAAG,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC"}

package/dist/agents/lib/cli-runtime.d.ts

@@ -0,0 +1,17 @@
+import type { RoleRuntime } from '../../config/index.js';
+import type { EventSink, RoleOutcome, RoleTask, Runtime } from './types.js';
+type CliUse = Extract<RoleRuntime, {
+    runtime: 'cli';
+}>;
+/**
+ * A local agent CLI (claude, codex, opencode, or any command) runs the role.
+ * It gets the prompt on stdin and in `{prompt}`, and the role's tools over a
+ * local MCP server in `{mcp}` / `{mcpUrl}`.
+ */
+export declare class CliRuntime implements Runtime {
+    private readonly use;
+    readonly label: string;
+    constructor(use: CliUse);
+    run(task: RoleTask, emit: EventSink): Promise<RoleOutcome>;
+}
+export {};

package/dist/agents/lib/cli-runtime.js

@@ -0,0 +1,156 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { stopGroup, track } from '../../processes/index.js';
+import { serveTools } from './mcp-server.js';
+function quote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** One line of output as feed text: a JSON event becomes its message, or nothing. */
+function displayLine(line) {
+    if (!line.trimStart().startsWith('{'))
+        return line;
+    try {
+        const event = JSON.parse(line);
+        if (event.type === 'item.completed' && typeof event.item?.text === 'string')
+            return event.item.text;
+        if (event.type === 'text' && typeof event.part?.text === 'string')
+            return event.part.text;
+        return '';
+    }
+    catch {
+        return line;
+    }
+}
+/**
+ * What a CLI printed. `claude -p --output-format json` prints one object with
+ * the result and its cost; `codex exec --json` and `opencode run --format
+ * json` print one event per line.
+ */
+function parseCliOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+        try {
+            const claude = JSON.parse(trimmed);
+            if (typeof claude.result === 'string') {
+                return {
+                    text: claude.result,
+                    costUsd: typeof claude.total_cost_usd === 'number' ? claude.total_cost_usd : 0,
+                    ...(claude.is_error === true ? { error: claude.result } : {}),
+                };
+            }
+        }
+        catch {
+            /* not one object: read it line by line */
+        }
+    }
+    const text = trimmed.split('\n').map(displayLine).filter(Boolean).join('\n');
+    return { text, costUsd: 0 };
+}
+/**
+ * A local agent CLI (claude, codex, opencode, or any command) runs the role.
+ * It gets the prompt on stdin and in `{prompt}`, and the role's tools over a
+ * local MCP server in `{mcp}` / `{mcpUrl}`.
+ */
+export class CliRuntime {
+    use;
+    label;
+    constructor(use) {
+        this.use = use;
+        this.label = `cli:${use.label}`;
+    }
+    async run(task, emit) {
+        const temp = await mkdtemp(join(tmpdir(), 'sloppatrol-agent-'));
+        let summary = '';
+        let finished = false;
+        let steps = 0;
+        const mcp = await serveTools(task.tools, {
+            maxCalls: task.maxSteps,
+            onStart(name, input) {
+                emit({ kind: 'tool-call', summary: `Called ${name}.`, tool: name, input });
+            },
+            onCall(name, _input, result, ms) {
+                steps++;
+                emit({
+                    kind: 'tool-result',
+                    summary: result.summary ?? `${name}: ${result.text.split('\n')[0]?.slice(0, 160) ?? ''}`,
+                    tool: name,
+                    output: result.text.slice(0, 2000),
+                    durationMs: ms,
+                });
+                if (result.done) {
+                    summary = result.text;
+                    finished = true;
+                }
+            },
+        });
+        try {
+            const prompt = `${task.system}\n\n${task.prompt}`;
+            const promptFile = join(temp, 'prompt.md');
+            const mcpFile = join(temp, 'mcp.json');
+            await writeFile(promptFile, prompt);
+            await writeFile(mcpFile, JSON.stringify({ mcpServers: { sloppatrol: { type: 'http', url: mcp.url } } }));
+            const values = {
+                prompt: promptFile,
+                mcp: mcpFile,
+                mcpUrl: mcp.url,
+                workdir: task.workdir,
+            };
+            const command = (this.use.command ?? '').replace(/\{(prompt|mcp|mcpUrl|workdir)\}/g, (_, name) => quote(values[name]));
+            const child = spawn('/bin/sh', ['-c', command], {
+                cwd: task.workdir,
+                // run_checks runs for minutes; Claude Code's default MCP tool
+                // timeout abandons it and the agent calls it again over the first.
+                env: { MCP_TOOL_TIMEOUT: String(task.timeoutMs), ...process.env },
+                detached: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            track(child);
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(prompt);
+            let stdout = '';
+            let stderr = '';
+            let partial = '';
+            child.stdout.on('data', (chunk) => {
+                stdout += chunk.toString();
+                const lines = (partial + chunk.toString()).split('\n');
+                partial = lines.pop() ?? '';
+                const text = lines.map(displayLine).filter(Boolean).join('\n').trim();
+                if (text)
+                    emit({ kind: 'thought', summary: text.slice(-300) });
+            });
+            child.stderr.on('data', (chunk) => {
+                stderr += chunk.toString();
+            });
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                stopGroup(child);
+            }, task.timeoutMs);
+            const code = await new Promise((done, reject) => {
+                child.once('error', reject);
+                child.once('exit', done);
+            }).finally(() => clearTimeout(timer));
+            const parsed = parseCliOutput(stdout);
+            if (parsed.text)
+                emit({ kind: 'thought', summary: parsed.text.slice(-300), costUsd: parsed.costUsd });
+            const base = { steps, costUsd: parsed.costUsd, summary: summary || parsed.text, finished };
+            if (timedOut)
+                return { ...base, stop: 'timeout' };
+            if (code !== 0 || parsed.error) {
+                return {
+                    ...base,
+                    stop: 'error',
+                    error: parsed.error || stderr.trim().split('\n').slice(-20).join('\n') || `CLI exited ${code}`,
+                };
+            }
+            return { ...base, stop: 'done' };
+        }
+        finally {
+            await mcp.close();
+            await rm(temp, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=cli-runtime.js.map

package/dist/agents/lib/cli-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-runtime.js","sourceRoot":"","sources":["../../../src/agents/lib/cli-runtime.ts"],"names":[],"mappings":"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"}

package/dist/agents/lib/mcp-server.d.ts

@@ -0,0 +1,22 @@
+import type { Tool, ToolResult } from './types.js';
+type Options = {
+    /** A call starts: a person can see a slow tool run while it runs. */
+    onStart?: (name: string, input: Record<string, unknown>) => void;
+    onCall?: (name: string, input: Record<string, unknown>, result: ToolResult, ms: number) => void;
+    maxCalls?: number;
+};
+/** Runs one tool call under the step budget. `finish` is always allowed. */
+export declare function callTool(tools: Tool[], name: string, input: Record<string, unknown>, budget: {
+    calls: number;
+    max: number;
+}): Promise<ToolResult>;
+/**
+ * Serves a role's tools to a CLI agent over streamable HTTP. Stateless: each
+ * request gets its own server and transport. The step budget lives out here,
+ * so it holds across every session the CLI opens.
+ */
+export declare function serveTools(tools: Tool[], options?: Options): Promise<{
+    url: string;
+    close(): Promise<void>;
+}>;
+export {};