krnl-code 1.0.4__py3-none-any.whl

krnl_agent/teams.py

@@ -0,0 +1,38 @@
+"""Multi-agent teams — a coordinator that delegates to specialist sub-agents,
+with team state that persists across sessions.
+
+A team is a named, persistent coordinator session (`team-<name>`). The
+coordinator breaks work into subtasks and delegates each to a specialist via
+`spawn_agent`; progress is tracked with `todo_write`. Because the team is a
+persisted session, you can stop and resume later:
+
+    krnl-agent --team-name auth-sprint "Plan and implement auth with tests"
+    krnl-agent --team-name auth-sprint            # resume the team
+"""
+from __future__ import annotations
+
+import re
+
+from . import sessions
+
+TEAM_PREFIX = "team-"
+
+
+def team_id(name: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9_-]+", "-", name).strip("-").lower() or "team"
+    return TEAM_PREFIX + slug
+
+
+def list_teams() -> list[dict]:
+    return [s for s in sessions.list_sessions() if str(s.get("id", "")).startswith(TEAM_PREFIX)]
+
+
+def coordinator_prompt(name: str) -> str:
+    return (
+        f"\n\n# Team mode — you are the COORDINATOR of team '{name}'.\n"
+        "Plan the work, then DELEGATE each independent subtask to a specialist via "
+        "`spawn_agent` (give each a focused role and a complete prompt). Track the "
+        "plan with `todo_write` (one item in_progress at a time). Run specialists in "
+        "parallel where possible, integrate their results, and verify the whole. "
+        "Team state persists, so summarize progress clearly for future sessions."
+    )

krnl_agent/tool_schemas.py

@@ -0,0 +1,431 @@
+"""OpenAI-style tool (function) schemas exposed to the model.
+
+These map 1:1 to the implementations in `tools.py`. Tools whose name appears in
+`MUTATING_TOOLS` go through the approval gate before they execute.
+"""
+from __future__ import annotations
+
+MUTATING_TOOLS = {
+    "write_file",
+    "edit_file",
+    "multi_edit",
+    "create_file",
+    "delete_file",
+    "run_command",
+    "bash_background",
+    "git_commit",
+    "worktree_add",
+    "worktree_remove",
+    "git_branch",
+    "git_push",
+    "open_pr",
+    "deploy",
+    "rollback",
+    "provision_db",
+}
+
+
+def _fn(name: str, description: str, properties: dict, required: list[str]) -> dict:
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
+        },
+    }
+
+
+TOOL_SCHEMAS = [
+    _fn(
+        "list_files",
+        "List files in the workspace (recursive, ignores configured paths). "
+        "Use to understand project structure.",
+        {
+            "path": {
+                "type": "string",
+                "description": "Directory relative to workspace root. Default '.'.",
+            }
+        },
+        [],
+    ),
+    _fn(
+        "read_file",
+        "Read a UTF-8 text file from the workspace. Optionally a line range.",
+        {
+            "path": {"type": "string", "description": "File path relative to root."},
+            "start_line": {"type": "integer", "description": "1-based start (optional)."},
+            "end_line": {"type": "integer", "description": "Inclusive end (optional)."},
+        },
+        ["path"],
+    ),
+    _fn(
+        "search_text",
+        "Search file contents across the workspace (ripgrep if available, else "
+        "a pure-Python fallback). Returns matching path:line: text rows.",
+        {
+            "query": {"type": "string", "description": "Substring or regex to find."},
+            "glob": {
+                "type": "string",
+                "description": "Optional file glob filter, e.g. '*.py'.",
+            },
+        },
+        ["query"],
+    ),
+    _fn(
+        "write_file",
+        "Create a new file or fully overwrite an existing one with `content`. "
+        "Requires user approval. Prefer edit_file for changing existing files.",
+        {
+            "path": {"type": "string"},
+            "content": {"type": "string", "description": "Full file contents."},
+        },
+        ["path", "content"],
+    ),
+    _fn(
+        "edit_file",
+        "Make a surgical edit by replacing an exact substring. `old_string` must "
+        "match the current file EXACTLY (incl. whitespace) and uniquely. Requires "
+        "user approval.",
+        {
+            "path": {"type": "string"},
+            "old_string": {"type": "string", "description": "Exact text to replace."},
+            "new_string": {"type": "string", "description": "Replacement text."},
+            "replace_all": {
+                "type": "boolean",
+                "description": "Replace every occurrence (default false).",
+            },
+        },
+        ["path", "old_string", "new_string"],
+    ),
+    _fn(
+        "create_file",
+        "Create a new file with `content`. Fails if it already exists. Requires "
+        "user approval.",
+        {"path": {"type": "string"}, "content": {"type": "string"}},
+        ["path", "content"],
+    ),
+    _fn(
+        "delete_file",
+        "Delete a file from the workspace. Requires user approval.",
+        {"path": {"type": "string"}},
+        ["path"],
+    ),
+    _fn(
+        "run_command",
+        "Run a shell command in the workspace root (e.g. run tests, a script, a "
+        "build). Requires user approval. Has a timeout; not for long-running "
+        "servers — use bash_background for those.",
+        {"command": {"type": "string", "description": "The shell command to run."}},
+        ["command"],
+    ),
+    _fn(
+        "glob",
+        "Find files by glob pattern (supports ** for recursion), e.g. 'src/**/*.ts'.",
+        {
+            "pattern": {"type": "string", "description": "Glob pattern."},
+            "path": {"type": "string", "description": "Base dir relative to root (default '.')."},
+        },
+        ["pattern"],
+    ),
+    _fn(
+        "repo_map",
+        "Get a compact symbol/outline map of the codebase (per-file classes, "
+        "functions, methods with line numbers). Read this FIRST to locate code "
+        "cheaply, then read_file only the ranges you need — saves tokens vs reading "
+        "whole files.",
+        {
+            "path": {"type": "string", "description": "Sub-path to map (default '.')."},
+            "lang": {"type": "string", "description": "Optional language filter: py|ts|js|go|rs|java|rb."},
+        },
+        [],
+    ),
+    _fn(
+        "secret_scan",
+        "Scan the workspace for hard-coded secrets/credentials (API keys, tokens, "
+        "private keys, connection strings). Returns masked path:line findings.",
+        {"path": {"type": "string", "description": "Sub-path to scan (default '.')."}},
+        [],
+    ),
+    _fn(
+        "dependency_audit",
+        "Audit project dependencies for known vulnerabilities using the ecosystem's "
+        "tool (pip-audit / npm audit / cargo audit / govulncheck) when installed.",
+        {},
+        [],
+    ),
+    _fn(
+        "deploy_check",
+        "List deployment targets (Cloud Run, Cloudflare, Vercel, Netlify, Fly, "
+        "Railway, Render, Docker, Kubernetes/Helm, AWS, Azure, + Neon/Supabase DBs) "
+        "and which are READY (CLI installed + credential env var set). Call this "
+        "FIRST before deploying to pick a target.",
+        {},
+        [],
+    ),
+    _fn(
+        "deploy",
+        "Deploy the current project to a target (e.g. 'cloudrun', 'cloudflare', "
+        "'vercel', 'fly', 'render'). Free-tier targets run directly; billable targets "
+        "are gated by the spend policy and need approval. `params` fills command "
+        "placeholders like {service},{region},{app},{dist}. Requires approval.",
+        {
+            "target": {"type": "string", "description": "Target name from deploy_check."},
+            "params": {"type": "object", "description": "Placeholder values for the deploy command."},
+        },
+        ["target"],
+    ),
+    _fn(
+        "rollback",
+        "Roll a deployment target back to its previous known-good release "
+        "(safe — only reverts state). Requires approval.",
+        {
+            "target": {"type": "string"},
+            "params": {"type": "object", "description": "e.g. {revision},{version},{deployment}."},
+        },
+        ["target"],
+    ),
+    _fn(
+        "provision_db",
+        "Provision a managed database before deploying the app: 'neon' (serverless "
+        "Postgres) or 'supabase' (full backend). Requires approval.",
+        {
+            "provider": {"type": "string", "description": "'neon' or 'supabase'."},
+            "params": {"type": "object"},
+        },
+        ["provider"],
+    ),
+    _fn(
+        "monitor_status",
+        "Report configured monitoring providers (Sentry/OpenTelemetry/Datadog/uptime) "
+        "and current unresolved error / uptime status for the deployed app.",
+        {},
+        [],
+    ),
+    _fn(
+        "health_check",
+        "Check a deployed app's health endpoint by URL. Returns healthy/unhealthy.",
+        {
+            "url": {"type": "string", "description": "Base URL of the deployed app."},
+            "path": {"type": "string", "description": "Health path (default /health)."},
+        },
+        ["url"],
+    ),
+    _fn(
+        "multi_edit",
+        "Apply several exact search/replace edits to ONE file atomically (all or "
+        "nothing). Each edit needs old_string (exact, unique unless replace_all) "
+        "and new_string. Requires approval.",
+        {
+            "path": {"type": "string"},
+            "edits": {
+                "type": "array",
+                "description": "List of edits applied in order.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "old_string": {"type": "string"},
+                        "new_string": {"type": "string"},
+                        "replace_all": {"type": "boolean"},
+                    },
+                    "required": ["old_string", "new_string"],
+                },
+            },
+        },
+        ["path", "edits"],
+    ),
+    _fn(
+        "web_search",
+        "Search the web for up-to-date information. Returns titles, URLs, snippets.",
+        {"query": {"type": "string"}},
+        ["query"],
+    ),
+    _fn(
+        "web_fetch",
+        "Fetch a URL and return its readable text content.",
+        {"url": {"type": "string"}},
+        ["url"],
+    ),
+    _fn(
+        "bash_background",
+        "Start a long-running command (dev server, watcher) in the background and "
+        "return immediately with a process id. Requires approval. Poll with "
+        "process_output, stop with process_kill.",
+        {"command": {"type": "string"}},
+        ["command"],
+    ),
+    _fn(
+        "process_output",
+        "Read recent output from a background process started with bash_background.",
+        {"id": {"type": "string"}, "tail": {"type": "integer", "description": "Lines (default 100)."}},
+        ["id"],
+    ),
+    _fn(
+        "process_kill",
+        "Stop a background process by id.",
+        {"id": {"type": "string"}},
+        ["id"],
+    ),
+    _fn("process_list", "List background processes and their status.", {}, []),
+    _fn("git_status", "Show 'git status --short --branch' for the workspace.", {}, []),
+    _fn(
+        "git_diff",
+        "Show 'git diff', optionally for one path.",
+        {"path": {"type": "string", "description": "Optional path to diff."}},
+        [],
+    ),
+    _fn(
+        "git_commit",
+        "Stage all changes and create a git commit. Requires approval.",
+        {
+            "message": {"type": "string", "description": "Commit message."},
+            "all": {"type": "boolean", "description": "git add -A first (default true)."},
+        },
+        ["message"],
+    ),
+    _fn(
+        "todo_write",
+        "Create or update the visible task checklist for a multi-step job. Pass the "
+        "FULL list each time. Mark exactly one item in_progress while working it.",
+        {
+            "todos": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "content": {"type": "string"},
+                        "status": {
+                            "type": "string",
+                            "enum": ["pending", "in_progress", "completed"],
+                        },
+                    },
+                    "required": ["content", "status"],
+                },
+            }
+        },
+        ["todos"],
+    ),
+    _fn(
+        "spawn_agent",
+        "Delegate a focused sub-task to a fresh sub-agent with its own context. Use "
+        "for independent investigations or parallelizable work. Returns the "
+        "sub-agent's final summary. The sub-agent can read/search/edit/run like you.",
+        {
+            "description": {"type": "string", "description": "Short label for the sub-task."},
+            "prompt": {"type": "string", "description": "Full instructions for the sub-agent."},
+        },
+        ["description", "prompt"],
+    ),
+    _fn(
+        "use_skill",
+        "Load the full instructions for one of the available SKILLS by name (see the "
+        "skills list in your system prompt). Call this before doing the skill's task.",
+        {"name": {"type": "string", "description": "The skill name to load."}},
+        ["name"],
+    ),
+    _fn(
+        "worktree_add",
+        "Create an isolated git worktree (a separate working copy) to make changes "
+        "safely without touching the main tree. Requires approval.",
+        {
+            "name": {"type": "string", "description": "Worktree name."},
+            "branch": {"type": "string", "description": "Optional new branch name."},
+        },
+        ["name"],
+    ),
+    _fn("worktree_list", "List git worktrees.", {}, []),
+    _fn(
+        "worktree_remove",
+        "Remove a git worktree created with worktree_add. Requires approval.",
+        {"name": {"type": "string"}},
+        ["name"],
+    ),
+    _fn(
+        "git_branch",
+        "Create and switch to a new git branch. Requires approval.",
+        {"name": {"type": "string"}},
+        ["name"],
+    ),
+    _fn(
+        "git_push",
+        "Push the current branch to origin (sets upstream). Requires approval.",
+        {"branch": {"type": "string", "description": "Branch (default current HEAD)."}},
+        [],
+    ),
+    _fn(
+        "open_pr",
+        "Open a GitHub pull request for the current branch via the gh CLI. Requires approval.",
+        {"title": {"type": "string"}, "body": {"type": "string"}},
+        ["title"],
+    ),
+    _fn(
+        "memory_write",
+        "Record a persistent fact, decision, error, or solution in the session memory. "
+        "Use this to remember key architectural decisions, facts, or resolutions.",
+        {
+            "type": {
+                "type": "string",
+                "enum": ["fact", "decision", "error", "solution"],
+                "description": "The type of memory entry.",
+            },
+            "content": {
+                "type": "string",
+                "description": "The detailed fact/decision/error/solution content.",
+            },
+            "related_files": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of related files (relative to workspace root).",
+            },
+        },
+        ["type", "content"],
+    ),
+]
+
+# Tools handled directly by the loop (not in tools.TOOL_FUNCS).
+LOOP_TOOLS = {"todo_write", "spawn_agent", "update_plan", "use_skill", "memory_write"}
+
+# In plan mode only these (read-only + planning) are offered.
+PLAN_MODE_TOOLS = {
+    "list_files",
+    "read_file",
+    "search_text",
+    "glob",
+    "repo_map",
+    "secret_scan",
+    "dependency_audit",
+    "deploy_check",
+    "monitor_status",
+    "health_check",
+    "web_search",
+    "web_fetch",
+    "process_list",
+    "git_status",
+    "git_diff",
+    "update_plan",
+    "todo_write",
+    "use_skill",
+    "memory_write",
+}
+
+
+def schemas_for(plan_mode: bool = False, extra: list | None = None) -> list:
+    """Return the tool schemas to advertise this turn."""
+    base = TOOL_SCHEMAS
+    if plan_mode:
+        base = [t for t in base if t["function"]["name"] in PLAN_MODE_TOOLS]
+        base = base + [_PLAN_SCHEMA]
+    return base + (extra or [])
+
+
+_PLAN_SCHEMA = _fn(
+    "update_plan",
+    "Present your implementation plan for the user to approve before you make any "
+    "changes. Call this when you've finished researching in plan mode.",
+    {"plan": {"type": "string", "description": "The plan as markdown."}},
+    ["plan"],
+)