agent2you 1.0.0__tar.gz

agent2you-1.0.0/LICENSE

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

agent2you-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: agent2you
+Version: 1.0.0
+Summary: Deploy a team of chat-resident AI agents from declarative manifests: Hermes + litellm + acp2api + subscription coding CLIs, one container per agent.
+Author: neprel
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/neprel/agent2you
+Project-URL: Repository, https://github.com/neprel/agent2you
+Project-URL: Issues, https://github.com/neprel/agent2you/issues
+Keywords: agents,ai,hermes,acp,mattermost,docker,fleet,claude-code,codex
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# agent2you
+
+Deploy a **team of chat-resident AI agents** from declarative manifests: each
+agent is one container holding Hermes (the employee), litellm (the failover
+chain), acp2api (an OpenAI endpoint over ACP) and the subscription coding CLIs
+(Claude Code, Codex, opencode, cline) that are its brain and hands.
+
+The design was extracted from a production fleet that runs infrastructure,
+product and PM agents as colleagues in Mattermost channels. Every decision in
+this pack — one container per agent, no provider API keys, chat as the only
+inter-agent surface, generated-not-hand-written configs — was measured there
+first.
+
+## What an agent is
+
+```
+   chat platform (Mattermost / Telegram / Slack / ...)
+        │  @mention
+   ┌────┴─────────────────────────────────────────┐
+   │  hermes      presence, sessions, memory, cron │
+   │  litellm     failover: next brain on 429      │   one
+   │  acp2api     OpenAI API ⇄ ACP, per-thread     │   container
+   │              session continuity               │   per agent
+   │  claude / codex / opencode / cline            │
+   │              each spends its own SUBSCRIPTION │
+   └───────────────────────────────────────────────┘
+```
+
+No provider API key exists anywhere in a default deployment: the CLIs log in to
+their own subscriptions, which is the legal basis of the arrangement — and the
+reason nothing here can quietly bill an API account.
+
+Nothing is shared between agents except memory (optional, bank-per-agent) and
+the chat workspace. Two agents cannot interfere with each other by construction.
+
+## Quickstart
+
+```bash
+uv tool install agent2you               # or: pipx install agent2you
+
+a2y init myfleet && cd myfleet          # a self-contained fleet workspace
+$EDITOR fleet.yaml agents/ana/          # who exists, what platform, what memory
+a2y render                              # manifests -> deploy/  (commit it)
+a2y build                               # the agent image, pinned end to end
+cp deploy/example.env deploy/.env       # secrets; a2y doctor checks parity
+$EDITOR deploy/.env
+a2y provision                           # prints the messenger account sequence
+a2y up
+a2y auth ana                            # sign the brains in (once; survives rebuilds)
+a2y doctor                              # end-to-end checks
+```
+
+Adding a colleague later is one command:
+
+```bash
+a2y agent add cqrtai-pm \
+  --description "Project manager for cqrtai: specs, tasks, sequencing." \
+  --github-token --projects cqrtai
+```
+
+It validates against the whole fleet (rolling back on failure), re-renders
+`deploy/`, and prints the numbered checklist of what remains (secrets,
+provisioning, sign-in). The command is deliberately non-interactive so that
+**your own assistant agent can run it**: the interview happens in chat, the
+tool call is the answer — see [docs/hiring.md](docs/hiring.md). Running agents
+discover the newcomer without a restart: the fleet roster in every SOUL.md
+regenerates on a loop from the mounted manifests.
+
+## The manifests
+
+`fleet.yaml` — deployment-level facts: platform (`mattermost` fully wired;
+other Hermes platforms pass their env through), memory (`hindsight` or `none`),
+network (`bridge` by default; shared VPN namespace as an advanced mode),
+observability (Phoenix traces, Prometheus token metrics), image tag, and
+`defaults` merged into every agent.
+
+`agents/<name>/agent.yaml` — the agent: description (its card, roster entry and
+the reason colleagues call it), brain chain and executors, access (ssh volume,
+GitHub token), memory banks, extra MCP servers.
+
+`agents/<name>/SOUL.md` — the persona. `SOUL-shared.md` is appended to everyone.
+
+`a2y render` turns those into `deploy/`: per-agent Hermes / litellm / acp2api /
+hindsight configs, a compose file, and an `example.env` naming every variable
+the deployment needs. The output is deterministic — same manifests, same bytes —
+so the deploy tree is reviewable and belongs in git. Anything the generator
+does not expose: `agents/<name>/overrides/<file>` replaces the generated file,
+and `hermes:`/`acp2api:` keys in agent.yaml deep-merge into those configs.
+
+## What the pack takes care of
+
+- **Session continuity per chat thread** — the `conversation-key` plugin +
+  litellm header forwarding + acp2api's conversation keying, so a thread keeps
+  one coding-agent session instead of cold-starting per message.
+- **A visible working turn** — progress narration into the chat post while the
+  agent works, the trace tucked behind the post's info card when it finishes,
+  and mid-turn steering (`/steer`) delivered INTO the running turn.
+- **Fleet discovery without restarts** — a roster generated from every agent's
+  own manifest, appended to each SOUL.md on a loop.
+- **Routing without a classifier** — untagged messages claimed by exactly one
+  agent from Mattermost facts alone; agent-to-agent messages always need an
+  explicit @mention, which is the loop guard.
+- **Memory in tiers** (optional) — a private Hindsight bank per agent written
+  automatically, shared project banks written deliberately through tools, and
+  bank missions pushed from the repository at every start.
+- **Cost visibility** — acp2api's Prometheus metrics (tokens per agent, per
+  executor, per account) and one Phoenix trace project per agent.
+- **The traps already sprung** — device-code-only logins, `CLAUDE_CONFIG_DIR`,
+  codex's sandbox mode, cline's self-update, the CA store, the tty-guarded
+  bashrc, healthchecks that mean something. They are encoded, not documented.
+
+## Docs
+
+- [docs/architecture.md](docs/architecture.md) — the stack and every decision in it
+- [docs/provisioning.md](docs/provisioning.md) — accounts, tokens, sign-ins, keys
+- [docs/hiring.md](docs/hiring.md) — the interview an assistant agent runs to add a colleague
+- [docs/extending.md](docs/extending.md) — custom tools, platforms, derived images
+
+## Development and releasing
+
+```bash
+uv run --group dev pytest      # the contract: render determinism, validation, env parity
+uv build                       # sdist + wheel (the vendored image ships as package data)
+```
+
+Releases publish to PyPI via **trusted publishing** (OIDC — no API token exists
+anywhere): bump `version` in pyproject.toml, commit, `git tag v<version>`,
+`git push --tags`. The workflow gates on the test suite and on the tag matching
+the version. GitHub Actions are pinned by commit SHA, not by tag — a tag can be
+moved onto a poisoned release; a sha cannot.
+
+## Status
+
+Extracted from a running deployment; the mattermost + hindsight + claude/codex
+path is the proven one. Telegram/Slack/Discord pass through to Hermes' own
+adapters and are not yet exercised end to end by the maintainers.

agent2you-1.0.0/README.md

@@ -0,0 +1,136 @@
+# agent2you
+
+Deploy a **team of chat-resident AI agents** from declarative manifests: each
+agent is one container holding Hermes (the employee), litellm (the failover
+chain), acp2api (an OpenAI endpoint over ACP) and the subscription coding CLIs
+(Claude Code, Codex, opencode, cline) that are its brain and hands.
+
+The design was extracted from a production fleet that runs infrastructure,
+product and PM agents as colleagues in Mattermost channels. Every decision in
+this pack — one container per agent, no provider API keys, chat as the only
+inter-agent surface, generated-not-hand-written configs — was measured there
+first.
+
+## What an agent is
+
+```
+   chat platform (Mattermost / Telegram / Slack / ...)
+        │  @mention
+   ┌────┴─────────────────────────────────────────┐
+   │  hermes      presence, sessions, memory, cron │
+   │  litellm     failover: next brain on 429      │   one
+   │  acp2api     OpenAI API ⇄ ACP, per-thread     │   container
+   │              session continuity               │   per agent
+   │  claude / codex / opencode / cline            │
+   │              each spends its own SUBSCRIPTION │
+   └───────────────────────────────────────────────┘
+```
+
+No provider API key exists anywhere in a default deployment: the CLIs log in to
+their own subscriptions, which is the legal basis of the arrangement — and the
+reason nothing here can quietly bill an API account.
+
+Nothing is shared between agents except memory (optional, bank-per-agent) and
+the chat workspace. Two agents cannot interfere with each other by construction.
+
+## Quickstart
+
+```bash
+uv tool install agent2you               # or: pipx install agent2you
+
+a2y init myfleet && cd myfleet          # a self-contained fleet workspace
+$EDITOR fleet.yaml agents/ana/          # who exists, what platform, what memory
+a2y render                              # manifests -> deploy/  (commit it)
+a2y build                               # the agent image, pinned end to end
+cp deploy/example.env deploy/.env       # secrets; a2y doctor checks parity
+$EDITOR deploy/.env
+a2y provision                           # prints the messenger account sequence
+a2y up
+a2y auth ana                            # sign the brains in (once; survives rebuilds)
+a2y doctor                              # end-to-end checks
+```
+
+Adding a colleague later is one command:
+
+```bash
+a2y agent add cqrtai-pm \
+  --description "Project manager for cqrtai: specs, tasks, sequencing." \
+  --github-token --projects cqrtai
+```
+
+It validates against the whole fleet (rolling back on failure), re-renders
+`deploy/`, and prints the numbered checklist of what remains (secrets,
+provisioning, sign-in). The command is deliberately non-interactive so that
+**your own assistant agent can run it**: the interview happens in chat, the
+tool call is the answer — see [docs/hiring.md](docs/hiring.md). Running agents
+discover the newcomer without a restart: the fleet roster in every SOUL.md
+regenerates on a loop from the mounted manifests.
+
+## The manifests
+
+`fleet.yaml` — deployment-level facts: platform (`mattermost` fully wired;
+other Hermes platforms pass their env through), memory (`hindsight` or `none`),
+network (`bridge` by default; shared VPN namespace as an advanced mode),
+observability (Phoenix traces, Prometheus token metrics), image tag, and
+`defaults` merged into every agent.
+
+`agents/<name>/agent.yaml` — the agent: description (its card, roster entry and
+the reason colleagues call it), brain chain and executors, access (ssh volume,
+GitHub token), memory banks, extra MCP servers.
+
+`agents/<name>/SOUL.md` — the persona. `SOUL-shared.md` is appended to everyone.
+
+`a2y render` turns those into `deploy/`: per-agent Hermes / litellm / acp2api /
+hindsight configs, a compose file, and an `example.env` naming every variable
+the deployment needs. The output is deterministic — same manifests, same bytes —
+so the deploy tree is reviewable and belongs in git. Anything the generator
+does not expose: `agents/<name>/overrides/<file>` replaces the generated file,
+and `hermes:`/`acp2api:` keys in agent.yaml deep-merge into those configs.
+
+## What the pack takes care of
+
+- **Session continuity per chat thread** — the `conversation-key` plugin +
+  litellm header forwarding + acp2api's conversation keying, so a thread keeps
+  one coding-agent session instead of cold-starting per message.
+- **A visible working turn** — progress narration into the chat post while the
+  agent works, the trace tucked behind the post's info card when it finishes,
+  and mid-turn steering (`/steer`) delivered INTO the running turn.
+- **Fleet discovery without restarts** — a roster generated from every agent's
+  own manifest, appended to each SOUL.md on a loop.
+- **Routing without a classifier** — untagged messages claimed by exactly one
+  agent from Mattermost facts alone; agent-to-agent messages always need an
+  explicit @mention, which is the loop guard.
+- **Memory in tiers** (optional) — a private Hindsight bank per agent written
+  automatically, shared project banks written deliberately through tools, and
+  bank missions pushed from the repository at every start.
+- **Cost visibility** — acp2api's Prometheus metrics (tokens per agent, per
+  executor, per account) and one Phoenix trace project per agent.
+- **The traps already sprung** — device-code-only logins, `CLAUDE_CONFIG_DIR`,
+  codex's sandbox mode, cline's self-update, the CA store, the tty-guarded
+  bashrc, healthchecks that mean something. They are encoded, not documented.
+
+## Docs
+
+- [docs/architecture.md](docs/architecture.md) — the stack and every decision in it
+- [docs/provisioning.md](docs/provisioning.md) — accounts, tokens, sign-ins, keys
+- [docs/hiring.md](docs/hiring.md) — the interview an assistant agent runs to add a colleague
+- [docs/extending.md](docs/extending.md) — custom tools, platforms, derived images
+
+## Development and releasing
+
+```bash
+uv run --group dev pytest      # the contract: render determinism, validation, env parity
+uv build                       # sdist + wheel (the vendored image ships as package data)
+```
+
+Releases publish to PyPI via **trusted publishing** (OIDC — no API token exists
+anywhere): bump `version` in pyproject.toml, commit, `git tag v<version>`,
+`git push --tags`. The workflow gates on the test suite and on the tag matching
+the version. GitHub Actions are pinned by commit SHA, not by tag — a tag can be
+moved onto a poisoned release; a sha cannot.
+
+## Status
+
+Extracted from a running deployment; the mattermost + hindsight + claude/codex
+path is the proven one. Telegram/Slack/Discord pass through to Hermes' own
+adapters and are not yet exercised end to end by the maintainers.

agent2you-1.0.0/a2y/__init__.py

@@ -0,0 +1,3 @@
+"""agent2you -- deploy a team of chat-resident AI agents from declarative manifests."""
+
+__version__ = "1.0.0"

agent2you-1.0.0/a2y/agents_cmd.py

@@ -0,0 +1,184 @@
+"""`a2y agent ...` -- manage agents in a fleet workspace.
+
+`a2y agent add` is deliberately non-interactive and single-shot: the intended
+interactive layer is a fleet agent (the assistant) interviewing the operator in
+chat and then calling this command with the answers. The tool stays
+deterministic; the conversation stays where conversations belong. See
+docs/hiring.md for the interview the assistant runs.
+
+Structured input: `--json` accepts a full agent.yaml body (file path or `-` for
+stdin), for callers that would rather build the manifest than spell flags.
+Flags win over `--json` keys.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+from .manifest import NAME_RE, ManifestError, load_fleet
+
+SOUL_SKELETON = """\
+# {name}
+
+You are {name}. {description}
+
+## Scope
+
+- What you own and answer for. Be precise: your colleagues route by this.
+- What you do NOT touch, even when convenient.
+
+## How you work
+
+- Never report success for a tool call that failed; quote the error instead.
+- "Posted" is not "delivered": a mention reaches only members of that channel.
+"""
+
+
+def cmd_agent_add(ns: argparse.Namespace) -> int:
+    root = Path.cwd()
+    if not (root / "fleet.yaml").is_file():
+        print("a2y: no fleet.yaml here -- run from a fleet workspace", file=sys.stderr)
+        return 2
+
+    name = ns.name
+    if not NAME_RE.match(name):
+        print(f"a2y: agent name {name!r} must be lowercase [a-z0-9-]", file=sys.stderr)
+        return 2
+    agent_dir = root / "agents" / name
+    if agent_dir.exists():
+        print(f"a2y: agents/{name}/ already exists", file=sys.stderr)
+        return 2
+
+    manifest: dict = {}
+    if ns.json:
+        raw = sys.stdin.read() if ns.json == "-" else Path(ns.json).read_text()
+        try:
+            manifest = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            print(f"a2y: --json is not valid JSON ({exc})", file=sys.stderr)
+            return 2
+        if not isinstance(manifest, dict):
+            print("a2y: --json must be an object (the agent.yaml body)", file=sys.stderr)
+            return 2
+
+    manifest["name"] = name
+    if ns.description:
+        manifest["description"] = ns.description
+    if not str(manifest.get("description") or "").strip():
+        print("a2y: --description is required (it is the agent's card and roster entry)",
+              file=sys.stderr)
+        return 2
+
+    if ns.chain:
+        brains = manifest.setdefault("brains", {})
+        brains["chain"] = [s.strip() for s in ns.chain.split(",") if s.strip()]
+    if ns.ssh or ns.github_token:
+        access = manifest.setdefault("access", {})
+        if ns.ssh:
+            access["ssh"] = True
+        if ns.github_token:
+            access["github_token"] = True
+    if ns.projects:
+        memory = manifest.setdefault("memory", {})
+        memory["projects"] = [s.strip() for s in ns.projects.split(",") if s.strip()]
+    if ns.reply_mode or ns.no_require_mention:
+        platform = manifest.setdefault("platform", {})
+        if ns.reply_mode:
+            platform["reply_mode"] = ns.reply_mode
+        if ns.no_require_mention:
+            platform["require_mention"] = False
+    if ns.ports_base:
+        manifest["ports"] = {"base": int(ns.ports_base)}
+
+    soul = SOUL_SKELETON.format(name=name, description=manifest["description"])
+    if ns.soul_file:
+        soul = sys.stdin.read() if ns.soul_file == "-" else Path(ns.soul_file).read_text()
+
+    # Write, then validate by loading the whole fleet; roll back on failure so a
+    # bad call leaves no half-created agent behind.
+    agent_dir.mkdir(parents=True)
+    (agent_dir / "agent.yaml").write_text(
+        yaml.safe_dump(manifest, sort_keys=False, allow_unicode=True, width=100))
+    (agent_dir / "SOUL.md").write_text(soul)
+    try:
+        fleet = load_fleet(root)
+    except ManifestError as exc:
+        (agent_dir / "agent.yaml").unlink()
+        (agent_dir / "SOUL.md").unlink()
+        agent_dir.rmdir()
+        print(f"a2y: rolled back agents/{name}/ -- {exc}", file=sys.stderr)
+        return 2
+
+    print(f"  created agents/{name}/agent.yaml")
+    print(f"  created agents/{name}/SOUL.md" + ("" if ns.soul_file else "  (skeleton -- write the real soul)"))
+
+    if not ns.no_render:
+        from .render import render_fleet
+        for rel in render_fleet(fleet):
+            print(f"  wrote deploy/{rel}")
+
+    agent = next(a for a in fleet.agents if a.name == name)
+    p = agent.env_prefix
+    print(f"\n=== next steps for {name} ===")
+    step = 1
+    print(f"  {step}. add to deploy/.env: {p}_LITELLM_MASTER_KEY=<random>"); step += 1
+    if fleet.platform_kind == "mattermost":
+        print(f"  {step}. `a2y provision {name}` -- create the Mattermost account, then set")
+        print(f"     {p}_MATTERMOST_TOKEN, {p}_MATTERMOST_HOME_CHANNEL (and empty {p}_MATTERMOST_CHANNELS)")
+        step += 1
+        print(f"  {step}. append the new USER ID to A2Y_MATTERMOST_ALLOWED_USERS and RECREATE the")
+        print(f"     other agents (`a2y up` recreates on env change) -- without this, messages")
+        print(f"     from {name} are dropped silently"); step += 1
+    if agent.access.get("github_token"):
+        print(f"  {step}. set {p}_GH_TOKEN (fine-grained PAT scoped to its repositories)"); step += 1
+    print(f"  {step}. `a2y up {name}`"); step += 1
+    print(f"  {step}. `a2y auth {name}` -- sign the brains in (device-code flows)"); step += 1
+    if agent.access.get("ssh"):
+        print(f"  {step}. register the git deploy key the entrypoint prints on first start"); step += 1
+    print(f"  {step}. verify with a real mention in the channel; `a2y doctor` last")
+    return 0
+
+
+def cmd_agent_list(_: argparse.Namespace) -> int:
+    fleet = load_fleet(Path.cwd())
+    for a in fleet.agents:
+        marks = []
+        if a.access.get("ssh"):
+            marks.append("ssh")
+        if a.access.get("github_token"):
+            marks.append("gh-token")
+        if a.project_banks():
+            marks.append("projects:" + ",".join(a.project_banks()))
+        suffix = f"  [{'; '.join(marks)}]" if marks else ""
+        print(f"  {a.name}  ({' -> '.join(a.chain)}){suffix}")
+        print(f"      {a.description}")
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("agent", help="manage agents (add, list)")
+    ssub = p.add_subparsers(dest="agent_cmd", required=True)
+
+    pa = ssub.add_parser(
+        "add", help="add an agent non-interactively (built for being called BY an agent)")
+    pa.add_argument("name")
+    pa.add_argument("--description", help="what the agent owns and answers for (required)")
+    pa.add_argument("--chain", help="brain chain, e.g. claude,codex (default: fleet defaults)")
+    pa.add_argument("--ssh", action="store_true", help="mount an ssh key volume")
+    pa.add_argument("--github-token", action="store_true", help="expects AGENT_<N>_GH_TOKEN")
+    pa.add_argument("--projects", help="shared memory banks, comma-separated")
+    pa.add_argument("--reply-mode", choices=["thread", "channel"])
+    pa.add_argument("--no-require-mention", action="store_true")
+    pa.add_argument("--ports-base", help="port block base (shared-namespace fleets only)")
+    pa.add_argument("--soul-file", help="SOUL.md content from a file, or - for stdin")
+    pa.add_argument("--json", help="full agent.yaml body as JSON (file or -); flags win")
+    pa.add_argument("--no-render", action="store_true")
+    pa.set_defaults(fn=cmd_agent_add)
+
+    pl = ssub.add_parser("list", help="list agents with chain and access")
+    pl.set_defaults(fn=cmd_agent_list)