zettcode-code-agents 0.4.6__py3-none-any.whl

zettcode/code_agents/__init__.py

@@ -0,0 +1,343 @@
+"""Codex and Claude Code as persistent gateway agents.
+
+Each is an :class:`~zettcode.broker.external.ExternalSession` of its own whose handler runs the tool's own CLI.
+The CLI's session id is kept in ``~/.zettcode/code-agents`` (or ``$ZETTCODE_CODE_AGENTS_DIR``), so the next message
+continues the same conversation. The gateway only sees ordinary external sessions; nothing here re-implements a
+model, a tool loop or a conversation store.
+
+The commands can be changed without changing this package, and so can where the agents work and how far they are
+trusted: see :mod:`zettcode.code_agents.config`. Those settings live in ``~/.zettcode/code-agents/config.json`` and are
+read again for every message, so an edit applies to the next one with no restart. The environment variables still work
+for the command itself:
+
+* ``ZETTCODE_CODEX_ARGS`` / ``ZETTCODE_CODEX_RESUME_ARGS``
+* ``ZETTCODE_CLAUDE_ARGS`` / ``ZETTCODE_CLAUDE_RESUME_ARGS``
+
+They are split with :mod:`shlex` and receive ``{prompt}``, ``{session}`` and ``{cwd}``; they are never run by a shell.
+The word ``{permission}`` on its own stands for the arguments of the trust level the settings choose.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import math
+import os
+import shlex
+import signal
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from zettcode.broker.external import ExternalSession
+from zettcode.broker.models import Incoming, Receipt
+from zettcode.broker.protocol import KIND_EXTERNAL
+from zettcode.code_agents.config import (
+    TIMEOUT,
+    ConfigError,
+    Settings,
+    Tool,
+    resolve,
+    state_directory,
+    work_directory,
+)
+from zettcode.gateway.agents import AgentPlugin
+
+#: The one place this plugin's version is written.
+__version__ = "0.4.6"
+
+
+def _timeout() -> float:
+    """Return how long one turn may run without a setting, read from the environment and checked before use."""
+    raw = os.environ.get("ZETTCODE_CODE_AGENTS_TIMEOUT", str(TIMEOUT))
+    try:
+        value = float(raw)
+    except ValueError:
+        raise RuntimeError(f"ZETTCODE_CODE_AGENTS_TIMEOUT must be a number of seconds, not {raw!r}") from None
+    if not math.isfinite(value) or value <= 0:
+        raise RuntimeError("ZETTCODE_CODE_AGENTS_TIMEOUT must be a positive number of seconds")
+    return value
+
+
+def _logo(name: str) -> str:
+    """Return one of the package's brand marks as a data URL."""
+    path = Path(__file__).with_name("logos") / name
+    try:
+        return "data:image/svg+xml;base64," + base64.b64encode(path.read_bytes()).decode()
+    except OSError:
+        return ""
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    """One tool's command line, new and resumed."""
+
+    binary: str
+    new_args: str
+    resume_args: str
+
+    def argv(
+        self, prompt: str, session: str, cwd: Path, *, resume: bool = True, permission: tuple[str, ...] = ()
+    ) -> list[str]:
+        """Return the command to run. The word ``{permission}``, alone, becomes the arguments of the trust level.
+
+        A template without that word is the person's own command line and is run exactly as written.
+        """
+        template = self.resume_args if resume and session and "{session}" in self.resume_args else self.new_args
+        values = {"prompt": prompt, "session": session, "cwd": str(cwd)}
+        argv = [self.binary]
+        for part in shlex.split(template):
+            if part == "{permission}":
+                argv.extend(permission)
+            else:
+                argv.append(part.format(**values))
+        return argv
+
+
+@dataclass(frozen=True, slots=True)
+class Launch:
+    """What one turn runs with: the command, where, for how long, and the trust arguments for a new and a resumed turn."""
+
+    command: Command
+    cwd: Path
+    timeout: float
+    new_flags: tuple[str, ...]
+    resume_flags: tuple[str, ...]
+
+
+def _events(stdout: str) -> tuple[str, str]:
+    """Return the last text and session id in a JSON or JSONL answer."""
+    text = ""
+    session = ""
+    for line in stdout.splitlines():
+        try:
+            event = json.loads(line)
+        except ValueError:
+            continue
+        if not isinstance(event, dict):
+            continue
+        for key in ("session_id", "thread_id"):
+            value = event.get(key)
+            if isinstance(value, str) and value:
+                session = value
+        for key in ("result", "text", "message", "content"):
+            value = event.get(key)
+            if isinstance(value, str) and value.strip():
+                text = value
+        item = event.get("item")
+        if isinstance(item, dict) and isinstance(item.get("text"), str):
+            text = item["text"]
+    return text, session
+
+
+class CliAgent(ExternalSession):
+    """An external session whose one handler runs a CLI and keeps its session id."""
+
+    def __init__(self, session_id: str, title: str, source: Tool | Command) -> None:
+        self._turns: set[asyncio.Task[None]] = set()
+        self._limit = max(1, int(os.environ.get("ZETTCODE_CODE_AGENTS_QUEUE", "4")))
+        super().__init__(session_id, title, kind=KIND_EXTERNAL, on_message=self._start_turn)
+        #: A tool's settings are read again for every turn; a bare command (a caller's own) is run as it is given.
+        self.source = source
+        self.state = state_directory() / f"{session_id}.json"
+        self._lock = asyncio.Lock()
+        self._process: asyncio.subprocess.Process | None = None
+
+    def _start_turn(self, message: Incoming) -> Receipt:
+        """Answer the broker now and run one CLI turn on a task."""
+        if len(self._turns) >= self._limit:
+            return Receipt(False, reason=f"{self.title} has {self._limit} turns waiting", busy=True)
+        task = asyncio.ensure_future(self._turn(message))
+        self._turns.add(task)
+        task.add_done_callback(self._turns.discard)
+        return Receipt(True, disposition="queued")
+
+    async def _turn(self, message: Incoming) -> None:
+        async with self._lock:
+            await self.set_status("working")
+            try:
+                answer = await self._run(message.text)
+            except Exception as error:  # noqa: BLE001 - the person gets the reason, the agent stays alive
+                answer = f"{self.title} failed: {error}"
+            finally:
+                await self.set_status("idle")
+            if message.group:
+                await self.send_group(message.group, answer)
+            else:
+                await self.reply(message, answer)
+
+    def _resolve(self) -> Launch:
+        """Return what this turn runs with, read now: a person's edit of the settings applies from the next message."""
+        source = self.source
+        if isinstance(source, Command):
+            return Launch(source, work_directory(), _timeout(), (), ())
+        settings: Settings = resolve(source, timeout=_timeout())
+        command = Command(settings.binary, settings.args, settings.resume_args)
+        return Launch(
+            command,
+            settings.cwd,
+            settings.timeout,
+            source.flags[settings.permission],
+            source.resume_flags[settings.permission],
+        )
+
+    async def _run(self, prompt: str) -> str:
+        launch = self._resolve()
+        command, timeout = launch.command, launch.timeout
+        session = self._session()
+        resumed = bool(session)
+        if not session and "session-id" in command.new_args:
+            session = str(uuid.uuid4())
+        # The trust arguments follow the template that is used: a resume template without {session} is the new one.
+        continuing = resumed and "{session}" in command.resume_args
+        argv = command.argv(
+            prompt,
+            session,
+            launch.cwd,
+            resume=resumed,
+            permission=launch.resume_flags if continuing else launch.new_flags,
+        )
+        options: dict[str, Any] = {}
+        if os.name != "nt":
+            options["start_new_session"] = True
+        self._process = await asyncio.create_subprocess_exec(
+            *argv,
+            cwd=str(launch.cwd),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            **options,
+        )
+        process = self._process
+        try:
+            stdout, stderr = await asyncio.wait_for(process.communicate(), timeout)
+        except asyncio.TimeoutError:
+            self._kill(process)
+            await process.wait()
+            raise RuntimeError(f"the {self.title} command did not finish in {timeout:g} seconds") from None
+        finally:
+            self._process = None
+        output = stdout.decode(errors="replace")
+        error = stderr.decode(errors="replace").strip()
+        if process.returncode not in (None, 0):
+            raise RuntimeError(error or f"exit code {process.returncode}")
+        text, found = _events(output)
+        if found:
+            self._save(found)
+        if text:
+            return text
+        if output.strip():
+            return output.strip()
+        raise RuntimeError(error or "the command said nothing")
+
+    async def close(self) -> None:
+        """Stop a running CLI process before closing the session."""
+        process, self._process = self._process, None
+        tasks, self._turns = list(self._turns), set()
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        if process is not None and process.returncode is None:
+            self._kill(process)
+            await process.wait()
+        await super().close()
+
+    @staticmethod
+    def _kill(process: asyncio.subprocess.Process) -> None:
+        """Kill the CLI and the children it forked, when the platform gives the process a session."""
+        if os.name == "nt":
+            process.kill()
+            return
+        try:
+            os.killpg(os.getpgid(process.pid), signal.SIGKILL)
+        except (ProcessLookupError, PermissionError):
+            process.kill()
+
+    def _session(self) -> str:
+        try:
+            data = json.loads(self.state.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return ""
+        value = data.get("session") if isinstance(data, dict) else None
+        return value if isinstance(value, str) else ""
+
+    def _save(self, session: str) -> None:
+        self.state.parent.mkdir(parents=True, exist_ok=True)
+        temporary = self.state.with_suffix(".tmp")
+        temporary.write_text(json.dumps({"session": session}), encoding="utf-8")
+        os.replace(temporary, self.state)
+
+
+_CODEX_FULL = ("--dangerously-bypass-approvals-and-sandbox",)
+
+#: Codex. ``exec`` takes ``--sandbox``; ``exec resume`` does not, and takes the same choice as a config override.
+CODEX = Tool(
+    name="codex",
+    env="ZETTCODE_CODEX",
+    binary="codex",
+    args="exec --json --skip-git-repo-check {permission} {prompt}",
+    resume_args="exec resume {session} --json {permission} {prompt}",
+    flags={
+        "full": _CODEX_FULL,
+        "workspace": ("--sandbox", "workspace-write"),
+        "read": ("--sandbox", "read-only"),
+    },
+    resume_flags={
+        "full": _CODEX_FULL,
+        "workspace": ("-c", 'sandbox_mode="workspace-write"'),
+        "read": ("-c", 'sandbox_mode="read-only"'),
+    },
+)
+
+_CLAUDE_FLAGS = {
+    "full": ("--permission-mode", "bypassPermissions"),
+    "workspace": ("--permission-mode", "acceptEdits"),
+    "read": ("--permission-mode", "plan"),
+}
+
+#: Claude Code, which takes the same ``--permission-mode`` for a new conversation and a resumed one.
+CLAUDE = Tool(
+    name="claude",
+    env="ZETTCODE_CLAUDE",
+    binary="claude",
+    args="{permission} -p {prompt} --output-format json --session-id {session}",
+    resume_args="{permission} -p {prompt} --output-format json --resume {session}",
+    flags=_CLAUDE_FLAGS,
+    resume_flags=_CLAUDE_FLAGS,
+)
+
+
+class CodexAgent(AgentPlugin):
+    name = CODEX.name
+    title = "Codex"
+    description = "OpenAI Codex CLI, in the same session every time"
+    avatar = _logo("codex.svg")
+
+    def create(self, session_id: str, title: str) -> ExternalSession:
+        return CliAgent(session_id, title, CODEX)
+
+
+class ClaudeCodeAgent(AgentPlugin):
+    name = CLAUDE.name
+    title = "Claude Code"
+    description = "Anthropic Claude Code, in the same session every time"
+    avatar = _logo("claude.svg")
+
+    def create(self, session_id: str, title: str) -> ExternalSession:
+        return CliAgent(session_id, title, CLAUDE)
+
+
+__all__ = [
+    "CLAUDE",
+    "CODEX",
+    "ClaudeCodeAgent",
+    "CliAgent",
+    "CodexAgent",
+    "Command",
+    "ConfigError",
+    "Launch",
+    "state_directory",
+    "work_directory",
+]

zettcode/code_agents/config.py

@@ -0,0 +1,199 @@
+"""The settings of the Codex and Claude Code agents, which belong to this plugin and not to the gateway.
+
+The gateway only starts an agent. Where it works, how far it is trusted and which command it runs are written in one
+JSON file, ``~/.zettcode/code-agents/config.json`` (``$ZETTCODE_CODE_AGENTS_CONFIG`` names another), and the file is
+read again when each message arrives, so an edit applies to the next message of every agent that is already running::
+
+    {
+      "cwd": "~/work",
+      "permission": "full",
+      "timeout": 900,
+      "codex": {"cwd": "~/work/api", "permission": "workspace"},
+      "claude": {"bin": "/opt/bin/claude"}
+    }
+
+A key inside ``"codex"`` or ``"claude"`` wins over the same key at the top; that wins over the environment variable
+this plugin read before there was a file; that wins over the default. ``bin``, ``args`` and ``resume_args`` belong to
+one tool and have no top-level form. A relative ``cwd`` is taken from the gateway process's folder, not the file's.
+
+``permission`` is how far the agent is trusted, and the plugin turns it into the arguments each CLI takes:
+
+* ``full`` (the default): the agent may do anything the user may, with nothing asked.
+* ``workspace``: it may write inside its folder; the rest of the machine is read-only or closed.
+* ``read``: it may look and not change.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import shlex
+import string
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+#: The trust levels, safest last. Each tool maps every one of them to its own arguments.
+PERMISSIONS = ("full", "workspace", "read")
+
+#: What an agent is trusted with when nothing says otherwise: it runs on its own, and nobody is there to answer a prompt.
+DEFAULT_PERMISSION = "full"
+
+#: How long one CLI turn may take before it is stopped.
+TIMEOUT = 900.0
+
+
+class ConfigError(RuntimeError):
+    """The settings cannot be used. The sentence names the file and the key, so it can be shown to the person as is."""
+
+
+def state_directory() -> Path:
+    """Return where the CLI session ids and the settings are kept."""
+    return Path(os.environ.get("ZETTCODE_CODE_AGENTS_DIR", str(Path.home() / ".zettcode" / "code-agents"))).expanduser()
+
+
+def work_directory() -> Path:
+    """Return the directory the CLI runs in when the settings do not name one."""
+    return Path(os.environ.get("ZETTCODE_CODE_AGENTS_CWD", str(Path.cwd()))).expanduser()
+
+
+def config_path() -> Path:
+    """Return the settings file."""
+    return Path(os.environ.get("ZETTCODE_CODE_AGENTS_CONFIG", str(state_directory() / "config.json"))).expanduser()
+
+
+@dataclass(frozen=True, slots=True)
+class Tool:
+    """What is known about one CLI before any settings: its name, its default command and what each trust level adds."""
+
+    name: str
+    #: The prefix of the environment variables that set this tool's command (``ZETTCODE_CODEX`` for ``_BIN``...).
+    env: str
+    binary: str
+    args: str
+    resume_args: str
+    #: The arguments each permission adds to a new conversation, and to a resumed one (a CLI may differ).
+    flags: Mapping[str, tuple[str, ...]]
+    resume_flags: Mapping[str, tuple[str, ...]]
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Everything one CLI turn runs with, resolved from the file, the environment and the defaults at that moment."""
+
+    cwd: Path
+    permission: str
+    timeout: float
+    binary: str
+    args: str
+    resume_args: str
+
+
+def read_config() -> dict[str, Any]:
+    """Read the settings file now. A missing or empty file is no settings; one that cannot be used is a ConfigError."""
+    path = config_path()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return {}
+    except OSError as error:
+        raise ConfigError(f"{path} cannot be read: {error.strerror or error}") from error
+    if not text.strip():
+        return {}
+    try:
+        data = json.loads(text)
+    except ValueError as error:
+        raise ConfigError(f"{path} is not valid JSON: {error}") from None
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path} must hold one JSON object")
+    return data
+
+
+def _text(key: str, value: object) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(f'"{key}" in {config_path()} must be a non-empty string')
+    return value
+
+
+#: The words a command template may name besides ``{permission}``, which must stand alone.
+_FIELDS = frozenset({"prompt", "session", "cwd"})
+
+
+def _template(key: str, value: object) -> str:
+    """Return a command template, refusing one that would fail on every message.
+
+    ``{permission}`` becomes several arguments, so it can only be a word of its own (``--sandbox={permission}`` cannot
+    work); any other word it names must be one the command is given. Both are caught here, once, naming the key.
+    """
+    text = _text(key, value)
+    where = f'"{key}" in {config_path()}'
+    try:
+        parts = shlex.split(text)
+    except ValueError as error:
+        raise ConfigError(f"{where} is not a command line: {error}") from None
+    for part in parts:
+        if part == "{permission}":
+            continue
+        try:
+            names = [name for _, name, _, _ in string.Formatter().parse(part) if name is not None]
+        except ValueError as error:
+            raise ConfigError(f"{where} has a word that cannot be filled in, {part!r}: {error}") from None
+        for name in names:
+            field = name.split(".")[0].split("[")[0]
+            if field == "permission":
+                raise ConfigError(f"{where}: {{permission}} must be a word of its own, not part of {part!r}")
+            if field not in _FIELDS:
+                raise ConfigError(
+                    f"{where} names {{{field}}}, which is not one of {{prompt}}, {{session}}, {{cwd}} or {{permission}}"
+                )
+    return text
+
+
+def resolve(tool: Tool, *, timeout: float = TIMEOUT) -> Settings:
+    """Return the settings of one tool as they are now.
+
+    Args:
+        tool: The CLI.
+        timeout: The timeout when neither the file nor the tool's section sets one.
+
+    Raises:
+        ConfigError: The file cannot be read or parsed, a value has the wrong type, ``permission`` is not a level, or
+            ``cwd`` is not a folder.
+    """
+    data = read_config()
+    section = data.get(tool.name, {})
+    if not isinstance(section, dict):
+        raise ConfigError(f'"{tool.name}" in {config_path()} must be an object')
+
+    def value(key: str, fallback: object, *, shared: bool = True) -> object:
+        if key in section:
+            return section[key]
+        if shared and key in data:
+            return data[key]
+        return fallback
+
+    folder = Path(_text("cwd", value("cwd", str(work_directory())))).expanduser().resolve()
+    if not folder.is_dir():
+        raise ConfigError(f'the folder {folder} ("cwd" in {config_path()}) does not exist')
+
+    permission = _text("permission", value("permission", DEFAULT_PERMISSION))
+    if permission not in tool.flags:
+        raise ConfigError(f'"permission" in {config_path()} is full, workspace or read, not {permission!r}')
+
+    limit = value("timeout", timeout)
+    if isinstance(limit, bool) or not isinstance(limit, (int, float)) or not math.isfinite(limit) or limit <= 0:
+        raise ConfigError(f'"timeout" in {config_path()} must be a positive number of seconds')
+
+    return Settings(
+        cwd=folder,
+        permission=permission,
+        timeout=float(limit),
+        binary=_text("bin", value("bin", os.environ.get(f"{tool.env}_BIN", tool.binary), shared=False)),
+        args=_template("args", value("args", os.environ.get(f"{tool.env}_ARGS", tool.args), shared=False)),
+        resume_args=_template(
+            "resume_args",
+            value("resume_args", os.environ.get(f"{tool.env}_RESUME_ARGS", tool.resume_args), shared=False),
+        ),
+    )

zettcode/code_agents/logos/claude.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <title>Claude</title>
+  <rect width="24" height="24" rx="5" fill="#F0EEE6"/>
+  <path d="M4.709 15.955l4.72-2.647.08-.23-.08-.128H9.2l-.79-.048-2.698-.073-2.339-.097-2.266-.122-.571-.121L0 11.784l.055-.352.48-.321.686.06 1.52.103 2.278.158 1.652.097 2.449.255h.389l.055-.157-.134-.098-.103-.097-2.358-1.596-2.552-1.688-1.336-.972-.724-.491-.364-.462-.158-1.008.656-.722.881.06.225.061.893.686 1.908 1.476 2.491 1.833.365.304.145-.103.019-.073-.164-.274-1.355-2.446-1.446-2.49-.644-1.032-.17-.619a2.97 2.97 0 01-.104-.729L6.283.134 6.696 0l.996.134.42.364.62 1.414 1.002 2.229 1.555 3.03.456.898.243.832.091.255h.158V9.01l.128-1.706.237-2.095.23-2.695.08-.76.376-.91.747-.492.584.28.48.685-.067.444-.286 1.851-.559 2.903-.364 1.942h.212l.243-.242.985-1.306 1.652-2.064.73-.82.85-.904.547-.431h1.033l.76 1.129-.34 1.166-1.064 1.347-.881 1.142-1.264 1.7-.79 1.36.073.11.188-.02 2.856-.606 1.543-.28 1.841-.315.833.388.091.395-.328.807-1.969.486-2.309.462-3.439.813-.042.03.049.061 1.549.146.662.036h1.622l3.02.225.79.522.474.638-.079.485-1.215.62-1.64-.389-3.829-.91-1.312-.329h-.182v.11l1.093 1.068 2.006 1.81 2.509 2.33.127.578-.322.455-.34-.049-2.205-1.657-.851-.747-1.926-1.62h-.128v.17l.444.649 2.345 3.521.122 1.08-.17.353-.608.213-.668-.122-1.374-1.925-1.415-2.167-1.143-1.943-.14.08-.674 7.254-.316.37-.729.28-.607-.461-.322-.747.322-1.476.389-1.924.315-1.53.286-1.9.17-.632-.012-.042-.14.018-1.434 1.967-2.18 2.945-1.726 1.845-.414.164-.717-.37.067-.662.401-.589 2.388-3.036 1.44-1.882.93-1.086-.006-.158h-.055L4.132 18.56l-1.13.146-.487-.456.061-.746.231-.243 1.908-1.312-.006.006z" fill="#D97757" fill-rule="nonzero"/>
+</svg>

zettcode/code_agents/logos/codex.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <title>Codex</title>
+  <rect width="24" height="24" rx="5" fill="#ffffff"/>
+  <path d="M9.064 3.344a4.578 4.578 0 012.285-.312c1 .115 1.891.54 2.673 1.275.01.01.024.017.037.021a.09.09 0 00.043 0 4.55 4.55 0 013.046.275l.047.022.116.057a4.581 4.581 0 012.188 2.399c.209.51.313 1.041.315 1.595a4.24 4.24 0 01-.134 1.223.123.123 0 00.03.115c.594.607.988 1.33 1.183 2.17.289 1.425-.007 2.71-.887 3.854l-.136.166a4.548 4.548 0 01-2.201 1.388.123.123 0 00-.081.076c-.191.551-.383 1.023-.74 1.494-.9 1.187-2.222 1.846-3.711 1.838-1.187-.006-2.239-.44-3.157-1.302a.107.107 0 00-.105-.024c-.388.125-.78.143-1.204.138a4.441 4.441 0 01-1.945-.466 4.544 4.544 0 01-1.61-1.335c-.152-.202-.303-.392-.414-.617a5.81 5.81 0 01-.37-.961 4.582 4.582 0 01-.014-2.298.124.124 0 00.006-.056.085.085 0 00-.027-.048 4.467 4.467 0 01-1.034-1.651 3.896 3.896 0 01-.251-1.192 5.189 5.189 0 01.141-1.6c.337-1.112.982-1.985 1.933-2.618.212-.141.413-.251.601-.33.215-.089.43-.164.646-.227a.098.098 0 00.065-.066 4.51 4.51 0 01.829-1.615 4.535 4.535 0 011.837-1.388zm3.482 10.565a.637.637 0 000 1.272h3.636a.637.637 0 100-1.272h-3.636zM8.462 9.23a.637.637 0 00-1.106.631l1.272 2.224-1.266 2.136a.636.636 0 101.095.649l1.454-2.455a.636.636 0 00.005-.64L8.462 9.23z" fill="url(#codex-gradient)"/>
+  <defs>
+    <linearGradient id="codex-gradient" gradientUnits="userSpaceOnUse" x1="12" x2="12" y1="3" y2="21">
+      <stop stop-color="#B1A7FF"/>
+      <stop offset=".5" stop-color="#7A9DFF"/>
+      <stop offset="1" stop-color="#3941FF"/>
+    </linearGradient>
+  </defs>
+</svg>

zettcode_code_agents-0.4.6.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: zettcode-code-agents
+Version: 0.4.6
+Summary: Gateway plugins that run Codex and Claude Code as persistent external agents
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode/tree/main/packages/zettcode-code-agents
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude,codex,gateway,zettcode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+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: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: zettcode-broker<0.5,>=0.4.6
+Requires-Dist: zettcode-gateway<0.5,>=0.4.6
+Description-Content-Type: text/markdown
+
+# zettcode-code-agents
+
+Gateway plugins that run **Codex** and **Claude Code** as external agents. Each is a persistent CLI session: the
+session id is kept in `~/.zettcode/code-agents/` (or `$ZETTCODE_CODE_AGENTS_DIR`), so every message continues the same
+conversation.
+
+Install the package beside the gateway and restart it:
+
+```bash
+pip install zettcode-code-agents
+```
+
+The New page then offers **Codex** and **Claude Code**. Both register as `kind="external"` sessions; the gateway owner can add one to a
+group, and it can then receive and write there.
+
+The gateway only starts an agent. Where it works, how far it is trusted and which command it runs are this plugin's
+settings, kept in its own file and read again **for every message, when its turn starts**, so an edit applies to the
+next message of every agent that is already running, a queued one included. Nothing has to be restarted.
+
+## Settings
+
+`~/.zettcode/code-agents/config.json` (or the file `$ZETTCODE_CODE_AGENTS_CONFIG` names). Every key is optional:
+
+```json
+{
+  "cwd": "~/work",
+  "permission": "full",
+  "timeout": 900,
+  "codex": { "cwd": "~/work/api", "permission": "workspace" },
+  "claude": { "bin": "/opt/bin/claude" }
+}
+```
+
+A key inside `"codex"` or `"claude"` wins over the same key at the top, which wins over the environment variable of the
+same setting, which wins over the default. `bin`, `args` and `resume_args` belong to one tool and are set only inside its
+section.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `cwd` | the gateway process's directory | The folder the CLI runs in. It must exist. A relative path is taken from the gateway process's folder, not from this file's. |
+| `permission` | `full` | How far the agent is trusted: `full`, `workspace` or `read`. |
+| `timeout` | `900` | Seconds one turn may take before it is stopped. |
+| `bin`, `args`, `resume_args` | see below | The command, per tool. |
+
+### Permission
+
+The default is `full`: the agent runs on its own and may do anything you may, because nobody is there to answer a
+prompt. **That is the plugin's choice, not the gateway's**: starting the gateway with `--no-full` limits the daemons it
+starts and does not limit these agents. Set `"permission"` to `workspace` or `read` to narrow them.
+
+| `permission` | Codex | Claude Code |
+| --- | --- | --- |
+| `full` | `--dangerously-bypass-approvals-and-sandbox` | `--permission-mode bypassPermissions` |
+| `workspace` | `--sandbox workspace-write` | `--permission-mode acceptEdits` |
+| `read` | `--sandbox read-only` | `--permission-mode plan` |
+
+`codex exec resume` takes no `--sandbox` (checked against `codex-cli 0.160.1`: it answers "unexpected argument"), so a
+resumed Codex turn is given the same choice as a configuration override, `-c sandbox_mode="workspace-write"` (or
+`"read-only"`). That flag is **accepted** by the CLI; that it **limits** a resumed run the way `--sandbox` limits the
+first one has not been verified. If you rely on `workspace` or `read` for Codex, send a second message that tries to
+write outside the folder and see that it is refused, before you trust it.
+
+A setting that cannot be used (invalid JSON, a folder that does not exist, an unknown level, a command that names
+a word it is not given, or `{permission}` written inside another word such as `--sandbox={permission}`) fails that
+message with a sentence naming the file and the key, in the agent's reply. Mend the file and send again.
+
+## Commands
+
+The commands are also configurable from the environment, which the `args` and `resume_args` keys override:
+
+| Variable | Default |
+| --- | --- |
+| `ZETTCODE_CODEX_BIN` | `codex` |
+| `ZETTCODE_CODEX_ARGS` | `exec --json --skip-git-repo-check {permission} {prompt}` |
+| `ZETTCODE_CODEX_RESUME_ARGS` | `exec resume {session} --json {permission} {prompt}` |
+| `ZETTCODE_CLAUDE_BIN` | `claude` |
+| `ZETTCODE_CLAUDE_ARGS` | `{permission} -p {prompt} --output-format json --session-id {session}` |
+| `ZETTCODE_CLAUDE_RESUME_ARGS` | `{permission} -p {prompt} --output-format json --resume {session}` |
+| `ZETTCODE_CODE_AGENTS_CWD` | the gateway process's directory |
+| `ZETTCODE_CODE_AGENTS_DIR` | `~/.zettcode/code-agents` |
+| `ZETTCODE_CODE_AGENTS_CONFIG` | `config.json` in that directory |
+| `ZETTCODE_CODE_AGENTS_QUEUE` | `4` turns waiting (read when the agent starts) |
+| `ZETTCODE_CODE_AGENTS_TIMEOUT` | `900` seconds |
+
+Arguments are split with `shlex`, never run by a shell, and receive `{prompt}`, `{session}` and `{cwd}`. The word
+`{permission}` on its own stands for the arguments of the chosen level; a command you write without it is run exactly
+as written, with no trust arguments added.
+
+The CLIs must be installed and signed in for the user running the gateway.

zettcode_code_agents-0.4.6.dist-info/RECORD

@@ -0,0 +1,9 @@
+zettcode/code_agents/__init__.py,sha256=RLyEUd5J8JYq3UvBQfzVTW_AEBxp8BZsXS0iz2WjNlI,12723
+zettcode/code_agents/config.py,sha256=KurLjtFBd5EkS5nANSzki8v_gxP9ckqKUv3VZKVCAAg,7966
+zettcode/code_agents/logos/claude.svg,sha256=GZJv6njiQcdUfffiU3kwUk6gYiqnMxCA-UZ6ed3qx7Q,1696
+zettcode/code_agents/logos/codex.svg,sha256=1P3mGLo4ythjyTcGB_4eGK5sRIyXMnxnznb4VF01jNA,1606
+zettcode_code_agents-0.4.6.dist-info/METADATA,sha256=YYWdEqYHQWzRQId_htKMTx4fkBEZVhBXrZnGAhLfldE,5785
+zettcode_code_agents-0.4.6.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+zettcode_code_agents-0.4.6.dist-info/entry_points.txt,sha256=EEOO1uNd63Z16B00FgO1qJpAbqRT61XPSScQaPBBSxE,114
+zettcode_code_agents-0.4.6.dist-info/licenses/LICENSE,sha256=O9b87-u8V1aSp6xkr9qnbHZIJAWNV6m04GEQjycLLiw,1069
+zettcode_code_agents-0.4.6.dist-info/RECORD,,

zettcode_code_agents-0.4.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zettcode_code_agents-0.4.6.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[zettcode.gateway.external]
+claude = zettcode.code_agents:ClaudeCodeAgent
+codex = zettcode.code_agents:CodexAgent

zettcode_code_agents-0.4.6.dist-info/licenses/LICENSE

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