agent-collab-kit 0.1.1__py3-none-any.whl

agent_collab.py

@@ -0,0 +1,234 @@
+"""Cooperative mail and exact-resource leases for a trusted local machine."""
+
+__version__ = "0.1.1"
+
+import argparse
+from contextlib import contextmanager
+import json
+import math
+import sqlite3
+import sys
+import time
+import uuid
+
+
+class Conflict(ValueError):
+    """An existing message or lease conflicts with this request."""
+
+
+def text_value(value, name):
+    if not isinstance(value, str) or not value.strip() or "\x00" in value:
+        raise ValueError(name + " must be a nonempty string without NUL")
+    return value
+
+
+def ttl_value(value):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError("ttl must be numeric")
+    if not math.isfinite(value) or not 0 < value <= 86400:
+        raise ValueError("ttl must be finite, positive and <= 86400 seconds")
+    return value
+
+
+class Store:
+    """Every mutating call uses one BEGIN IMMEDIATE transaction.
+
+    clock is injectable for tests; production assumes a trusted wall clock.
+    Opening requires an explicitly initialized database.
+    """
+
+    def __init__(self, db, clock=time.time):
+        text_value(str(db), "db")
+        self.clock = clock
+        self.conn = sqlite3.connect(str(db), timeout=10, isolation_level=None)
+        self.conn.row_factory = sqlite3.Row
+        self.conn.execute("PRAGMA busy_timeout=10000")
+        version = self.conn.execute("PRAGMA user_version").fetchone()[0]
+        if version != 1:
+            self.conn.close()
+            raise ValueError("database is not initialized; run init")
+
+    @staticmethod
+    def initialize(db):
+        text_value(str(db), "db")
+        conn = sqlite3.connect(str(db), timeout=10, isolation_level=None)
+        try:
+            conn.execute("PRAGMA busy_timeout=10000")
+            conn.execute("BEGIN IMMEDIATE")
+            version = conn.execute("PRAGMA user_version").fetchone()[0]
+            if version not in (0, 1):
+                raise ValueError("unsupported database version")
+            conn.execute("""CREATE TABLE IF NOT EXISTS messages (
+                id TEXT PRIMARY KEY, idempotency_key TEXT NOT NULL UNIQUE,
+                sender TEXT NOT NULL, recipient TEXT NOT NULL, body TEXT NOT NULL,
+                created_at REAL NOT NULL, acknowledged_at REAL)""")
+            conn.execute("""CREATE TABLE IF NOT EXISTS leases (
+                resource TEXT PRIMARY KEY COLLATE BINARY, owner TEXT NOT NULL,
+                generation TEXT NOT NULL, expires_at REAL NOT NULL)""")
+            conn.execute("PRAGMA user_version=1")
+            conn.execute("COMMIT")
+        except Exception:
+            if conn.in_transaction:
+                conn.execute("ROLLBACK")
+            raise
+        finally:
+            conn.close()
+
+    def close(self):
+        self.conn.close()
+
+    def now(self):
+        value = self.clock()
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ValueError("clock must return a finite number")
+        if not math.isfinite(value):
+            raise ValueError("clock must return a finite number")
+        return value
+
+    @contextmanager
+    def transaction(self):
+        self.conn.execute("BEGIN IMMEDIATE")
+        try:
+            yield
+            self.conn.execute("COMMIT")
+        except Exception:
+            self.conn.execute("ROLLBACK")
+            raise
+
+    def send(self, sender, recipient, body, key):
+        for name, value in (("sender", sender), ("recipient", recipient),
+                            ("body", body), ("key", key)):
+            text_value(value, name)
+        with self.transaction():
+            old = self.conn.execute(
+                "SELECT * FROM messages WHERE idempotency_key=?", (key,)
+            ).fetchone()
+            if old is not None:
+                if (old["sender"], old["recipient"], old["body"]) != (
+                        sender, recipient, body):
+                    raise Conflict("idempotency key has a different payload")
+                return dict(old)
+            identifier = str(uuid.uuid4())
+            self.conn.execute(
+                "INSERT INTO messages VALUES (?,?,?,?,?,?,NULL)",
+                (identifier, key, sender, recipient, body, self.now()))
+            return dict(self.conn.execute(
+                "SELECT * FROM messages WHERE id=?", (identifier,)).fetchone())
+
+    def inbox(self, recipient):
+        text_value(recipient, "recipient")
+        return [dict(row) for row in self.conn.execute(
+            "SELECT * FROM messages WHERE recipient=? AND acknowledged_at IS NULL "
+            "ORDER BY created_at, id", (recipient,))]
+
+    def ack(self, identifier, recipient):
+        text_value(identifier, "id")
+        text_value(recipient, "recipient")
+        with self.transaction():
+            row = self.conn.execute(
+                "SELECT * FROM messages WHERE id=? AND recipient=?",
+                (identifier, recipient)).fetchone()
+            if row is None:
+                raise Conflict("message not found for recipient")
+            if row["acknowledged_at"] is None:
+                self.conn.execute(
+                    "UPDATE messages SET acknowledged_at=? WHERE id=?",
+                    (self.now(), identifier))
+            return dict(self.conn.execute(
+                "SELECT * FROM messages WHERE id=?", (identifier,)).fetchone())
+
+    def claim(self, resource, owner, ttl):
+        text_value(resource, "resource")
+        text_value(owner, "owner")
+        ttl_value(ttl)
+        with self.transaction():
+            now = self.now()
+            row = self.conn.execute(
+                "SELECT * FROM leases WHERE resource=?", (resource,)).fetchone()
+            if row is not None and row["expires_at"] > now:
+                raise Conflict("resource has an active lease")
+            generation = str(uuid.uuid4())
+            self.conn.execute("INSERT OR REPLACE INTO leases VALUES (?,?,?,?)",
+                              (resource, owner, generation, now + ttl))
+            return {"resource": resource, "owner": owner,
+                    "generation": generation, "expires_at": now + ttl}
+
+    def _owned(self, resource, owner, generation, now):
+        for name, value in (("resource", resource), ("owner", owner),
+                            ("generation", generation)):
+            text_value(value, name)
+        row = self.conn.execute(
+            "SELECT * FROM leases WHERE resource=? AND owner=? AND generation=?",
+            (resource, owner, generation)).fetchone()
+        if row is None or row["expires_at"] <= now:
+            raise Conflict("lease token does not identify an active lease")
+        return row
+
+    def renew(self, resource, owner, generation, ttl):
+        ttl_value(ttl)
+        with self.transaction():
+            now = self.now()
+            self._owned(resource, owner, generation, now)
+            self.conn.execute("UPDATE leases SET expires_at=? WHERE resource=?",
+                              (now + ttl, resource))
+            return dict(self.conn.execute(
+                "SELECT * FROM leases WHERE resource=?", (resource,)).fetchone())
+
+    def release(self, resource, owner, generation):
+        with self.transaction():
+            self._owned(resource, owner, generation, self.now())
+            self.conn.execute("DELETE FROM leases WHERE resource=?", (resource,))
+            return {"released": resource}
+
+    def leases(self):
+        now = self.now()
+        return [dict(row) for row in self.conn.execute(
+            "SELECT * FROM leases WHERE expires_at>? ORDER BY resource", (now,))]
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--db", required=True, help="explicit local SQLite file")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("init")
+    send = commands.add_parser("send")
+    for name in ("sender", "recipient", "body", "key"):
+        send.add_argument("--" + name, required=True)
+    inbox = commands.add_parser("inbox")
+    inbox.add_argument("--recipient", required=True)
+    ack = commands.add_parser("ack")
+    ack.add_argument("--id", required=True)
+    ack.add_argument("--recipient", required=True)
+    for command in ("claim", "renew", "release"):
+        sub = commands.add_parser(command)
+        sub.add_argument("--resource", required=True)
+        sub.add_argument("--owner", required=True)
+        if command != "claim":
+            sub.add_argument("--generation", required=True)
+        if command != "release":
+            sub.add_argument("--ttl", required=True, type=float)
+    commands.add_parser("leases")
+    args = vars(parser.parse_args(argv))
+    db, command = args.pop("db"), args.pop("command")
+    store = None
+    try:
+        if command == "init":
+            Store.initialize(db)
+            result = {"initialized": db}
+        else:
+            store = Store(db)
+            if command == "ack":
+                args["identifier"] = args.pop("id")
+            result = getattr(store, command)(**args)
+        print(json.dumps(result, ensure_ascii=False))
+        return 0
+    except (ValueError, sqlite3.Error, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    finally:
+        if store is not None:
+            store.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_collab_kit-0.1.1.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: agent-collab-kit
+Version: 0.1.1
+Summary: Local SQLite mailbox, acknowledgements and cooperative leases for AI agents on one trusted machine. Python standard library only.
+Author: ALTA VISTA360, S.L.U.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kanibal-studio/agent-collab-kit
+Project-URL: Issues, https://github.com/kanibal-studio/agent-collab-kit/issues
+Project-URL: PyPI, https://pypi.org/project/agent-collab-kit/
+Keywords: ai-agents,multi-agent,coordination,sqlite,mailbox,leases,claude-code
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Agent Collab Kit
+
+A small Python 3.10+ standard-library tool for cooperative work on one trusted
+machine: durable messages, explicit acknowledgements, and leases for exact
+resource names. Inspired by operational patterns, this is an original standalone
+implementation, not an export of a production system. It runs without a provider,
+agent framework, cloud service, Git execution, or automatic orchestration.
+It does not claim a new coordination model.
+
+## Try it with an isolated database
+
+Run from this directory on a local disk. The example uses a temporary directory
+and fictitious participants; never point a demonstration at a live project DB.
+Shell commands below use a POSIX shell:
+
+```sh
+DEMO_DIR=$(mktemp -d)
+DB="$DEMO_DIR/demo.db"
+python3 agent_collab.py --db "$DB" init
+python3 agent_collab.py --db "$DB" send --sender worker-a --recipient integrator --key demo-result-1 --body 'Addition is ready for review'
+python3 agent_collab.py --db "$DB" inbox --recipient integrator
+# Copy the returned message id into MESSAGE_ID.
+python3 agent_collab.py --db "$DB" ack --recipient integrator --id MESSAGE_ID
+python3 agent_collab.py --db "$DB" claim --resource src/add.py --owner worker-a --ttl 300
+# Copy the returned generation UUID into GENERATION.
+python3 agent_collab.py --db "$DB" renew --resource src/add.py --owner worker-a --generation GENERATION --ttl 300
+python3 agent_collab.py --db "$DB" leases
+python3 agent_collab.py --db "$DB" release --resource src/add.py --owner worker-a --generation GENERATION
+python3 -m unittest discover -s tests -v
+```
+
+All commands require `--db`. `init` is repeatable. Commands return JSON on success,
+exit 0, or an error on stderr, exit 1 (invalid CLI syntax exits 2). An idempotency
+key is unique across the database: repeating the same sender, recipient and body
+returns the existing message, including its acknowledgement state. Reusing a key
+for different content fails. `inbox` shows only pending mail for the named recipient.
+`ack` requires that recipient name and is repeatable. Acknowledgement means the
+caller marked the message received; it does not prove work was delivered or tested.
+
+## Cooperative leases and recovery
+
+Use the fictitious [collaboration board](examples/COLLAB.md) to agree on distinct
+responsibilities and one integrator. Claim every exact resource before editing;
+use a shared resource such as `__commit__` to serialize integration by agreement.
+Resource names are opaque and case-sensitive. `src`, `src/a.py`, and `src/A.py`
+are separate resources. Paths are not normalized, folders have no recursive
+coverage, and aliases such as `./src/a.py` require a naming convention.
+
+A claim creates a fresh generation UUID. An active claim conflicts even for the
+same owner; renew using the current generation. TTL must be finite, positive and
+at most 86400 seconds. Renew and release require the matching owner and generation
+and an unexpired lease. At the exact expiration time, a new claim may take over.
+An expired token cannot renew or release its successor, even with the same owner.
+`leases` lists active leases only; expired rows remain until replaced.
+
+After a crash, reopen the same database, inspect pending messages and leases,
+check the actual work and running processes, then agree on a takeover. There is
+no forced release. Lease expiry does not stop the previous worker or undo edits:
+a paused worker may resume after takeover. Workers must check ownership and stop
+on loss; this tool provides no filesystem fencing. The test suite demonstrates
+expiry, stale tokens, persistence and two real processes racing for one claim.
+
+Every mutation uses SQLite `BEGIN IMMEDIATE` and a 10-second busy timeout.
+A timeout is an error, not a successful claim; inspect state before retrying.
+The API accepts an injected clock for tests; normal operation trusts the wall
+clock. Clock corrections can shorten or prolong leases. Close connections before
+making a consistent backup, and retain SQLite sidecars if present. No background
+service, watcher, automatic renewal, pruning or deletion is supplied.
+
+## Trust and limits
+
+Use a single trusted machine and a local disk. Network filesystems and separate
+hosts are unsupported. Names and UUIDs are cooperative tokens, not authenticated
+identities or security boundaries: anyone with database access can impersonate a
+participant, read messages, or alter state. Use operating-system permissions and
+keep secrets out of message bodies. Coordination does not guarantee exclusive
+writes, safe Git operations, exactly-once external effects, or code quality.
+The tool reads no production configuration and invokes no external commands.
+
+Database files and common SQLite sidecars are ignored by Git; keep any custom
+DB filename outside the repository or extend the ignore rules yourself.
+
+## Help project agents improve
+
+The [supervised improvement method](examples/AGENT_IMPROVEMENT.md) shows how
+business agents can contribute evidence and proposals to development, with an
+isolated reproduction, regression and counterfactual checks, cost/quality
+measurement, an integrator's adoption or rejection decision, and learning saved
+in artifacts the agent actually consumes. Its triage example is fictional.
+The kit coordinates this loop through mail and exact-resource claims; it does
+not train models or authorize operational actions automatically.
+
+## Use with Claude Code
+
+Run one Claude Code session per worker on the same machine and give every session
+the same database, kept outside any repository:
+
+```sh
+mkdir -p ~/.agent-collab
+python3 /path/to/agent_collab.py --db ~/.agent-collab/team.db init
+```
+
+A short block in each project's `CLAUDE.md` is enough for the sessions to use it:
+
+```markdown
+## Coordination
+- At the start of a task, read your mail:
+  `python3 /path/to/agent_collab.py --db ~/.agent-collab/team.db inbox --recipient <your-name>`,
+  then acknowledge each message you have handled with `ack`.
+- Before editing a file, claim its exact path with `claim --resource <path> --owner <your-name> --ttl 900`,
+  renew with the returned generation while you work, and `release` it when done.
+- If a claim is refused, do not edit that file: `send` a message to the current owner instead.
+- Only the integrator commits, after claiming `__commit__`.
+```
+
+Each session runs these commands through its usual shell tool, so your permission
+settings still apply. The leases stay cooperative: they guide sessions that follow
+the instruction and do not stop one that ignores it.
+
+## Project context and license
+
+Prepared by [Kanibal Studio](https://github.com/kanibal-studio), associated with
+ALTA VISTA360, S.L.U. Our public sites are [K-Pulse](https://infos.kanibal-studio.com/),
+[Altavista360](https://altavista360.com), and
+[Altavista Conseil](https://altavista-conseil.com). These links provide context;
+this local tool has no integration with those sites.
+
+This package is released under the [MIT license](LICENSE).
+
+**En français :** cet outil local facilite la coordination volontaire de plusieurs
+agents : messages persistants, accusés de réception explicites et baux sur noms
+exacts. Il ne contrôle ni les identités ni les fichiers. Un seul intégrateur
+vérifie et intègre le travail. Les exemples et tests utilisent des données fictives.

agent_collab_kit-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_collab.py,sha256=0N5_ghMNO5iT785QC5fAPUoKYdtoE3zNqr5V9NZNlwI,9314
+agent_collab_kit-0.1.1.dist-info/licenses/LICENSE,sha256=Bwbo0cToS5HWt5DDFX2RrK-xVE-t0pFi7zJqnyeGMc4,1078
+agent_collab_kit-0.1.1.dist-info/METADATA,sha256=0WfPFfvk53BeAuTRevmUvISpUf4iAOfHxEca8FmwacA,8470
+agent_collab_kit-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+agent_collab_kit-0.1.1.dist-info/entry_points.txt,sha256=yvU9u_pZalj3QHA_RY3Irzylz44TWdk946S_bEJnf90,51
+agent_collab_kit-0.1.1.dist-info/top_level.txt,sha256=dXuak1gY0WOhxY3xm_xnpnY6qWASpraPJkLhDwZV6r4,13
+agent_collab_kit-0.1.1.dist-info/RECORD,,

agent_collab_kit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_collab_kit-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-collab = agent_collab:main

agent_collab_kit-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ALTA VISTA360, S.L.U.
+
+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_collab_kit-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_collab