Files
computer/cptr/utils/tools.py
T
Timothy Jaeryang Baek 759ffd1b2d refac
2026-06-19 23:58:06 +02:00

2171 lines
75 KiB
Python

"""Tool definitions: plain functions with schema introspection.
Tools are real async functions. Schemas are auto-generated from
type hints + docstrings via inspect. Keyword-only parameters are
never exposed to the LLM — they carry injected execution context:
- Legacy tools use ``*, workspace: str`` (injected by execute_tool).
- Context-aware tools use ``*, __context__: dict`` containing
workspace, user_id, and model_id (injected by execute_tool).
"""
from __future__ import annotations
import asyncio
import fnmatch
import inspect
import json
import os
import re
import time
import uuid
from pathlib import Path
from typing import Callable, Optional, Pattern, get_args, get_origin, get_type_hints
from cptr.env import CHAT_TOOL_COMMAND_MAX_CHARS, CHAT_TOOL_MAX_CHARS, EXECUTE_TIMEOUT
try:
import fcntl
import pty
import signal
import struct
import subprocess
import termios
_PTY_AVAILABLE = True
except ImportError:
import signal
import subprocess
_PTY_AVAILABLE = False # Windows
# ── Background task state ───────────────────────────────────
_bg_tasks: dict[str, dict] = {}
# task_id → {
# "master_fd": int | None, PTY mode (Unix) — read/write through this fd
# "proc": Popen | Process, The child process handle
# "output": bytearray, In-memory ring buffer (256KB cap)
# "command": str,
# "done": bool,
# "exit_code": int | None,
# "log_path": str,
# }
_BG_TASK_LIMIT = 5
_MAX_LOG_SIZE = 50 * 1024 * 1024 # 50MB — rotate when exceeded
def _spawn_pty(command: str, cwd: str, env: dict) -> tuple:
"""Spawn a command under a PTY (Unix only). Returns (proc, master_fd)."""
master_fd, slave_fd = pty.openpty()
try:
fcntl.ioctl(slave_fd, termios.TIOCSWINSZ, struct.pack("HHHH", 24, 80, 0, 0))
proc = subprocess.Popen(
command,
shell=True,
stdin=slave_fd,
stdout=slave_fd,
stderr=slave_fd,
cwd=cwd,
env=env,
start_new_session=True,
)
except Exception:
os.close(slave_fd)
os.close(master_fd)
raise
os.close(slave_fd)
return proc, master_fd
def _kill_process_group(pid: int, force: bool = False) -> None:
"""Send signal to the child's entire process group.
SIGTERM for graceful shutdown (default), SIGKILL for force.
Falls back to signalling just the leader if the group is gone.
"""
sig = signal.SIGKILL if force else signal.SIGTERM
try:
os.killpg(pid, sig)
except (ProcessLookupError, PermissionError):
try:
os.kill(pid, sig)
except ProcessLookupError:
pass
def _rotate_log(log_path: str, log_file) -> tuple:
"""Keep the newest half of the log file. Returns new (file, bytes_written)."""
log_file.flush()
log_file.close()
with open(log_path, "r", encoding="utf-8") as f:
lines = f.readlines()
keep = lines[len(lines) // 2:]
with open(log_path, "w", encoding="utf-8") as f:
f.write(json.dumps({"type": "log_rotated", "ts": time.time()}) + "\n")
for line in keep:
f.write(line)
new_file = open(log_path, "a", encoding="utf-8")
new_size = sum(len(l.encode("utf-8", errors="replace")) for l in keep)
return new_file, new_size
async def _collect_bg_output(task_id: str):
"""Read output from a background process (PTY or pipe) into memory + JSONL log."""
task = _bg_tasks.get(task_id)
if not task:
return
master_fd = task.get("master_fd")
proc = task["proc"]
log_path = task.get("log_path")
log_file = None
log_bytes = 0
try:
if log_path:
Path(log_path).parent.mkdir(parents=True, exist_ok=True)
log_file = open(log_path, "a", encoding="utf-8")
entry = json.dumps({"type": "start", "command": task["command"],
"pid": proc.pid, "ts": time.time()}) + "\n"
log_file.write(entry)
log_file.flush()
log_bytes += len(entry.encode("utf-8", errors="replace"))
loop = asyncio.get_event_loop()
while True:
# Read from PTY fd (Unix) or subprocess pipe (Windows fallback)
if master_fd is not None:
try:
chunk = await loop.run_in_executor(None, os.read, master_fd, 4096)
if not chunk:
break
except OSError:
break # EIO when child exits
else:
chunk = await proc.stdout.read(4096)
if not chunk:
break
task = _bg_tasks.get(task_id)
if task:
task["output"].extend(chunk)
task["total_bytes"] += len(chunk)
if len(task["output"]) > 256 * 1024:
task["output"] = task["output"][-256 * 1024:]
if log_file:
entry = json.dumps({"type": "output",
"data": chunk.decode(errors="replace"),
"ts": time.time()}) + "\n"
entry_size = len(entry.encode("utf-8", errors="replace"))
if log_bytes + entry_size > _MAX_LOG_SIZE:
log_file, log_bytes = _rotate_log(log_path, log_file)
log_file.write(entry)
log_file.flush()
log_bytes += entry_size
except Exception:
pass
finally:
# Wait for the process to finish and collect exit code
task = _bg_tasks.get(task_id)
if master_fd is not None:
exit_code = await loop.run_in_executor(None, proc.wait)
try:
os.close(master_fd)
except OSError:
pass
else:
await proc.wait()
exit_code = proc.returncode
if task:
task["done"] = True
task["exit_code"] = exit_code
task["master_fd"] = None # fd is closed
if log_file:
log_file.write(
json.dumps({"type": "end", "exit_code": exit_code,
"ts": time.time()}) + "\n"
)
log_file.close()
# ── Helper ──────────────────────────────────────────────────
def _is_dotenv(path: Path) -> bool:
"""Return True if the path refers to a .env file (e.g. .env, .env.local)."""
return path.name == ".env" or path.name.startswith(".env.")
_DOTENV_ERROR = "Error: access to .env files is not allowed for security reasons."
def _human_size(size: int) -> str:
"""Format byte size for display."""
for unit in ("B", "KB", "MB", "GB"):
if size < 1024:
return f"{size}{unit}" if unit == "B" else f"{size:.1f}{unit}"
size /= 1024
return f"{size:.1f}TB"
def _truncate_output(text: str, max_chars: int = 80_000) -> str:
"""Truncate long output, keeping head and tail."""
if len(text) <= max_chars:
return text
half = max_chars // 2
return text[:half] + "\n\n... (truncated) ...\n\n" + text[-half:]
# ── Image support ───────────────────────────────────────────
IMAGE_EXTENSIONS = {
".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif",
}
_IMAGE_MAX_BYTES = 5 * 1024 * 1024 # 5 MB target for API payload
_IMAGE_MIME = {
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".gif": "image/gif",
".webp": "image/webp",
".bmp": "image/bmp",
".tiff": "image/tiff",
".tif": "image/tiff",
}
def _read_image_file(full: Path, path: str) -> str:
"""Read an image file and return a data URI string.
If the file exceeds _IMAGE_MAX_BYTES, attempts to resize it down
using Pillow. Falls back to a text error if Pillow is unavailable
and the file is too large.
"""
import base64
size = full.stat().st_size
ext = full.suffix.lower()
media_type = _IMAGE_MIME.get(ext, "image/png")
data = full.read_bytes()
if size > _IMAGE_MAX_BYTES:
try:
from PIL import Image
import io
img = Image.open(io.BytesIO(data))
# Progressively scale down until under limit
# Use JPEG for lossy formats, PNG for lossless
out_format = "JPEG" if ext in (".jpg", ".jpeg", ".bmp", ".tiff", ".tif") else "PNG"
if out_format == "JPEG":
media_type = "image/jpeg"
# Convert RGBA to RGB for JPEG
if img.mode in ("RGBA", "P"):
img = img.convert("RGB")
else:
media_type = "image/png"
scale = 0.8 # start at 80%
for _ in range(10):
new_w = int(img.width * scale)
new_h = int(img.height * scale)
if new_w < 100 or new_h < 100:
break
resized = img.resize((new_w, new_h), Image.LANCZOS)
buf = io.BytesIO()
save_kwargs = {"quality": 85} if out_format == "JPEG" else {}
resized.save(buf, format=out_format, **save_kwargs)
if buf.tell() <= _IMAGE_MAX_BYTES:
data = buf.getvalue()
size = len(data)
break
scale *= 0.7 # more aggressive on each pass
else:
return f"Error: image too large ({_human_size(full.stat().st_size)}) and could not be resized below 5MB."
except ImportError:
return (
f"Error: image file is too large ({_human_size(size)}). "
f"Install Pillow (`pip install Pillow`) to enable automatic resizing."
)
b64 = base64.b64encode(data).decode("ascii")
return f"data:{media_type};base64,{b64}"
# ── Tool functions ──────────────────────────────────────────
async def read_file(
path: str,
start_line: int = 0,
end_line: int = 0,
*,
workspace: str,
) -> str:
"""Read file contents with optional line range. Lines are 1-indexed.
Supports absolute paths for user-attached files.
:param path: Path relative to workspace root, or absolute path for attached files.
:param start_line: First line to read (1-indexed, 0 = from beginning).
:param end_line: Last line to read (inclusive, 0 = to end of file).
"""
full = _resolve_path(path, workspace)
if _is_dotenv(full):
return _DOTENV_ERROR
if not full.is_file():
return f"Error: file not found: {path}"
# Image files: return base64 JSON instead of garbled text
if full.suffix.lower() in IMAGE_EXTENSIONS:
return await asyncio.to_thread(_read_image_file, full, path)
def _read():
size = full.stat().st_size
if size > 500_000:
return f"Error: file too large ({size} bytes, max 500KB)"
# Try strict text decoding first
try:
content = full.read_text(errors="strict")
except (UnicodeDecodeError, ValueError):
# Binary file — try document extraction (PDF, DOCX, XLSX, etc.)
try:
from cptr.utils.documents import extract_by_path
text = extract_by_path(str(full))
if text:
lines = text.splitlines()
total = len(lines)
if start_line > 0 or end_line > 0:
s = max(1, start_line) - 1
e = min(total, end_line) if end_line > 0 else total
selected = lines[s:e]
numbered = [f"{i + s + 1}: {line}" for i, line in enumerate(selected)]
return f"File: {path} | Lines {s + 1}-{e} of {total}\n" + "\n".join(numbered)
capped = lines[:800]
numbered = [f"{i + 1}: {line}" for i, line in enumerate(capped)]
header = f"File: {path} | Total lines: {total}"
if total > 800:
header += " (showing first 800)"
return header + "\n" + "\n".join(numbered)
except ImportError as e:
return f"Error: reading {full.suffix} files requires: {e}"
except Exception as e:
return f"Error: failed to extract text from {path}: {e}"
return f"Error: binary file ({full.suffix}), cannot read as text"
lines = content.splitlines()
total = len(lines)
if start_line > 0 or end_line > 0:
s = max(1, start_line) - 1 # Convert to 0-indexed
e = min(total, end_line) if end_line > 0 else total
selected = lines[s:e]
numbered = [f"{i + s + 1}: {line}" for i, line in enumerate(selected)]
header = f"File: {path} | Lines {s + 1}-{e} of {total}\n"
return header + "\n".join(numbered)
else:
# Cap at 800 lines, show line numbers
capped = lines[:800]
numbered = [f"{i + 1}: {line}" for i, line in enumerate(capped)]
header = f"File: {path} | Total lines: {total}"
if total > 800:
header += " (showing first 800)"
return header + "\n" + "\n".join(numbered)
return await asyncio.to_thread(_read)
async def list_directory(
path: str = ".",
recursive: bool = False,
*,
workspace: str,
) -> str:
"""List files and directories with metadata (sizes, child counts).
:param path: Directory path relative to workspace root.
:param recursive: Whether to list recursively.
"""
full = _resolve_path(path, workspace)
if not full.is_dir():
return f"Error: not a directory: {path}"
def _list():
ignore = {
".git",
"node_modules",
"__pycache__",
".venv",
"venv",
".next",
"build",
"dist",
".cptr",
".svelte-kit",
}
entries = []
if recursive:
for root, dirs, files in os.walk(full):
dirs[:] = sorted(d for d in dirs if d not in ignore)
rel = Path(root).relative_to(full)
for f in sorted(files):
fpath = Path(root) / f
try:
sz = fpath.stat().st_size
except OSError:
sz = 0
entries.append(f"{rel / f} ({_human_size(sz)})")
else:
for item in sorted(full.iterdir()):
if item.name in ignore:
continue
if item.is_dir():
try:
count = sum(1 for _ in item.rglob("*") if _.is_file())
except (PermissionError, OSError):
count = 0
entries.append(f"{item.name}/ ({count} files)")
else:
try:
sz = item.stat().st_size
except OSError:
sz = 0
entries.append(f"{item.name} ({_human_size(sz)})")
return "\n".join(entries) if entries else "(empty directory)"
res = await asyncio.to_thread(_list)
return _truncate_output(res, max_chars=CHAT_TOOL_MAX_CHARS)
async def search_files(
query: str,
path: str = ".",
regex: bool = False,
case_insensitive: bool = False,
include: str = "",
filenames_only: bool = False,
*,
workspace: str,
) -> str:
"""Search files for a pattern using ripgrep. Fast, respects .gitignore.
:param query: Search pattern (plain text or regex).
:param path: Directory to search in, relative to workspace.
:param regex: Treat query as a regular expression.
:param case_insensitive: Case-insensitive matching.
:param include: Glob pattern to filter files (e.g. '*.py', '*.ts').
:param filenames_only: Only return filenames, not matching lines.
"""
full = _resolve_path(path, workspace)
if not full.is_dir():
return f"Error: not a directory: {path}"
# Try ripgrep first
try:
res = await _search_rg(query, full, regex, case_insensitive, include, filenames_only)
except FileNotFoundError:
# ripgrep not installed, fall back to Python
res = await _search_python(query, full, case_insensitive)
return _truncate_output(res, max_chars=CHAT_TOOL_MAX_CHARS)
async def _search_rg(
query: str, full: Path, regex: bool, case_insensitive: bool, include: str, filenames_only: bool
) -> str:
"""Search using ripgrep."""
args = ["rg", "--no-heading", "--max-count=50", "--color=never"]
# Never search .env files
args.extend(["--glob", "!.env", "--glob", "!.env.*"])
if not regex:
args.append("--fixed-strings")
if case_insensitive:
args.append("--ignore-case")
if filenames_only:
args.append("--files-with-matches")
else:
args.append("--line-number")
if include:
for glob in include.split(","):
glob = glob.strip()
if glob:
args.extend(["--glob", glob])
args.extend(["--", query, str(full)])
proc = await asyncio.create_subprocess_exec(
*args,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.PIPE,
)
stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=15)
output = stdout.decode(errors="replace").strip()
if proc.returncode == 1:
return "No matches found."
if proc.returncode > 1:
err = stderr.decode(errors="replace").strip()
raise FileNotFoundError(err) if "not found" in err.lower() else Exception(err)
# Make paths relative
prefix = str(full) + os.sep
lines = output.splitlines()[:50]
result = [line.replace(prefix, "") for line in lines]
return "\n".join(result) if result else "No matches found."
async def _search_python(query: str, full: Path, case_insensitive: bool) -> str:
"""Fallback search using pure Python (when ripgrep not installed)."""
def _read_text_for_search(fpath: Path) -> str | None:
"""Read a file for searching, skipping binary-looking files.
Match ripgrep's default binary handling closely enough for the fallback:
files containing NUL bytes are treated as binary and are not decoded or
returned as replacement-character text.
"""
try:
data = fpath.read_bytes()
except (OSError, PermissionError):
return None
if b"\0" in data:
return None
return data.decode(errors="replace")
def _walk_and_search():
results = []
ignore = {".git", "node_modules", "__pycache__", ".venv", "venv"}
q = query.lower() if case_insensitive else query
for root, dirs, files in os.walk(full):
dirs[:] = [d for d in dirs if d not in ignore]
for fname in files:
fpath = Path(root) / fname
if _is_dotenv(fpath):
continue
text = _read_text_for_search(fpath)
if text is None:
continue
for i, line in enumerate(text.splitlines(), 1):
target = line.lower() if case_insensitive else line
if q in target:
rel = fpath.relative_to(full)
results.append(f"{rel}:{i}: {line.strip()}")
if len(results) >= 50:
results.append("... (truncated at 50 matches)")
return "\n".join(results)
return "\n".join(results) if results else "No matches found."
return await asyncio.to_thread(_walk_and_search)
async def create_file(
path: str = "",
content: str = "",
overwrite: bool = False,
artifact_type: str = "",
*,
workspace: str,
) -> str:
"""Create a new file, or create an artifact for user review.
When artifact_type is set, path is optional. The artifact is saved automatically.
:param path: Path relative to workspace root (optional for artifacts).
:param content: File contents to write.
:param overwrite: Set to true to overwrite an existing file.
:param artifact_type: Set to 'implementation_plan' to present a plan for user review before coding.
"""
# Artifact mode: save to .cptr/artifacts/ (same location as create_artifact)
# When artifact_type is set, path is ignored.
if artifact_type:
from datetime import datetime, timezone
ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S")
artifact_dir = Path(workspace) / ".cptr" / "artifacts"
artifact_dir.mkdir(parents=True, exist_ok=True)
artifact_path = artifact_dir / f"{ts}_{artifact_type}.md"
def _write_artifact():
artifact_path.write_text(content)
await asyncio.to_thread(_write_artifact)
rel_path = str(artifact_path.relative_to(Path(workspace)))
display_title = artifact_type.replace("_", " ").title()
return json.dumps({
"artifact_type": artifact_type,
"title": display_title,
"path": rel_path,
"bytes": len(content),
})
if not path:
return "Error: path is required when artifact_type is not set."
full = _resolve_path(path, workspace)
if _is_dotenv(full):
return _DOTENV_ERROR
if full.is_file() and not overwrite:
return f"Error: file already exists: {path}. Use overwrite=true or edit_file to modify."
def _write():
full.parent.mkdir(parents=True, exist_ok=True)
full.write_text(content)
await asyncio.to_thread(_write)
return f"Created {path} ({len(content)} bytes, {len(content.splitlines())} lines)"
async def create_artifact(
content: str,
artifact_type: str = "implementation_plan",
title: str = "",
*,
workspace: str,
) -> str:
"""Create an artifact for user review. Use for implementation plans and analysis.
:param content: Artifact content as markdown.
:param artifact_type: Type of artifact, e.g. 'implementation_plan'.
:param title: Display title for the artifact card.
"""
from datetime import datetime, timezone
artifact_type = artifact_type or "implementation_plan"
ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S")
artifact_dir = Path(workspace) / ".cptr" / "artifacts"
artifact_dir.mkdir(parents=True, exist_ok=True)
artifact_path = artifact_dir / f"{ts}_{artifact_type}.md"
def _write():
artifact_path.write_text(content)
await asyncio.to_thread(_write)
display_title = title or artifact_type.replace("_", " ").title()
rel_path = str(artifact_path.relative_to(Path(workspace)))
return json.dumps({
"artifact_type": artifact_type,
"title": display_title,
"path": rel_path,
"bytes": len(content),
})
async def write_file(path: str, content: str, *, workspace: str) -> str:
"""Write or create a file (full content). Prefer edit_file for modifications.
:param path: Path relative to workspace root.
:param content: File contents to write.
"""
full = _resolve_path(path, workspace)
if _is_dotenv(full):
return _DOTENV_ERROR
def _write():
full.parent.mkdir(parents=True, exist_ok=True)
full.write_text(content)
await asyncio.to_thread(_write)
return f"Wrote {len(content)} bytes to {path}"
async def edit_file(
path: str,
target: str,
replacement: str,
start_line: int = 0,
end_line: int = 0,
*,
workspace: str,
) -> str:
"""Replace a specific text block in a file. Only provide the text that changes.
:param path: Path relative to workspace root.
:param target: Exact text to find and replace (must match file content exactly).
:param replacement: Text to replace the target with.
:param start_line: Narrow search to lines starting here (1-indexed, 0 = from start).
:param end_line: Narrow search to lines ending here (0 = to end).
"""
full = _resolve_path(path, workspace)
if _is_dotenv(full):
return _DOTENV_ERROR
if not full.is_file():
return f"Error: file not found: {path}"
def _edit():
content = full.read_text(errors="replace")
if start_line > 0 or end_line > 0:
lines = content.splitlines(keepends=True)
total = len(lines)
s = max(1, start_line) - 1
e = min(total, end_line) if end_line > 0 else total
region = "".join(lines[s:e])
if target not in region:
return f"Error: target text not found in lines {s + 1}-{e} of {path}"
count = region.count(target)
if count > 1:
return (
f"Error: target text found {count} times in lines {s + 1}-{e}. "
f"Narrow the line range or use a more specific target."
)
new_region = region.replace(target, replacement, 1)
new_content = "".join(lines[:s]) + new_region + "".join(lines[e:])
else:
count = content.count(target)
if count == 0:
return f"Error: target text not found in {path}"
if count > 1:
return (
f"Error: target text found {count} times in {path}. "
f"Use start_line/end_line to disambiguate."
)
new_content = content.replace(target, replacement, 1)
full.write_text(new_content)
return None # success sentinel
result = await asyncio.to_thread(_edit)
if result is not None:
return result
target_lines = len(target.splitlines())
replacement_lines = len(replacement.splitlines())
return (
f"Edited {path}: replaced {target_lines} lines with {replacement_lines} lines "
f"({len(target)} chars → {len(replacement)} chars)"
)
async def multi_edit_file(
path: str,
edits: str,
*,
workspace: str,
) -> str:
"""Apply multiple non-contiguous edits to a file in one operation.
:param path: Path relative to workspace root.
:param edits: JSON array of edit objects, each with 'target' and 'replacement' strings, and optional 'start_line'/'end_line' integers.
"""
full = _resolve_path(path, workspace)
if _is_dotenv(full):
return _DOTENV_ERROR
if not full.is_file():
return f"Error: file not found: {path}"
try:
edit_list = json.loads(edits)
except json.JSONDecodeError as e:
return f"Error: invalid edits JSON: {e}"
if not isinstance(edit_list, list) or not edit_list:
return "Error: edits must be a non-empty JSON array"
def _apply():
content = full.read_text(errors="replace")
applied = 0
for i, edit in enumerate(edit_list):
target = edit.get("target", "")
replacement = edit.get("replacement", "")
if not target:
return f"Error: edit {i + 1} missing 'target'"
if target not in content:
return f"Error: target not found for edit {i + 1}: {target[:100]}..."
count = content.count(target)
if count > 1:
return (
f"Error: edit {i + 1} target found {count} times. "
f"Each target must be unique in the file."
)
content = content.replace(target, replacement, 1)
applied += 1
full.write_text(content)
return f"Applied {applied} edits to {path}"
return await asyncio.to_thread(_apply)
async def run_command(
command: str,
cwd: str = ".",
wait: Optional[int] = None,
*,
workspace: str,
) -> str:
"""Run a shell command. Returns a task_id for status checks and input.
:param command: The shell command to execute.
:param cwd: Working directory relative to workspace root.
:param wait: Seconds to wait for the command to finish before returning (max 300). Returns early if done sooner. Null returns immediately. Use 30-60 for installs and builds, 5-10 for quick commands, null or 0 for long-lived servers.
"""
work_dir = _resolve_path(cwd, workspace)
if not work_dir.is_dir():
return f"Error: not a directory: {cwd}"
active = sum(1 for t in _bg_tasks.values() if not t.get("done"))
if active >= _BG_TASK_LIMIT:
return f"Error: too many running tasks ({active}/{_BG_TASK_LIMIT}). Kill one first."
env = {**os.environ, "PAGER": "cat", "GIT_PAGER": "cat"}
master_fd = None
try:
if _PTY_AVAILABLE:
proc, master_fd = _spawn_pty(command, str(work_dir), env)
else:
proc = await asyncio.create_subprocess_shell(
command,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.STDOUT,
stdin=asyncio.subprocess.PIPE,
cwd=str(work_dir),
env=env,
)
except Exception as e:
return f"Error: {e}"
task_id = uuid.uuid4().hex[:8]
log_dir = Path(workspace) / ".cptr" / "task_logs"
log_dir.mkdir(parents=True, exist_ok=True)
log_path = log_dir / f"{task_id}.jsonl"
_bg_tasks[task_id] = {
"master_fd": master_fd,
"proc": proc,
"output": bytearray(),
"total_bytes": 0,
"command": command,
"done": False,
"exit_code": None,
"log_path": str(log_path),
"log_task": None,
}
log_task = asyncio.create_task(_collect_bg_output(task_id))
_bg_tasks[task_id]["log_task"] = log_task
# Wait for the command to finish inline (matches open-terminal behaviour)
if wait is None and EXECUTE_TIMEOUT:
wait = EXECUTE_TIMEOUT
if wait is not None and wait > 0:
try:
await asyncio.wait_for(asyncio.shield(log_task), timeout=min(wait, 300))
except asyncio.TimeoutError:
pass
task = _bg_tasks.get(task_id)
output = task["output"].decode(errors="replace") if task else ""
output = _truncate_output(output, max_chars=CHAT_TOOL_COMMAND_MAX_CHARS)
done = task.get("done", False) if task else True
exit_code = task.get("exit_code") if task else None
next_offset = task.get("total_bytes", 0) if task else 0
if done:
status = f"exited (code {exit_code})"
else:
status = "running"
return (
f"Task {task_id}: {status}\n"
f"Command: {command}\n"
f"next_offset: {next_offset}\n"
f"---\n{output}"
)
async def check_task(task_id: str, offset: int = 0, wait: Optional[int] = None, *, workspace: str) -> str:
"""Check status and recent output of a background task.
:param task_id: The task ID returned by run_command.
:param offset: Byte offset from previous check. Pass next_offset from the last response to get only new output.
:param wait: Seconds to wait for the task to finish before returning (max 300). Returns early if done sooner. Null returns immediately.
"""
task = _bg_tasks.get(task_id)
if not task:
available = list(_bg_tasks.keys())
return f"Error: no task with id '{task_id}'. Active tasks: {available or 'none'}"
# Optionally wait for the task to finish
if wait is None and EXECUTE_TIMEOUT:
wait = EXECUTE_TIMEOUT
if wait is not None and wait > 0 and not task.get("done"):
collect = task.get("log_task")
if collect and not collect.done():
try:
await asyncio.wait_for(asyncio.shield(collect), timeout=min(wait, 300))
except asyncio.TimeoutError:
pass
buf = task["output"]
total = task.get("total_bytes", 0)
buf_start = total - len(buf) # byte offset of first byte in buffer
if offset <= buf_start:
# Requested offset is before buffer start (old output was trimmed)
raw = buf
else:
# Slice to only return new output since offset
skip = offset - buf_start
raw = buf[skip:]
output = raw.decode(errors="replace")
output = _truncate_output(output, max_chars=CHAT_TOOL_COMMAND_MAX_CHARS)
next_offset = total
if task.get("done", False):
status = f"exited (code {task.get('exit_code')})"
else:
status = "running"
return f"Task {task_id}: {status}\nCommand: {task['command']}\nnext_offset: {next_offset}\n---\n{output}"
async def kill_task(task_id: str, force: bool = False, *, workspace: str) -> str:
"""Terminate a running task. Sends SIGTERM for graceful shutdown by default.
:param task_id: The task ID to kill.
:param force: Send SIGKILL instead of SIGTERM for immediate termination.
"""
task = _bg_tasks.get(task_id)
if not task:
available = list(_bg_tasks.keys())
return f"Error: no task with id '{task_id}'. Active tasks: {available or 'none'}"
if task.get("done", False):
exit_code = task.get("exit_code")
_bg_tasks.pop(task_id, None)
return f"Task {task_id} already finished (code {exit_code})"
proc = task["proc"]
_kill_process_group(proc.pid, force=force)
_bg_tasks.pop(task_id, None)
action = "Killed" if force else "Terminated"
return f"{action} task {task_id}"
async def send_input(task_id: str, input: str, *, workspace: str) -> str:
"""Send input to a running task's stdin. Use for interactive prompts, REPLs, or control characters.
:param task_id: The task ID returned by run_command.
:param input: Text to send. Use \\n for Enter, \\x03 for Ctrl-C, \\x04 for Ctrl-D.
"""
task = _bg_tasks.get(task_id)
if not task:
available = list(_bg_tasks.keys())
return f"Error: no task '{task_id}'. Active: {available or 'none'}"
if task.get("done", False):
return f"Error: task {task_id} already exited (code {task.get('exit_code')})"
# LLMs emit literal "\n" — convert to real characters
try:
text = input.encode("raw_unicode_escape").decode("unicode_escape")
except (UnicodeDecodeError, ValueError):
text = input
master_fd = task.get("master_fd")
if master_fd is not None:
# PTY mode: write to master fd
try:
os.write(master_fd, text.encode())
except OSError:
return f"Error: PTY closed for task {task_id}"
else:
# Pipe mode fallback
proc = task["proc"]
if proc.stdin is None:
return f"Error: task {task_id} has no stdin"
try:
proc.stdin.write(text.encode())
await proc.stdin.drain()
except (BrokenPipeError, ConnectionResetError, OSError):
return f"Error: stdin closed for task {task_id}"
return f"Sent {len(text)} bytes to task {task_id}"
async def web_search(query: str, *, workspace: str) -> str:
"""Search the web for information. Returns summaries with source URLs.
:param query: The search query.
"""
# Defer to web module
from cptr.utils.web import web_search_handler
return await web_search_handler(query)
async def read_url(url: str, *, workspace: str) -> str:
"""Fetch content from a URL and return as text. Converts HTML to readable text.
:param url: The URL to fetch.
"""
from cptr.utils.web import read_url_handler
return await read_url_handler(url)
# ── Path safety ──────────────────────────────────────────────
def _resolve_path(path: str, workspace: str) -> Path:
"""Resolve a path within the workspace or uploads dir. Rejects traversal."""
from cptr.utils.storage import UPLOADS_DIR
p = Path(path)
# Allow absolute paths to the uploads directory (for user-attached files)
if p.is_absolute():
full = p.resolve()
uploads = str(UPLOADS_DIR.resolve())
ws = str(Path(workspace).resolve())
if str(full).startswith(uploads) or str(full).startswith(ws):
return full
raise ValueError(f"Path outside allowed directories: {path}")
# Relative paths resolve against workspace
ws = Path(workspace).resolve()
full = (ws / path).resolve()
if not str(full).startswith(str(ws)):
raise ValueError(f"Path traversal rejected: {path}")
return full
async def create_automation(
name: str,
prompt: str,
rrule: str,
*,
__context__: dict,
) -> str:
"""Create a scheduled automation that runs a prompt on a recurring or one-time schedule.
The rrule parameter must be a valid iCalendar RRULE string. Common examples:
- Every day at 9am: "DTSTART:20250101T090000\\nRRULE:FREQ=DAILY"
- Every Monday at 8am: "DTSTART:20250106T080000\\nRRULE:FREQ=WEEKLY;BYDAY=MO"
- Every hour: "RRULE:FREQ=HOURLY;INTERVAL=1"
- Once at a specific time: "DTSTART:20250415T140000\\nRRULE:FREQ=DAILY;COUNT=1"
- First day of every month: "DTSTART:20250101T090000\\nRRULE:FREQ=MONTHLY;BYMONTHDAY=1"
:param name: A short descriptive name for the automation.
:param prompt: The instructions/prompt to execute on each run.
:param rrule: An iCalendar RRULE string defining the schedule.
"""
workspace = __context__["workspace"]
user_id = __context__["user_id"]
model_id = __context__.get("model_id", "")
try:
import time
from cptr.models.automations import Automation as AutomationModel
from cptr.utils.automations import next_run_ns, next_n_runs_ns, validate_rrule
# Validate RRULE
try:
validate_rrule(rrule)
except ValueError as e:
return json.dumps({"error": f"Invalid schedule: {e}"})
if not model_id:
return json.dumps({"error": "Could not detect model from current chat context."})
now_ns = int(time.time() * 1_000_000_000)
nxt = next_run_ns(rrule)
automation = await AutomationModel.create(
user_id=user_id,
name=name,
prompt=prompt,
model_id=model_id,
workspace=workspace,
rrule=rrule,
next_run_at=nxt,
is_active=True,
created_at=now_ns,
)
return json.dumps({
"status": "success",
"id": automation.id,
"name": automation.name,
"model_id": automation.model_id,
"is_active": automation.is_active,
"next_runs": next_n_runs_ns(rrule),
})
except Exception as e:
return json.dumps({"error": str(e)})
async def list_automations(
status: str = "",
count: int = 10,
*,
__context__: dict,
) -> str:
"""List scheduled automations for the current workspace.
:param status: Filter by status: "active", "paused", or empty for all.
:param count: Maximum number of automations to return (default: 10).
"""
workspace = __context__["workspace"]
user_id = __context__["user_id"]
try:
from cptr.models.automations import Automation as AutomationModel
from cptr.utils.automations import next_n_runs_ns
items, total = await AutomationModel.get_by_workspace(
user_id=user_id,
workspace=workspace or None,
status=status or None,
limit=count,
)
automations = []
for item in items:
automations.append({
"id": item.id,
"name": item.name,
"prompt_snippet": item.prompt[:100] + ("..." if len(item.prompt) > 100 else ""),
"model_id": item.model_id,
"rrule": item.rrule,
"is_active": item.is_active,
"last_run_at": item.last_run_at,
"next_runs": next_n_runs_ns(item.rrule),
})
return json.dumps({"automations": automations, "total": total})
except Exception as e:
return json.dumps({"error": str(e)})
async def update_automation(
automation_id: str,
name: str = "",
prompt: str = "",
rrule: str = "",
model_id: str = "",
*,
__context__: dict,
) -> str:
"""Update an existing automation. Only provided fields are changed.
:param automation_id: The ID of the automation to update.
:param name: New name (optional).
:param prompt: New prompt/instructions (optional).
:param rrule: New iCalendar RRULE schedule string (optional).
:param model_id: New model ID (optional).
"""
try:
import time
from cptr.models.automations import Automation as AutomationModel
from cptr.utils.automations import next_run_ns, next_n_runs_ns, validate_rrule
automation = await AutomationModel.get_by_id(automation_id)
if not automation:
return json.dumps({"error": "Automation not found"})
kwargs = {}
if name:
kwargs["name"] = name
if prompt:
kwargs["prompt"] = prompt
if model_id:
kwargs["model_id"] = model_id
if rrule:
try:
validate_rrule(rrule)
except ValueError as e:
return json.dumps({"error": f"Invalid schedule: {e}"})
kwargs["rrule"] = rrule
kwargs["next_run_at"] = next_run_ns(rrule)
if not kwargs:
return json.dumps({"error": "No fields to update"})
now_ns = int(time.time() * 1_000_000_000)
success = await AutomationModel.update_by_id(automation_id, updated_at=now_ns, **kwargs)
if not success:
return json.dumps({"error": "Failed to update automation"})
final_rrule = rrule or automation.rrule
return json.dumps({
"status": "success",
"id": automation_id,
"updated_fields": list(kwargs.keys()),
"next_runs": next_n_runs_ns(final_rrule),
})
except Exception as e:
return json.dumps({"error": str(e)})
async def toggle_automation(
automation_id: str,
*,
__context__: dict,
) -> str:
"""Pause or resume a scheduled automation. If active, it will be paused. If paused, it will be resumed.
:param automation_id: The ID of the automation to toggle.
"""
try:
from cptr.models.automations import Automation as AutomationModel
from cptr.utils.automations import next_run_ns
automation = await AutomationModel.get_by_id(automation_id)
if not automation:
return json.dumps({"error": "Automation not found"})
nxt = next_run_ns(automation.rrule) if not automation.is_active else None
toggled = await AutomationModel.toggle(automation_id, next_run_at=nxt)
if not toggled:
return json.dumps({"error": "Failed to toggle automation"})
return json.dumps({
"status": "success",
"id": toggled.id,
"name": toggled.name,
"is_active": toggled.is_active,
})
except Exception as e:
return json.dumps({"error": str(e)})
async def delete_automation(
automation_id: str,
*,
__context__: dict,
) -> str:
"""Delete a scheduled automation and all its run history.
:param automation_id: The ID of the automation to delete.
"""
try:
from cptr.models.automations import Automation as AutomationModel
automation = await AutomationModel.get_by_id(automation_id)
if not automation:
return json.dumps({"error": "Automation not found"})
name = automation.name
success = await AutomationModel.delete(automation_id)
if not success:
return json.dumps({"error": "Failed to delete automation"})
return json.dumps({"status": "success", "message": f'Automation "{name}" deleted'})
except Exception as e:
return json.dumps({"error": str(e)})
# ── Skill tools ─────────────────────────────────────────────
# Track activated skills per session (cleared on import)
_activated_skills: set[str] = set()
async def view_skill(
skill_name: str,
*,
workspace: str,
) -> str:
"""Load the full instructions and resource listing for an available skill.
:param skill_name: The name of the skill to load (from the <available_skills> catalog).
"""
from cptr.utils.skills import load_skill, format_skill_content
# Deduplication: if already activated, return short notice
if skill_name in _activated_skills:
return f"Skill '{skill_name}' is already loaded in this session. Refer to the existing <skill_content> above."
skill = load_skill(workspace, skill_name)
if not skill:
return f"Error: skill '{skill_name}' not found. Check <available_skills> for valid names."
_activated_skills.add(skill_name)
return format_skill_content(skill)
# ── Browser tools ────────────────────────────────────────────
async def _get_browser_config() -> dict:
"""Read browser config from DB."""
try:
from cptr.models import Config
return {
"enabled": await Config.get("browser.enabled") or False,
"provider": await Config.get("browser.provider") or "local",
"cdp_url": await Config.get("browser.cdp_url") or "http://localhost:9222",
"auto_launch": await Config.get("browser.auto_launch") if await Config.get("browser.auto_launch") is not None else True,
"session_timeout": int(await Config.get("browser.session_timeout_minutes") or 10),
"firecrawl_api_key": await Config.get("browser.firecrawl_api_key") or "",
"firecrawl_base_url": await Config.get("browser.firecrawl_base_url") or "https://api.firecrawl.dev",
"browser_use_api_key": await Config.get("browser.browser_use_api_key") or "",
"browser_use_base_url": await Config.get("browser.browser_use_base_url") or "https://api.browser-use.com",
}
except Exception:
return {"enabled": False, "provider": "local"}
async def _get_cdp_session(chat_id: str) -> "CDPClient":
"""Get or create a CDP session for the current chat."""
cfg = await _get_browser_config()
cdp_url = cfg["cdp_url"]
if cfg.get("auto_launch", True):
from cptr.utils.browser.launcher import ensure_browser
cdp_url = await ensure_browser(port=int(cdp_url.split(":")[-1]))
from cptr.utils.browser.session import session_manager
session_manager.set_timeout(cfg.get("session_timeout", 10))
return await session_manager.get_or_create(chat_id, cdp_url)
async def browser_navigate(url: str, *, __context__: dict) -> str:
"""Navigate to a URL in the browser. Returns the page title and status.
:param url: The URL to navigate to.
"""
cfg = await _get_browser_config()
provider = cfg.get("provider", "local")
if provider == "firecrawl":
key = cfg.get("firecrawl_api_key", "")
if not key:
return "Error: Firecrawl API key not configured. Set it in Settings > Browser."
from cptr.utils.browser.firecrawl import scrape
content = await scrape(url, key, cfg.get("firecrawl_base_url", ""))
return f"Navigated to {url} (via Firecrawl)\n\n{content}"
if provider == "browser_use":
key = cfg.get("browser_use_api_key", "")
if not key:
return "Error: Browser-Use API key not configured. Set it in Settings > Browser."
from cptr.utils.browser.browser_use import browse
result = await browse(f"Navigate to {url} and describe what you see", key, cfg.get("browser_use_base_url", ""))
return f"Navigated to {url} (via Browser-Use)\n\n{result}"
# Local CDP
chat_id = __context__.get("chat_id", "default")
client = await _get_cdp_session(chat_id)
result = await client.navigate(url)
return f"Navigated to {url}\nTitle: {result.get('title', '')}"
async def browser_snapshot(*, __context__: dict) -> str:
"""Get the current page content. For local browser, returns an accessibility tree with ref IDs (@e1, @e2, etc.) that can be used with browser_click and browser_type. For cloud providers, returns page content as text."""
cfg = await _get_browser_config()
provider = cfg.get("provider", "local")
if provider in ("firecrawl", "browser_use"):
return "Snapshot is only meaningful after browser_navigate. The navigate result already contains the page content."
chat_id = __context__.get("chat_id", "default")
client = await _get_cdp_session(chat_id)
return await client.snapshot()
async def browser_click(ref: str, *, __context__: dict) -> str:
"""Click an element on the page identified by its ref ID from the snapshot (e.g. @e1).
:param ref: The ref ID of the element to click (e.g. @e1, @e5).
"""
cfg = await _get_browser_config()
if cfg.get("provider", "local") != "local":
return "Error: browser_click requires Local CDP provider. Cloud providers (Firecrawl, Browser-Use) don't support interactive browsing. Switch to Local CDP in Settings > Browser."
chat_id = __context__.get("chat_id", "default")
client = await _get_cdp_session(chat_id)
await client.click(ref)
# Return updated snapshot so the AI sees the result
return await client.snapshot()
async def browser_type(ref: str, text: str, *, __context__: dict) -> str:
"""Type text into an input element identified by its ref ID from the snapshot.
:param ref: The ref ID of the input element (e.g. @e3).
:param text: The text to type.
"""
cfg = await _get_browser_config()
if cfg.get("provider", "local") != "local":
return "Error: browser_type requires Local CDP provider. Switch to Local CDP in Settings > Browser."
chat_id = __context__.get("chat_id", "default")
client = await _get_cdp_session(chat_id)
await client.type_text(ref, text)
return await client.snapshot()
async def browser_screenshot(*, __context__: dict) -> str:
"""Take a screenshot of the current browser page. Saves the image to the workspace.
"""
cfg = await _get_browser_config()
if cfg.get("provider", "local") != "local":
return "Error: browser_screenshot requires Local CDP provider."
chat_id = __context__.get("chat_id", "default")
client = await _get_cdp_session(chat_id)
png_bytes = await client.screenshot()
# Save to workspace
workspace = __context__.get("workspace", ".")
screenshots_dir = Path(workspace) / ".cptr" / "screenshots"
screenshots_dir.mkdir(parents=True, exist_ok=True)
import time
filename = f"screenshot_{int(time.time())}.png"
filepath = screenshots_dir / filename
filepath.write_bytes(png_bytes)
return f"Screenshot saved: {filepath}"
async def browser_evaluate(javascript: str, *, __context__: dict) -> str:
"""Execute JavaScript in the browser page and return the result.
:param javascript: The JavaScript expression to evaluate.
"""
cfg = await _get_browser_config()
if cfg.get("provider", "local") != "local":
return "Error: browser_evaluate requires Local CDP provider."
chat_id = __context__.get("chat_id", "default")
client = await _get_cdp_session(chat_id)
return await client.evaluate(javascript)
async def image_generate(
prompt: str,
image: Optional[str] = None,
images: Optional[list[str]] = None,
size: Optional[str] = None,
n: int = 1,
background: Optional[str] = None,
*,
__context__: dict,
) -> str:
"""Generate or edit image files from a prompt.
:param prompt: Detailed description of the image to create or the edits to make.
:param image: Optional source image file id, /api/files/... URL, or workspace path for edit mode.
:param images: Optional source image file ids, /api/files/... URLs, or workspace paths for edit mode.
:param size: Optional image size, such as 1024x1024.
:param n: Number of images to create, from 1 to 4.
:param background: Optional background setting supported by the image provider.
"""
image_refs: list[str] = []
if image:
image_refs.append(image)
if images:
image_refs.extend(images)
if image_refs:
from cptr.utils.images import edit_images
results = await edit_images(
prompt,
image_refs,
user_id=__context__.get("user_id"),
size=size,
n=n,
background=background,
workspace=__context__.get("workspace"),
)
kind = "edit"
else:
from cptr.utils.images import generate_images
results = await generate_images(
prompt,
user_id=__context__.get("user_id"),
size=size,
n=n,
workspace=__context__.get("workspace"),
)
kind = "generation"
return json.dumps(
{
"status": "success",
"kind": kind,
"images": [result.as_dict() for result in results],
},
ensure_ascii=False,
)
# ── Registry ────────────────────────────────────────────────
TOOLS: dict[str, dict] = {
# Read-only (auto-approve)
"read_file": {"fn": read_file, "auto": True},
"list_directory": {"fn": list_directory, "auto": True},
"search_files": {"fn": search_files, "auto": True},
"check_task": {"fn": check_task, "auto": True},
"web_search": {"fn": web_search, "auto": True},
"read_url": {"fn": read_url, "auto": True},
"list_automations": {"fn": list_automations, "auto": True},
"view_skill": {"fn": view_skill, "auto": True},
# Write / mutate (require approval unless auto_approve_all)
"create_file": {"fn": create_file, "auto": False},
"edit_file": {"fn": edit_file, "auto": False},
"multi_edit_file": {"fn": multi_edit_file, "auto": False},
"write_file": {"fn": write_file, "auto": False},
"run_command": {"fn": run_command, "auto": False},
"send_input": {"fn": send_input, "auto": False},
"kill_task": {"fn": kill_task, "auto": False},
"create_automation": {"fn": create_automation, "auto": False},
"update_automation": {"fn": update_automation, "auto": False},
"toggle_automation": {"fn": toggle_automation, "auto": False},
"delete_automation": {"fn": delete_automation, "auto": False},
"image_generate": {"fn": image_generate, "auto": False},
}
# Browser tools — conditionally included in schemas based on browser.enabled
BROWSER_TOOLS: dict[str, dict] = {
"browser_navigate": {"fn": browser_navigate, "auto": False},
"browser_snapshot": {"fn": browser_snapshot, "auto": True},
"browser_click": {"fn": browser_click, "auto": False},
"browser_type": {"fn": browser_type, "auto": False},
"browser_screenshot": {"fn": browser_screenshot, "auto": True},
"browser_evaluate": {"fn": browser_evaluate, "auto": False},
}
# ── Sub-agent ───────────────────────────────────────────────
_DEFAULT_SUBAGENT_SYSTEM = """You are a sub-agent working on a specific task assigned by the lead agent.
You have full access to the workspace — you can read, write, edit files, and run commands.
Focus exclusively on your assigned task. Do NOT work on anything outside your scope.
When done, end with a clear summary:
- What you did
- What files you changed (if any)
- Any issues or open questions
"""
_subagent_semaphore: asyncio.Semaphore | None = None
async def _get_subagent_config() -> dict:
"""Load sub-agent settings from config with defaults."""
from cptr.models import Config
return {
"max_concurrent": int(await Config.get("subagents.max_concurrent") or 3),
"background_enabled": (await Config.get("subagents.background_enabled"))
in (True, "true", "1"),
"max_async": int(await Config.get("subagents.max_async") or 3),
"max_iterations": int(await Config.get("subagents.max_iterations") or 30),
"max_output": int(await Config.get("subagents.max_output") or 30_000),
"system_prompt": (await Config.get("subagents.system_prompt"))
or _DEFAULT_SUBAGENT_SYSTEM,
}
def _truncate_output(text: str, max_chars: int) -> str:
"""Truncate text to max_chars, appending a note if truncated."""
if len(text) <= max_chars:
return text
return text[:max_chars] + "\n\n[output truncated]"
async def delegate_task(
task: str,
context: str = "",
background: bool = False,
*,
__context__: dict,
) -> str:
"""Delegate a task to a sub-agent. Use background=true for long-running independent work.
:param task: What the sub-agent should do.
:param context: Optional context (e.g. relevant file paths, decisions made so far).
:param background: Return a handle immediately and inject the final result into this chat when done.
"""
global _subagent_semaphore
config = await _get_subagent_config()
if background:
if not config["background_enabled"]:
return "Error: background sub-agents are disabled in settings."
from cptr.utils.async_subagents import (
attach_subagent_chat,
fail_reserved_subagent,
reserve_async_subagent,
start_async_subagent,
)
reserve = await reserve_async_subagent(
config["max_async"],
task=task,
context=context,
workspace=__context__["workspace"],
user_id=__context__["user_id"],
parent_chat_id=__context__["chat_id"],
parent_message_id=__context__.get("message_id"),
connection=__context__["connection"],
model=__context__["model_id"],
model_id=__context__.get("full_model_id") or __context__["model_id"],
)
if reserve.get("status") == "rejected":
return f"Error: {reserve['error']}"
delegation_id = reserve["delegation_id"]
try:
chat, assistant_msg = await _create_subagent_chat(
task=task,
context=context,
workspace=__context__["workspace"],
model=__context__["model_id"],
user_id=__context__["user_id"],
parent_chat_id=__context__["chat_id"],
config=config,
delegation_id=delegation_id,
)
except Exception as e:
await fail_reserved_subagent(delegation_id, str(e))
return f"Error: failed to create background sub-agent: {e}"
await attach_subagent_chat(
delegation_id,
subagent_chat_id=chat.id,
subagent_message_id=assistant_msg.id,
)
async def _runner() -> str:
return await _run_existing_subagent_chat(
assistant_msg_id=assistant_msg.id,
chat_id=chat.id,
workspace=__context__["workspace"],
connection=__context__["connection"],
model=__context__["model_id"],
user_id=__context__["user_id"],
config=config,
)
await start_async_subagent(delegation_id, _runner)
return json.dumps(
{
"status": "dispatched",
"delegation_id": delegation_id,
"subagent_chat_id": chat.id,
"mode": "background",
"task": task,
}
)
if _subagent_semaphore is None:
_subagent_semaphore = asyncio.Semaphore(config["max_concurrent"])
async with _subagent_semaphore:
return await _run_subagent_chat(
task=task,
context=context,
workspace=__context__["workspace"],
connection=__context__["connection"],
model=__context__["model_id"],
user_id=__context__["user_id"],
parent_chat_id=__context__["chat_id"],
config=config,
)
async def _create_subagent_chat(
task: str,
context: str,
workspace: str,
model: str,
user_id: str,
parent_chat_id: str,
config: dict,
delegation_id: str | None = None,
):
"""Create the real chat/messages used by a sub-agent."""
from cptr.models import Chat, ChatMessage
from cptr.utils.chat_export import export_chat_to_file
from cptr.utils.config import now_ms
user_content = f"{task}\n\n## Context\n{context}" if context else task
meta = {
"workspace": workspace,
"subagent": True,
"parent_chat_id": parent_chat_id,
"params": {
"tool_approval_mode": "full", # auto-approve all tools
},
}
if delegation_id:
meta["delegation_id"] = delegation_id
chat = await Chat.create(
user_id=user_id,
title=f"Sub-agent: {task[:60]}",
meta=meta,
created_at=now_ms(),
)
user_msg = await ChatMessage.create(
chat_id=chat.id,
role="user",
content=user_content,
created_at=now_ms(),
)
assistant_msg = await ChatMessage.create(
chat_id=chat.id,
role="assistant",
content="",
parent_id=user_msg.id,
model=model,
done=False,
created_at=now_ms(),
)
await Chat.update_current_message(chat.id, assistant_msg.id, now_ms())
await export_chat_to_file(chat.id)
return chat, assistant_msg
async def _run_existing_subagent_chat(
assistant_msg_id: str,
chat_id: str,
workspace: str,
connection: dict,
model: str,
user_id: str,
config: dict,
) -> str:
"""Run the agent loop for an already-created sub-agent chat."""
from cptr.models import ChatMessage
from cptr.utils.chat_task import run_chat_task
await run_chat_task(
message_id=assistant_msg_id,
chat_id=chat_id,
user_id=user_id,
connection=connection,
workspace=workspace,
model=model,
)
result_msg = await ChatMessage.get_by_id(assistant_msg_id)
output = result_msg.content if result_msg else "Sub-agent produced no output."
return _truncate_output(output, config["max_output"])
async def _run_subagent_chat(
task: str,
context: str,
workspace: str,
connection: dict,
model: str,
user_id: str,
parent_chat_id: str,
config: dict,
) -> str:
"""Create a real chat and run the agent loop on it."""
chat, assistant_msg = await _create_subagent_chat(
task=task,
context=context,
workspace=workspace,
model=model,
user_id=user_id,
parent_chat_id=parent_chat_id,
config=config,
)
return await _run_existing_subagent_chat(
assistant_msg_id=assistant_msg.id,
chat_id=chat.id,
workspace=workspace,
connection=connection,
model=model,
user_id=user_id,
config=config,
)
SUBAGENT_TOOLS: dict[str, dict] = {
"delegate_task": {"fn": delegate_task, "auto": True},
}
# Combined lookup for execution and approval (always available regardless of config)
ALL_TOOLS: dict[str, dict] = {**TOOLS, **BROWSER_TOOLS, **SUBAGENT_TOOLS}
# ── External tool servers ───────────────────────────────────
_tool_server_cache: dict | None = None # {"servers": [...], "tools": {name: {server, spec}}}
async def _load_tool_servers() -> dict:
"""Load and cache external tool server config + specs.
Returns a dict with 'servers' (raw config list) and 'tools' mapping
prefixed tool names to {server, spec, type}.
"""
global _tool_server_cache
if _tool_server_cache is not None:
return _tool_server_cache
from cptr.models import Config
servers = await Config.get("tool_servers") or []
tools: dict[str, dict] = {}
for server in servers:
if not server.get("enabled", True):
continue
server_id = server.get("id", "")
server_type = server.get("type", "openapi")
try:
if server_type == "openapi":
from cptr.utils.openapi import fetch_openapi_spec, convert_openapi_to_tool_specs
url = server.get("url", "").rstrip("/")
path = server.get("path", "openapi.json")
if path.startswith("http"):
spec_url = path
else:
spec_url = f"{url}/{path.lstrip('/')}"
headers = _build_server_headers(server)
openapi_spec = await fetch_openapi_spec(spec_url, headers)
server["_openapi_spec"] = openapi_spec
for spec in convert_openapi_to_tool_specs(openapi_spec):
prefixed = f"{server_id}_{spec['name']}"
tools[prefixed] = {
"server": server,
"spec": {**spec, "name": prefixed},
"original_name": spec["name"],
"type": "openapi",
}
elif server_type == "mcp":
from cptr.utils.mcp.client import MCPClient
client = MCPClient()
headers = _build_server_headers(server)
await client.connect(server.get("url", ""), headers)
for spec in await client.list_tool_specs():
prefixed = f"{server_id}_{spec['name']}"
tools[prefixed] = {
"server": server,
"spec": {**spec, "name": prefixed},
"original_name": spec["name"],
"type": "mcp",
}
await client.disconnect()
elif server_type == "mcp_stdio":
from cptr.utils.mcp.stdio_manager import stdio_manager
command = server.get("command", "")
args = server.get("args", [])
env = server.get("env")
cwd = server.get("cwd")
if not command:
continue
client = await stdio_manager.get_client(
server_id, command, args, env, cwd
)
for spec in await client.list_tool_specs():
prefixed = f"{server_id}_{spec['name']}"
tools[prefixed] = {
"server": server,
"spec": {**spec, "name": prefixed},
"original_name": spec["name"],
"type": "mcp_stdio",
}
# Don't disconnect — keep process alive
except Exception:
import logging
logging.getLogger(__name__).warning(
"Failed to load tool server '%s'", server_id, exc_info=True
)
_tool_server_cache = {"servers": servers, "tools": tools}
return _tool_server_cache
def invalidate_tool_server_cache() -> None:
"""Clear the external tool server cache, forcing a reload on next access.
Also disconnects all stdio MCP processes so they can be re-spawned
with potentially updated configuration.
"""
global _tool_server_cache
_tool_server_cache = None
# Disconnect stdio servers that may have been reconfigured/removed
try:
from cptr.utils.mcp.stdio_manager import stdio_manager
import asyncio
loop = asyncio.get_event_loop()
if loop.is_running():
asyncio.ensure_future(stdio_manager.disconnect_all())
else:
loop.run_until_complete(stdio_manager.disconnect_all())
except Exception:
pass
def _build_server_headers(server: dict) -> dict | None:
"""Build auth + custom headers for a tool server connection."""
headers = dict(server.get("headers") or {})
auth_type = server.get("auth_type", "bearer")
if auth_type == "bearer":
key = server.get("key", "")
if key:
headers["Authorization"] = f"Bearer {key}"
return headers or None
def _extract_mcp_result(result: list) -> str:
"""Extract text from MCP tool result content items."""
texts = []
for item in result:
if isinstance(item, dict):
if item.get("type") == "text":
texts.append(item.get("text", ""))
else:
texts.append(json.dumps(item))
return "\n".join(texts) if texts else "(no output)"
async def _execute_external_tool(name: str, args: dict) -> str:
"""Execute an external tool by its prefixed name ({server_id}_{tool_name})."""
cache = await _load_tool_servers()
tool_info = cache["tools"].get(name)
if not tool_info:
return f"Error: external tool '{name}' not found"
server = tool_info["server"]
original_name = tool_info["original_name"]
tool_type = tool_info["type"]
headers = _build_server_headers(server)
try:
if tool_type == "mcp":
from cptr.utils.mcp.client import MCPClient
client = MCPClient()
await client.connect(server.get("url", ""), headers)
try:
result = await client.call_tool(original_name, args)
return _extract_mcp_result(result)
finally:
await client.disconnect()
elif tool_type == "mcp_stdio":
from cptr.utils.mcp.stdio_manager import stdio_manager
client = await stdio_manager.get_client(
server.get("id", ""),
server.get("command", ""),
server.get("args", []),
server.get("env"),
server.get("cwd"),
)
result = await client.call_tool(original_name, args)
return _extract_mcp_result(result)
elif tool_type == "openapi":
from cptr.utils.openapi import execute_openapi_tool
openapi_spec = server.get("_openapi_spec", {})
return await execute_openapi_tool(
server_url=server.get("url", "").rstrip("/"),
openapi_spec=openapi_spec,
tool_name=original_name,
args=args,
headers=headers,
)
else:
return f"Error: unknown tool server type: {tool_type}"
except Exception as e:
return f"Error executing external tool '{name}': {e}"
# ── Schema from function signature ──────────────────────────
_TYPE_MAP = {str: "string", int: "integer", bool: "boolean", float: "number"}
def _unwrap_optional(hint):
"""If hint is Optional[X] (Union[X, None]), return X."""
args = getattr(hint, '__args__', None)
if args and type(None) in args:
real = [a for a in args if a is not type(None)]
if len(real) == 1:
return real[0]
return hint
def _schema_for_type(hint) -> dict:
origin = get_origin(hint)
if origin is list:
args = get_args(hint)
item_hint = _unwrap_optional(args[0]) if args else str
return {
"type": "array",
"items": _schema_for_type(item_hint),
}
return {"type": _TYPE_MAP.get(hint, "string")} # type: ignore[arg-type]
def _parse_param_descriptions(docstring: str) -> dict[str, str]:
"""Extract :param name: description lines from docstring."""
descs: dict[str, str] = {}
if not docstring:
return descs
for line in docstring.splitlines():
line = line.strip()
if line.startswith(":param "):
rest = line[7:]
if ":" in rest:
name, desc = rest.split(":", 1)
descs[name.strip()] = desc.strip()
return descs
def _fn_to_schema(name: str, fn) -> dict:
"""Introspect function → {name, description, parameters} for LLM."""
doc = inspect.getdoc(fn) or ""
description = doc.split("\n")[0]
param_descs = _parse_param_descriptions(doc)
hints = get_type_hints(fn)
sig = inspect.signature(fn)
properties: dict[str, dict] = {}
required: list[str] = []
for pname, param in sig.parameters.items():
# Skip injected context params (keyword-only, never exposed to LLM)
if param.kind == inspect.Parameter.KEYWORD_ONLY:
continue
raw_hint = hints.get(pname)
hint = _unwrap_optional(raw_hint) if raw_hint else raw_hint
prop: dict = _schema_for_type(hint)
if pname in param_descs:
prop["description"] = param_descs[pname]
if param.default is not inspect.Parameter.empty:
prop["default"] = param.default
properties[pname] = prop
# Positional with no default → required
if param.default is inspect.Parameter.empty:
required.append(pname)
return {
"name": name,
"description": description,
"parameters": {
"type": "object",
"properties": properties,
"required": required,
},
}
def _without_background_param(schema: dict) -> dict:
"""Return a delegate_task schema copy without the background option."""
if schema.get("name") != "delegate_task":
return schema
schema = {
**schema,
"parameters": {
**schema.get("parameters", {}),
"properties": dict(schema.get("parameters", {}).get("properties", {})),
},
}
schema["parameters"]["properties"].pop("background", None)
required = schema["parameters"].get("required")
if isinstance(required, list):
schema["parameters"]["required"] = [r for r in required if r != "background"]
return schema
async def get_tool_list() -> list[dict]:
"""Return tool schemas for the LLM.
Automatically includes browser tools when browser.enabled is true,
and external tool server tools when configured.
"""
tools = dict(TOOLS)
background_subagents_enabled = False
try:
from cptr.models import Config
if (await Config.get("browser.enabled")) in (True, "true", "1"):
tools.update(BROWSER_TOOLS)
if (await Config.get("subagents.enabled")) in (True, "true", "1"):
tools.update(SUBAGENT_TOOLS)
background_subagents_enabled = (await Config.get("subagents.background_enabled")) in (
True,
"true",
"1",
)
images_generation_enabled = (await Config.get("images.generation_enabled")) in (
True,
"true",
"1",
)
images_edit_enabled = (await Config.get("images.edit_enabled")) in (True, "true", "1")
if not (images_generation_enabled or images_edit_enabled):
tools.pop("image_generate", None)
except Exception:
tools.pop("image_generate", None)
pass
schemas = [_fn_to_schema(name, t["fn"]) for name, t in tools.items()]
if not background_subagents_enabled:
schemas = [_without_background_param(s) for s in schemas]
# Add external tool server schemas
try:
cache = await _load_tool_servers()
for tool_info in cache["tools"].values():
schemas.append(tool_info["spec"])
except Exception:
pass
return schemas
async def execute_tool(name: str, args: dict, __context__: dict) -> str:
"""Execute a tool by name, injecting execution context."""
info = ALL_TOOLS.get(name)
if info:
fn = info["fn"]
try:
sig = inspect.signature(fn)
if "__context__" in sig.parameters:
return await fn(**args, __context__=__context__)
else:
# Legacy tools: inject workspace directly
return await fn(**args, workspace=__context__["workspace"])
except Exception as e:
return f"Error executing {name}: {e}"
# Check external tool servers
cache = await _load_tool_servers()
if name in cache["tools"]:
return await _execute_external_tool(name, args)
return f"Error: unknown tool: {name}"