agent-parley 0.1.0__tar.gz

agent_parley-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "agent-parley-local",
+  "interface": {
+    "displayName": "Agent Parley Local"
+  },
+  "plugins": [
+    {
+      "name": "agent-parley",
+      "source": {
+        "source": "local",
+        "path": "./plugins/agent-parley"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

agent_parley-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "agent-parley-local",
+  "description": "Coordination plugins for running several coding agents side by side in separate Git worktrees.",
+  "owner": {
+    "name": "Suneel Kaushik S",
+    "email": "suneel944@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "agent-parley",
+      "source": "./plugins/agent-parley",
+      "description": "Shared issue ownership and handoffs across coding agents.",
+      "version": "0.1.0"
+    }
+  ]
+}

agent_parley-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+graphify-out/
+.mypy_cache/

agent_parley-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [0.1.0](https://github.com/suneel944/agent-parley/compare/v0.0.1...v0.1.0) (2026-09-09)
+
+
+### ⚠ BREAKING CHANGES
+
+* rename the project to agent-parley and restart at 0.0.1 ([#20](https://github.com/suneel944/agent-parley/issues/20))
+
+### Features
+
+* complete the first release with issue dependencies and automated publishing ([#26](https://github.com/suneel944/agent-parley/issues/26)) ([9158d61](https://github.com/suneel944/agent-parley/commit/9158d61f1b8a269461744cb10b92b6b788233cfd))
+* rename the project to agent-parley and restart at 0.0.1 ([#20](https://github.com/suneel944/agent-parley/issues/20)) ([8a7dcc0](https://github.com/suneel944/agent-parley/commit/8a7dcc08d387560bc23a5ebdb101275f99887c28))
+* support any participant roster and record enforcement history ([#18](https://github.com/suneel944/agent-parley/issues/18)) ([fba4428](https://github.com/suneel944/agent-parley/commit/fba4428a7310f9c0d67bcfe8b90f54e5d8a66d11))
+
+
+### Bug fixes
+
+* grant the release caller the identity permission it delegates ([#22](https://github.com/suneel944/agent-parley/issues/22)) ([8ea3e03](https://github.com/suneel944/agent-parley/commit/8ea3e030368bc777c1aac9ab78defea8b180d63f))
+
+## [0.0.1] - 2026-09-10
+
+### Added
+
+- First release of Agent Parley: a coordination launcher that runs several
+  native coding-agent CLIs in separate Git worktrees under one Linux user, with
+  shared issue ownership, explicit handoffs, advisory file reservations, bounded
+  peer messaging, native lifecycle hooks and a live dashboard.

agent_parley-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,18 @@
+# Code of conduct
+
+Treat contributors and users with respect. Critique code and ideas with concrete
+evidence. Welcome questions and corrections, and give people room to learn.
+
+Harassment, threats, discriminatory abuse, sexualized conduct, and publishing
+someone's private information without consent are not acceptable. These rules
+apply to this project's issues, pull requests, discussions, and other community
+spaces, including conduct while representing the project elsewhere.
+
+Report concerns privately to suneel944@gmail.com. Include links or relevant
+context without republishing private information. The maintainer will review
+reports discreetly, consider the impact and context, and may issue a warning,
+remove content, restrict participation, or ban an account. Retaliation against
+someone who reports a concern is not acceptable.
+
+If you disagree with a moderation decision, request reconsideration privately
+with any missing context. Maintainers are expected to follow these rules too.

agent_parley-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# Contributing
+
+## Coding standard
+
+Use the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
+as the Python review baseline. Automated checks cover a subset of that guide;
+passing lint is not a claim of complete style or correctness compliance.
+
+- Use four-space indentation, an 80-character target, descriptive snake_case
+  functions and variables, and CapWords classes. Let Ruff handle formatting.
+- Document public modules, classes, and functions. Use Google-style `Args`,
+  `Returns`, `Yields`, and `Raises` sections where callers need the contract.
+- Annotate production function parameters and return values. Prefer explicit
+  keyword parameters over unstructured option dictionaries.
+- Group standard-library, third-party, and local imports. Use absolute package
+  paths. Prefer module-qualified references when introducing new dependencies.
+- Keep functions focused. Separate CLI orchestration, issue transitions,
+  checkpoint observation, and persistence. Prefer the standard library and
+  existing helpers before adding a dependency or abstraction.
+- Runtime imports must remain within Python's standard library and this package.
+  Development tools do not belong in installed runtime dependencies.
+- Put contracts and rationale in docstrings and focused documentation, not inline
+  Python comments. The policy gate checks every production and script function,
+  including private helpers. Descriptive test names document scenarios.
+- Validate operational input with real conditionals, not assertions. Catch
+  expected failures at the appropriate boundary and preserve diagnostic context.
+- Close files and sockets with context managers. Pass subprocess arguments as
+  lists; never interpolate user input into a shell. Make exit-code handling explicit.
+
+This project uses Ruff rather than the guide's Pylint recommendation. Ruff enforces
+Google-style docstrings, import ordering, annotations on production function
+boundaries, and selected bug and Pylint-derived diagnostics. Pytest tests use
+descriptive names and dynamically injected fixtures, so documentation and fixture
+annotation rules are excluded there. Existing directly imported classes and
+helpers are retained; this is an explicit deviation from Google's module-only
+import preference. Do not describe the repository as Google-certified.
+
+## Coordination invariants
+
+- Resolve all linked worktrees to one common Git repository identity.
+- Serialize issue mutations under the existing operation lock and publish state
+  atomically. Do not introduce timeout-based ownership takeover.
+- Require the current offer ID and named recipient for handoff acceptance.
+- Treat file reservations as advisory and peer messages as untrusted data.
+- Preserve native authentication, approvals, and permission decisions.
+- Keep credentials and runtime state outside target source trees. Preserve work
+  on failures, process exits, and restarts.
+- Distinguish observed activity, attempted delivery, explicit acknowledgement,
+  reported verification, and independently verified completion.
+
+## Verification and review
+
+Install the local hooks after cloning:
+
+```sh
+uv sync --locked
+uv run --locked pre-commit install
+uv run --locked pre-commit run --all-files
+```
+
+`.pre-commit-config.yaml` runs Ruff lint/format checks, type checking and the
+repository policy gate using locked tools. It does not rewrite files on commit.
+CI runs the complete gate independently of local hook installation.
+
+Open a focused issue before proposing a substantial behavior change. Branch from
+current `main`, keep commits reviewable, and use the PR template. Explain the
+problem, final behavior, exact verification, and compatibility risks. Every PR
+must pass the required checks and resolve review conversations. Protected `main`
+requires a PR and rejects force pushes and deletion. CI, secret scanning,
+PR hygiene, current-base checks and resolved conversations apply to everyone,
+including administrators, without exemptions.
+
+A separate ruleset requires independent approval. While the repository has one
+maintainer, `@suneel944` has a named exception to that review-only ruleset when
+merging a PR. It does not exempt the account from any required check or permit
+direct pushes. Revisit the review exception when additional maintainers join.
+
+Use Conventional Commit PR titles, such as `fix: preserve pending messages` or
+`ci: validate release metadata`; squash merges retain that title for automated
+changelogs. Assign an owner, add a change-type label, and reference an existing
+local issue with `Refs #N` or a closing keyword. Match linked issue milestones
+when present. Release PRs always require a milestone. Bot-generated descriptions
+retain their native format, but ownership and issue rules still apply.
+
+Contribution text must omit generator credits, assistant attribution, robot
+signatures, and assistant coauthor trailers. This applies to tracked files,
+commit messages, PRs, issues, and comments, including closed items. Keep required
+license notices and factual product documentation intact. Repository policy and
+PR hygiene checks enforce the textual attribution boundary.
+
+Release Please prepares a version and changelog PR after merges to `main`.
+Package, plugin, marketplace and lockfile versions move together. The generated
+PR gets an owner, release issue and milestone, and explicitly dispatched checks
+because GitHub's workflow token does not trigger workflows on its own PR writes.
+Review and merge it through the normal protected-branch gate. Publication creates
+a draft, runs `make check` and the history secret scan, attaches release bundles,
+downloads and verifies their checksums, then publishes. Failed publication keeps
+the release draft; rerun Release with its existing tag to retry. Published assets
+are never overwritten. The release workflow can also publish a manually pushed
+version tag, provided its commit belongs to `main` history.
+
+Contributions are accepted under the repository's MIT license. Submit only work
+you have the right to contribute. Follow CODE_OF_CONDUCT.md and report security
+issues using SECURITY.md rather than public issue templates.
+
+Run focused checks while editing. Before submitting implementation changes, run:
+
+```sh
+make check
+```
+
+CI runs the same locked dependency, lint, formatting, typing, policy, build, and
+test gate. A separate secret scan examines Git history. Actions are pinned to
+commit IDs and receive read-only permissions unless release publication needs
+write access. Dependency updates are proposed through Dependabot PRs.
+Do not weaken
+checks to make a change pass. Explain any narrowly justified rule exception.
+Tests should exercise behavior, especially concurrency, persistence, cancellation,
+and permission boundaries. Distinguish real MCP transport tests from native model
+behavior; the latter requires an explicit two-terminal trial.
+
+Update the README and architecture diagrams when responsibilities or flows change.
+Keep runtime code in the top-level `agent_parley/` package. `make build` must
+produce an installable wheel and a source archive containing both native plugin
+manifests and the shared skill. The installed-package test uses a temporary tool
+environment outside the checkout to catch accidental source-tree imports.
+Keep changes scoped and review the final diff for accidental credentials, runtime
+artifacts, and unrelated edits. Publish the commands actually run and their results.

agent_parley-0.1.0/LICENSE

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

agent_parley-0.1.0/Makefile

@@ -0,0 +1,37 @@
+.PHONY: install install-dev install-system build check release-artifacts benchmark
+install:
+	@set -eu; \
+	bridge_requirements=$$(mktemp); \
+	trap 'rm -f "$$bridge_requirements"' EXIT; \
+	uv export --locked --no-dev --no-emit-project --no-hashes > "$$bridge_requirements"; \
+	uv tool install --python 3.12 . --with-requirements "$$bridge_requirements"
+
+install-dev:
+	@set -eu; \
+	bridge_requirements=$$(mktemp); \
+	trap 'rm -f "$$bridge_requirements"' EXIT; \
+	uv export --locked --no-dev --no-emit-project --no-hashes > "$$bridge_requirements"; \
+	uv tool install --python 3.12 --editable . --with-requirements "$$bridge_requirements"
+
+install-system:
+	@test "$$(id -u)" -eq 0 || { echo 'Run sudo env "PATH=$$PATH" make install-system'; exit 1; }
+	UV_TOOL_DIR=/opt/agent-parley/tools UV_TOOL_BIN_DIR=/usr/local/bin \
+	UV_PYTHON_INSTALL_DIR=/opt/agent-parley/python $(MAKE) install
+
+build:
+	uv build --no-sources
+
+release-artifacts: build
+	uv run --locked python scripts/release_artifacts.py
+
+benchmark:
+	uv run --locked python scripts/benchmark.py
+
+check:
+	uv sync --locked
+	uv run --locked ruff check .
+	uv run --locked ruff format --check .
+	uv run --locked mypy
+	uv run --locked python scripts/check_policy.py
+	$(MAKE) build
+	uv run --locked pytest -q

agent_parley-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.5
+Name: agent-parley
+Version: 0.1.0
+Summary: Run several coding agents in isolated worktrees with shared coordination.
+Project-URL: Repository, https://github.com/suneel944/agent-parley
+Project-URL: Issues, https://github.com/suneel944/agent-parley/issues
+Author-email: Suneel Kaushik S <suneel944@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,codex,coordination,git-worktree,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/suneel944/agent-parley@main/docs/assets/agent-parley.png" width="560" alt="Agent Parley — separate work, shared context">
+</p>
+
+<p align="center">
+  <strong>Separate worktrees. Shared context. One screen.</strong>
+</p>
+
+<p align="center">
+  Run several coding agents at once and know who owns what.<br>
+  Every claim, handoff and refusal is recorded, attributed and visible.
+</p>
+
+<p align="center">
+  <a href="https://github.com/suneel944/agent-parley/releases"><img src="https://img.shields.io/github/v/release/suneel944/agent-parley?style=flat&color=blue" alt="Release"></a>
+  <a href="#install"><img src="https://img.shields.io/badge/runtime_dependencies-0-brightgreen?style=flat" alt="Zero runtime dependencies"></a>
+  <a href="#install"><img src="https://img.shields.io/badge/python-3.12%2B-blue?style=flat" alt="Python 3.12+"></a>
+  <a href="#providers-and-accounts"><img src="https://img.shields.io/badge/native_CLIs-claude_%2B_codex-orange?style=flat" alt="claude and codex"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#see-it">See it</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#run-it">Run</a> ·
+  <a href="#what-it-enforces">Enforce</a> ·
+  <a href="#watch-one-provider">Filter</a> ·
+  <a href="#providers-and-accounts">Providers</a> ·
+  <a href="docs/architecture.md">Docs</a> ·
+  <a href="#what-it-does-not-do">Limits</a>
+</p>
+
+---
+
+## See it
+
+Launch a lane, see who owns what, watch every lane at once, narrow to one
+provider, and watch a hook refuse a branch switch inside an assigned lane.
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/suneel944/agent-parley@main/docs/assets/screenshot-top.svg" width="900" alt="agent-parley top showing three lanes with issues, mail, leases, denials and served calls">
+</p>
+
+One screen for every lane: session state, branch drift, issues owned, handoffs
+pending, unread mail, held reservations, delivered context, and what enforcement
+denied. Read-only, no model call, `q` quits.
+
+Every frame on this page is real command output from a demo project. Only the
+state and project paths are shortened.
+
+## Install
+
+Linux with pidfd support, Git, and [uv](https://docs.astral.sh/uv/). No clone.
+The wheel needs no third-party runtime packages.
+
+```sh
+uv tool install agent-parley
+# to track the default branch instead:
+# uv tool install git+https://github.com/suneel944/agent-parley
+```
+
+Then add the plugin to whichever CLI you drive. One marketplace serves both.
+
+```sh
+claude plugin marketplace add suneel944/agent-parley
+claude plugin install agent-parley@agent-parley-local
+```
+
+```sh
+codex plugin marketplace add suneel944/agent-parley
+codex plugin add agent-parley@agent-parley-local
+```
+
+The plugin carries the shared `coordinate` skill, so an agent can read
+coordination state, claim an issue and hand work off in its own words. It is deliberately
+skill-only: the launcher supplies MCP configuration and lifecycle hooks per
+session, and it is also what creates the worktrees and runs the coordination
+service. The plugin alone gives an agent the skill and nothing to coordinate
+through.
+
+For a pinned, checksummed install, take a wheel from
+[Releases](https://github.com/suneel944/agent-parley/releases) instead.
+
+## Run it
+
+From a committed, clean checkout, one terminal per agent:
+
+```sh
+# Terminal 1
+agent-parley run claude
+
+# Terminal 2
+agent-parley run codex
+```
+
+That is the whole setup. The first run registers the repository, creates that
+participant's worktree and branch, starts the coordination service, and hands
+you the native CLI. Prompt it exactly as you always do.
+
+A new name creates its own lane, so a second account of the same provider, or
+another provider, is one more terminal:
+
+```sh
+agent-parley credentials add account-2 --config-home ~/.claude-account-2
+agent-parley run claude-2 --provider claude --credentials account-2
+```
+
+Then watch the work:
+
+```sh
+agent-parley status   # ownership, activity and reported results
+agent-parley top      # every lane live, including what enforcement denied
+```
+
+When a lane's work is ready, integrate it from the base checkout:
+
+```sh
+agent-parley participant merge claude-2
+```
+
+It always records a merge commit, refuses on a running session, a dirty tree or
+a drifted lane, and leaves a conflict in place for you to resolve. It never
+resets, cleans, stashes or force-switches.
+
+## What it enforces
+
+**Ownership changes only through explicit claims and accepted handoffs.** No
+timeout and no process exit moves an issue. `agent-parley status` reports who
+owns what, which handoff is waiting on an offer ID, and any lane that left its
+assigned branch. An owner can record that one issue waits on another with
+`agent-parley issue block 42 --on 17`; the listing then names who holds the
+blocking issue, and every lane sees the change at its next checkpoint. A
+recorded dependency informs, it does not gate.
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/suneel944/agent-parley@main/docs/assets/screenshot-status.svg" width="880" alt="agent-parley status listing issue owners, a pending handoff, and a lane on the wrong branch">
+</p>
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/suneel944/agent-parley@main/docs/assets/screenshot-issues.svg" width="880" alt="agent-parley issue list showing an issue that waits on another, the participant holding it, and a pending handoff with its offer ID">
+</p>
+
+**Native hooks decide before the tool runs.** They block branch changes inside
+an assigned lane, catch drift after any bypass, and deliver short updates only
+when coordination state actually changes. Each notice is capped at 1,536 UTF-8
+bytes; an unchanged checkpoint adds no context at all.
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/suneel944/agent-parley@main/docs/assets/screenshot-hooks.svg" width="820" alt="Two hook denials with their reasons, and the bounded briefing a session start receives">
+</p>
+
+**Seven scoped MCP tools carry the coordination.** Conflicting reservations
+grant nothing and name the blocking owner with that owner's declared reason.
+Sends need an idempotency key, so a retry returns the original message instead
+of a duplicate. Fetching an inbox never marks a message read.
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/suneel944/agent-parley@main/docs/assets/screenshot-coordination.svg" width="880" alt="A granted reservation, a denied one naming the blocking owner, a deduplicated send, and an inbox page">
+</p>
+
+Enforcement is recorded, not discarded. Every hook decision carries an
+enumerated reason and lands in that participant's event log; every served call
+is recorded inside the transaction that carried its effect. That is why `top`
+can show what was denied, to whom, and how often.
+
+That history is bounded, and it can leave the state directory. A lane keeps two
+event files and discards records older than fourteen days, so `top` reports
+recent enforcement rather than the whole project. `--since` narrows any count
+to a window, and `events export` writes the retained records as JSON Lines you
+can keep for as long as you need:
+
+```sh
+agent-parley top --since 6h
+agent-parley events export --since 7d --output enforcement.jsonl
+```
+
+## Watch one provider
+
+With a dozen lanes open, the whole table is rarely what you want. `--provider`
+narrows the view to the participants driven by one provider, and the header
+counts only the rows it shows:
+
+```sh
+agent-parley top --provider codex
+agent-parley top --provider claude --provider codex
+```
+
+## Providers and accounts
+
+A provider states which native CLI drives a participant and how that CLI reaches
+a model. Every provider drives one of two adapters, which is why two plugin
+installations cover all of them:
+
+| Provider | Native CLI it drives | Plugin that carries `coordinate` |
+| --- | --- | --- |
+| `claude` | `claude` | Claude Code |
+| `codex` | `codex` | Codex |
+| `deepseek`, `kimi`, `grok` | `claude` or `codex`, vendor endpoint | that adapter's plugin |
+| your own, via `agent-parley provider add` | the adapter you name | that adapter's plugin |
+
+`claude` and `codex` work out of the box. The `deepseek`, `kimi` and `grok`
+presets carry no endpoint, so their base URL and key must be exported in the
+launching shell; the launcher refuses to start when a required variable is unset
+rather than falling back to another account. Coordination state records variable
+names and config directories, never credential values.
+
+Credential profiles point a provider's config-home variable at a separate
+directory, so one provider can run under several logins. Up to 32 participants
+per project.
+
+## How it fits together
+
+```mermaid
+flowchart TD
+    Repo[Your repository] --> Launcher[Agent Parley launcher]
+    Launcher --> Claude[Participant · own worktree]
+    Launcher --> Codex[Participant · own worktree]
+    Claude <-->|Seven scoped MCP tools| Server[Local coordination service]
+    Codex <-->|Seven scoped MCP tools| Server
+    Server --> DB[(SQLite WAL · mail and reservations)]
+    Claude --> Claims[Atomic issue claims and handoffs]
+    Codex --> Claims
+    DB --> Hooks[Native checkpoints · bounded updates]
+    Claims --> Hooks
+    Hooks -.-> Claude
+    Hooks -.-> Codex
+```
+
+The coordination engine is built in-house with Python's standard library. It has
+no runtime dependencies and makes no model calls. Your existing logins and
+permission settings still apply.
+
+## What it does not do
+
+Worktrees and reservations are coordination boundaries, not OS sandboxes. Agent
+Bridge does not merge branches, approve commands, or wake idle agents. Reported
+`ready` is ready for review, not verified completion. Token usage still depends
+on the native agents; the bridge reports injected bytes rather than claiming a
+token-saving percentage.
+
+## Contributing
+
+Run `make check` before opening a PR. It checks formatting, lint, typing,
+documentation rules, package builds, and behavior tests.
+
+[Contributing](CONTRIBUTING.md) · [Architecture](docs/architecture.md) ·
+[Operations](docs/operations.md) · [Security](SECURITY.md) ·
+[Code of Conduct](CODE_OF_CONDUCT.md) · [MIT license](LICENSE)