convene 0.1.0__tar.gz

convene-0.1.0/.github/ISSUE_TEMPLATE/measurement.yml

@@ -0,0 +1,65 @@
+name: Measurement
+description: Report a number — a confirmation, a contradiction, or a new result
+labels: ["measurement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Measurements are the most valuable thing you can contribute here.
+        A run that **contradicts** a table in FINDINGS.md is worth more than
+        another confirmation of it.
+
+        Every claim needs its sample size and the build it came from. See
+        [CONTRIBUTING.md](../blob/develop/CONTRIBUTING.md#the-claim-standard).
+  - type: input
+    id: claude-version
+    attributes:
+      label: Claude Code version
+      description: "`claude --version`"
+      placeholder: "2.1.237 (Claude Code)"
+    validations: { required: true }
+  - type: input
+    id: platform
+    attributes:
+      label: OS and architecture
+      placeholder: "macOS 15.3 arm64 / Ubuntu 24.04 x86_64 / Windows 11"
+    validations: { required: true }
+  - type: dropdown
+    id: auth
+    attributes:
+      label: Auth mode
+      options: ["login (subscription)", "sandbox_token (subscription)", "api_key"]
+    validations: { required: true }
+  - type: dropdown
+    id: topic
+    attributes:
+      label: Which claim does this touch?
+      options:
+        - "1. -p uses the subscription login / --bare does not"
+        - "2. Prompt cache — the ~9.5x, or where the threshold sits"
+        - "3. Concurrency ceiling"
+        - "4. Multi-turn cost and behaviour"
+        - "5. Auth failure returning success"
+        - "6. Lockdown flags worth ~88x"
+        - "A question FINDINGS.md lists as unmeasured"
+        - "Something not covered yet"
+    validations: { required: true }
+  - type: textarea
+    id: numbers
+    attributes:
+      label: The numbers
+      description: >
+        Token counts and costs, not just costs — a cost claim without tokens
+        cannot be checked. Say how many runs (n) each row represents.
+      render: text
+      placeholder: |
+        n=3 bursts per row, claude-sonnet-5, effort=low
+        n=20  wall=31.4s  errors=7  (5x rate_limit, 2x overloaded)
+    validations: { required: true }
+  - type: textarea
+    id: command
+    attributes:
+      label: How to reproduce it
+      description: The exact command, ideally `convene bench ...`
+      render: shell
+    validations: { required: true }

convene-0.1.0/.github/ISSUE_TEMPLATE/tool-problem.yml

@@ -0,0 +1,41 @@
+name: Tool problem
+description: convene itself is broken, or does something it shouldn't
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **If a call started billing API credits instead of your subscription,
+        say so in the title** — that is the most serious class of bug here.
+
+        Please run `convene doctor` first and paste the output; it answers
+        most of what would otherwise be a round trip.
+  - type: textarea
+    id: doctor
+    attributes:
+      label: "`convene doctor` output"
+      description: Redact the email if you like — the plan and auth method are what matter.
+      render: text
+    validations: { required: true }
+  - type: input
+    id: version
+    attributes:
+      label: convene and Python versions
+      placeholder: "convene 0.1.0, Python 3.12.4"
+    validations: { required: true }
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened, and what you expected
+    validations: { required: true }
+  - type: textarea
+    id: repro
+    attributes:
+      label: Smallest reproduction
+      render: python
+    validations: { required: true }
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback or error output
+      render: text

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

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      # The `live` marker is excluded by default in pyproject. CI has no Claude
+      # Code login, and tests that spend money must never run unattended.
+      - run: pytest -q
+      - run: ruff check src tests claude_cli.py
+      - run: ruff format --check src tests claude_cli.py
+
+  scope-guard:
+    # The scope rule in the README is load-bearing, so it is enforced rather
+    # than merely documented: no HTTP server, no OpenAI-compatible endpoint,
+    # and never the --bare flag.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: No --bare flag anywhere in the package
+        run: |
+          if grep -rn -- '"--bare"' src/; then
+            echo "::error::--bare forces API-key auth and never reads OAuth."
+            exit 1
+          fi
+      - name: No network server in the package
+        run: |
+          if grep -rnE '^\s*(import|from)\s+(http\.server|socketserver|flask|fastapi|uvicorn|aiohttp)\b' src/; then
+            echo "::error::convene exposes no network endpoint. See README > Scope."
+            exit 1
+          fi

convene-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed.
+#
+# Uses PyPI Trusted Publishing, so there is no API token in this repo and
+# nothing to leak or rotate. One-time setup on PyPI:
+#
+#   pypi.org -> Your projects -> Publishing -> Add a new pending publisher
+#     PyPI project name : convene
+#     Owner             : YashShelar007
+#     Repository        : convene
+#     Workflow name     : release.yml
+#     Environment       : pypi
+#
+# Then: git tag v0.1.0 && git push origin v0.1.0
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - name: Tag must match the version in pyproject
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(ls dist/*.tar.gz | sed -E 's/.*convene-(.*)\.tar\.gz/\1/')
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag $tag does not match built version $pkg"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

convene-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Credentials and machine identity. Never commit these.
+data/
+*.oauth-token
+oauth-token
+.credentials.json
+
+# Call logs and ledgers contain your prompts, costs and account activity.
+logs/
+*.log
+*.sqlite3
+*.db
+
+# Local expert registries may hold proprietary prompts.
+experts.local.toml
+convene.local.toml
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# macOS
+.DS_Store
+
+scratch/

convene-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing
+
+This repo's product is **verified claims about an undocumented interface**, and
+a small library that acts on them. The code is thin; the value is in knowing
+which assertions are backed by how much evidence. That shapes everything below.
+
+## Branches
+
+| Branch | What it means |
+|---|---|
+| `main` | Claims that have been verified, and code that has been run. Treat it as published. |
+| `develop` | Integration. New measurements and features land here first. |
+
+- `develop` is the **default branch**. Open PRs against it.
+- `main` changes only by PR from `develop`, tagged on merge.
+- Maintainers push to `develop` directly for doc fixes and verified findings.
+  Outside contributions come as PRs.
+
+Releases are tagged when a **claim set** changes — a new measurement, a
+retraction, a corrected derivation — or when the API changes. The version
+people cite should match what they read.
+
+## The claim standard
+
+The most useful contribution here is usually a measurement, not a patch. It is
+also the easiest thing to get wrong, because a single lucky run looks exactly
+like a law.
+
+**Every empirical claim carries its sample size and the build it came from.**
+
+- Good: "cache engages between 914 and 1232 total prompt tokens
+  (claude-sonnet-5, Claude Code 2.1.237, macOS arm64, n=1 per size across 8
+  sizes)"
+- Not good: "the cache threshold is 1024 tokens"
+
+If you can't reach n>1, say so. "Observed once" is a fine claim.
+"Anthropic changed X" is not, unless you have both sides of the change.
+
+Claims about *cost* must report the tokens too. `total_cost_usd` is a
+client-side list-price estimate, not a bill, and on subscription auth it is an
+accounting figure rather than a charge. A cost claim without the token counts
+cannot be checked.
+
+## What's most wanted
+
+The open questions are listed at the bottom of [FINDINGS.md](FINDINGS.md). The
+highest-value ones:
+
+1. **The real concurrency ceiling.** n=20 is simply the largest burst anyone
+   has tried. Where does it actually start erroring, and what does the envelope
+   look like when it does?
+2. **A Linux or Windows column.** Every number in FINDINGS.md is macOS arm64.
+3. **Cache TTL.** Warm reads were ~30s apart. How long does an entry live?
+4. **A build newer than 2.1.237** — especially one where `--bare` has become
+   the default for `-p`, which would break subscription auth entirely.
+5. **Counter-examples.** A run that contradicts a table in FINDINGS.md is worth
+   more than another confirmation of it.
+
+Reproduce the existing numbers first:
+
+```bash
+convene bench
+```
+
+## Scope: what will be declined
+
+convene runs the first-party `claude` binary locally, under the user's own
+login. It is not a proxy. Three properties are load-bearing, and PRs that
+change any of them will be declined regardless of quality:
+
+- **No network endpoint.** No HTTP server, no OpenAI-compatible shim, no
+  daemon that other machines or programs can call. See *Scope* in the README
+  for why — this is the exact shape Anthropic blocked in 2026.
+- **No credential extraction or forwarding.** The library reads no token files
+  it did not create, and sends credentials nowhere.
+- **No silent API-key fallback.** `AuthMode.API_KEY` must never be selected
+  implicitly, and the key-stripping in `subprocess_env` must not be weakened.
+
+Feature ideas inside scope are in [ROADMAP.md](ROADMAP.md).
+
+## Hard rules for the code
+
+Each corresponds to a way this has already gone wrong, or would.
+
+- **Never pass `--bare`.** It forces API-key auth and never reads OAuth. It
+  would silently move billing from a subscription to API credits.
+- **Never weaken the `is_error` check.** Auth failure arrives as
+  `subtype: "success"` with exit code 0. `subtype == "success"` alone does not
+  catch it. Pinned by `tests/test_runtime.py`.
+- **Never drop a lockdown flag** without a measurement showing the cost is
+  unchanged. They are worth ~88x together.
+- **Never strip `--session-id`/`--resume` calls of session persistence.**
+  `--no-session-persistence` makes a session unresumable, which defeats the
+  point of a durable session.
+- **Keep the core dependency-free.** A tool for reducing spend should not drag
+  in a tree of transitive dependencies. `tomllib` is why the floor is 3.11.
+- **Normalise costs, don't pass them through.** Live sessions report cumulative
+  cost, durable ones report per-call. `Turn.cost_usd` is always incremental.
+
+## Releasing
+
+Releases go out through PyPI Trusted Publishing — there is no API token in this
+repo. The one-time PyPI setup is documented at the top of
+[`.github/workflows/release.yml`](.github/workflows/release.yml).
+
+After that, a release is:
+
+```bash
+# on develop, with FINDINGS.md and the version in pyproject.toml both current
+gh pr create --base main --head develop
+# once merged:
+git checkout main && git pull
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+The workflow refuses to publish if the tag does not match the version in
+`pyproject.toml`, so bump that in the same PR.
+
+## Testing a change
+
+```bash
+pip install -e ".[dev]"
+pytest                 # 46 tests, no spend, no network
+ruff check src tests
+```
+
+Tests that make real calls are marked `live` and excluded by default. Run them
+before anything touching the runtime, sessions, or auth:
+
+```bash
+pytest -m live         # a few cents, needs a working `claude` login
+```
+
+If you change a documented number, change FINDINGS.md in the same PR and say in
+the description which command you actually ran. A number in the docs that no
+test or bench command reproduces is a bug.

convene-0.1.0/FINDINGS.md

@@ -0,0 +1,239 @@
+# Findings
+
+Measured behaviour of `claude -p` used as an inference endpoint. Everything
+here carries its sample size and the build it came from, because this document
+is the product — the code is a thin wrapper around these facts.
+
+Reproduce any of it with:
+
+```bash
+convene bench
+```
+
+**Environment for every measurement below unless stated otherwise:** Claude
+Code **2.1.237**, macOS 15 (arm64), subscription auth (`authMethod:
+claude.ai`, Max plan), model `claude-sonnet-5`, `effort=low`, calls locked down
+with the flag set in [`runtime.py`](src/convene/runtime.py).
+
+---
+
+## 1. `claude -p` uses your subscription login. `--bare` does not.
+
+This is the most widely repeated wrong claim about headless Claude Code, and
+it appears in blog posts and search summaries as *"the `-p` flag bypasses OAuth
+and requires an `ANTHROPIC_API_KEY`."*
+
+It is false, and Anthropic's own documentation says which half is true. From
+[the headless docs](https://code.claude.com/docs/en/headless), on `--bare`:
+
+> Set `ANTHROPIC_API_KEY` before running it, because bare mode doesn't use your
+> subscription login.
+
+> In bare mode, Claude Code never reads OAuth credentials or the system keychain.
+
+So the API-key requirement belongs to `--bare`, not to `-p`. A plain `-p` run
+reads your OAuth login normally. Every call in this document was made with no
+API key in the environment (n≈150 calls, all succeeded).
+
+**This is why convene never passes `--bare`,** despite it being faster to
+start and despite Anthropic recommending it for scripted calls.
+
+### The forward risk
+
+The same page says:
+
+> `--bare` is the recommended mode for scripted and SDK calls, and will become
+> the default for `-p` in a future release.
+
+If that lands and there is no opt-out, subscription auth through this library
+breaks. `convene doctor` probes for it with a real call rather than comparing
+version strings, because the failure will not announce itself.
+
+---
+
+## 2. The prompt cache works, and it is worth ~9.5x
+
+Same ~4.4k-token system prompt, three **separate processes**, no session
+resumption, ~30s apart (n=1 per row):
+
+| | `cache_creation` | `cache_read` | `input_tokens` | cost | elapsed |
+|---|---:|---:|---:|---:|---:|
+| cold | 4434 | 0 | 2 | **$0.02670** | 7.1s |
+| warm | 243 | 4191 | 2 | **$0.00281** | 6.5s |
+| warm | 243 | 4191 | 2 | **$0.00281** | 6.5s |
+
+**9.5x cheaper**, and the cache survives process death because it lives
+server-side keyed on the prompt prefix.
+
+The practical consequence inverts ordinary prompt advice: a long, *stable*
+system prompt is the cheap option, and a short one you retune per call is the
+expensive one. This is the entire argument for the expert registry.
+
+Confirmed independently on a real workload — the `triage` expert in
+[`examples/experts.toml`](examples/experts.toml), 5 support tickets, warm-up
+enabled (n=1 run):
+
+```
+t1  cache_read=   0   $0.01311     <- cold, creates the entry
+t2  cache_read=1504   $0.00469
+t3  cache_read=1504   $0.00454
+t4  cache_read=1504   $0.00469
+t5  cache_read=1504   $0.00520
+```
+
+2.8x on a prompt a quarter the size of the synthetic one. The effect scales
+with system-prompt length.
+
+### Where the cache starts
+
+Sweeping one system prompt's length, one call per size (n=1 per row):
+
+| system prompt chars | total `input_tokens` | `cache_creation` | cached? |
+|---:|---:|---:|:--|
+| 285 | 354 | 0 | no |
+| 570 | 434 | 0 | no |
+| 1140 | 594 | 0 | no |
+| 1710 | 754 | 0 | no |
+| 2280 | 914 | 0 | no |
+| 3420 | 2 | 1232 | **yes** |
+| 5700 | 2 | 1872 | yes |
+| 14820 | 2 | 241 (+4191 read) | yes |
+
+The transition sits between **914 and 1232 total prompt tokens**, consistent
+with the 1024-token minimum Anthropic documents for Sonnet and Opus. Haiku's
+documented minimum is 2048; **that has not been measured here.**
+
+Two things this table shows that are easy to miss:
+
+- The threshold applies to the **whole prompt**, not the system prompt alone.
+  A locked-down call carries ~150 tokens of harness before your text.
+- Once a cache entry exists, `input_tokens` collapses to **2**. Almost the
+  entire prompt moves into the cache accounting.
+
+### Chars per token, and why the lint under-estimates
+
+The sweep above gives 2.78–3.04 chars/token, but it repeats one sentence, and
+repetitive text tokenises unusually well. The structured `triage` prompt —
+markdown headings, short lines, lists — measured **2.2 chars/token** (2976
+chars against ~1354 system tokens).
+
+`convene experts lint` uses 2.9, which therefore *under*-estimates real
+prompts. That is deliberate: a false "might be too short to cache" warning
+costs nothing, while false reassurance costs money on every call.
+
+---
+
+## 3. Concurrency runs much further than "about 5"
+
+Identical trivial calls, one burst per row, no retries (n=1 burst per row):
+
+| n | wall | per-call min / med / max | errors |
+|---:|---:|---:|---:|
+| 1 | 6.3s | 6.3 / 6.3 / 6.3 | 0 |
+| 5 | 6.8s | 6.4 / 6.6 / 6.8 | 0 |
+| 10 | 9.9s | 7.0 / 7.2 / 9.8 | 0 |
+| 20 | 12.1s | 8.9 / 10.4 / 12.0 | 0 |
+
+Throughput climbs from 0.16 to 1.65 calls/second — about **10x** — with zero
+rate-limit errors. Latency degrades gracefully rather than failing.
+
+**This is not a discovered ceiling.** Nobody has found where it actually
+breaks; 20 is simply the largest burst tested. convene defaults to 12 as a
+deliberate midpoint that leaves headroom for the interactive Claude Code
+sharing the same rate-limit pool. If you find the real limit,
+[open an issue](https://github.com/YashShelar007/convene/issues).
+
+Each concurrent call is a full Node process, so local RAM becomes the binding
+constraint before long.
+
+---
+
+## 4. Multi-turn works, two ways, and they cost differently
+
+Three-turn conversation, "my favourite number is 41" → "+1?" → "×2?". Both
+kinds answered 42 then 82, so both retained state (n=1 each):
+
+| | turn 1 | turn 2 | turn 3 | total |
+|---|---:|---:|---:|---:|
+| `LiveSession` (one hot process) | 3.2s / $0.00099 | 2.3s / $0.00113 | 5.8s / $0.00130 | **$0.00342** |
+| `Session` (`--session-id` + `--resume`) | 3.6s / $0.00257 | 3.4s / $0.00840 | 3.2s / $0.00388 | **$0.01485** |
+
+The hot process was **4.3x cheaper** for the same conversation, because
+`--resume` re-establishes context from disk on every turn.
+
+Use `Session` anyway when the conversation must outlive the program — it is on
+disk and resumable tomorrow, from any working directory since Claude Code
+2.1.223. Use `LiveSession` when it does not.
+
+### The cost-reporting trap
+
+The two paths report `total_cost_usd` differently, and neither documents it:
+
+```
+LiveSession   0.000987 -> 0.002121 -> 0.003417    cumulative per session
+Session       0.000990 -> 0.001130 -> 0.001300    per call
+```
+
+Summing the raw field across a live session's turns **triple-counts**.
+convene's `Turn.cost_usd` is always the incremental cost; the raw figure stays
+on `turn.result.cost_usd`. Pinned by
+[`tests/test_sessions.py`](tests/test_sessions.py).
+
+Input tokens grow as history accumulates (299 → 363 → 417 on a trivial
+conversation). A long session is a growing prompt, not a free one.
+
+---
+
+## 5. Auth failure does not look like a failure
+
+The single nastiest behaviour in this interface. On an expired or missing
+login, the CLI returns:
+
+```json
+{"subtype": "success", "is_error": true, "result": "Not logged in · Please run /login"}
+```
+
+…and exits **0**.
+
+Neither the exit code nor `subtype` catches it. `is_error` is the only reliable
+signal, which is why `decode_envelope` checks `subtype != "success" or
+is_error`. That same condition also catches `error_*` subtypes such as
+`error_max_structured_output_retries`.
+
+Do not "simplify" it to `subtype == "success"`. Pinned by
+[`tests/test_runtime.py`](tests/test_runtime.py).
+
+---
+
+## 6. The lockdown flags are worth ~88x
+
+Measured on an identical one-word prompt (n=1, carried forward from this
+project's predecessor and re-checkable with `convene doctor --lockdown`):
+
+```
+locked down   in=  144   cache_create=    0   cost=$0.00051
+plain -p      in=    2   cache_create= 9504   cost=$0.04478     88x
+```
+
+A default `claude -p` loads the full agent system prompt, every tool
+definition, your skills, MCP servers, project settings and `CLAUDE.md`. The gap
+depends on how much you have configured, so re-measure on your own machine:
+
+```bash
+convene doctor --lockdown
+```
+
+---
+
+## What has not been measured
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+1. **The real concurrency ceiling.** n=20 is the largest burst tried.
+2. **Haiku's cache threshold.** Documented as 2048 tokens; unverified here.
+3. **Cache TTL on this path.** Warm reads were ~30s apart. How long an entry
+   survives is unknown.
+4. **Linux and Windows.** Every number above is macOS arm64.
+5. **Rate-limit behaviour at the weekly cap.** No measurement of what a
+   subscription limit looks like in the envelope.
+6. **Whether `--bare` has become the `-p` default** in any build after 2.1.237.

convene-0.1.0/LICENSE

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