spens-ai 1.2.5__tar.gz

spens_ai-1.2.5/.gitconfig

@@ -0,0 +1,2 @@
+[safe]
+	directory = /workspace

spens_ai-1.2.5/.gitignore

@@ -0,0 +1,9 @@
+__pycache__
+.ruff_cache
+.venv
+testing
+.spens
+.pytest_cache
+.uv-cache/
+dist
+feedback.md

spens_ai-1.2.5/.gitlab-ci.yml

@@ -0,0 +1,270 @@
+# GitLab CI/CD configuration for spens
+#
+# test    - ruff + pytest across supported Python versions
+# version - bump version, update CHANGELOG, and create a git tag (default branch)
+# build   - sdist + wheel (tags and default branch)
+# publish - upload to this project's GitLab PyPI registry and to the public PyPI (tags)
+# release - cut a GitLab Release with the artifacts attached (tags)
+# pages   - build the docs site and publish it as GitLab Pages (tags)
+
+stages:
+  - test
+  - version
+  - build
+  - publish
+  - release
+
+workflow:
+  rules:
+    - if: $CI_COMMIT_TAG
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    # Don't run a duplicate branch pipeline when an MR is already open
+    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
+      when: never
+    - if: $CI_COMMIT_BRANCH
+
+variables:
+  UV_VERSION: "0.9"
+  PYTHON_VERSION: "3.12"
+  UV_CACHE_DIR: .uv-cache
+  # Hardlinks don't work across CI volume mounts; copying silences the warning
+  UV_LINK_MODE: copy
+  UV_PUBLISH_URL: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi
+  UV_PUBLISH_USERNAME: gitlab-ci-token
+  UV_PUBLISH_PASSWORD: ${CI_JOB_TOKEN}
+
+default:
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-bookworm-slim
+  interruptible: true
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+
+# Only jobs that resolve dependencies need the uv cache.
+.uv-cached:
+  cache:
+    key:
+      files:
+        - uv.lock
+    paths:
+      - $UV_CACHE_DIR
+  after_script:
+    - uv cache prune --ci
+
+lint:
+  extends: .uv-cached
+  stage: test
+  allow_failure: true
+  script:
+    - uv sync --extra dev
+    - |
+      status=0
+      uv run ruff check --output-format=gitlab --output-file=code-quality.json . || status=$?
+      uv run ruff format --check . || status=1
+      exit $status
+  artifacts:
+    when: always
+    reports:
+      codequality: code-quality.json
+
+test:
+  extends: .uv-cached
+  stage: test
+  parallel:
+    matrix:
+      - PYTHON_VERSION: ["3.11", "3.12", "3.13"]
+  script:
+    - uv sync --extra dev
+    - uv run pytest tests/unit -v --junitxml=report.xml
+  artifacts:
+    when: always
+    reports:
+      junit: report.xml
+
+# Python Semantic Release — analyzes conventional commits on main,
+# bumps version in pyproject.toml, updates CHANGELOG.md, commits,
+# creates a git tag, and pushes back to GitLab. The new tag then
+# triggers the build/publish/release jobs.
+semantic-release:
+  stage: version
+  image: python:3.12-slim
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  before_script:
+    - apt-get update && apt-get install -y --no-install-recommends git
+    - pip install --quiet python-semantic-release "uv~=${UV_VERSION}"
+  script:
+    - |
+      # GitLab checks out a detached HEAD; PSR needs to be on a branch
+      git checkout "${CI_COMMIT_BRANCH}" || git checkout -B "${CI_COMMIT_BRANCH}"
+      git config --global user.email "semantic-release-bot@gitlab.com"
+      git config --global user.name "Semantic Release Bot"
+      semantic-release version
+  variables:
+    # Full history is required for PSR to analyse all commits
+    GIT_DEPTH: "0"
+    # PSR expects GITLAB_TOKEN with api + write_repository scopes.
+    # Re-use the existing RELEASE_PLEASE_TOKEN project variable.
+    GITLAB_TOKEN: $RELEASE_PLEASE_TOKEN
+    GIT_COMMITTER_NAME: "semantic-release-bot"
+    GIT_COMMITTER_EMAIL: "semantic-release-bot@gitlab.com"
+
+build:
+  stage: build
+  variables:
+    UV_CACHE_DIR: /tmp/uv-cache
+  rules:
+    - if: $CI_COMMIT_TAG
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  script:
+    - uv build
+    - ls -l dist/
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 week
+
+# Publish to this project's GitLab PyPI registry using the built-in job token.
+# Install with:
+#   uv add spens-ai --index-url https://__token__:<token>@gitlab.com/api/v4/projects/<id>/packages/pypi/simple
+publish:pypi:gitlab:
+  extends: .uv-cached
+  stage: publish
+  interruptible: false
+  needs:
+    - job: build
+      artifacts: true
+  rules:
+    - if: $CI_COMMIT_TAG
+  script:
+    - |
+      set -eu
+      version="${CI_COMMIT_TAG#v}"
+      if ! ls dist/ | grep -q -- "-${version}"; then
+        echo "dist/ does not contain version ${version} — is the tag out of sync with pyproject.toml?"
+        ls -l dist/
+        exit 1
+      fi
+    - uv publish dist/*
+
+# Publish to the public PyPI (https://pypi.org/project/spens-ai/). The
+# distribution is named spens-ai because "spens" is already taken on PyPI.
+# Requires a masked, protected PYPI_API_TOKEN CI/CD variable holding an API
+# token created at pypi.org. Without it the job is skipped and only the
+# GitLab registry publish above happens.
+publish:pypi:public:
+  stage: publish
+  interruptible: false
+  needs:
+    - job: build
+      artifacts: true
+  rules:
+    - if: $CI_COMMIT_TAG && $PYPI_API_TOKEN
+  variables:
+    UV_PUBLISH_URL: "https://upload.pypi.org/legacy/"
+    UV_PUBLISH_USERNAME: "__token__"
+    UV_PUBLISH_PASSWORD: "$PYPI_API_TOKEN"
+  script:
+    - uv publish dist/*
+
+# Attach the sdist and wheel to a GitLab Release. glab uploads them to the
+# generic package registry and links them in one step.
+release:gitlab:
+  stage: release
+  image: registry.gitlab.com/gitlab-org/cli:latest
+  interruptible: false
+  needs:
+    - job: build
+      artifacts: true
+    - job: publish:pypi:gitlab
+    - job: publish:pypi:public
+      optional: true
+  rules:
+    - if: $CI_COMMIT_TAG
+  variables:
+    GLAB_ENABLE_CI_AUTOLOGIN: "true"
+  script:
+    - |
+      glab release create "$CI_COMMIT_TAG" dist/* \
+        --name "spens ${CI_COMMIT_TAG}" \
+        --notes "Release ${CI_COMMIT_TAG}. The package is published to the project's GitLab PyPI registry and to PyPI as spens-ai; the sdist and wheel are attached below as assets." \
+        --use-package-registry \
+        --package-name spens-ai \
+        --ref "$CI_COMMIT_SHA"
+
+# Build the fumadocs documentation site (docs/) as a static export and
+# publish it as GitLab Pages. The special `pages` job name makes GitLab
+# publish the `public/` artifact automatically once the job succeeds.
+pages:
+  stage: release
+  image: node:22-bookworm-slim
+  interruptible: false
+  rules:
+    - if: $CI_COMMIT_TAG
+  cache:
+    key:
+      files:
+        - docs/package-lock.json
+    paths:
+      - docs/.npm-cache
+  variables:
+    npm_config_cache: "$CI_PROJECT_DIR/docs/.npm-cache"
+  script:
+    - cd docs
+    - npm ci
+    - npm run build
+    - rm -rf "$CI_PROJECT_DIR/public"
+    - mv out "$CI_PROJECT_DIR/public"
+  artifacts:
+    paths:
+      - public
+
+spens-review:
+  tags: [landlock]
+  stage: test
+  allow_failure: true
+  rules:
+      - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  image: docker:27
+  services:
+    - docker:27-dind
+  variables:
+    # How the job container talks to the dind daemon (service alias is "docker")
+    DOCKER_HOST: tcp://docker:2376
+    DOCKER_TLS_CERTDIR: "/certs"
+    GITLAB_TOKEN: $RELEASE_PLEASE_TOKEN
+
+  before_script:
+    # gettext provides envsubst for prompt variable substitution
+    - apk add --no-cache curl jq git gettext
+    # Install uv
+    - curl -LsSf https://astral.sh/uv/install.sh | sh
+    - export PATH="/root/.local/bin:$PATH"
+    # Wait for the dind daemon to be ready before spens tries to use it
+    - until docker info > /dev/null 2>&1; do sleep 1; done
+    - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+  script:
+    - uv tool install spens-ai
+        --extra-index-url "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/api/v4/projects/refwd1%2Fspens/packages/pypi/simple"
+    - export SPENS_PROMPT="$(envsubst < prompts/code-review.md)"
+    # Fail here, not later: an empty SPENS_PROMPT (broken envsubst, missing
+    # prompt file) would otherwise surface as a confusing spens usage error.
+    - test -n "$SPENS_PROMPT"
+    - spens ocr.json pi . "$SPENS_PROMPT" --config ./.spens.config.ocr.json --accept-changes --output jsonl
+
+    - |
+      jq -n --rawfile body feedback.md \
+        '{body: ("## Spens Review\n\n" + $body)}' > payload.json
+      curl --fail --silent --show-error \
+        --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
+        --header "Content-Type: application/json" \
+        --request POST \
+        --data-binary "@payload.json" \
+        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}/notes"
+
+  artifacts:
+    when: always
+    paths:
+      - feedback.md

spens_ai-1.2.5/.spens.config.json

@@ -0,0 +1,31 @@
+{
+  "addition_capture_urls": ["*opencode.ai*", "*api.fireworks.ai*", "*192.168.8.10*", "*api.anthropic.com*"],
+  "exclude_capture_urls": ["*models.opencode.ai*"],
+  "nono_override": "nono-override.json",
+  "env": [],
+  "default_env": "python-3.13",
+  "default_agent": "pi",
+  "domain_rules": [
+    {"pattern": "*github.com", "allow": ["GET"]},
+    {"pattern": "*anthropic.com", "allow": ["GET", "POST"]},
+    {"pattern": "*release-assets.githubusercontent.com", "allow": ["GET"]},
+    {"pattern": "*pi.dev", "allow": ["GET"]},
+    {"pattern": "*npmjs.org", "allow": ["GET"]},
+    {"pattern": "*pypi.org", "allow": ["GET"]},
+    {"pattern": "*files.pythonhosted.org", "allow": ["GET"]},
+    {"pattern": "*platform.claude.com", "allow": ["GET"]},
+    {"pattern": "*api.anthropic.com", "allow": ["GET", "POST", "PUT", "DELETE", "OPTIONS"]},
+    {"pattern": "*opencode.ai", "allow": ["GET", "POST", "PUT", "DELETE", "OPTIONS"]},
+    {"pattern": "*api.fireworks.ai", "allow": ["GET", "POST", "PUT", "DELETE", "OPTIONS"]},
+    {"pattern": "bootstrap.pypa.io", "allow": ["GET"]},
+    {"pattern": "www.fumadocs.dev", "allow": ["GET"]}
+
+  ],
+  "inject_headers": [
+    {
+      "placeholder": "FIREWORKS_API_KEY",
+      "env_var": "FIREWORKS_API_KEY",
+      "for_domains": ["*api.fireworks.ai*"]
+    }
+  ]
+}

spens_ai-1.2.5/.spens.config.ocr.json

@@ -0,0 +1,23 @@
+{
+  "addition_capture_urls": ["*api.fireworks.ai*"],
+  "exclude_capture_urls": ["*models.opencode.ai*"],
+  "nono_override": "nono-override-ocr.json",
+  "env": ["OCR_LLM_URL", "OCR_LLM_MODEL"],
+  "default_env": "python-3.12",
+  "default_agent": "pi",
+  "domain_rules": [
+    {"pattern": "*api.fireworks.ai", "allow": ["GET", "POST", "PUT", "DELETE", "OPTIONS"]}
+  ],
+  "inject_headers": [
+    {
+      "placeholder": "OCR_LLM_TOKEN",
+      "env_var": "OCR_LLM_TOKEN",
+      "for_domains": ["*api.fireworks.ai*"]
+    },
+    {
+      "placeholder": "FIREWORKS_API_KEY",
+      "env_var": "FIREWORKS_API_KEY",
+      "for_domains": ["*api.fireworks.ai*"]
+    }
+  ]
+}

spens_ai-1.2.5/ARCHITECTURE.md

@@ -0,0 +1,83 @@
+# Spens Architecture
+
+This document explains, in technical terms, how spens runs a session from start to finish. For user-facing documentation, see the [README](README.md). For development setup, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## The three building blocks
+
+Spens combines three tools:
+
+- **Docker** - isolated, ephemeral runtime environments
+- **[nono.sh](https://nono.sh/)** - a sandboxed shell with filesystem access control and audit logging; the agent runs as a non-root user inside it
+- **[mitmproxy](https://www.mitmproxy.org/)** - an SSL-intercepting proxy that captures and decodes LLM API traffic
+
+## Overview
+
+A spens session involves three cooperating pieces: a CLI process on the host, an interceptor container, and an agent container. The CLI orchestrates everything: it loads templates and config, builds the images, creates the networks and containers, and collects the results.
+
+```
+host (spens CLI)
+  |
+  |  docker network: internal (no internet)
+  |    +---------------------------+        +---------------------------+
+  |    |  interceptor container   |        |  agent container          |
+  |    |  - mitmproxy + addon     |<-------|  nono sandbox             |
+  |    |  - DNS forwarder         | proxy  |  - unprivileged user      |
+  |    |  - traces/ volume        |  :9090 |  - agent binary           |
+  |    +---------------------------+        +---------------------------+
+  |  docker network: egress (internet only for the interceptor)
+```
+
+## Step by step
+
+1. **Load inputs.** The CLI resolves the environment and agent templates (built-in, local `templates/`, or a direct `.json` file), and reads `.spens.config.json` from the workspace if present.
+2. **Generate the agent image.** `builder.py` writes a Dockerfile from the templates: base image, system packages, the unprivileged agent user, the nono.sh installation, the agent's install command, and any static config files. It also generates a combined nono profile (extending the environment's and agent's base profiles, or copying the user's `nono_override` file) and an entrypoint script, and builds the image with Docker. The generated profile is baked into the image twice: as `spens-profile.json` (the active profile, which may be overridden by a user-supplied `nono_override` or bind-mount) and as `spens-base.json` (the generated base profile, never overridden). This lets a custom profile safely declare `"extends": ["spens-base"]` to inherit Spens internals without recreating them.
+3. **Generate the interceptor image.** A second Dockerfile installs mitmproxy and copies in the spens addon, its helpers, and a DNS forwarder. The addon's runtime config (capture URLs, domain rules, inject rules) is generated from `.spens.config.json` and baked into the image.
+4. **Create the networks.** Two Docker networks are created per session: an internal network (`docker network create --internal`) holding the agent and the interceptor, and an egress network giving the interceptor (and only the interceptor) internet access. Docker drops all routed egress from the internal network, so the agent's only reachable neighbor is the interceptor.
+5. **Start the interceptor.** The interceptor container runs mitmdump with the spens addon on port 9090, plus a DNS forwarder on port 53. It generates its CA certificate on first run, before it starts listening. The session's traces directory is bind-mounted into it.
+6. **Start the agent.** The agent container joins the internal network, points its `/etc/resolv.conf` at the interceptor's DNS forwarder, and receives proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) plus the mitmproxy CA certificate. Its entrypoint waits for readiness markers from the interceptor, runs any `pre_sandbox_commands`, then starts the agent under `nono run` with the combined profile, the workspace mounted read-write at `/workspace`, and the allowed folders granted.
+7. **Capture.** Every byte the agent sends flows through the interceptor: LLM API calls are decoded (including streaming responses) and written to `traces/captured.jsonl`; every request and response is logged to `traces/request_log.jsonl`; DNS queries are logged to `traces/dns_log.jsonl`. Domain rules are enforced fail-closed on both plain requests and `CONNECT` tunnel targets. Placeholders are swapped for real secrets only on matching hostnames, and real secret values are masked before anything is written to disk. nono writes its audit ledger and rollback snapshots to `nono-audit/`.
+8. **Summarize.** When the agent exits, the CLI computes a session summary (tokens, cost, models, file changes) from the captured traces and writes `session_summary.json`. Costing runs on the host, after the container exits, per the rules in [Cost estimation](README.md#cost-estimation). The end-of-session prompt asks whether to keep the agent's workspace changes or roll them back via nono's rollback snapshots.
+9. **Persist.** Everything is written under `<workspace>/.spens/sessions/<session-id>/` (or the `--spens-dir` path): `events.jsonl`, `state.json`, `traces/`, `nono-audit/`, and `session_summary.json`. The log viewer and the status/cancel/attach commands are thin readers over these files.
+
+## Session directory layout
+
+```
+<workspace>/.spens/sessions/<session-id>/
+  events.jsonl           machine-readable event stream for the session
+  state.json             current session state (running, finished, canceled, error)
+  session_summary.json   tokens, cost, models, file changes, pricing sources
+  traces/
+    captured.jsonl       decoded LLM API calls (requests, responses, streamed chunks)
+    request_log.jsonl    every HTTP request/response and CONNECT decision
+    dns_log.jsonl        every DNS query the agent made
+  nono-audit/
+    audit/               nono audit events and the integrity ledger
+    rollbacks/           rollback snapshots and per-file change records
+```
+
+## The interceptor
+
+The interceptor is a Python container running two processes:
+
+- **mitmdump with the spens addon** (`spens/data/mitmproxy_addon.py`). It intercepts HTTPS by terminating TLS with its own CA certificate (which the agent trusts), then re-originating the connection upstream. The addon implements: LLM traffic capture for the OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages APIs (including SSE streaming); domain rule enforcement with a fail-closed policy; placeholder-to-secret substitution scoped by hostname; secret masking in logs; and the request log. `rawtcp` forwarding is disabled and HTTP/2 is disabled, so non-HTTP protocols inside a `CONNECT` tunnel fail closed inside the proxy instead of being blindly forwarded.
+- **The DNS forwarder** (`spens/data/dns_forwarder.py`). Docker's embedded DNS is special-cased past the egress filtering of `--internal` networks, so the agent's `/etc/resolv.conf` is pointed at this forwarder instead. Every query is logged to `traces/dns_log.jsonl`, and resolution only works for the proxy path, closing the last uncaptured channel.
+
+Domain policy semantics live in `spens/data/mitmproxy_helpers.py` (`is_allowed`, `host_allowed`, `domain_matches`) and are shared by the HTTP hooks and the DNS forwarder, so the two channels cannot drift apart. Patterns are matched against the hostname only, at a label boundary: a pattern for `anthropic.com` matches `anthropic.com` and `api.anthropic.com`, but not `api.anthropic.com.attacker.example` or `evil-anthropic.com`. When no rules are configured at all there is no policy to enforce, so HTTP egress is allow-all (see [Default network policy](README.md#default-network-policy) in the README).
+
+## The agent sandbox
+
+Inside the agent container, the agent never runs as root. It runs as an unprivileged user (uid 1000) under the nono sandbox, which adds filesystem access control on top: the workspace is allowed, a small set of agent folders is allowed, and everything else is off limits. nono records an audit ledger with an integrity chain (Merkle root) and takes rollback snapshots of the workspace, which is what powers the accept/reject decision at the end of a session. Because bind-mount permissions are enforced by numeric uid, the agent can only write to the workspace if the host directory is owned by (or writable by) uid 1000.
+
+## Policy masking
+
+The workspace is mounted read-write into the agent, and the workspace is also where spens reads its own trust-sensitive inputs (`.spens.config.json`, `templates/`, and any `nono_override` file). Left visible and writable, an untrusted agent - or a cloned malicious repo - could rewrite the policy the *next* session honors: downgrade `egress` to `legacy`, clear the domain rules, add `pre_sandbox_commands`, or define an agent template whose `configuration` block mounts `~/.ssh` from the host.
+
+By the time the agent starts, those inputs have already been consumed and baked into the built images and generated configs, so the agent never needs to see them. Each input is overlaid with a read-only empty mask inside the agent container: `/dev/null` for the config and override files, an empty hardened tmpfs (`noexec,nosuid,nodev`) for `templates/`. The host copies are untouched; the agent can neither read them nor persist a poisoned policy for a later run (anything it writes to a masked path is ephemeral and discarded when the container exits).
+
+This blocks tampering *across* sessions. It does not vet a config that is malicious the first time you run against an untrusted repo - review `.spens.config.json`, `templates/`, and any `nono_override` in a repo you don't trust before running spens on it.
+
+## Non-interactive and background sessions
+
+Every session, in every mode, writes the same `events.jsonl` and `state.json`. The `--output` flag only changes what is rendered to stdout: `tty` renders a rich-based live view, `jsonl` streams the raw events, and `background` prints the session id and detaches. Detached sessions are launched by a child process that owns the docker run; `spens status`, `spens cancel`, and `spens attach` read and write the same `state.json` and `events.jsonl`, and the first writer of a terminal state (`finished`, `canceled`, `error`) wins, so an external cancel can never be overwritten by the running session.
+
+Yolo mode (a prompt passed on the CLI) is delivered to the container as the `SPENS_YOLO_PROMPT` environment variable. The entrypoint runs the agent template's `yolo_command` with `{prompt}` filled in, instead of the interactive agent, so the image is not rebuilt per prompt. If the template has no `yolo_command`, passing a prompt is an error.

spens_ai-1.2.5/CHANGELOG.md

@@ -0,0 +1,154 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.2.5 (2026-09-24)
+
+### Bug Fixes
+
+- Force re-release
+  ([`002c06c`](https://gitlab.com/refwd1/spens/-/commit/002c06c386ca214300395a8a88dcd5a1313d8a1a))
+
+
+## v1.2.4 (2026-09-24)
+
+### Bug Fixes
+
+- Offical pypi package
+  ([`378ea2b`](https://gitlab.com/refwd1/spens/-/commit/378ea2bf5a45d44d1919ff5b5aa6b3d84ef978f0))
+
+
+## v1.2.3 (2026-09-23)
+
+### Bug Fixes
+
+- Cleaned up ci/cd. Generated example docs
+  ([`b397fc3`](https://gitlab.com/refwd1/spens/-/commit/b397fc3bad103e09b539c1c0e4fd40fecf36c247))
+
+
+## v1.2.2 (2026-09-23)
+
+### Bug Fixes
+
+- Fixed codex and opencode so they work now
+  ([`dda74ff`](https://gitlab.com/refwd1/spens/-/commit/dda74ff6b71db33cbc66db2db69ef80769c718a7))
+
+
+## v1.2.1 (2026-09-23)
+
+### Bug Fixes
+
+- Spelling errors
+  ([`8c81081`](https://gitlab.com/refwd1/spens/-/commit/8c810818f573218c602e815cbbdf4403d45ec6b6))
+
+
+## v1.2.0 (2026-09-22)
+
+### Features
+
+- **docs**: Added inital docs
+  ([`061aa59`](https://gitlab.com/refwd1/spens/-/commit/061aa59a733f22cd5f0c42042ef32eae7a543494))
+
+
+## v1.1.2 (2026-09-22)
+
+### Bug Fixes
+
+- Changed inheretence model for base profile.
+  ([`d7f8547`](https://gitlab.com/refwd1/spens/-/commit/d7f8547ee7940808167cefc8ecb4170dc54303ec))
+
+
+## v1.1.1 (2026-09-22)
+
+### Bug Fixes
+
+- Set jsonnl mode
+  ([`e40350a`](https://gitlab.com/refwd1/spens/-/commit/e40350af26913c30fc37ddf7e1734da5c74e8f73))
+
+
+## v1.1.0 (2026-09-21)
+
+### Features
+
+- **config**: Added ability to change spens.config.json file to support different runners, added OCR
+  to the review chain
+  ([`93e5bfe`](https://gitlab.com/refwd1/spens/-/commit/93e5bfe84530a33110aa265cdc60b744d1468846))
+
+
+## v1.0.2 (2026-09-21)
+
+### Bug Fixes
+
+- Fixing release
+  ([`32c199d`](https://gitlab.com/refwd1/spens/-/commit/32c199d8eec274891181b2a0d12ee811ee2e8fe8))
+
+- Hopefulyl fixing the release for real
+  ([`5575aa3`](https://gitlab.com/refwd1/spens/-/commit/5575aa3860e3721a431143b95854d17c031904bd))
+
+
+## v1.0.1 (2026-09-21)
+
+### Bug Fixes
+
+- Release
+  ([`e69da54`](https://gitlab.com/refwd1/spens/-/commit/e69da54f91729fe3469dad3d064a7fda679952b3))
+
+- Updated lock file
+  ([`7398188`](https://gitlab.com/refwd1/spens/-/commit/7398188778f625379148c9b65513e28af9989480))
+
+
+## v1.0.0 (2026-09-21)
+
+### Bug Fixes
+
+- Fix git issue with semantic-release
+  ([`ec2be98`](https://gitlab.com/refwd1/spens/-/commit/ec2be986a02ed5d79cb64ef4d34919d1ab79b5de))
+
+- Fixing semantic release
+  ([`d8d4f08`](https://gitlab.com/refwd1/spens/-/commit/d8d4f0873c45696a9bd70c93db9f3832b636cd07))
+
+### Features
+
+- **release**: Enabled release please
+  ([`9af2698`](https://gitlab.com/refwd1/spens/-/commit/9af26983a20bbfe2b7275fb95e889caf2226b7ab))
+
+- **release**: Switched to semantic release
+  ([`7674e2b`](https://gitlab.com/refwd1/spens/-/commit/7674e2b6f593d9b765064e47b9e3d875f9c6cfc5))
+
+
+## v0.4.3 (2026-09-20)
+
+### Bug Fixes
+
+- Fixing broken script
+  ([`0ad7144`](https://gitlab.com/refwd1/spens/-/commit/0ad7144ecbe97be53897f58ed1134752a0c44268))
+
+- Ruff formating
+  ([`3a99d2b`](https://gitlab.com/refwd1/spens/-/commit/3a99d2b416cb62526ad5d3c1fc0c5cf5aaf3730d))
+
+- Tweaks
+  ([`7d50829`](https://gitlab.com/refwd1/spens/-/commit/7d50829386e9bdaf5ef29abd59394d7c5e7c3454))
+
+
+## v0.4.2 (2026-09-20)
+
+### Bug Fixes
+
+- Continuing to tweak gitlab
+  ([`6a1ae15`](https://gitlab.com/refwd1/spens/-/commit/6a1ae154e1dde8169c168b4717bbd072c9457d51))
+
+
+## v0.4.0 (2026-09-20)
+
+### Bug Fixes
+
+- Fixed ci/cd issue
+  ([`b5158e5`](https://gitlab.com/refwd1/spens/-/commit/b5158e5e60b47ccf34a27514453a684e17015ca9))
+
+- Fixed viewerd bugs with custom sessions
+  ([`9e6e894`](https://gitlab.com/refwd1/spens/-/commit/9e6e8947356fefa72ba46da7547b3cc3d6605440))
+
+
+## v0.3.0 (2026-09-20)
+
+- Initial Release

spens_ai-1.2.5/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to Spens
+
+This document covers development setup, tests, and the project layout. For using spens, see the [README](README.md). For how spens works internally, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Requirements
+
+- Python 3.11, 3.12, or 3.13
+- [uv](https://docs.astral.sh/uv/) for dependency management (the repo ships a `uv.lock`)
+- Docker, for running sessions and the end-to-end tests (on macOS, [OrbStack](https://orbstack.dev) is required)
+- Git
+
+## Setup
+
+```bash
+git clone https://gitlab.com/refwd1/spens.git
+cd spens
+uv sync --extra dev
+```
+
+This creates a `.venv` with spens installed in editable mode, plus the dev tools (pytest and ruff).
+
+Run the CLI from the checkout:
+
+```bash
+uv run spens list
+```
+
+## Unit tests
+
+```bash
+uv run pytest tests/unit -v
+```
+
+Unit tests do not need Docker. They cover config generation, template loading, builder output, the pricing table, the summarizer, and the pure helper functions used by the interceptor addon.
+
+## Lint and format
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+```
+
+Ruff is configured in `pyproject.toml` with a line length of 120. CI runs both, so run them before opening a merge request.
+
+## End-to-end tests
+
+```bash
+uv run python tests/e2e/runner.py
+```
+
+Requires Docker and an `ANTHROPIC_API_KEY` in the environment. It runs each built-in agent in each built-in environment against `tests/e2e/workspace` and reports pass/fail per combination.
+
+## CI and releases
+
+`.gitlab-ci.yml` runs ruff and pytest (on Python 3.11, 3.12, and 3.13) on every push. On tags it builds the sdist and wheel, publishes them to the project's GitLab PyPI registry and to the public PyPI (as `spens-ai`, when the `PYPI_API_TOKEN` CI/CD variable is set), and creates a GitLab release with the artifacts attached.
+
+## Project layout
+
+```
+spens/
+  cli.py              CLI entry point and argument parsing
+  init.py             spens init questionnaire and config generation
+  config.py           .spens.config.json loader
+  templates.py        Environment and agent template loading
+  builder.py          Dockerfile, nono profile, and entrypoint generation
+  runner.py           Session orchestration (interceptor + agent containers)
+  background.py       Detached (background) session launching
+  control.py          status / cancel / attach commands
+  sessions.py         Session directory and trace loading helpers
+  events.py           Session event stream (events.jsonl)
+  sinks/              Output rendering (tty, jsonl, background)
+  viewer.py           Log viewer web server and trace parser
+  summarizer.py       Session summary stats and cost estimation
+  pricing.py          Model pricing data (fetch, cache, lookup)
+  ui.py               rich-based terminal rendering
+  static/             Log viewer frontend (html, css, js)
+  data/
+    mitmproxy_addon.py    Interceptor addon (LLM capture, domain filtering, key injection)
+    mitmproxy_helpers.py  Pure helpers for the interceptor addon (unit-testable without mitmproxy)
+    dns_forwarder.py      Logging DNS forwarder
+    pricing/              Vendored pricing snapshots (offline fallback)
+    templates/            Built-in environment and agent templates
+    init_templates/       Partial configs used by spens init
+```
+
+## License
+
+Spens is MIT licensed. See `license.md`.