atgent 0.3.0__py3-none-any.whl

agent_mailbox/__init__.py

@@ -0,0 +1,3 @@
+"""atgent: email to local coding agents."""
+
+__version__ = "0.2.0"

agent_mailbox/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

agent_mailbox/claude_approvals.py

@@ -0,0 +1,268 @@
+"""Claude's native SDK permission channel, backed by one-use email decisions.
+
+The wire format mirrors anthropics/claude-agent-sdk-python's internal Query.
+Only a native can_use_tool request can be approved; CLI deny rules and hooks
+still run first. No plugin, MCP server, persistent settings, or replay is used.
+"""
+
+import json
+import queue
+import subprocess
+import tempfile
+import threading
+import time
+
+
+def claude_email_command(config, job):
+    command = list(config["agents"]["claude"]["command"])
+    forbidden = (
+        "--dangerously-skip-permissions",
+        "--allow-dangerously-skip-permissions",
+    )
+    if any(arg.split("=", 1)[0] in forbidden for arg in command):
+        raise ValueError("Email approvals cannot use permission bypass flags")
+    command += [
+        "-p",
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--input-format",
+        "stream-json",
+        "--permission-mode",
+        "default",
+        "--permission-prompts",
+        "host",
+        "--permission-prompt-tool",
+        "stdio",
+    ]
+    from .core import model_args
+
+    command += model_args(config, job, "claude")
+    if job.get("session"):
+        command.append("--resume=" + job["session"])
+    return command
+
+
+def permission_response(request_id, approved, original_input):
+    decision = (
+        {"behavior": "allow", "updatedInput": original_input}
+        if approved
+        else {"behavior": "deny", "message": "Email approval denied or unavailable."}
+    )
+    return {
+        "type": "control_response",
+        "response": {
+            "subtype": "success",
+            "request_id": request_id,
+            "response": decision,
+        },
+    }
+
+
+def run_claude(worker, job, prompt, env, deadline):
+    """Run a single turn while keeping stdin open for native permission replies."""
+    from .runtime import consume_event, process_start
+
+    proc = None
+    reader = None
+    events = queue.Queue()
+    pending = {}
+    seen = set()
+    text = ""
+    error = None
+    status = "completed"
+    initialized = False
+    got_result = False
+    init_id = "mailbox_initialize"
+    init_deadline = min(deadline, time.monotonic() + 120)
+
+    def read_events():
+        try:
+            for line in proc.stdout:
+                try:
+                    event = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(event, dict):
+                    events.put(event)
+        finally:
+            events.put(None)
+
+    def send(value):
+        proc.stdin.write(json.dumps(value, ensure_ascii=False) + "\n")
+        proc.stdin.flush()
+
+    try:
+        with tempfile.TemporaryFile() as err:
+            proc = subprocess.Popen(
+                claude_email_command(worker.config, job),
+                cwd=worker.config["projects"][job["project"]],
+                env=env,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=err,
+                text=True,
+                start_new_session=True,
+            )
+            worker.store.process(job["id"], proc.pid, process_start(proc.pid))
+            reader = threading.Thread(target=read_events, daemon=True)
+            reader.start()
+            send(
+                {
+                    "type": "control_request",
+                    "request_id": init_id,
+                    "request": {"subtype": "initialize", "hooks": None},
+                }
+            )
+            stream_closed = False
+            while not stream_closed:
+                if worker.shutdown.is_set() or worker.store.cancelled(
+                    job["thread"], job["id"]
+                ):
+                    status = "interrupted" if worker.shutdown.is_set() else "cancelled"
+                    break
+                now = time.monotonic()
+                if now >= deadline or (not initialized and now >= init_deadline):
+                    status = "timed_out"
+                    error = (
+                        "Claude permission channel initialization timed out."
+                        if not initialized
+                        else None
+                    )
+                    break
+                # Consume the durable grant immediately before allowing exactly one
+                # matching call. An approved email is not a persistent permission rule.
+                for request_id, (token, original_input) in list(pending.items()):
+                    decision = worker.store.approval_decision(token)
+                    if decision == "pending":
+                        continue
+                    approved = decision == "approved" and worker.store.consume_approval(
+                        token
+                    )
+                    send(permission_response(request_id, approved, original_input))
+                    del pending[request_id]
+                try:
+                    event = events.get(timeout=0.1)
+                except queue.Empty:
+                    if proc.poll() is not None and not reader.is_alive():
+                        stream_closed = True
+                    continue
+                if event is None:
+                    stream_closed = True
+                    continue
+                if event.get("type") == "control_response":
+                    response = event.get("response", {})
+                    if response.get("request_id") == init_id:
+                        if initialized or response.get("subtype") != "success":
+                            raise ValueError("Invalid Claude initialization response")
+                        initialized = True
+                        send(
+                            {
+                                "type": "user",
+                                "session_id": "",
+                                "parent_tool_use_id": None,
+                                "message": {"role": "user", "content": prompt},
+                            }
+                        )
+                    continue
+                if event.get("type") == "control_cancel_request":
+                    # CLI abandoned the call. Never send a late allow to it.
+                    abandoned = pending.pop(event.get("request_id"), None)
+                    if abandoned:
+                        worker.store.revoke_approval(abandoned[0])
+                    continue
+                if event.get("type") == "control_request":
+                    request_id, request = (
+                        event.get("request_id"),
+                        event.get("request", {}),
+                    )
+                    if (
+                        not initialized
+                        or not isinstance(request_id, str)
+                        or request_id in seen
+                    ):
+                        raise ValueError(
+                            "Invalid or duplicate Claude permission request"
+                        )
+                    seen.add(request_id)
+                    if (
+                        request.get("subtype") != "can_use_tool"
+                        or not isinstance(request.get("tool_name"), str)
+                        or not isinstance(request.get("input"), dict)
+                    ):
+                        send(permission_response(request_id, False, {}))
+                        continue
+                    timeout = min(
+                        worker.config.get("approval_timeout_seconds", 900),
+                        max(1, int(deadline - time.monotonic())),
+                    )
+                    payload = {
+                        "agent": "claude",
+                        "request_id": request_id,
+                        "tool_name": request["tool_name"],
+                        "input": request["input"],
+                        "tool_use_id": request.get("tool_use_id"),
+                        "decision_reason": request.get("decision_reason"),
+                        "cwd": worker.config["projects"][job["project"]],
+                        "session": job.get("session"),
+                        "project": job["project"],
+                        "native_request": request,
+                    }
+                    try:
+                        token = worker.store.request_approval(job, payload, timeout)
+                    except ValueError:
+                        send(permission_response(request_id, False, {}))
+                        continue
+                    pending[request_id] = (token, request["input"])
+                    continue
+                session, result, event_error = consume_event(event, "claude")
+                if session:
+                    if job.get("session") and session != job["session"]:
+                        raise ValueError(
+                            "Claude resumed a different session; refusing to continue"
+                        )
+                    worker.store.session(job["thread"], session)
+                if result is not None:
+                    text = result
+                if event_error:
+                    error = event_error
+                if event.get("type") == "result":
+                    got_result = True
+                    # One runner job is one turn; stdin otherwise intentionally stays
+                    # open for the permission host. Closing here ends the CLI cleanly.
+                    proc.stdin.close()
+            if status != "completed":
+                worker.terminate(proc)
+            else:
+                try:
+                    proc.wait(timeout=10)
+                except subprocess.TimeoutExpired:
+                    worker.terminate(proc)
+                    status = "failed"
+                    error = "Claude permission channel did not close after its result."
+                if status == "completed" and (
+                    proc.returncode or error or not got_result or not text
+                ):
+                    status = (
+                        "needs_review"
+                        if (error or "").startswith("Permission review needed:")
+                        else "failed"
+                    )
+            return (
+                status,
+                error
+                or text
+                or f"Claude exit {proc.returncode}; review locally; no automatic replay.",
+            )
+    finally:
+        try:
+            worker.store.revoke_approvals(job["id"])
+        finally:
+            # Database errors must never leave the child agent running.
+            if proc:
+                worker.terminate(proc)
+                if reader:
+                    reader.join(timeout=5)
+                for stream in (proc.stdin, proc.stdout):
+                    if stream and not stream.closed:
+                        stream.close()

agent_mailbox/cli.py

@@ -0,0 +1,319 @@
+import argparse
+import fcntl
+import json
+import logging
+import os
+import signal
+import subprocess
+import sys
+import threading
+from pathlib import Path
+
+from .core import MODEL, Store, load_config, pickup_command, resume_spec
+from .runtime import Gmail, Worker, recover_processes
+
+DEFAULT_CONFIG = Path.home() / ".config" / "agent-mailbox" / "config.json"
+
+
+def main():
+    os.umask(0o077)
+    parser = argparse.ArgumentParser(
+        prog="atgent", description="Email an idea. Your local coding agent gets to work."
+    )
+    parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG)
+    sub = parser.add_subparsers(dest="action", required=True)
+    init = sub.add_parser(
+        "init", help="Create a Gmail configuration (no secrets stored)"
+    )
+    init.add_argument("--email", help="Skip the guided setup and write a minimal config")
+    init.add_argument("--project", type=Path, default=Path.cwd())
+    sub.add_parser("run", help="Run intake and worker in this process")
+    sub.add_parser(
+        "start", help="Start an ordinary detached process; no login/reboot persistence"
+    )
+    sub.add_parser("shutdown", help="Stop this runner and its active task")
+    sub.add_parser(
+        "doctor", help="Check mailbox access, agent installation and local queue"
+    )
+    sub.add_parser("status", help="Show tasks and notification delivery state")
+    sub.add_parser(
+        "rebaseline", help="Explicitly skip historical mail after a Sent folder reset"
+    )
+    for action in (
+        "install-service",
+        "uninstall-service",
+        "service-status",
+        "oauth-login",
+    ):
+        sub.add_parser(action)
+    pickup = sub.add_parser(
+        "pickup", help="Print command to resume a local agent session"
+    )
+    pickup.add_argument("task")
+    sub.add_parser("list", help="Pick an email task's session and resume it here")
+    resume = sub.add_parser(
+        "open", help="Resume a task's agent session in this terminal (picker if no task)"
+    )
+    resume.add_argument("task", nargs="?")
+    model = sub.add_parser("model", help="Set an agent's default model, e.g. model claude opus")
+    model.add_argument("agent", choices=("codex", "claude"))
+    model.add_argument("model", help="Model name, or 'default' to use the agent's own default")
+    args = parser.parse_args()
+    args.config = args.config.expanduser().resolve()
+    state = args.config.parent / "state"
+    if args.action == "init":
+        if args.config.exists():
+            parser.error("Config already exists; edit it directly")
+        if not args.email:
+            if not (sys.stdin.isatty() and sys.stdout.isatty()):
+                parser.error("init without --email needs an interactive terminal")
+            from .ui import setup, yes
+
+            setup(args.config)
+            if yes("Check mailbox access and agents now with doctor?"):
+                subprocess.run(
+                    [sys.executable, "-m", "agent_mailbox", "--config", str(args.config), "doctor"]
+                )
+            return
+        args.config.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        local, domain = args.email.split("@", 1)
+        config = {
+            "transport": "gmail-sent",
+            "email": args.email,
+            "recipient": f"{local}+agents@{domain}",
+            "password_env": "AGENT_MAILBOX_PASSWORD",
+            "default_project": "main",
+            "projects": {"main": str(args.project.expanduser().resolve())},
+            "agents": {
+                "codex": {"command": ["codex"]},
+                "claude": {"command": ["claude"]},
+            },
+            "poll_seconds": 15,
+            "task_timeout_seconds": 3600,
+            "codex_sandbox": "workspace-write",
+        }
+        args.config.write_text(json.dumps(config, indent=2) + "\n")
+        print(
+            f"Created {args.config}. Configure your password resolver, then run atgent doctor."
+        )
+        return
+    if args.action == "model":
+        raw = json.loads(args.config.read_text())
+        if args.agent not in raw.get("agents", {}):
+            parser.error(f"{args.agent} is not configured; run atgent init")
+        if args.model == "default":
+            raw["agents"][args.agent].pop("model", None)
+        elif not MODEL.fullmatch(args.model):
+            parser.error("Model names contain only letters, numbers, . _ or -")
+        else:
+            raw["agents"][args.agent]["model"] = args.model
+        args.config.write_text(json.dumps(raw, indent=2) + "\n")
+        print(f"{args.agent} default model: {raw['agents'][args.agent].get('model', 'agent default')}")
+        return
+    config = load_config(args.config)
+    state.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if args.action in ("install-service", "uninstall-service", "service-status"):
+        from .service import manage
+
+        manage(args.action, args.config)
+        return
+    if args.action == "oauth-login":
+        from .oauth import login
+
+        login(config, state)
+        print("Gmail OAuth credential stored")
+        return
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+    )
+    pidfile = state / "runner.pid"
+    lockfile = state / "runner.lock"
+    if args.action == "start":
+        # The child acquires the lock before touching the queue. Check first for friendly output.
+        with lockfile.open("a") as lock:
+            try:
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                parser.error("Runner is already active")
+            fcntl.flock(lock, fcntl.LOCK_UN)
+        with (state / "runner.log").open("ab") as log:
+            proc = subprocess.Popen(
+                [
+                    sys.executable,
+                    "-m",
+                    "agent_mailbox",
+                    "--config",
+                    str(args.config),
+                    "run",
+                ],
+                stdin=subprocess.DEVNULL,
+                stdout=log,
+                stderr=log,
+                start_new_session=True,
+            )
+        print(f"Started process {proc.pid}. Log: {state / 'runner.log'}")
+        return
+    store = Store(state / "queue.sqlite3")
+    if args.action == "shutdown":
+        # Signal only while our held advisory lock proves a runner owns this PID file.
+        with lockfile.open("a") as lock:
+            try:
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                os.kill(int(pidfile.read_text()), signal.SIGTERM)
+                print("Shutdown requested")
+                return
+        print("Runner is not active")
+        return
+    if args.action == "status":
+        print(
+            json.dumps(
+                {
+                    "jobs": store.rows(
+                        "SELECT id,thread,status,created FROM jobs ORDER BY id DESC LIMIT 30"
+                    ),
+                    "approvals": store.rows(
+                        "SELECT job,thread,status,expires FROM approvals WHERE status='pending' ORDER BY expires"
+                    ),
+                    "notifications": store.rows(
+                        "SELECT status,COUNT(*) AS count FROM outbox GROUP BY status"
+                    ),
+                },
+                indent=2,
+            )
+        )
+        return
+    if args.action == "pickup":
+        rows = store.rows("SELECT * FROM threads WHERE id=?", (args.task,))
+        if not rows or not rows[0]["session"]:
+            parser.error("No resumable session for this task")
+        if store.rows(
+            "SELECT 1 FROM jobs WHERE thread=? AND status IN ('queued','running','stopping')",
+            (args.task,),
+        ):
+            parser.error("Stop the email task before picking it up locally")
+        command = pickup_command(config, rows[0])
+        if not command:
+            parser.error("This task's project or agent is no longer configured")
+        print(command)
+        return
+    if args.action in ("list", "open"):
+        from .ui import pick, plain_lines, rows_for, yes
+
+        threads = store.rows(
+            "SELECT t.*, (SELECT status FROM jobs WHERE thread=t.id ORDER BY id DESC LIMIT 1) AS last,"
+            " (SELECT result FROM jobs WHERE thread=t.id AND result IS NOT NULL ORDER BY id DESC LIMIT 1) AS result,"
+            " (SELECT MAX(created) FROM jobs WHERE thread=t.id) AS updated"
+            " FROM threads t WHERE t.session IS NOT NULL ORDER BY updated DESC LIMIT 60"
+        )
+        interactive = sys.stdin.isatty() and sys.stdout.isatty()
+        task = args.task if args.action == "open" else None
+        if not task:
+            if not threads:
+                print("No resumable email tasks yet")
+                return
+            rows = rows_for(config, threads)
+            if not interactive:
+                print("\n".join(plain_lines(rows)))
+                return
+            chosen = pick(rows)
+            if chosen is None:
+                return
+            task = chosen["id"]
+        found = [t for t in threads if t["id"] == task] or store.rows(
+            "SELECT * FROM threads WHERE id=?", (task,)
+        )
+        if not found or not found[0]["session"]:
+            parser.error("No resumable session for this task")
+        if store.active(task):
+            if not interactive or not yes(
+                f"Task {task} is still running from email. Stop the email task and open it here?",
+                default=False,
+            ):
+                parser.error("Still running from email. Reply stop in its thread, or say yes here")
+            print("Stopping the email task...")
+            if not store.stop_and_wait(task):
+                parser.error("The runner has not released the session yet; try again in a minute")
+        spec = resume_spec(config, found[0], terminal=True)
+        if not spec:
+            parser.error("This task's project or agent is no longer configured")
+        cwd, argv, env = spec
+        os.chdir(cwd)
+        os.execvpe(argv[0], argv, {**os.environ, **env})
+    transport = Gmail(config, store)
+    if args.action == "doctor":
+        mail = transport.connect()
+        mail.logout()
+        print("Gmail authenticated; trusted Sent folder available")
+        import smtplib
+        import ssl
+
+        with smtplib.SMTP_SSL(
+            "smtp.gmail.com", 465, timeout=30, context=ssl.create_default_context()
+        ) as smtp:
+            transport.smtp_auth(smtp)
+        print("SMTP authenticated; no email sent")
+        for agent, spec in config["agents"].items():
+            result = subprocess.run(
+                spec["command"] + ["--version"],
+                capture_output=True,
+                text=True,
+                timeout=20,
+                env={**os.environ, **spec.get("env", {})},
+            )
+            print(
+                f"{agent}: {'installed' if result.returncode == 0 else 'unavailable'}"
+            )
+        print(f"Send to {config['recipient']}; subject: Codex: your task")
+        return
+    if args.action == "rebaseline":
+        # Never reset the watermark under a running intake process.
+        with lockfile.open("a") as lock:
+            try:
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                parser.error("Shut down the runner before rebaselining")
+            with store.transaction() as db:
+                db.execute("DELETE FROM meta WHERE key IN ('uidvalidity','last_uid')")
+            transport.poll()
+        print("Historical mail skipped; new-message intake armed")
+        return
+    with lockfile.open("a") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            parser.error("Runner is already active")
+        pidfile.write_text(str(os.getpid()))
+        shutdown = threading.Event()
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            signal.signal(sig, lambda *_: shutdown.set())
+        recover_processes(store)
+        store.recover()
+        # Arm intake before workers can execute anything.
+        transport.poll()
+        workers = [
+            threading.Thread(target=Worker(config, store, shutdown).run, daemon=True)
+            for _ in range(config.get("max_workers", 1))
+        ]
+        for worker in workers:
+            worker.start()
+        try:
+            while not shutdown.is_set():
+                try:
+                    transport.poll()
+                    transport.flush()
+                except Exception as exc:
+                    # Errors may include auth material. Log only the class.
+                    logging.error(
+                        "Mail cycle failed (%s); will reconnect", type(exc).__name__
+                    )
+                shutdown.wait(config.get("poll_seconds", 15))
+        finally:
+            shutdown.set()
+            for worker in workers:
+                worker.join(timeout=20)
+            pidfile.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    main()