sous-mcp 0.1.0__tar.gz

sous_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,116 @@
+name: Bug report
+description: Something in sous behaves differently than documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Found a way out of the sandbox — writing outside `project_root`,
+        running a non-allowlisted command, leaking secrets past the env
+        scrub? Please close this and use
+        [private reporting](https://github.com/krcm0209/sous/security/advisories/new)
+        instead. See [SECURITY.md](https://github.com/krcm0209/sous/blob/main/SECURITY.md).
+
+  - type: checkboxes
+    id: prerequisites
+    attributes:
+      label: Prerequisites
+      options:
+        - label: I am on an Apple silicon Mac (sous does not run anywhere else)
+          required: true
+        - label: I searched existing issues
+          required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Which commit are you running?
+      description: >-
+        sous has no released versions yet, so the commit identifies the build:
+        run `git rev-parse --short HEAD` in the checkout you installed from.
+      placeholder: "02278fb"
+    validations:
+      required: true
+
+  - type: input
+    id: macos
+    attributes:
+      label: macOS version and chip
+      placeholder: "15.5, M4 Pro, 48 GB"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: "`uv run python -V`"
+      placeholder: "3.14.7"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: model
+    attributes:
+      label: Model
+      description: >-
+        Which backend loads depends on this — a model with a `vision_config`
+        runs through VLMEngine, everything else through LMEngine.
+      options:
+        - The default (mlx-community/Qwen3.8-27B-mxfp8)
+        - A different MLX model
+        - Not applicable — the bug does not involve the worker
+    validations:
+      required: true
+
+  - type: input
+    id: model_id
+    attributes:
+      label: Model id, if not the default
+      placeholder: "mlx-community/Qwen3-0.6B-4bit"
+
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: >-
+        What you delegated, what you expected, and what sous did instead.
+        Include the exact task instructions if the worker misbehaved.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. sous serve
+        2. Ask Claude to delegate: "..."
+        3. ...
+    validations:
+      required: true
+
+  - type: markdown
+    attributes:
+      value: >-
+        **Before pasting a transcript:** every worker turn is journaled, so
+        transcripts routinely contain files from the project sous was working
+        in. Please redact anything you would not publish.
+
+  - type: textarea
+    id: transcript
+    attributes:
+      label: Transcript excerpt (optional)
+      description: >-
+        Relevant lines from `~/.sous/tasks/<id>/transcript.jsonl`. The report
+        of a failed task includes its `transcript_path`.
+      render: text
+
+  - type: textarea
+    id: config
+    attributes:
+      label: Relevant config (optional)
+      description: >-
+        The parts of `~/.sous/config.toml` that matter — usually
+        `[commands] allowlist` for anything involving command execution.
+      render: toml

sous_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,7 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/krcm0209/sous/security/advisories/new
+    about: >-
+      Sandbox escapes, allowlist bypasses, environment leaks and similar go
+      through private disclosure — please do not open a public issue for them.

sous_mcp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,50 @@
+name: Feature request
+description: Suggest a capability or a change in behaviour
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Worth skimming
+        [what's in scope](https://github.com/krcm0209/sous/blob/main/CONTRIBUTING.md#whats-in-scope)
+        first — it saves writing up something the project has already decided
+        against.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you hitting?
+      description: >-
+        The situation that prompted this, rather than the solution. What were
+        you trying to get sous to do?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What should sous do instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered (optional)
+      description: >-
+        Including anything you tried that nearly worked — a config change, a
+        different allowlist entry, a different model.
+
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope
+      options:
+        - label: >-
+            I understand sous deliberately targets Apple silicon, and that
+            running the worker elsewhere is not a current goal
+          required: true
+        - label: >-
+            This does not widen what a worker may do without human approval —
+            or if it does, I have said so explicitly above
+          required: true

sous_mcp-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!--
+CI already reports whether lint, types, and the fast test suite pass, so this
+template only asks for the things it cannot check for you.
+-->
+
+## What and why
+
+<!-- What changed, and what problem it solves. The diff covers what; the why
+     is the part that is hard to recover later. -->
+
+## How you verified it
+
+<!-- CI runs `pytest -m "not model"` and nothing else. The model-marked engine
+     tests and scripts/e2e_smoke.py never run there, so if you touched the
+     engine layer, this is the only place that evidence exists. Commands and
+     their output beat "tested locally". -->
+
+## Checklist
+
+- [ ] Touched the engine layer (`src/sous/engine/`): ran `uv run pytest -m model`,
+      and/or `uv run python scripts/e2e_smoke.py`
+- [ ] Touched the sandbox (`src/sous/toolexec.py`): included a test that fails
+      without this change
+- [ ] Fixing something intermittent: ran it repeatedly rather than once, and
+      said how many times above
+- [ ] Commit subject follows [Conventional Commits](https://www.conventionalcommits.org/)
+
+<!-- Strike out or delete any line that does not apply. -->

sous_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

sous_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,131 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+# A newer push to the same branch/PR makes the in-flight run obsolete.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Fail loudly if uv.lock and pyproject.toml have drifted, rather than
+  # silently re-resolving to versions nobody tested.
+  #
+  # UV_LOCKED, not UV_FROZEN: --frozen means "use the lockfile as-is without
+  # checking it", which downgrades `uv lock --check` to a validity-only check
+  # and lets real drift pass with exit 0. --locked asserts the lockfile is
+  # up to date and fails otherwise, for both `uv lock --check` and `uv sync`.
+  UV_LOCKED: "1"
+
+# setup-uv is pinned to an exact release: it stopped publishing floating major
+# tags after v7, so `@v10` does not resolve. Dependabot keeps it current.
+jobs:
+  lint:
+    name: Lint & lockfile
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: uv.lock is in sync with pyproject.toml
+        run: uv lock --check
+
+      # Linting needs only the pure-Python dev group. Skipping the project
+      # install keeps mlx (and therefore macOS) out of this job entirely.
+      - name: Install dev tooling
+        run: uv sync --only-group dev --no-install-project
+
+      - name: ruff check
+        run: uv run --no-sync ruff check --output-format=github .
+
+      - name: ruff format
+        run: uv run --no-sync ruff format --check .
+
+  test:
+    name: Tests
+    # Apple silicon: mlx-metal is sys_platform == 'darwin' gated, and this is
+    # the only platform sous actually targets.
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Install project and dev dependencies
+        run: uv sync
+
+      # The `model` marker needs a multi-GB MLX model download — local only.
+      # `slow` tests (process-group kills) do run here.
+      - name: pytest
+        run: uv run --no-sync pytest -m "not model"
+
+  typecheck:
+    name: Type check
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      # ty needs the real dependency types resolved, so this job installs
+      # the full environment rather than the dev group alone.
+      - name: Install project and dev dependencies
+        run: uv sync
+
+      - name: ty
+        run: uv run --no-sync ty check
+
+  build:
+    name: Build sdist + wheel
+    runs-on: macos-15
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [lint, test, typecheck]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: uv build
+        run: uv build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # Trusted publishing (OIDC): PyPI trusts this repo's `pypi` environment
+  # directly, so no API token exists anywhere to leak. Requires the
+  # trusted-publisher registration on pypi.org (project sous-mcp, owner
+  # krcm0209, repo sous, workflow ci.yml, environment pypi) BEFORE the
+  # first tag is pushed.
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [build]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sous-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

sous_mcp-0.1.0/.github/workflows/publish-mcp-registry.yml

@@ -0,0 +1,54 @@
+name: Publish to MCP Registry
+
+# Deliberately manual (workflow_dispatch, never a tag trigger): listing in
+# the official registry syndicates to Smithery, PulseMCP, and friends —
+# i.e. it turns discovery ON. Run it from the Actions tab when the project
+# is ready for that.
+on:
+  workflow_dispatch:
+
+permissions:
+  id-token: write # GitHub OIDC proves the io.github.krcm0209/* namespace
+  contents: read
+
+jobs:
+  publish:
+    name: Publish server.json
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # The registry verifies ownership by reading the mcp-name marker out
+      # of the PyPI package's rendered README, so the exact version the
+      # entry references must already be live on PyPI — fail fast here
+      # instead of publishing a listing that points at nothing. The
+      # version-specific endpoint 404s for unpublished versions, which is
+      # the check; PyPI's latest-version field would wrongly reject a valid
+      # older release.
+      - name: Check server.json versions agree and are live on PyPI
+        run: |
+          declared=$(jq -r '.version' server.json)
+          pkgver=$(jq -r '.packages[0].version' server.json)
+          echo "server.json version: $declared / package version: $pkgver"
+          test "$declared" = "$pkgver"
+          curl -sf "https://pypi.org/pypi/sous-mcp/${pkgver}/json" > /dev/null \
+            || { echo "sous-mcp ${pkgver} is not live on PyPI"; exit 1; }
+
+      # Pinned and checksum-verified: this job can mint registry-publishing
+      # OIDC credentials, so it must never execute a mutable `latest`
+      # binary. Bump the pin deliberately; checksums come from the
+      # registry_<version>_checksums.txt asset on the same release.
+      - name: Install mcp-publisher (pinned, checksum-verified)
+        env:
+          MCP_PUBLISHER_VERSION: v1.8.1
+          MCP_PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+        run: |
+          curl -sfLO "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz"
+          echo "${MCP_PUBLISHER_SHA256}  mcp-publisher_linux_amd64.tar.gz" | sha256sum -c -
+          tar xzf mcp-publisher_linux_amd64.tar.gz mcp-publisher
+
+      - name: Authenticate to the MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish
+        run: ./mcp-publisher publish

sous_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/

sous_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

sous_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+sous is an MCP daemon that delegates mechanical coding tasks from Claude
+Code to a sandboxed local MLX worker. macOS / Apple silicon only. The goal
+is plan economics: volume output is generated locally for free so heavy
+Claude Code use stretches further — evaluate features against that goal.
+
+## Commands
+
+- `uv sync` — full setup (installs Python 3.14 and everything). Never pip.
+- `uv run pytest -m "not model"` — the test suite. `model`-marked tests
+  download multi-GB weights and are local/manual only; `slow`-marked tests
+  spawn real processes and take seconds — run them, don't skip or mock them.
+- `uv run ty check` — type check (ty, NOT mypy; covers tests and scripts too).
+- `uv run ruff check . && uv run ruff format --check .` — lint/format.
+- `uv lock --check` — lockfile sync. CI runs exactly these four jobs.
+- `uv run python scripts/e2e_smoke.py` — agent loop against a tiny real model.
+
+## Gotchas
+
+- Python >=3.14 required. `except A, B:` without parentheses (PEP 758, e.g.
+  src/sous/cli.py) is valid 3.14 syntax, not a Python 2 bug — don't "fix" it.
+- Type-suppression pragmas are `# ty: ignore[rule]`, never `# type: ignore`.
+- mlx / mlx_lm / mlx_vlm imports are deliberately function-local (absent on
+  non-macOS; the lint CI job runs on ubuntu; tests use fake engines). Don't
+  hoist them to module level.
+- e2e_smoke.py often ends `failed` or `budget-exhausted` even when it worked —
+  the 0.6B model can't reliably emit `finish`. Judge by hello.txt content.
+- Budget exhaustion is `done` with outcome `budget-exhausted`, never `failed`.
+- Tests must never touch the real `~/.sous` — always pass tmp_path-based
+  config_path/data_dir.
+- `docs/superpowers/**` are point-in-time design/plan records: never edit,
+  reformat, or "sync" them with current code (they are also ruff-excluded).
+
+## Security boundary
+
+`src/sous/toolexec.py` is the sandbox (path confinement, command allowlist,
+process-group kill, stat audit). Any change there needs a test that fails
+without it. Odd-looking code is load-bearing (the un-reaped zombie during
+the group kill, EPERM suppression, ctime in the audit) — read the comments
+before touching. Suspected-flaky tests get run in a loop, not judged on one
+pass.
+
+## Workflow
+
+- Comments explain non-obvious *why*; never restate what code does.
+- Conventional Commits (`feat:`/`fix:`/`docs:`/...), imperative lowercase
+  subject, *why* in the body.
+- `main` is protected: branch + PR, all four CI jobs green.

sous_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to sous
+
+Thanks for looking. Contributions are welcome — bug reports especially.
+
+A few things worth knowing before you spend time on this.
+
+## Before you start
+
+**You need an Apple silicon Mac.** This is not a preference. `mlx-metal` is
+`sys_platform == 'darwin'` gated, the worker runs on Metal, and CI itself runs
+on macOS ARM runners. On any other machine you will not be able to run the
+test suite, so there is no practical way to verify a change. Python 3.14 is
+also required, though uv installs that for you.
+
+**This is a single-maintainer project.** Reviews may take a while. If you are
+planning anything beyond a focused fix, open an issue first — it is no fun to
+write a large PR and then discover it conflicts with where the project is
+going.
+
+## What's in scope
+
+Good candidates: bug reports with a reproduction, focused fixes, clearer
+documentation, additional test coverage — particularly around the sandbox.
+
+Please open an issue before starting on: new tools exposed to the worker,
+changes to the task lifecycle or MCP surface, or anything that widens what a
+worker is permitted to do.
+
+sous deliberately targets Apple silicon. Porting it to Linux or CUDA is not a
+small PR, and is not currently a goal.
+
+## Setup
+
+```bash
+uv sync
+```
+
+That is the whole thing. uv resolves the interpreter and every dependency from
+`uv.lock`.
+
+## Checks before you push
+
+CI runs four jobs. You can reproduce all of them locally:
+
+```bash
+uv run pytest -m "not model"                        # Tests
+uv run ty check                                     # Type check
+uv run ruff check . && uv run ruff format --check . # Lint
+uv lock --check                                     # Lockfile in sync
+```
+
+`ruff format .` (without `--check`) applies the formatting rather than just
+reporting it.
+
+Two suites do **not** run in CI, and are worth running yourself when you touch
+the engine layer:
+
+```bash
+uv run pytest -m model              # engine tests; downloads real models
+uv run python scripts/e2e_smoke.py  # the full agent loop, tiny model
+```
+
+`model`-marked tests are excluded from CI because they need multi-GB
+downloads. `slow`-marked tests — the process-group kill tests, which use real
+processes on purpose — *do* run in CI, so don't skip them locally.
+
+## Pull requests
+
+`main` is protected, so work on a branch and open a PR. All four CI jobs must
+be green.
+
+Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):
+`feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `test:`, `refactor:`. Keep the
+subject imperative and lowercase after the type.
+
+Explain *why* in the body, not just what — the diff already says what changed.
+If a fix is subtle, say what you verified and how, especially for anything
+timing-dependent.
+
+## Conventions
+
+- **ruff** with `line-length = 100`; config lives in `pyproject.toml`.
+- **ty** type-checks the whole repo, tests included. Test doubles that
+  deliberately implement only part of an interface use `cast`, with a comment
+  saying why — see `tests/test_worker.py`.
+- **`docs/`** is excluded from ruff. The design spec and implementation plan
+  are point-in-time records; reformatting the Python inside their code blocks
+  rewrites history for no benefit.
+- Match the comment density and style of the surrounding code. This codebase
+  explains non-obvious *reasoning* in comments and is fairly light on
+  restating what the code says.
+
+## Touching the sandbox
+
+`src/sous/toolexec.py` is the security boundary: path confinement, the command
+allowlist, and the process-group kill that stops a timed-out command's
+descendants from writing files after the audit. The guarantees it makes are
+described under [Security model](README.md#security-model).
+
+Changes there need a test that fails without them, and will get a closer read.
+Some of the behaviour is OS-level and genuinely unmockable — the existing
+tests spawn real processes for that reason. If you are fixing something
+intermittent, run the affected test in a loop before concluding it is fixed; a
+single green run proves very little.
+
+## Questions
+
+Open an issue.
+
+For anything security-sensitive, please don't — use GitHub's private
+vulnerability reporting instead (**Security** tab → **Report a vulnerability**),
+so a live weakness isn't described in public while it is unfixed. See
+[SECURITY.md](SECURITY.md).

sous_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 krcm0209
+
+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.