agent2you 1.0.0__py3-none-any.whl

a2y/__init__.py

@@ -0,0 +1,3 @@
+"""agent2you -- deploy a team of chat-resident AI agents from declarative manifests."""
+
+__version__ = "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)

a2y/cli.py

@@ -0,0 +1,264 @@
+"""The a2y command line.
+
+    a2y init <dir> [--name N]   create a fleet workspace
+    a2y agent add <name> ...    add an agent (non-interactive; see docs/hiring.md)
+    a2y agent list              list agents
+    a2y render                  manifests -> deploy/
+    a2y build                   build the agent image from ./image
+    a2y up [agent ...]          ensure volumes, then docker compose up -d
+    a2y down [agent ...]        docker compose stop
+    a2y doctor                  check manifests, env parity, compose, logins
+    a2y auth [agent]            print the interactive sign-in instructions
+    a2y provision [agent]       print the messenger provisioning sequence
+
+Run everything except `init` from a fleet workspace (the directory with
+fleet.yaml).
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__
+from .manifest import Fleet, ManifestError, load_fleet
+
+
+def _fleet() -> Fleet:
+    return load_fleet(Path.cwd())
+
+
+def _compose(fleet: Fleet, *args: str) -> int:
+    deploy = fleet.root / "deploy"
+    env_file = deploy / ".env"
+    cmd = ["docker", "compose", "-f", str(deploy / "docker-compose.yaml")]
+    if env_file.is_file():
+        cmd += ["--env-file", str(env_file)]
+    cmd += list(args)
+    return subprocess.call(cmd)
+
+
+def cmd_init(ns: argparse.Namespace) -> int:
+    from .scaffold import init_workspace
+
+    dest = Path(ns.dir).resolve()
+    dest.mkdir(parents=True, exist_ok=True)
+    name = ns.name or dest.name
+    created = init_workspace(dest, name=name, first_agent=ns.agent)
+    if not created:
+        print(f"{dest}: nothing to do (already initialised)")
+        return 0
+    for rel in created:
+        print(f"  created {rel}")
+    print(
+        f"\nNext:\n"
+        f"  1. edit {dest / 'fleet.yaml'} and agents/{ns.agent}/\n"
+        f"  2. a2y render && a2y build\n"
+        f"  3. cp deploy/example.env deploy/.env  # then fill it\n"
+        f"  4. a2y up && a2y auth {ns.agent}\n"
+        f"  docs: see the agent2you pack's docs/ directory"
+    )
+    return 0
+
+
+def cmd_render(_: argparse.Namespace) -> int:
+    from .render import render_fleet
+
+    fleet = _fleet()
+    changed = render_fleet(fleet)
+    if changed:
+        for rel in changed:
+            print(f"  wrote deploy/{rel}")
+    else:
+        print("deploy/ already up to date")
+    return 0
+
+
+def cmd_build(ns: argparse.Namespace) -> int:
+    fleet = _fleet()
+    image_dir = fleet.root / "image"
+    dockerfile = image_dir / "agent.dockerfile"
+    if not dockerfile.is_file():
+        print(f"{dockerfile} not found -- was this workspace created by `a2y init`?", file=sys.stderr)
+        return 1
+    cmd = ["docker", "build", "-f", str(dockerfile), "-t", fleet.image_tag]
+    if ns.no_cache:
+        cmd.append("--no-cache")
+    cmd.append(str(image_dir))
+    print("+", " ".join(cmd))
+    rc = subprocess.call(cmd)
+    if rc == 0:
+        print(f"Built {fleet.image_tag}. Set A2Y_IMAGE={fleet.image_tag} in deploy/.env.")
+    return rc
+
+
+def cmd_up(ns: argparse.Namespace) -> int:
+    from .render import ensure_volumes, render_fleet
+
+    fleet = _fleet()
+    render_fleet(fleet)
+    for d in ensure_volumes(fleet):
+        print(f"  created {d.relative_to(fleet.root)}")
+    services = [f"agent-{n}" for n in ns.agents] if ns.agents else []
+    return _compose(fleet, "up", "-d", *services)
+
+
+def cmd_down(ns: argparse.Namespace) -> int:
+    fleet = _fleet()
+    services = [f"agent-{n}" for n in ns.agents] if ns.agents else []
+    return _compose(fleet, "stop", *services)
+
+
+def cmd_doctor(_: argparse.Namespace) -> int:
+    from .doctor import run_doctor
+
+    return run_doctor(_fleet())
+
+
+AUTH_TEXT = """\
+=== {agent}: signing the brains in ===
+
+The logins live in volumes/agent-{agent}/ and survive rebuilds; this is done once
+per agent. Use DEVICE-CODE flows only: browser-callback logins listen on the
+container's own localhost, which your browser cannot reach.
+
+  docker exec -it agent-{agent} bash
+
+{steps}
+Forges (only if this agent uses them):
+
+  gh auth login --hostname github.com --git-protocol ssh   # web-browser one-time code
+  tea login add --name <forge> --url <gitea-url> --token <token>
+
+Verify with a real turn, not with the login command's exit code: mention the agent
+in its channel and watch the trace. A missing login surfaces as
+`500 Authentication required` from acp2api on the FIRST turn only.
+"""
+
+AUTH_STEPS = {
+    "claude": "  claude          # then /login -- pick the subscription, it prints a URL and a code\n",
+    "codex": "  codex login --device-auth\n",
+    "opencode": "  # opencode: point it at your endpoint in ~/.config/opencode/opencode.json\n",
+    "cline": "  # cline: requires an interactive cline-account login before ACP works at all\n",
+}
+
+
+def cmd_auth(ns: argparse.Namespace) -> int:
+    fleet = _fleet()
+    agents = [a for a in fleet.agents if not ns.agent or a.name == ns.agent]
+    if not agents:
+        print(f"no agent named {ns.agent!r}", file=sys.stderr)
+        return 1
+    for a in agents:
+        steps = "".join(
+            AUTH_STEPS.get(a.executors[ex].get("kind") or ex, "") for ex in a.chain
+        )
+        print(AUTH_TEXT.format(agent=a.name, steps=steps))
+    return 0
+
+
+PROVISION_MM = """\
+=== {agent}: Mattermost account (ordinary user + personal access token) ===
+
+Agents are ordinary `system_user` accounts, NOT bot accounts -- Mattermost
+refuses bots several things (incoming webhooks, for one), and a colleague should
+read as a colleague.
+
+Via the local admin socket (on the Mattermost host):
+
+  M="docker exec <mattermost-container> mmctl --local"
+  $M user create --email {agent}@{team}.local --username {agent} --password '<strong>'
+  $M team users add {team} {agent}
+  $M channel users add {team}:<channel> {agent}
+  # a personal access token needs the role that permits one:
+  #   sql: update users set roles='system_user system_user_access_token' where username='{agent}';
+  $M token generate {agent} "agent gateway"
+
+Or via the v4 REST API (works from anywhere; login_id must be the USERNAME --
+the admin email answers 401 that reads like a wrong password):
+
+  POST /api/v4/users/login  {{"login_id": "<admin-username>", "password": "..."}}
+  POST /api/v4/users        -> user id
+  PUT  /api/v4/users/{{id}}/roles   {{"roles": "system_user system_user_access_token"}}
+  POST /api/v4/teams/<team>/members
+  POST /api/v4/channels/<id>/members
+  POST /api/v4/users/{{id}}/tokens  -> the token, RETURNED ONLY ONCE
+
+Then:
+  1. put the token in deploy/.env as {prefix}_MATTERMOST_TOKEN
+  2. append the new USER ID to A2Y_MATTERMOST_ALLOWED_USERS
+  3. recreate the OTHER agents (that list is container environment) -- without
+     this, messages from the new colleague are dropped with no error anywhere.
+
+Membership POSTs are no-ops when already present, so the sequence is safe to
+re-run after a partial failure.
+"""
+
+
+def cmd_provision(ns: argparse.Namespace) -> int:
+    fleet = _fleet()
+    if fleet.platform_kind != "mattermost":
+        print(f"platform.kind is {fleet.platform_kind!r}; provisioning docs cover mattermost. "
+              "For other Hermes platforms create the bot/account per that platform's docs and "
+              "pass its variables via platform.env.")
+        return 0
+    agents = [a for a in fleet.agents if not ns.agent or a.name == ns.agent]
+    for a in agents:
+        print(PROVISION_MM.format(agent=a.name, team=fleet.platform.get("team", "<team>"),
+                                  prefix=a.env_prefix))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="a2y", description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--version", action="version", version=f"a2y {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("init", help="create a fleet workspace")
+    p.add_argument("dir")
+    p.add_argument("--name", help="fleet name (default: directory name)")
+    p.add_argument("--agent", default="ana", help="name of the first agent (default: ana)")
+    p.set_defaults(fn=cmd_init)
+
+    from .agents_cmd import register as register_agent_cmd
+    register_agent_cmd(sub)
+
+    p = sub.add_parser("render", help="manifests -> deploy/")
+    p.set_defaults(fn=cmd_render)
+
+    p = sub.add_parser("build", help="build the agent image")
+    p.add_argument("--no-cache", action="store_true")
+    p.set_defaults(fn=cmd_build)
+
+    p = sub.add_parser("up", help="ensure volumes, docker compose up -d")
+    p.add_argument("agents", nargs="*")
+    p.set_defaults(fn=cmd_up)
+
+    p = sub.add_parser("down", help="docker compose stop")
+    p.add_argument("agents", nargs="*")
+    p.set_defaults(fn=cmd_down)
+
+    p = sub.add_parser("doctor", help="check the deployment end to end")
+    p.set_defaults(fn=cmd_doctor)
+
+    p = sub.add_parser("auth", help="print brain sign-in instructions")
+    p.add_argument("agent", nargs="?")
+    p.set_defaults(fn=cmd_auth)
+
+    p = sub.add_parser("provision", help="print messenger provisioning sequence")
+    p.add_argument("agent", nargs="?")
+    p.set_defaults(fn=cmd_provision)
+
+    ns = parser.parse_args(argv)
+    try:
+        return ns.fn(ns)
+    except ManifestError as exc:
+        print(f"a2y: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

a2y/doctor.py

@@ -0,0 +1,116 @@
+"""`a2y doctor` -- say what is wrong before a container has to."""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from .manifest import Fleet
+from . import render as R
+
+
+def _env_names(text: str) -> list[str]:
+    return [m.group(1) for m in re.finditer(r"^([A-Z][A-Z0-9_]*)=", text, re.M)]
+
+
+def run_doctor(fleet: Fleet) -> int:
+    problems = 0
+
+    def warn(msg: str) -> None:
+        nonlocal problems
+        problems += 1
+        print(f"  ✗ {msg}")
+
+    def ok(msg: str) -> None:
+        print(f"  ✓ {msg}")
+
+    deploy = fleet.root / "deploy"
+
+    # 1. deploy tree freshness -- render into memory and compare.
+    print("deploy tree")
+    if not deploy.is_dir():
+        warn("deploy/ does not exist -- run `a2y render`")
+    else:
+        import io
+        from contextlib import redirect_stdout
+        with redirect_stdout(io.StringIO()):
+            changed = R.render_fleet(fleet)
+        if changed:
+            warn(f"deploy/ was stale; render just refreshed: {', '.join(changed)}")
+        else:
+            ok("deploy/ matches the manifests")
+
+    # 2. .env parity -- the invariant that a missing variable can break an
+    #    UNRELATED service's compose render.
+    print("environment")
+    example = deploy / "example.env"
+    dotenv = deploy / ".env"
+    if not dotenv.is_file():
+        warn("deploy/.env is missing -- `cp deploy/example.env deploy/.env` and fill it")
+    elif example.is_file():
+        have = dict.fromkeys(_env_names(dotenv.read_text()))
+        missing = [n for n in _env_names(example.read_text()) if n not in have]
+        if missing:
+            warn(f".env is missing variable(s) from example.env: {', '.join(missing)}")
+        else:
+            ok(".env carries every variable example.env declares")
+        empty = [
+            line.split("=", 1)[0]
+            for line in dotenv.read_text().splitlines()
+            if re.match(r"^[A-Z][A-Z0-9_]*=$", line.strip())
+        ]
+        if empty:
+            print(f"  · empty (fill or confirm deliberate): {', '.join(empty)}")
+
+    # 3. docker
+    print("docker")
+    if not shutil.which("docker"):
+        warn("docker is not on PATH")
+    else:
+        ok("docker present")
+        if dotenv.is_file():
+            proc = subprocess.run(
+                ["docker", "compose", "-f", str(deploy / "docker-compose.yaml"),
+                 "--env-file", str(dotenv), "config", "-q"],
+                capture_output=True, text=True,
+            )
+            if proc.returncode != 0:
+                warn(f"compose config does not render:\n{proc.stderr.strip()}")
+            else:
+                ok("docker compose config renders")
+
+    # 4. volumes
+    print("volumes")
+    missing_dirs = [
+        str(Path("volumes") / a.container)
+        for a in fleet.agents
+        if not (fleet.root / "volumes" / a.container).is_dir()
+    ]
+    if missing_dirs:
+        print(f"  · not created yet (a2y up will): {', '.join(missing_dirs)}")
+    else:
+        ok("state directories exist")
+
+    # 5. logins -- the one step nobody can automate.
+    print("brains (sign-in state is per volume; empty means not signed in yet)")
+    for a in fleet.agents:
+        base = fleet.root / "volumes" / a.container
+        for ex in a.chain:
+            kind = a.executors[ex].get("kind") or ex
+            marker = {
+                "claude": base / "claude" / ".credentials.json",
+                "codex": base / "codex" / "auth.json",
+            }.get(kind)
+            if marker is None:
+                continue
+            state = "signed in" if marker.is_file() else "NOT signed in (a2y auth)"
+            print(f"  · {a.name}/{ex}: {state}")
+
+    print()
+    if problems:
+        print(f"{problems} problem(s).")
+        return 1
+    print("No problems found.")
+    return 0