codicent-cli 0.8.6__tar.gz → 0.9.0__tar.gz

{codicent_cli-0.8.6 → codicent_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codicent-cli
-Version: 0.8.6
+Version: 0.9.0
 Summary: Command-line interface for the Codicent API
 Home-page: https://github.com/izaxon/codicent-cli
 Author: Johan Isaksson
@@ -101,6 +101,16 @@ pip install git+https://github.com/izaxon/codicent-cli.git@v0.4.8
 
 ## Usage
 
+### Coding agent sandbox
+
+`codicent agent exec` defaults to `--sandbox workspace-write`, which confines
+filesystem tools to `--cwd`. `read-only` also forbids file edits. Both modes
+reject shell commands because setting a command's working directory does not
+isolate its filesystem access. To allow shell commands, explicitly pass
+`--sandbox danger-full-access`; processes can then access files outside the workspace.
+`--approval-policy on-request` asks before mutations; `never` skips those prompts.
+Search and instruction discovery exclude links that escape their workspace or repository.
+
 ### Basic Setup
 
 1. Set the `CODICENT_TOKEN` environment variable with your Codicent API token:

{codicent_cli-0.8.6 → codicent_cli-0.9.0}/README.md

@@ -55,6 +55,16 @@ pip install git+https://github.com/izaxon/codicent-cli.git@v0.4.8
 
 ## Usage
 
+### Coding agent sandbox
+
+`codicent agent exec` defaults to `--sandbox workspace-write`, which confines
+filesystem tools to `--cwd`. `read-only` also forbids file edits. Both modes
+reject shell commands because setting a command's working directory does not
+isolate its filesystem access. To allow shell commands, explicitly pass
+`--sandbox danger-full-access`; processes can then access files outside the workspace.
+`--approval-policy on-request` asks before mutations; `never` skips those prompts.
+Search and instruction discovery exclude links that escape their workspace or repository.
+
 ### Basic Setup
 
 1. Set the `CODICENT_TOKEN` environment variable with your Codicent API token:

codicent_cli-0.9.0/agent.py

@@ -0,0 +1,431 @@
+"""`codicent agent` — standalone coding-agent mode (ADR-023).
+
+The Codicent server is the reasoning layer (model, memory, tool loop); this
+module is the local harness: workspace boundary, sandbox/approval enforcement,
+local tool execution, session persistence, and structured stdout for
+orchestrators like DINT. Rich is intentionally never imported here.
+"""
+import argparse
+import base64
+import json
+import os
+import re
+import sys
+import time
+
+import requests
+
+from agent_policy import (
+    AgentPolicy,
+    APPROVAL_NEVER,
+    APPROVAL_ON_REQUEST,
+    APPROVAL_POLICIES,
+    NEED_APPROVAL,
+    SANDBOX_FULL_ACCESS,
+    SANDBOX_LEVELS,
+    SANDBOX_WORKSPACE_WRITE,
+)
+from agent_protocol import (
+    EXIT_APPROVAL_REQUIRED,
+    EXIT_CANCELLED,
+    EXIT_ERROR,
+    EXIT_OK,
+    OUTPUT_FORMATS,
+    OUTPUT_JSONL,
+    OUTPUT_TEXT,
+    ProtocolEmitter,
+)
+from agent_session import AgentSession, SessionError
+from agent_tools import STATUS_CANCELLED, STATUS_NEED_APPROVAL, ToolDispatcher
+from agent_workspace import WorkspaceContext, WorkspaceError
+
+POLL_INTERVAL_SECONDS = 1.5
+DEFAULT_TURN_TIMEOUT = 600
+
+DELEGATION_PREFIXES = (
+    "#execute_command\n",
+    "#fs_read\n",
+    "#fs_write\n",
+    "#fs_list\n",
+    "#fs_search\n",
+    "#apply_patch\n",
+)
+
+
+# ---------------------------------------------------------------------------
+# Wire protocol (StartAi2ChatAsync / GetMessageHistory / AddChatMessage)
+# ---------------------------------------------------------------------------
+def decode_jwt_payload(token):
+    payload = token.split(".")[1]
+    payload += "=" * (-len(payload) % 4)
+    return json.loads(base64.urlsafe_b64decode(payload).decode("utf-8"))
+
+
+def start_chat_async(base_url, token, project, message, conversation_id=None):
+    payload = {"message": message, "project": project}
+    if conversation_id:
+        payload["messageId"] = str(conversation_id)
+    resp = requests.post(
+        f"{base_url}app/StartAi2ChatAsync",
+        json=payload,
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return resp.json().get("promptMessageId")
+
+
+def fetch_history(base_url, token, message_id):
+    resp = requests.get(
+        f"{base_url}app/GetMessageHistory",
+        params={"messageId": str(message_id)},
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=15,
+    )
+    resp.raise_for_status()
+    return resp.json() if resp.text else []
+
+
+def post_child_message(base_url, token, project, parent_id, body):
+    resp = requests.post(
+        f"{base_url}app/AddChatMessage",
+        json={"content": f"@{project}\n{body}", "type": "ai-chat-answer2", "parentId": str(parent_id)},
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+def post_function_result(base_url, token, project, parent_id, function_name, result_content, tool_id):
+    fr = {"role": "function", "name": function_name, "content": result_content, "id": tool_id or ""}
+    return post_child_message(base_url, token, project, parent_id, f"#function_result\n{json.dumps(fr)}")
+
+
+def post_batch_results(base_url, token, project, parent_id, items):
+    """items: original batch dicts with delegation contents replaced in place
+    (key casing preserved, so the server deserializes what it serialized)."""
+    return post_child_message(
+        base_url, token, project, parent_id, f"#function_results_batch\n{json.dumps(items)}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Delegation parsing
+# ---------------------------------------------------------------------------
+def strip_mention_and_tag(content, tag):
+    body = re.sub(r"^@\S+\s*", "", content).strip()
+    return re.sub(r"^" + re.escape(tag) + r"\s*\n?", "", body).strip()
+
+
+def parse_delegation_content(content):
+    """If content starts with a delegation prefix, return (tool, data), else None."""
+    if not content:
+        return None
+    for prefix in DELEGATION_PREFIXES:
+        if content.startswith(prefix):
+            try:
+                data = json.loads(content[len(prefix):])
+            except ValueError:
+                return None
+            return prefix.rstrip("\n").lstrip("#"), data
+    return None
+
+
+def parse_single_delegation(message_content):
+    """Parse a #function_result message. Returns (name, tool, data, tool_id) or None."""
+    body = strip_mention_and_tag(message_content, "#function_result")
+    try:
+        fr = json.loads(body)
+    except ValueError:
+        return None
+    parsed = parse_delegation_content(fr.get("content") or fr.get("Content") or "")
+    if not parsed:
+        return None
+    tool, data = parsed
+    return fr.get("name") or fr.get("Name") or tool, tool, data, fr.get("id") or fr.get("Id") or ""
+
+
+def parse_batch_delegations(message_content):
+    """Parse a #function_results_batch message.
+
+    Returns (items, delegations) where items is the original list of dicts and
+    delegations is a list of (index, content_key, tool, data); empty
+    delegations means the batch is already fully resolved.
+    Returns None if the content is not a valid batch.
+    """
+    body = strip_mention_and_tag(message_content, "#function_results_batch")
+    try:
+        items = json.loads(body)
+    except ValueError:
+        return None
+    if not isinstance(items, list):
+        return None
+    delegations = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            continue
+        content_key = "content" if "content" in item else ("Content" if "Content" in item else None)
+        if content_key is None:
+            continue
+        parsed = parse_delegation_content(item.get(content_key) or "")
+        if parsed:
+            tool, data = parsed
+            delegations.append((index, content_key, tool, data))
+    return items, delegations
+
+
+# ---------------------------------------------------------------------------
+# CLI entry
+# ---------------------------------------------------------------------------
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="codicent agent",
+        description="Run Codicent as a repository coding agent in the current folder.",
+    )
+    sub = parser.add_subparsers(dest="subcommand")
+    execp = sub.add_parser("exec", help="Execute one agent turn")
+    execp.add_argument("--cwd", default=None, help="Workspace root (default: current directory)")
+    execp.add_argument("--output-format", choices=OUTPUT_FORMATS, default=OUTPUT_TEXT)
+    execp.add_argument("--sandbox", choices=SANDBOX_LEVELS, default=SANDBOX_WORKSPACE_WRITE,
+                       help="Filesystem access level; shell commands require danger-full-access")
+    execp.add_argument("--approval-policy", choices=APPROVAL_POLICIES, default=APPROVAL_ON_REQUEST)
+    execp.add_argument("--resume", default=None, metavar="SESSION_ID")
+    execp.add_argument("--prompt", default=None, help="The task prompt (or pass as positional text)")
+    execp.add_argument("--timeout", type=float, default=DEFAULT_TURN_TIMEOUT, help="Turn timeout in seconds")
+    execp.add_argument("prompt_words", nargs="*", help=argparse.SUPPRESS)
+    return parser
+
+
+def _get_token():
+    from auth import CodicentAuth
+
+    token = CodicentAuth().get_cached_token()
+    if not token:
+        token = os.getenv("CODICENT_TOKEN")
+    return token
+
+
+def build_prompt_message(prompt, instructions):
+    if not instructions:
+        return prompt
+    parts = ["<repository-instructions>"]
+    for name, content in instructions:
+        parts.append(f"# file: {name}")
+        parts.append(content)
+    parts.append("</repository-instructions>")
+    parts.append("")
+    parts.append(prompt)
+    return "\n".join(parts)
+
+
+def run_agent_command(argv):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.subcommand != "exec":
+        parser.print_help(sys.stderr)
+        return EXIT_ERROR
+
+    emitter = ProtocolEmitter(output_format=args.output_format)
+
+    prompt = args.prompt or " ".join(args.prompt_words).strip()
+    if not prompt:
+        emitter.error("no prompt given (use --prompt)")
+        return EXIT_ERROR
+
+    try:
+        workspace = WorkspaceContext(args.cwd)
+    except WorkspaceError as e:
+        emitter.error(str(e))
+        return EXIT_ERROR
+
+    token = _get_token()
+    if not token:
+        emitter.error("authentication required: run 'codicent auth' or set CODICENT_TOKEN")
+        return EXIT_ERROR
+    try:
+        jwt = decode_jwt_payload(token)
+        project = jwt["project"]
+        base_url = jwt.get("baseUrl", "https://codicent.com/")
+    except Exception as e:
+        emitter.error(f"could not read project from token: {e}")
+        return EXIT_ERROR
+
+    try:
+        if args.resume:
+            session = AgentSession.load(args.resume)
+        else:
+            session = AgentSession.new(workspace.root)
+            session.save()
+    except SessionError as e:
+        emitter.error(str(e))
+        return EXIT_ERROR
+    emitter.session_id = session.session_id
+    emitter.session()
+
+    policy = AgentPolicy(sandbox=args.sandbox, approval=args.approval_policy)
+    headless = args.output_format == OUTPUT_JSONL or not sys.stdin.isatty()
+    confirm_fn = None
+    if policy.approval == APPROVAL_ON_REQUEST and not headless:
+        def confirm_fn(tool, summary):
+            try:
+                answer = input(f"Allow {tool}: {summary}? (y/N) ")
+            except (KeyboardInterrupt, EOFError):
+                return False
+            return answer.strip().lower() == "y"
+
+    dispatcher = ToolDispatcher(workspace, policy, confirm_fn=confirm_fn)
+
+    if args.sandbox == SANDBOX_FULL_ACCESS:
+        emitter.log("WARNING: danger-full-access sandbox — no workspace confinement")
+
+    instructions = []
+    try:
+        instructions = workspace.discover_instructions()
+        if instructions:
+            emitter.log(f"instructions: {', '.join(name for name, _ in instructions)}")
+    except Exception as e:
+        emitter.log(f"instruction discovery failed: {e}")
+
+    message = build_prompt_message(prompt, instructions)
+
+    try:
+        return _run_turn(emitter, dispatcher, session, base_url, token, project, message, args.timeout, headless)
+    except KeyboardInterrupt:
+        dispatcher.cancel()
+        emitter.error("cancelled")
+        return EXIT_CANCELLED
+    except requests.RequestException as e:
+        emitter.error(f"server request failed: {e}")
+        return EXIT_ERROR
+
+
+def _run_turn(emitter, dispatcher, session, base_url, token, project, message, timeout, headless):
+    prompt_id = start_chat_async(base_url, token, project, message, session.conversation_id)
+    if not prompt_id:
+        emitter.error("server did not return a prompt message id")
+        return EXIT_ERROR
+    session.touch(prompt_id)
+
+    deadline = time.time() + timeout
+    last_seen_id = None
+
+    while time.time() < deadline:
+        if dispatcher.cancelled:
+            emitter.error("cancelled")
+            return EXIT_CANCELLED
+        try:
+            history = fetch_history(base_url, token, prompt_id)
+        except requests.RequestException as e:
+            emitter.log(f"history fetch error: {e}")
+            time.sleep(POLL_INTERVAL_SECONDS)
+            continue
+
+        if not history or len(history) < 2:
+            time.sleep(POLL_INTERVAL_SECONDS)
+            continue
+
+        last = history[-1]
+        last_id = last.get("id") or last.get("Id")
+        content = last.get("content") or last.get("Content") or ""
+
+        if last_id == last_seen_id:
+            time.sleep(POLL_INTERVAL_SECONDS)
+            continue
+        last_seen_id = last_id
+
+        # Batch delegation (check before single: "#function_result" is a
+        # substring of "#function_results_batch").
+        if "#function_results_batch" in content:
+            if not dispatcher.already_handled(last_id):
+                parsed = parse_batch_delegations(content)
+                if parsed:
+                    items, delegations = parsed
+                    if delegations:
+                        code = _handle_batch(
+                            emitter, dispatcher, base_url, token, project, last_id, items, delegations, headless
+                        )
+                        if code is not None:
+                            return code
+                dispatcher.mark_handled(last_id)
+            time.sleep(POLL_INTERVAL_SECONDS)
+            continue
+
+        if "#function_result" in content:
+            if not dispatcher.already_handled(last_id):
+                delegation = parse_single_delegation(content)
+                if delegation:
+                    name, tool, data, tool_id = delegation
+                    code = _handle_single(
+                        emitter, dispatcher, base_url, token, project, last_id, name, tool, data, tool_id, headless
+                    )
+                    if code is not None:
+                        return code
+                dispatcher.mark_handled(last_id)
+            time.sleep(POLL_INTERVAL_SECONDS)
+            continue
+
+        intermediate_markers = ("#chat2", "#finish_reason_function_call", "#finish_reason_tool_calls_batch")
+        if any(marker in content for marker in intermediate_markers):
+            time.sleep(POLL_INTERVAL_SECONDS)
+            continue
+
+        # Final answer: strip @mention and leading tags for output.
+        clean = re.sub(r"^@\S+\s*", "", content).strip()
+        clean = re.sub(r"^(#\S+\s*)+", "", clean).strip()
+        session.touch(last_id)
+        emitter.text(clean)
+        emitter.done()
+        return EXIT_OK
+
+    emitter.error(f"turn timed out after {int(timeout)}s")
+    return EXIT_ERROR
+
+
+def _handle_single(emitter, dispatcher, base_url, token, project, msg_id, name, tool, data, tool_id, headless):
+    """Execute one delegated call and post the result. Returns an exit code to
+    terminate with, or None to continue polling."""
+    decision = dispatcher.evaluate(tool, data)
+    if decision.verdict == NEED_APPROVAL and headless:
+        emitter.need_approval(tool, dispatcher.describe(tool, data))
+        return EXIT_APPROVAL_REQUIRED
+
+    emitter.tool(tool, dispatcher.describe(tool, data))
+    result, status = dispatcher.dispatch(tool, data)
+    if status == STATUS_CANCELLED:
+        emitter.error("cancelled")
+        return EXIT_CANCELLED
+    if status == STATUS_NEED_APPROVAL:
+        emitter.need_approval(tool, dispatcher.describe(tool, data))
+        return EXIT_APPROVAL_REQUIRED
+    post_function_result(base_url, token, project, msg_id, name, result, tool_id)
+    return None
+
+
+def _handle_batch(emitter, dispatcher, base_url, token, project, msg_id, items, delegations, headless):
+    """Execute every delegated item in a batch and post the resolved batch.
+    Returns an exit code to terminate with, or None to continue polling."""
+    if headless:
+        pending = [
+            (tool, data)
+            for _index, _key, tool, data in delegations
+            if dispatcher.evaluate(tool, data).verdict == NEED_APPROVAL
+        ]
+        if pending:
+            for tool, data in pending:
+                emitter.need_approval(tool, dispatcher.describe(tool, data))
+            return EXIT_APPROVAL_REQUIRED
+
+    for index, content_key, tool, data in delegations:
+        emitter.tool(tool, dispatcher.describe(tool, data))
+        result, status = dispatcher.dispatch(tool, data)
+        if status == STATUS_CANCELLED:
+            emitter.error("cancelled")
+            return EXIT_CANCELLED
+        if status == STATUS_NEED_APPROVAL:
+            emitter.need_approval(tool, dispatcher.describe(tool, data))
+            return EXIT_APPROVAL_REQUIRED
+        items[index][content_key] = result
+
+    post_batch_results(base_url, token, project, msg_id, items)
+    return None

codicent_cli-0.9.0/agent_policy.py

@@ -0,0 +1,78 @@
+"""Sandbox and approval policy for agent mode (ADR-023 §6–§7).
+
+Sandbox level and approval policy are independent axes: the sandbox says what
+is reachable at all, the approval policy says what needs a human first.
+Unknown tools are denied — the policy is fail-closed.
+"""
+from collections import namedtuple
+
+from agent_workspace import WorkspaceEscapeError
+
+SANDBOX_READ_ONLY = "read-only"
+SANDBOX_WORKSPACE_WRITE = "workspace-write"
+SANDBOX_FULL_ACCESS = "danger-full-access"
+SANDBOX_LEVELS = (SANDBOX_READ_ONLY, SANDBOX_WORKSPACE_WRITE, SANDBOX_FULL_ACCESS)
+
+APPROVAL_ON_REQUEST = "on-request"
+APPROVAL_NEVER = "never"
+APPROVAL_POLICIES = (APPROVAL_ON_REQUEST, APPROVAL_NEVER)
+
+READ_TOOLS = frozenset({"fs_read", "fs_list", "fs_search"})
+WRITE_TOOLS = frozenset({"fs_write", "apply_patch"})
+COMMAND_TOOLS = frozenset({"execute_command"})
+KNOWN_TOOLS = READ_TOOLS | WRITE_TOOLS | COMMAND_TOOLS
+
+ALLOW = "allow"
+DENY = "deny"
+NEED_APPROVAL = "need_approval"
+
+Decision = namedtuple("Decision", ["verdict", "reason"])
+
+
+class AgentPolicy:
+    def __init__(self, sandbox=SANDBOX_WORKSPACE_WRITE, approval=APPROVAL_ON_REQUEST):
+        if sandbox not in SANDBOX_LEVELS:
+            raise ValueError(f"unknown sandbox level: {sandbox}")
+        if approval not in APPROVAL_POLICIES:
+            raise ValueError(f"unknown approval policy: {approval}")
+        self.sandbox = sandbox
+        self.approval = approval
+
+    def evaluate(self, tool, data, workspace):
+        """Return a Decision for one delegated tool call. Never raises."""
+        if tool not in KNOWN_TOOLS:
+            return Decision(DENY, f"unknown tool '{tool}'")
+
+        if tool in READ_TOOLS:
+            return self._check_path(data.get("path", ""), workspace)
+
+        if tool in WRITE_TOOLS:
+            if self.sandbox == SANDBOX_READ_ONLY:
+                return Decision(DENY, "read-only sandbox forbids filesystem writes")
+            if tool != "apply_patch":
+                # Paths are validated per-file when the patch is parsed; fs_write
+                # is checked here.
+                decision = self._check_path(data.get("path", ""), workspace)
+                if decision.verdict != ALLOW:
+                    return decision
+            if self.approval == APPROVAL_ON_REQUEST:
+                return Decision(NEED_APPROVAL, "filesystem write requires approval")
+            return Decision(ALLOW, "")
+
+        # execute_command
+        if self.sandbox == SANDBOX_READ_ONLY:
+            return Decision(DENY, "read-only sandbox forbids shell commands")
+        if self.sandbox != SANDBOX_FULL_ACCESS:
+            return Decision(DENY, "shell commands require --sandbox danger-full-access; cwd confinement cannot sandbox a process")
+        if self.approval == APPROVAL_ON_REQUEST:
+            return Decision(NEED_APPROVAL, "command execution requires approval")
+        return Decision(ALLOW, "")
+
+    def _check_path(self, path, workspace):
+        if self.sandbox == SANDBOX_FULL_ACCESS:
+            return Decision(ALLOW, "")
+        try:
+            workspace.resolve(path)
+        except WorkspaceEscapeError as e:
+            return Decision(DENY, str(e))
+        return Decision(ALLOW, "")

codicent_cli-0.9.0/agent_protocol.py

@@ -0,0 +1,76 @@
+"""Structured output protocol for `codicent agent exec` (ADR-023 §3–§4, frozen).
+
+JSONL mode writes exactly one JSON object per stdout line and nothing else;
+all diagnostics go to stderr. Text mode is a minimal human-readable rendering
+(never Rich — Rich stays out of agent mode entirely).
+"""
+import json
+import sys
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_APPROVAL_REQUIRED = 2
+EXIT_CANCELLED = 130
+
+OUTPUT_JSONL = "jsonl"
+OUTPUT_TEXT = "text"
+OUTPUT_FORMATS = (OUTPUT_JSONL, OUTPUT_TEXT)
+
+EVENT_TYPES = ("session", "tool", "need_approval", "text", "done", "error")
+
+
+class ProtocolEmitter:
+    def __init__(self, session_id="", output_format=OUTPUT_TEXT, stdout=None, stderr=None):
+        if output_format not in OUTPUT_FORMATS:
+            raise ValueError(f"unknown output format: {output_format}")
+        self.session_id = session_id
+        self.output_format = output_format
+        self.stdout = stdout if stdout is not None else sys.stdout
+        self.stderr = stderr if stderr is not None else sys.stderr
+
+    def _emit(self, event_type, text=None, tool=None):
+        event = {"type": event_type, "session_id": self.session_id}
+        if tool is not None:
+            event["tool"] = tool
+        if text is not None:
+            event["text"] = text
+        if self.output_format == OUTPUT_JSONL:
+            self.stdout.write(json.dumps(event, ensure_ascii=False) + "\n")
+        else:
+            if event_type == "session":
+                self.stdout.write(f"[session {self.session_id}]\n")
+            elif event_type == "tool":
+                self.stdout.write(f"[tool] {tool}: {text}\n")
+            elif event_type == "need_approval":
+                self.stdout.write(f"[approval required] {tool}: {text}\n")
+            elif event_type == "text":
+                self.stdout.write(f"{text}\n")
+            elif event_type == "done":
+                self.stdout.write("[done]\n")
+            elif event_type == "error":
+                self.stdout.write(f"[error] {text}\n")
+        self.stdout.flush()
+        return event
+
+    def session(self):
+        return self._emit("session")
+
+    def tool(self, tool, text):
+        return self._emit("tool", text=text, tool=tool)
+
+    def need_approval(self, tool, text):
+        return self._emit("need_approval", text=text, tool=tool)
+
+    def text(self, text):
+        return self._emit("text", text=text)
+
+    def done(self):
+        return self._emit("done")
+
+    def error(self, text):
+        return self._emit("error", text=text)
+
+    def log(self, text):
+        """Diagnostic line — stderr only, never stdout."""
+        self.stderr.write(f"{text}\n")
+        self.stderr.flush()