@openlucaskaka/kagent 0.1.7

package/src/kagent/runtime/tools.py

@@ -0,0 +1,3532 @@
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import os
+import re
+import socket
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Dict
+
+from kagent.integrations.memory import MilvusLongTermMemory, RedisShortTermMemory
+from kagent.providers.embeddings import (
+    EmbeddingProviderConfig,
+    OpenAICompatibleEmbeddingProvider,
+)
+from kagent.runtime.file_transaction import capture_text_states, workspace_transaction
+from kagent.runtime.patch_checkpoints import (
+    PatchCheckpointStore,
+    commit_checkpointed_text_changes,
+)
+from kagent.runtime.policy import RuntimePolicy
+from kagent.runtime.redaction import redact_runtime_payload
+from kagent.runtime.sandbox import run_shell_sandboxed
+from kagent.runtime.skills import RuntimeSkillRegistry
+from kagent.runtime.task_state import TASK_EVENTS, TASK_STATES, TaskStateMachine
+from kagent.runtime.types import AgentObservation
+from kagent.runtime.workspace import VIRTUAL_WORKSPACE_KINDS, RuntimeWorkspace
+
+RuntimeToolHandler = Callable[[Dict[str, Any]], Dict[str, Any]]
+_ARTIFACT_KINDS = ("report", "plan", "decision", "data", "message")
+_ARTIFACT_FORMATS = ("markdown", "plain_text", "json")
+_TASK_STATUSES = ("pending", "in_progress", "blocked", "done", "failed")
+_TASK_PRIORITIES = ("low", "normal", "high")
+_SHORT_TEXT_MAX_LENGTH = 200
+_TASK_TITLE_MAX_LENGTH = 500
+_LONG_TEXT_MAX_LENGTH = 20000
+_TAGS_MAX_ITEMS = 20
+_DECISION_CRITERIA_MAX_ITEMS = 20
+_DECISION_OPTIONS_MAX_ITEMS = 50
+_RUBRIC_CRITERIA_MAX_ITEMS = 100
+_TASK_ITEMS_MAX_ITEMS = 200
+_RUBRIC_SEVERITIES = ("low", "normal", "blocking")
+_DELEGATE_GOAL_MAX_LENGTH = 4000
+_DELEGATE_MAX_ITERATIONS = 3
+_HTTP_REQUEST_MAX_BYTES = 65536
+_HTTP_REQUEST_TIMEOUT_SECONDS = 10.0
+_BLOCKED_HTTP_HOSTS = {"localhost", "localhost."}
+_HTTP_REDIRECT_STATUS_CODES = {301, 302, 303, 307, 308}
+_URL_SECRET_KEY_PARTS = (
+    "api_key",
+    "apikey",
+    "authorization",
+    "bearer",
+    "password",
+    "secret",
+    "token",
+)
+_URL_SECRET_VALUE_PATTERNS = (
+    re.compile(r"sk-[A-Za-z0-9:_-]{6,}"),
+    re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._:/+=-]{6,}"),
+)
+_APPLY_PATCH_MAX_BYTES = 20000
+_READ_FILE_MAX_BYTES = 65536
+_LIST_FILES_MAX_DEPTH = 5
+_LIST_FILES_MAX_ENTRIES = 500
+_SHELL_COMMAND_MAX_LENGTH = 2000
+_SHELL_COMMAND_MAX_OUTPUT_BYTES = 32768
+_SHELL_COMMAND_DEFAULT_TIMEOUT_SECONDS = 10.0
+_SHELL_COMMAND_MAX_TIMEOUT_SECONDS = 30.0
+_SHELL_BACKGROUND_PATTERN = re.compile(r"(?<!&)&(?!&)")
+_SHELL_INTERACTIVE_PATTERNS = (
+    re.compile(r"\bpython[0-9.]*\s+-i\b"),
+    re.compile(r"\b(ipython|node|ruby|irb)\b\s*$"),
+    re.compile(r"\b(read|vim|vi|nano|less|more|top|tail\s+-f)\b"),
+)
+_SHELL_DESTRUCTIVE_PATTERNS = (
+    re.compile(r"\brm\b(?=[^;&|]*-[A-Za-z]*r)(?=[^;&|]*-[A-Za-z]*f)"),
+    re.compile(r"\bsudo\b"),
+    re.compile(r"\b(?:chmod|chown|chgrp)\b(?=[^;&|]*\s-R\b)"),
+    re.compile(r"\bdd\s+if="),
+    re.compile(r"\b(?:mkfs|diskutil|shutdown|reboot|halt)\b"),
+)
+_SHELL_SECRET_EXPOSURE_PATTERNS = (
+    re.compile(r"^\s*(?:env|printenv|set|export)\b(?:\s|$)"),
+    re.compile(r"\b(?:cat|grep|awk|sed)\b[^;&|]*(?:^|[\s/\\])\.env(?:[\s.]|$)"),
+    re.compile(r"\b(?:cat|grep|awk|sed)\b[^;&|]*(?:secret|token|api[_-]?key)", re.I),
+)
+_SHELL_NETWORK_COMMAND_PATTERNS = (
+    re.compile(r"\b(?:curl|wget|ssh|scp|sftp|rsync|nc|netcat|telnet)\b"),
+)
+_SHELL_INLINE_NETWORK_CODE_PATTERNS = (
+    re.compile(
+        r"\bpython[0-9.]*\b[^;&|]*\s+-c\s+.+"
+        r"\b(?:socket|urllib|http\.client|requests|httpx|aiohttp)\b",
+        re.I,
+    ),
+    re.compile(
+        r"\bnode\b[^;&|]*\s+-e\s+.+"
+        r"(?:\bfetch\s*\(|require\s*\(\s*['\"](?:net|http|https|dgram)['\"]\s*\))",
+        re.I,
+    ),
+)
+_SHELL_PIPE_TO_SHELL_PATTERN = re.compile(
+    r"\|\s*(?:sh|bash|zsh|python[0-9.]*|node|ruby)\b"
+)
+_RUNTIME_WORKSPACE_DIR_ENV_VARS = (
+    "KAGENT_RUNTIME_WORKSPACE_DIR",
+    "KAGENT_SERVICE_RUNTIME_WORKSPACE_DIR",
+)
+_RUNTIME_SKILLS_DIR_ENV_VARS = (
+    "KAGENT_RUNTIME_SKILLS_DIR",
+    "KAGENT_SKILLS_DIR",
+)
+_REDIS_URL_ENV_VARS = ("KAGENT_REDIS_URL",)
+_MILVUS_URL_ENV_VARS = ("KAGENT_MILVUS_URL",)
+_EMBEDDING_BASE_URL_ENV_VARS = ("KAGENT_EMBEDDING_BASE_URL", "KAGENT_LLM_BASE_URL")
+_EMBEDDING_API_KEY_ENV_VARS = ("KAGENT_EMBEDDING_API_KEY", "KAGENT_LLM_API_KEY")
+_EMBEDDING_MODEL_ENV_VARS = ("KAGENT_EMBEDDING_MODEL",)
+_EMBEDDING_MAX_RETRIES_ENV_VAR = "KAGENT_EMBEDDING_MAX_RETRIES"
+_EMBEDDING_RETRY_BACKOFF_ENV_VAR = "KAGENT_EMBEDDING_RETRY_BACKOFF_SECONDS"
+_EXTERNAL_BACKEND_TIMEOUT_ENV_VAR = "KAGENT_EXTERNAL_BACKEND_TIMEOUT_SECONDS"
+_APP_NAME_MAX_LENGTH = 120
+_APP_NAME_ALLOWED_PATTERN = re.compile(r"^[\w .+()#&-]+$", re.UNICODE)
+_OPEN_COMMAND_TIMEOUT_SECONDS = 10.0
+
+
+@dataclass(frozen=True)
+class _PatchOperation:
+    operation: str
+    relative_path: str
+    destination_path: str = ""
+    content: str = ""
+    lines: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RuntimeToolSpec:
+    name: str
+    description: str
+    handler: RuntimeToolHandler
+    input_schema: Dict[str, Any] = field(default_factory=lambda: {"type": "object"})
+    output_schema: Dict[str, Any] = field(default_factory=lambda: {"type": "object"})
+    timeout_seconds: float = 30.0
+
+    def __post_init__(self) -> None:
+        if self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+
+
+_TEXT_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["text"],
+    "properties": {"text": {"type": "string"}},
+    "additionalProperties": False,
+}
+
+_ARTIFACT_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "artifact_id",
+        "title",
+        "kind",
+        "format",
+        "content",
+        "tags",
+        "bytes",
+    ],
+    "properties": {
+        "artifact_id": {"type": "string"},
+        "title": {"type": "string"},
+        "kind": {"type": "string", "enum": list(_ARTIFACT_KINDS)},
+        "format": {"type": "string", "enum": list(_ARTIFACT_FORMATS)},
+        "content": {"type": "string"},
+        "tags": {"type": "array", "items": {"type": "string"}},
+        "bytes": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_APPLY_PATCH_CHANGED_FILE_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["path", "operation", "bytes", "sha256"],
+    "properties": {
+        "path": {"type": "string"},
+        "previous_path": {"type": "string"},
+        "operation": {"type": "string", "enum": ["add", "update", "delete", "move"]},
+        "bytes": {"type": "number", "minimum": 0},
+        "sha256": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_APPLY_PATCH_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["changed_files", "file_count"],
+    "properties": {
+        "changed_files": {
+            "type": "array",
+            "items": _APPLY_PATCH_CHANGED_FILE_OUTPUT_SCHEMA,
+        },
+        "file_count": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_PATCH_HISTORY_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["checkpoints", "checkpoint_count"],
+    "properties": {
+        "checkpoints": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["checkpoint_id", "created_at", "file_count", "paths"],
+                "properties": {
+                    "checkpoint_id": {"type": "string"},
+                    "created_at": {"type": "string"},
+                    "file_count": {"type": "number", "minimum": 0},
+                    "paths": {"type": "array", "items": {"type": "string"}},
+                },
+                "additionalProperties": False,
+            },
+        },
+        "checkpoint_count": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_REVERT_PATCH_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "checkpoint_id",
+        "reverted_checkpoint_id",
+        "changed_files",
+        "file_count",
+    ],
+    "properties": {
+        "checkpoint_id": {"type": "string"},
+        "reverted_checkpoint_id": {"type": "string"},
+        "changed_files": {
+            "type": "array",
+            "items": _APPLY_PATCH_CHANGED_FILE_OUTPUT_SCHEMA,
+        },
+        "file_count": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_DECISION_CRITERION_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["name", "weight"],
+    "properties": {
+        "name": {"type": "string"},
+        "weight": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_DECISION_RANKING_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["rank", "name", "score", "scores", "rationale"],
+    "properties": {
+        "rank": {"type": "number", "minimum": 1},
+        "name": {"type": "string"},
+        "score": {"type": "number"},
+        "scores": {"type": "array", "items": {"type": "number"}},
+        "rationale": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_DECISION_MATRIX_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["question", "criteria", "rankings", "winner"],
+    "properties": {
+        "question": {"type": "string"},
+        "criteria": {
+            "type": "array",
+            "items": _DECISION_CRITERION_OUTPUT_SCHEMA,
+        },
+        "rankings": {
+            "type": "array",
+            "items": _DECISION_RANKING_OUTPUT_SCHEMA,
+        },
+        "winner": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_RUBRIC_CRITERION_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["name", "passed", "severity", "evidence"],
+    "properties": {
+        "name": {"type": "string"},
+        "passed": {"type": "boolean"},
+        "severity": {"type": "string", "enum": list(_RUBRIC_SEVERITIES)},
+        "evidence": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_RUBRIC_SCORE_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "criteria",
+        "passed",
+        "failed",
+        "total",
+        "score_percent",
+        "blocking_failures",
+        "failed_criteria",
+    ],
+    "properties": {
+        "criteria": {
+            "type": "array",
+            "items": _RUBRIC_CRITERION_OUTPUT_SCHEMA,
+        },
+        "passed": {"type": "number", "minimum": 0},
+        "failed": {"type": "number", "minimum": 0},
+        "total": {"type": "number", "minimum": 0},
+        "score_percent": {"type": "number", "minimum": 0, "maximum": 100},
+        "blocking_failures": {"type": "array", "items": {"type": "string"}},
+        "failed_criteria": {"type": "array", "items": {"type": "string"}},
+    },
+    "additionalProperties": False,
+}
+
+_TASK_ITEM_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["title", "status", "priority"],
+    "properties": {
+        "title": {"type": "string"},
+        "status": {"type": "string", "enum": list(_TASK_STATUSES)},
+        "priority": {"type": "string", "enum": list(_TASK_PRIORITIES)},
+        "owner": {"type": "string"},
+        "due": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_TASK_STATUS_COUNTS_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": list(_TASK_STATUSES),
+    "properties": {
+        "pending": {"type": "number", "minimum": 0},
+        "in_progress": {"type": "number", "minimum": 0},
+        "blocked": {"type": "number", "minimum": 0},
+        "done": {"type": "number", "minimum": 0},
+        "failed": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_TASK_LIST_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["items", "counts", "total"],
+    "properties": {
+        "items": {"type": "array", "items": _TASK_ITEM_OUTPUT_SCHEMA},
+        "counts": _TASK_STATUS_COUNTS_OUTPUT_SCHEMA,
+        "total": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_TASK_TRANSITION_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["previous_state", "event", "state"],
+    "properties": {
+        "previous_state": {"type": "string", "enum": list(TASK_STATES)},
+        "event": {"type": "string", "enum": list(TASK_EVENTS)},
+        "state": {"type": "string", "enum": list(TASK_STATES)},
+    },
+    "additionalProperties": False,
+}
+
+_HTTP_REQUEST_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "url",
+        "status_code",
+        "content_type",
+        "body_text",
+        "bytes",
+        "truncated",
+    ],
+    "properties": {
+        "url": {"type": "string"},
+        "status_code": {"type": "number", "minimum": 100, "maximum": 599},
+        "content_type": {"type": "string"},
+        "body_text": {"type": "string"},
+        "bytes": {"type": "number", "minimum": 0},
+        "truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_OPEN_URL_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["url", "opened", "application", "command"],
+    "properties": {
+        "url": {"type": "string"},
+        "opened": {"type": "boolean"},
+        "application": {"type": "string"},
+        "command": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_OPEN_APP_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["application", "opened", "command"],
+    "properties": {
+        "application": {"type": "string"},
+        "opened": {"type": "boolean"},
+        "command": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_READ_FILE_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["path", "content", "bytes", "truncated", "sha256"],
+    "properties": {
+        "path": {"type": "string"},
+        "content": {"type": "string"},
+        "bytes": {"type": "number", "minimum": 0},
+        "truncated": {"type": "boolean"},
+        "sha256": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_LIST_FILES_ENTRY_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["path", "type", "bytes"],
+    "properties": {
+        "path": {"type": "string"},
+        "type": {"type": "string", "enum": ["directory", "file"]},
+        "bytes": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_LIST_FILES_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["root", "entries", "file_count", "truncated"],
+    "properties": {
+        "root": {"type": "string"},
+        "entries": {"type": "array", "items": _LIST_FILES_ENTRY_OUTPUT_SCHEMA},
+        "file_count": {"type": "number", "minimum": 0},
+        "truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_ASSET_METADATA_SCHEMA = {
+    "type": "object",
+    "required": [
+        "kind",
+        "path",
+        "bytes",
+        "sha256",
+        "created_at",
+        "updated_at",
+        "metadata",
+    ],
+    "properties": {
+        "kind": {"type": "string", "enum": list(VIRTUAL_WORKSPACE_KINDS)},
+        "path": {"type": "string"},
+        "bytes": {"type": "number", "minimum": 0},
+        "sha256": {"type": "string"},
+        "created_at": {"type": "string"},
+        "updated_at": {"type": "string"},
+        "metadata": {"type": "object"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_READ_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "kind",
+        "path",
+        "bytes",
+        "sha256",
+        "created_at",
+        "updated_at",
+        "metadata",
+        "content",
+        "truncated",
+    ],
+    "properties": {
+        **_WORKSPACE_ASSET_METADATA_SCHEMA["properties"],
+        "content": {"type": "string"},
+        "truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_LIST_ENTRY_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["path", "type", "bytes", "sha256"],
+    "properties": {
+        "path": {"type": "string"},
+        "type": {"type": "string", "enum": ["directory", "file"]},
+        "bytes": {"type": "number", "minimum": 0},
+        "sha256": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_LIST_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["kind", "root", "entries", "file_count", "truncated"],
+    "properties": {
+        "kind": {"type": "string", "enum": list(VIRTUAL_WORKSPACE_KINDS)},
+        "root": {"type": "string"},
+        "entries": {
+            "type": "array",
+            "items": _WORKSPACE_LIST_ENTRY_OUTPUT_SCHEMA,
+        },
+        "file_count": {"type": "number", "minimum": 0},
+        "truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_SEARCH_MATCH_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["path", "line_number", "line", "byte_offset", "sha256"],
+    "properties": {
+        "path": {"type": "string"},
+        "line_number": {"type": "number", "minimum": 1},
+        "line": {"type": "string"},
+        "byte_offset": {"type": "number", "minimum": 0},
+        "sha256": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_SEARCH_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["kind", "root", "query", "matches", "match_count", "truncated"],
+    "properties": {
+        "kind": {"type": "string", "enum": list(VIRTUAL_WORKSPACE_KINDS)},
+        "root": {"type": "string"},
+        "query": {"type": "string"},
+        "matches": {
+            "type": "array",
+            "items": _WORKSPACE_SEARCH_MATCH_OUTPUT_SCHEMA,
+        },
+        "match_count": {"type": "number", "minimum": 0},
+        "truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_HISTORY_REVISION_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "revision_id",
+        "bytes",
+        "sha256",
+        "created_at",
+        "content",
+        "content_truncated",
+    ],
+    "properties": {
+        "revision_id": {"type": "string"},
+        "bytes": {"type": "number", "minimum": 0},
+        "sha256": {"type": "string"},
+        "created_at": {"type": "string"},
+        "content": {"type": "string"},
+        "content_truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_HISTORY_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["kind", "path", "revisions", "revision_count", "truncated"],
+    "properties": {
+        "kind": {"type": "string", "enum": list(VIRTUAL_WORKSPACE_KINDS)},
+        "path": {"type": "string"},
+        "revisions": {
+            "type": "array",
+            "items": _WORKSPACE_HISTORY_REVISION_OUTPUT_SCHEMA,
+        },
+        "revision_count": {"type": "number", "minimum": 0},
+        "truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_DIFF_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "kind",
+        "path",
+        "revision_id",
+        "from_sha256",
+        "to_sha256",
+        "diff",
+        "bytes",
+        "truncated",
+    ],
+    "properties": {
+        "kind": {"type": "string", "enum": list(VIRTUAL_WORKSPACE_KINDS)},
+        "path": {"type": "string"},
+        "revision_id": {"type": "string"},
+        "from_sha256": {"type": "string"},
+        "to_sha256": {"type": "string"},
+        "diff": {"type": "string"},
+        "bytes": {"type": "number", "minimum": 0},
+        "truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_WORKSPACE_RESTORE_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "kind",
+        "path",
+        "restored_revision_id",
+        "previous_sha256",
+        "sha256",
+        "bytes",
+        "updated_at",
+    ],
+    "properties": {
+        "kind": {"type": "string", "enum": list(VIRTUAL_WORKSPACE_KINDS)},
+        "path": {"type": "string"},
+        "restored_revision_id": {"type": "string"},
+        "previous_sha256": {"type": "string"},
+        "sha256": {"type": "string"},
+        "bytes": {"type": "number", "minimum": 0},
+        "updated_at": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_MEMORY_PUT_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["backend", "namespace", "key", "stored", "ttl_seconds"],
+    "properties": {
+        "backend": {"type": "string", "enum": ["redis"]},
+        "namespace": {"type": "string"},
+        "key": {"type": "string"},
+        "stored": {"type": "boolean"},
+        "ttl_seconds": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_MEMORY_GET_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["backend", "namespace", "key", "found", "value"],
+    "properties": {
+        "backend": {"type": "string", "enum": ["redis"]},
+        "namespace": {"type": "string"},
+        "key": {"type": "string"},
+        "found": {"type": "boolean"},
+        "value": {},
+    },
+    "additionalProperties": False,
+}
+
+_MEMORY_UPSERT_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["backend", "collection", "memory_id", "stored"],
+    "properties": {
+        "backend": {"type": "string", "enum": ["milvus"]},
+        "collection": {"type": "string"},
+        "memory_id": {"type": "string"},
+        "stored": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+_MEMORY_SEARCH_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["backend", "collection", "matches", "match_count"],
+    "properties": {
+        "backend": {"type": "string", "enum": ["milvus"]},
+        "collection": {"type": "string"},
+        "matches": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["memory_id", "text", "score", "metadata"],
+                "properties": {
+                    "memory_id": {"type": "string"},
+                    "text": {"type": "string"},
+                    "score": {"type": "number"},
+                    "metadata": {"type": "object"},
+                },
+                "additionalProperties": False,
+            },
+        },
+        "match_count": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_MEMORY_REMEMBER_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "backend",
+        "collection",
+        "memory_id",
+        "stored",
+        "embedding_model",
+        "vector_dimensions",
+    ],
+    "properties": {
+        **_MEMORY_UPSERT_OUTPUT_SCHEMA["properties"],
+        "embedding_model": {"type": "string"},
+        "vector_dimensions": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_MEMORY_RECALL_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "backend",
+        "collection",
+        "matches",
+        "match_count",
+        "embedding_model",
+        "vector_dimensions",
+    ],
+    "properties": {
+        **_MEMORY_SEARCH_OUTPUT_SCHEMA["properties"],
+        "embedding_model": {"type": "string"},
+        "vector_dimensions": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_DELEGATE_TASK_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "child_run_id",
+        "status",
+        "answer",
+        "error_code",
+        "child_iteration_count",
+        "child_observation_count",
+    ],
+    "properties": {
+        "child_run_id": {"type": "string"},
+        "status": {
+            "type": "string",
+            "enum": ["done", "failed", "requires_approval", "cancelled"],
+        },
+        "answer": {"type": "string"},
+        "error_code": {"type": "string"},
+        "child_iteration_count": {"type": "string"},
+        "child_observation_count": {"type": "string"},
+    },
+    "additionalProperties": False,
+}
+
+_SKILL_LIST_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["skills", "skill_count"],
+    "properties": {
+        "skills": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["name", "description", "tags"],
+                "properties": {
+                    "name": {"type": "string"},
+                    "description": {"type": "string"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                },
+                "additionalProperties": False,
+            },
+        },
+        "skill_count": {"type": "number", "minimum": 0},
+    },
+    "additionalProperties": False,
+}
+
+_SKILL_GET_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": ["name", "description", "instructions", "tags"],
+    "properties": {
+        "name": {"type": "string"},
+        "description": {"type": "string"},
+        "instructions": {"type": "string"},
+        "tags": {"type": "array", "items": {"type": "string"}},
+    },
+    "additionalProperties": False,
+}
+
+_SHELL_COMMAND_OUTPUT_SCHEMA = {
+    "type": "object",
+    "required": [
+        "command",
+        "cwd",
+        "sandbox",
+        "exit_code",
+        "stdout",
+        "stderr",
+        "duration_seconds",
+        "timed_out",
+        "truncated",
+    ],
+    "properties": {
+        "command": {"type": "string"},
+        "cwd": {"type": "string"},
+        "sandbox": {
+            "type": "object",
+            "required": [
+                "enabled",
+                "backend",
+                "enforced",
+                "filesystem",
+                "network",
+                "env_policy",
+            ],
+            "properties": {
+                "enabled": {"type": "string", "enum": ["true"]},
+                "backend": {
+                    "type": "string",
+                    "enum": ["linux-bwrap", "macos-seatbelt", "soft", "windows-soft"],
+                },
+                "enforced": {"type": "string", "enum": ["true", "false"]},
+                "filesystem": {"type": "string", "enum": ["workspace"]},
+                "network": {"type": "string", "enum": ["disabled"]},
+                "env_policy": {"type": "string", "enum": ["minimal"]},
+                "fallback_reason": {"type": "string"},
+            },
+            "additionalProperties": False,
+        },
+        "exit_code": {"type": "number"},
+        "stdout": {"type": "string"},
+        "stderr": {"type": "string"},
+        "duration_seconds": {"type": "number", "minimum": 0},
+        "timed_out": {"type": "boolean"},
+        "truncated": {"type": "boolean"},
+    },
+    "additionalProperties": False,
+}
+
+
+def default_runtime_tools(
+    *,
+    runtime_workspace_dir: str = "",
+    runtime_skills_dir: str = "",
+    redis_url: str = "",
+    milvus_url: str = "",
+    embedding_base_url: str = "",
+    embedding_api_key: str = "",
+    embedding_model: str = "",
+    embedding_timeout_seconds: float = 30.0,
+    embedding_max_retries: int = 2,
+    embedding_retry_backoff_seconds: float = 0.25,
+    external_backend_timeout_seconds: float = 2.0,
+    delegate_runner: Callable[[str, int], Dict[str, Any]] | None = None,
+    include_delegate_tool: bool = True,
+) -> Dict[str, RuntimeToolSpec]:
+    active_redis_url = redis_url.strip() or _first_env_value(_REDIS_URL_ENV_VARS)
+    active_milvus_url = milvus_url.strip() or _first_env_value(_MILVUS_URL_ENV_VARS)
+    active_embedding_config = _embedding_config(
+        base_url=embedding_base_url,
+        api_key=embedding_api_key,
+        model=embedding_model,
+        timeout_seconds=embedding_timeout_seconds,
+        max_retries=embedding_max_retries,
+        retry_backoff_seconds=embedding_retry_backoff_seconds,
+    )
+    active_backend_timeout = _backend_timeout_seconds(external_backend_timeout_seconds)
+    tools = {
+        "apply_patch": RuntimeToolSpec(
+            name="apply_patch",
+            description=(
+                "Apply a Codex-style workspace patch. Supports adding, updating, "
+                "moving, and deleting files "
+                "inside the current workspace and rejects absolute paths, parent "
+                "traversal, unsafe deletes, and accidental overwrites. To create hello.md, "
+                "use exactly: *** Begin Patch\n*** Add File: hello.md\n+content\n*** End Patch"
+            ),
+            handler=_apply_patch,
+            input_schema={
+                "type": "object",
+                "required": ["patch"],
+                "properties": {
+                    "patch": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": _APPLY_PATCH_MAX_BYTES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_APPLY_PATCH_OUTPUT_SCHEMA,
+        ),
+        "patch_history": RuntimeToolSpec(
+            name="patch_history",
+            description=(
+                "List committed file-change checkpoints for the current workspace. "
+                "Use this before revert_patch and pass back the exact checkpoint ID "
+                "and paths selected by the user."
+            ),
+            handler=_patch_history,
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "limit": {"type": "number", "minimum": 1, "maximum": 100},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_PATCH_HISTORY_OUTPUT_SCHEMA,
+        ),
+        "revert_patch": RuntimeToolSpec(
+            name="revert_patch",
+            description=(
+                "Restore files from a reviewed patch checkpoint. The exact paths from "
+                "patch_history are required and current file SHA-256 values must still "
+                "match the checkpoint. The revert creates a new checkpoint for redo."
+            ),
+            handler=_revert_patch,
+            input_schema={
+                "type": "object",
+                "required": ["checkpoint_id", "paths"],
+                "properties": {
+                    "checkpoint_id": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 120,
+                    },
+                    "paths": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": 200,
+                        "items": {"type": "string", "minLength": 1},
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_REVERT_PATCH_OUTPUT_SCHEMA,
+        ),
+        "artifact": RuntimeToolSpec(
+            name="artifact",
+            description=(
+                "Record a structured artifact such as a report, plan, "
+                "decision, data, or message."
+            ),
+            handler=_artifact,
+            input_schema={
+                "type": "object",
+                "required": ["title", "kind", "content"],
+                "properties": {
+                    "title": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": _SHORT_TEXT_MAX_LENGTH,
+                    },
+                    "kind": {
+                        "type": "string",
+                        "enum": list(_ARTIFACT_KINDS),
+                    },
+                    "content": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": _LONG_TEXT_MAX_LENGTH,
+                    },
+                    "format": {
+                        "type": "string",
+                        "enum": list(_ARTIFACT_FORMATS),
+                    },
+                    "tags": {
+                        "type": "array",
+                        "maxItems": _TAGS_MAX_ITEMS,
+                        "items": {"type": "string"},
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_ARTIFACT_OUTPUT_SCHEMA,
+        ),
+        "decision_matrix": RuntimeToolSpec(
+            name="decision_matrix",
+            description="Rank options with weighted criteria for structured decisions.",
+            handler=_decision_matrix,
+            input_schema={
+                "type": "object",
+                "required": ["question", "criteria", "options"],
+                "properties": {
+                    "question": {"type": "string"},
+                    "criteria": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": _DECISION_CRITERIA_MAX_ITEMS,
+                        "items": {
+                            "type": "object",
+                            "required": ["name", "weight"],
+                            "properties": {
+                                "name": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "maxLength": _SHORT_TEXT_MAX_LENGTH,
+                                },
+                                "weight": {"type": "number", "minimum": 0},
+                            },
+                            "additionalProperties": False,
+                        },
+                    },
+                    "options": {
+                        "type": "array",
+                        "minItems": 2,
+                        "maxItems": _DECISION_OPTIONS_MAX_ITEMS,
+                        "items": {
+                            "type": "object",
+                            "required": ["name", "scores"],
+                            "properties": {
+                                "name": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "maxLength": _SHORT_TEXT_MAX_LENGTH,
+                                },
+                                "scores": {
+                                    "type": "array",
+                                    "minItems": 1,
+                                    "items": {"type": "number"},
+                                },
+                                "rationale": {"type": "string"},
+                            },
+                            "additionalProperties": False,
+                        },
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_DECISION_MATRIX_OUTPUT_SCHEMA,
+        ),
+        "note": RuntimeToolSpec(
+            name="note",
+            description="Record a short note as an artifact observation.",
+            handler=_note,
+            input_schema={
+                "type": "object",
+                "required": ["text"],
+                "properties": {
+                    "text": {"type": "string", "maxLength": _LONG_TEXT_MAX_LENGTH}
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_TEXT_OUTPUT_SCHEMA,
+        ),
+        "http_request": RuntimeToolSpec(
+            name="http_request",
+            description=(
+                "Fetch a URL with an HTTP GET request. This does not open a "
+                "browser window; use open_url when the user asks to open a "
+                "web page. This tool is policy-gated and should only run after "
+                "explicit approval. Private, loopback, and link-local targets "
+                "are rejected."
+            ),
+            handler=_http_request,
+            input_schema={
+                "type": "object",
+                "required": ["url"],
+                "properties": {
+                    "url": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 2048,
+                    },
+                    "max_bytes": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _HTTP_REQUEST_MAX_BYTES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_HTTP_REQUEST_OUTPUT_SCHEMA,
+        ),
+        "list_files": RuntimeToolSpec(
+            name="list_files",
+            description=(
+                "List files and directories inside the current workspace with "
+                "bounded depth and entry count."
+            ),
+            handler=_list_files,
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "maxLength": 2048},
+                    "max_depth": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": _LIST_FILES_MAX_DEPTH,
+                    },
+                    "limit": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _LIST_FILES_MAX_ENTRIES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_LIST_FILES_OUTPUT_SCHEMA,
+        ),
+        "open_url": RuntimeToolSpec(
+            name="open_url",
+            description=(
+                "Open an http:// or https:// URL in a local browser window on "
+                "macOS. Uses Google Chrome automation first, with macOS open "
+                "fallbacks. Use this when the user asks to open a web page."
+            ),
+            handler=_open_url,
+            input_schema={
+                "type": "object",
+                "required": ["url"],
+                "properties": {
+                    "url": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 2048,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_OPEN_URL_OUTPUT_SCHEMA,
+        ),
+        "open_app": RuntimeToolSpec(
+            name="open_app",
+            description=(
+                "Open a local macOS application by application name. Use this "
+                "when the user asks to open an installed app such as Chrome, "
+                "Cursor, WeChat, Feishu, or Terminal. The input is an app name, "
+                "not a path or shell command."
+            ),
+            handler=_open_app,
+            input_schema={
+                "type": "object",
+                "required": ["application"],
+                "properties": {
+                    "application": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": _APP_NAME_MAX_LENGTH,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_OPEN_APP_OUTPUT_SCHEMA,
+        ),
+        "read_file": RuntimeToolSpec(
+            name="read_file",
+            description=(
+                "Read a UTF-8 text file inside the current workspace with a "
+                "bounded byte limit."
+            ),
+            handler=_read_file,
+            input_schema={
+                "type": "object",
+                "required": ["path"],
+                "properties": {
+                    "path": {"type": "string", "minLength": 1, "maxLength": 2048},
+                    "max_bytes": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _READ_FILE_MAX_BYTES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_READ_FILE_OUTPUT_SCHEMA,
+        ),
+        "workspace_write": RuntimeToolSpec(
+            name="workspace_write",
+            description=(
+                "Write UTF-8 text into the runtime virtual workspace. "
+                "Kinds are workspace, reports, logs, policies, and memories. "
+                "Paths are relative to the selected virtual directory and "
+                "cannot escape it."
+            ),
+            handler=lambda payload: _workspace_write(
+                payload,
+                runtime_workspace_dir=runtime_workspace_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["kind", "path", "content"],
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": list(VIRTUAL_WORKSPACE_KINDS),
+                    },
+                    "path": {"type": "string", "minLength": 1, "maxLength": 2048},
+                    "content": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": _LONG_TEXT_MAX_LENGTH,
+                    },
+                    "metadata": {"type": "object"},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_WORKSPACE_ASSET_METADATA_SCHEMA,
+        ),
+        "workspace_read": RuntimeToolSpec(
+            name="workspace_read",
+            description="Read a UTF-8 text asset from the runtime virtual workspace.",
+            handler=lambda payload: _workspace_read(
+                payload,
+                runtime_workspace_dir=runtime_workspace_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["kind", "path"],
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": list(VIRTUAL_WORKSPACE_KINDS),
+                    },
+                    "path": {"type": "string", "minLength": 1, "maxLength": 2048},
+                    "max_bytes": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _READ_FILE_MAX_BYTES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_WORKSPACE_READ_OUTPUT_SCHEMA,
+        ),
+        "workspace_history": RuntimeToolSpec(
+            name="workspace_history",
+            description=(
+                "Read previous versions saved before overwriting a UTF-8 text "
+                "asset in the runtime virtual workspace."
+            ),
+            handler=lambda payload: _workspace_history(
+                payload,
+                runtime_workspace_dir=runtime_workspace_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["kind", "path"],
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": list(VIRTUAL_WORKSPACE_KINDS),
+                    },
+                    "path": {"type": "string", "minLength": 1, "maxLength": 2048},
+                    "limit": {"type": "number", "minimum": 1, "maximum": 50},
+                    "max_bytes": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _READ_FILE_MAX_BYTES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_WORKSPACE_HISTORY_OUTPUT_SCHEMA,
+        ),
+        "workspace_diff": RuntimeToolSpec(
+            name="workspace_diff",
+            description=(
+                "Compare the current UTF-8 text asset in the runtime virtual "
+                "workspace against a saved previous version and return a bounded "
+                "unified diff."
+            ),
+            handler=lambda payload: _workspace_diff(
+                payload,
+                runtime_workspace_dir=runtime_workspace_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["kind", "path"],
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": list(VIRTUAL_WORKSPACE_KINDS),
+                    },
+                    "path": {"type": "string", "minLength": 1, "maxLength": 2048},
+                    "revision_id": {"type": "string", "maxLength": 120},
+                    "context_lines": {"type": "number", "minimum": 0, "maximum": 20},
+                    "max_bytes": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _READ_FILE_MAX_BYTES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_WORKSPACE_DIFF_OUTPUT_SCHEMA,
+        ),
+        "workspace_restore": RuntimeToolSpec(
+            name="workspace_restore",
+            description=(
+                "Restore a runtime virtual workspace text asset to a reviewed "
+                "saved revision. Requires the expected current SHA-256 so a "
+                "concurrent edit cannot be overwritten silently. The current "
+                "content is saved as a new revision before restoration."
+            ),
+            handler=lambda payload: _workspace_restore(
+                payload,
+                runtime_workspace_dir=runtime_workspace_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "required": [
+                    "kind",
+                    "path",
+                    "revision_id",
+                    "expected_current_sha256",
+                    "expected_revision_sha256",
+                ],
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": list(VIRTUAL_WORKSPACE_KINDS),
+                    },
+                    "path": {"type": "string", "minLength": 1, "maxLength": 2048},
+                    "revision_id": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "expected_current_sha256": {
+                        "type": "string",
+                        "minLength": 64,
+                        "maxLength": 64,
+                    },
+                    "expected_revision_sha256": {
+                        "type": "string",
+                        "minLength": 64,
+                        "maxLength": 64,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_WORKSPACE_RESTORE_OUTPUT_SCHEMA,
+        ),
+        "workspace_list": RuntimeToolSpec(
+            name="workspace_list",
+            description=(
+                "List assets inside a runtime virtual workspace directory with "
+                "bounded depth and entry count."
+            ),
+            handler=lambda payload: _workspace_list(
+                payload,
+                runtime_workspace_dir=runtime_workspace_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["kind"],
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": list(VIRTUAL_WORKSPACE_KINDS),
+                    },
+                    "path": {"type": "string", "maxLength": 2048},
+                    "max_depth": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": _LIST_FILES_MAX_DEPTH,
+                    },
+                    "limit": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _LIST_FILES_MAX_ENTRIES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_WORKSPACE_LIST_OUTPUT_SCHEMA,
+        ),
+        "workspace_search": RuntimeToolSpec(
+            name="workspace_search",
+            description=(
+                "Search UTF-8 text assets inside a runtime virtual workspace "
+                "directory with bounded depth, byte, and result limits."
+            ),
+            handler=lambda payload: _workspace_search(
+                payload,
+                runtime_workspace_dir=runtime_workspace_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["kind", "query"],
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": list(VIRTUAL_WORKSPACE_KINDS),
+                    },
+                    "query": {"type": "string", "minLength": 1, "maxLength": 500},
+                    "path": {"type": "string", "maxLength": 2048},
+                    "max_depth": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": _LIST_FILES_MAX_DEPTH,
+                    },
+                    "limit": {"type": "number", "minimum": 1, "maximum": 50},
+                    "max_bytes": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _READ_FILE_MAX_BYTES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_WORKSPACE_SEARCH_OUTPUT_SCHEMA,
+        ),
+        "memory_put": RuntimeToolSpec(
+            name="memory_put",
+            description=(
+                "Store short-term structured runtime memory in Redis by namespace "
+                "and key. Requires KAGENT_REDIS_URL or service redis_url."
+            ),
+            handler=lambda payload: _memory_put(
+                payload,
+                redis_url=active_redis_url,
+                timeout_seconds=active_backend_timeout,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["namespace", "key", "value"],
+                "properties": {
+                    "namespace": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "key": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "value": {},
+                    "ttl_seconds": {"type": "number", "minimum": 0},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_MEMORY_PUT_OUTPUT_SCHEMA,
+        ),
+        "memory_get": RuntimeToolSpec(
+            name="memory_get",
+            description=(
+                "Read short-term structured runtime memory from Redis by "
+                "namespace and key."
+            ),
+            handler=lambda payload: _memory_get(
+                payload,
+                redis_url=active_redis_url,
+                timeout_seconds=active_backend_timeout,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["namespace", "key"],
+                "properties": {
+                    "namespace": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "key": {"type": "string", "minLength": 1, "maxLength": 120},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_MEMORY_GET_OUTPUT_SCHEMA,
+        ),
+        "memory_upsert": RuntimeToolSpec(
+            name="memory_upsert",
+            description=(
+                "Store long-term semantic memory in Milvus. The caller must "
+                "provide an embedding vector; this runtime does not invent "
+                "vectors from text."
+            ),
+            handler=lambda payload: _memory_upsert(
+                payload,
+                milvus_url=active_milvus_url,
+                timeout_seconds=active_backend_timeout,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["collection", "memory_id", "text", "vector"],
+                "properties": {
+                    "collection": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "memory_id": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "text": {"type": "string", "minLength": 1, "maxLength": 20000},
+                    "vector": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": 4096,
+                        "items": {"type": "number"},
+                    },
+                    "metadata": {"type": "object"},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_MEMORY_UPSERT_OUTPUT_SCHEMA,
+        ),
+        "memory_search": RuntimeToolSpec(
+            name="memory_search",
+            description=(
+                "Search long-term semantic memory in Milvus with an embedding "
+                "vector. Requires KAGENT_MILVUS_URL or service milvus_url."
+            ),
+            handler=lambda payload: _memory_search(
+                payload,
+                milvus_url=active_milvus_url,
+                timeout_seconds=active_backend_timeout,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["collection", "vector"],
+                "properties": {
+                    "collection": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "vector": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": 4096,
+                        "items": {"type": "number"},
+                    },
+                    "limit": {"type": "number", "minimum": 1, "maximum": 50},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_MEMORY_SEARCH_OUTPUT_SCHEMA,
+        ),
+        "memory_remember": RuntimeToolSpec(
+            name="memory_remember",
+            description=(
+                "Embed text with the configured OpenAI-compatible embedding "
+                "provider and store it in Milvus long-term memory."
+            ),
+            handler=lambda payload: _memory_remember(
+                payload,
+                milvus_url=active_milvus_url,
+                embedding_config=active_embedding_config,
+                timeout_seconds=active_backend_timeout,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["collection", "memory_id", "text"],
+                "properties": {
+                    "collection": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "memory_id": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "text": {"type": "string", "minLength": 1, "maxLength": 20000},
+                    "metadata": {"type": "object"},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_MEMORY_REMEMBER_OUTPUT_SCHEMA,
+        ),
+        "memory_recall": RuntimeToolSpec(
+            name="memory_recall",
+            description=(
+                "Embed a text query with the configured OpenAI-compatible "
+                "embedding provider and search Milvus long-term memory."
+            ),
+            handler=lambda payload: _memory_recall(
+                payload,
+                milvus_url=active_milvus_url,
+                embedding_config=active_embedding_config,
+                timeout_seconds=active_backend_timeout,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["collection", "query"],
+                "properties": {
+                    "collection": {"type": "string", "minLength": 1, "maxLength": 120},
+                    "query": {"type": "string", "minLength": 1, "maxLength": 20000},
+                    "limit": {"type": "number", "minimum": 1, "maximum": 50},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_MEMORY_RECALL_OUTPUT_SCHEMA,
+        ),
+        "shell_command": RuntimeToolSpec(
+            name="shell_command",
+            description=(
+                "Run a bounded non-interactive shell command inside the current "
+                "workspace. Captures stdout/stderr, returns the process exit code, "
+                "rejects workspace escapes and obvious interactive/background "
+                "commands, and is policy-gated by default."
+            ),
+            handler=_shell_command,
+            input_schema={
+                "type": "object",
+                "required": ["command"],
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": _SHELL_COMMAND_MAX_LENGTH,
+                    },
+                    "cwd": {"type": "string", "maxLength": 2048},
+                    "timeout_seconds": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _SHELL_COMMAND_MAX_TIMEOUT_SECONDS,
+                    },
+                    "max_output_bytes": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _SHELL_COMMAND_MAX_OUTPUT_BYTES,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_SHELL_COMMAND_OUTPUT_SCHEMA,
+            timeout_seconds=_SHELL_COMMAND_MAX_TIMEOUT_SECONDS + 1,
+        ),
+        "skill_list": RuntimeToolSpec(
+            name="skill_list",
+            description="List installed runtime skills available to the agent.",
+            handler=lambda payload: _skill_list(
+                payload,
+                runtime_skills_dir=runtime_skills_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {},
+                "additionalProperties": False,
+            },
+            output_schema=_SKILL_LIST_OUTPUT_SCHEMA,
+        ),
+        "skill_get": RuntimeToolSpec(
+            name="skill_get",
+            description="Read one installed runtime skill's instructions by name.",
+            handler=lambda payload: _skill_get(
+                payload,
+                runtime_skills_dir=runtime_skills_dir,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["name"],
+                "properties": {
+                    "name": {"type": "string", "minLength": 1, "maxLength": 80},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_SKILL_GET_OUTPUT_SCHEMA,
+        ),
+        "task_list": RuntimeToolSpec(
+            name="task_list",
+            description="Create a structured task list with normalized status counts.",
+            handler=_task_list,
+            input_schema={
+                "type": "object",
+                "required": ["items"],
+                "properties": {
+                    "items": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": _TASK_ITEMS_MAX_ITEMS,
+                        "items": {
+                            "type": "object",
+                            "required": ["title"],
+                            "properties": {
+                                "title": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "maxLength": _TASK_TITLE_MAX_LENGTH,
+                                },
+                                "status": {
+                                    "type": "string",
+                                    "enum": list(_TASK_STATUSES),
+                                },
+                                "priority": {
+                                    "type": "string",
+                                    "enum": list(_TASK_PRIORITIES),
+                                },
+                                "owner": {"type": "string"},
+                                "due": {"type": "string"},
+                            },
+                            "additionalProperties": False,
+                        },
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_TASK_LIST_OUTPUT_SCHEMA,
+        ),
+        "task_transition": RuntimeToolSpec(
+            name="task_transition",
+            description=(
+                "Advance one task through the runtime task lifecycle using a "
+                "validated state-machine transition."
+            ),
+            handler=_task_transition,
+            input_schema={
+                "type": "object",
+                "required": ["state", "event"],
+                "properties": {
+                    "state": {"type": "string", "enum": list(TASK_STATES)},
+                    "event": {"type": "string", "enum": list(TASK_EVENTS)},
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_TASK_TRANSITION_OUTPUT_SCHEMA,
+        ),
+        "rubric_score": RuntimeToolSpec(
+            name="rubric_score",
+            description=(
+                "Score a result against pass/fail rubric criteria and report "
+                "blocking failures."
+            ),
+            handler=_rubric_score,
+            input_schema={
+                "type": "object",
+                "required": ["criteria"],
+                "properties": {
+                    "criteria": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": _RUBRIC_CRITERIA_MAX_ITEMS,
+                        "items": {
+                            "type": "object",
+                            "required": ["name", "passed"],
+                            "properties": {
+                                "name": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "maxLength": _SHORT_TEXT_MAX_LENGTH,
+                                },
+                                "passed": {"type": "boolean"},
+                                "severity": {
+                                    "type": "string",
+                                    "enum": list(_RUBRIC_SEVERITIES),
+                                },
+                                "evidence": {
+                                    "type": "string",
+                                    "maxLength": _LONG_TEXT_MAX_LENGTH,
+                                },
+                            },
+                            "additionalProperties": False,
+                        },
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_RUBRIC_SCORE_OUTPUT_SCHEMA,
+        ),
+        "transform_text": RuntimeToolSpec(
+            name="transform_text",
+            description="Transform text with uppercase, lowercase, reverse, or trim modes.",
+            handler=_transform_text,
+            input_schema={
+                "type": "object",
+                "required": ["text", "mode"],
+                "properties": {
+                    "text": {"type": "string"},
+                    "mode": {
+                        "type": "string",
+                        "enum": ["uppercase", "lowercase", "reverse", "trim"],
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_TEXT_OUTPUT_SCHEMA,
+        ),
+    }
+    if include_delegate_tool:
+        tools["delegate_task"] = RuntimeToolSpec(
+            name="delegate_task",
+            description=(
+                "Delegate a bounded subtask to a child kagent runtime. Child "
+                "runs return a compact summary and cannot delegate again by default."
+            ),
+            handler=lambda payload: _delegate_task(
+                payload,
+                delegate_runner=delegate_runner,
+            ),
+            input_schema={
+                "type": "object",
+                "required": ["goal"],
+                "properties": {
+                    "goal": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": _DELEGATE_GOAL_MAX_LENGTH,
+                    },
+                    "max_iterations": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": _DELEGATE_MAX_ITERATIONS,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            output_schema=_DELEGATE_TASK_OUTPUT_SCHEMA,
+            timeout_seconds=30.0,
+        )
+    return tools
+
+
+def registered_runtime_tool_metadata() -> list[Dict[str, Any]]:
+    return runtime_tool_metadata(default_runtime_tools())
+
+
+def runtime_tool_metadata(tools: Dict[str, RuntimeToolSpec]) -> list[Dict[str, Any]]:
+    default_allowed_tools = RuntimePolicy().allowed_tools
+    return [
+        {
+            "name": tool.name,
+            "description": tool.description,
+            "approval_required_by_default": str(
+                tool.name not in default_allowed_tools
+            ).lower(),
+            "input_schema": tool.input_schema,
+            "output_schema": tool.output_schema,
+            "timeout_seconds": f"{tool.timeout_seconds:.1f}",
+        }
+        for tool in sorted(tools.values(), key=lambda item: item.name)
+    ]
+
+
+def execute_runtime_tool(
+    registry: Dict[str, RuntimeToolSpec],
+    tool_name: str,
+    input_payload: Dict[str, Any],
+    *,
+    action_id: str = "",
+) -> AgentObservation:
+    started_at = _utc_timestamp()
+    started_timer = time.perf_counter()
+    tool = registry.get(tool_name)
+    if tool is None:
+        return AgentObservation(
+            action_id=action_id,
+            tool=tool_name,
+            status="failed",
+            output={},
+            error_code="tool_not_found",
+            error="tool is not registered",
+            started_at=started_at,
+            completed_at=_utc_timestamp(),
+            duration_seconds=_duration_since(started_timer),
+        )
+    try:
+        _validate_tool_input(input_payload, tool.input_schema)
+        output = _run_tool_handler(tool, input_payload)
+    except TimeoutError as exc:
+        return AgentObservation(
+            action_id=action_id,
+            tool=tool_name,
+            status="failed",
+            output={},
+            error_code="tool_execution_timeout",
+            error=str(exc) or "tool execution exceeded timeout",
+            started_at=started_at,
+            completed_at=_utc_timestamp(),
+            duration_seconds=_duration_since(started_timer),
+        )
+    except ValueError as exc:
+        return AgentObservation(
+            action_id=action_id,
+            tool=tool_name,
+            status="failed",
+            output={},
+            error_code="invalid_tool_input",
+            error=str(exc),
+            started_at=started_at,
+            completed_at=_utc_timestamp(),
+            duration_seconds=_duration_since(started_timer),
+        )
+    except Exception as exc:
+        return AgentObservation(
+            action_id=action_id,
+            tool=tool_name,
+            status="failed",
+            output={},
+            error_code="tool_execution_failed",
+            error=str(exc) or type(exc).__name__,
+            started_at=started_at,
+            completed_at=_utc_timestamp(),
+            duration_seconds=_duration_since(started_timer),
+        )
+    try:
+        _validate_tool_input(output, tool.output_schema, "output")
+    except ValueError as exc:
+        return AgentObservation(
+            action_id=action_id,
+            tool=tool_name,
+            status="failed",
+            output={},
+            error_code="invalid_tool_output",
+            error=str(exc),
+            started_at=started_at,
+            completed_at=_utc_timestamp(),
+            duration_seconds=_duration_since(started_timer),
+        )
+    return AgentObservation(
+        action_id=action_id,
+        tool=tool_name,
+        status="ok",
+        output=output,
+        started_at=started_at,
+        completed_at=_utc_timestamp(),
+        duration_seconds=_duration_since(started_timer),
+    )
+
+
+def _run_tool_handler(
+    tool: RuntimeToolSpec,
+    input_payload: Dict[str, Any],
+) -> Dict[str, Any]:
+    output = tool.handler(input_payload)
+    if not isinstance(output, dict):
+        raise ValueError("output must be an object")
+    return output
+
+
+def _note(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    text = input_payload.get("text")
+    if not isinstance(text, str):
+        raise ValueError("text must be a string")
+    return {"text": text}
+
+
+def _read_file(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    relative_path = input_payload.get("path")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    normalized_path = relative_path.strip()
+    max_bytes = int(input_payload.get("max_bytes", _READ_FILE_MAX_BYTES))
+    workspace_root = Path.cwd().resolve()
+    target = _resolve_workspace_relative_path(workspace_root, normalized_path)
+    if not target.exists():
+        raise ValueError(f"file does not exist: {normalized_path}")
+    if target.is_dir():
+        raise ValueError(f"path is a directory: {normalized_path}")
+    body = target.read_bytes()
+    truncated = len(body) > max_bytes
+    visible_body = body[:max_bytes] if truncated else body
+    return {
+        "path": _workspace_output_path(workspace_root, target),
+        "content": visible_body.decode("utf-8", errors="replace"),
+        "bytes": len(visible_body),
+        "truncated": truncated,
+        "sha256": hashlib.sha256(body).hexdigest(),
+    }
+
+
+def _list_files(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    relative_path = input_payload.get("path", ".")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    normalized_path = relative_path.strip()
+    max_depth = int(input_payload.get("max_depth", _LIST_FILES_MAX_DEPTH))
+    limit = int(input_payload.get("limit", _LIST_FILES_MAX_ENTRIES))
+    workspace_root = Path.cwd().resolve()
+    root = _resolve_workspace_relative_path(workspace_root, normalized_path)
+    if not root.exists():
+        raise ValueError(f"path does not exist: {normalized_path}")
+    if root.is_file():
+        entries = [_file_entry(workspace_root, root)]
+        return {
+            "root": _workspace_output_path(workspace_root, root),
+            "entries": entries,
+            "file_count": len(entries),
+            "truncated": False,
+        }
+    entries = []
+    truncated = False
+    for path in _iter_workspace_entries(root, max_depth=max_depth):
+        if len(entries) >= limit:
+            truncated = True
+            break
+        entries.append(_file_entry(workspace_root, path))
+    return {
+        "root": _workspace_output_path(workspace_root, root),
+        "entries": entries,
+        "file_count": len(entries),
+        "truncated": truncated,
+    }
+
+
+def _workspace_write(
+    input_payload: Dict[str, Any],
+    *,
+    runtime_workspace_dir: str = "",
+) -> Dict[str, Any]:
+    kind = input_payload.get("kind")
+    relative_path = input_payload.get("path")
+    content = input_payload.get("content")
+    metadata = input_payload.get("metadata", {})
+    if not isinstance(kind, str):
+        raise ValueError("kind must be a string")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    if not isinstance(content, str):
+        raise ValueError("content must be a string")
+    if not isinstance(metadata, dict):
+        raise ValueError("metadata must be an object")
+    return _runtime_workspace(runtime_workspace_dir).write_text(
+        kind,
+        relative_path.strip(),
+        content,
+        metadata=metadata,
+    )
+
+
+def _workspace_read(
+    input_payload: Dict[str, Any],
+    *,
+    runtime_workspace_dir: str = "",
+) -> Dict[str, Any]:
+    kind = input_payload.get("kind")
+    relative_path = input_payload.get("path")
+    if not isinstance(kind, str):
+        raise ValueError("kind must be a string")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    return _runtime_workspace(runtime_workspace_dir).read_text(
+        kind,
+        relative_path.strip(),
+        max_bytes=int(input_payload.get("max_bytes", _READ_FILE_MAX_BYTES)),
+    )
+
+
+def _workspace_list(
+    input_payload: Dict[str, Any],
+    *,
+    runtime_workspace_dir: str = "",
+) -> Dict[str, Any]:
+    kind = input_payload.get("kind")
+    relative_path = input_payload.get("path", ".")
+    if not isinstance(kind, str):
+        raise ValueError("kind must be a string")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    return _runtime_workspace(runtime_workspace_dir).list(
+        kind,
+        relative_path.strip(),
+        max_depth=int(input_payload.get("max_depth", _LIST_FILES_MAX_DEPTH)),
+        limit=int(input_payload.get("limit", _LIST_FILES_MAX_ENTRIES)),
+    )
+
+
+def _workspace_history(
+    input_payload: Dict[str, Any],
+    *,
+    runtime_workspace_dir: str = "",
+) -> Dict[str, Any]:
+    kind = input_payload.get("kind")
+    relative_path = input_payload.get("path")
+    if not isinstance(kind, str):
+        raise ValueError("kind must be a string")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    return _runtime_workspace(runtime_workspace_dir).history(
+        kind,
+        relative_path.strip(),
+        limit=int(input_payload.get("limit", 20)),
+        max_bytes=int(input_payload.get("max_bytes", _READ_FILE_MAX_BYTES)),
+    )
+
+
+def _workspace_diff(
+    input_payload: Dict[str, Any],
+    *,
+    runtime_workspace_dir: str = "",
+) -> Dict[str, Any]:
+    kind = input_payload.get("kind")
+    relative_path = input_payload.get("path")
+    revision_id = input_payload.get("revision_id", "")
+    if not isinstance(kind, str):
+        raise ValueError("kind must be a string")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    if not isinstance(revision_id, str):
+        raise ValueError("revision_id must be a string")
+    return _runtime_workspace(runtime_workspace_dir).diff(
+        kind,
+        relative_path.strip(),
+        revision_id=revision_id.strip(),
+        context_lines=int(input_payload.get("context_lines", 3)),
+        max_bytes=int(input_payload.get("max_bytes", _READ_FILE_MAX_BYTES)),
+    )
+
+
+def _workspace_restore(
+    input_payload: Dict[str, Any],
+    *,
+    runtime_workspace_dir: str = "",
+) -> Dict[str, Any]:
+    kind = input_payload.get("kind")
+    relative_path = input_payload.get("path")
+    revision_id = input_payload.get("revision_id")
+    expected_current_sha256 = input_payload.get("expected_current_sha256")
+    expected_revision_sha256 = input_payload.get("expected_revision_sha256")
+    if not isinstance(kind, str):
+        raise ValueError("kind must be a string")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    if not isinstance(revision_id, str) or not revision_id.strip():
+        raise ValueError("revision_id must be a non-empty string")
+    if not isinstance(expected_current_sha256, str):
+        raise ValueError("expected_current_sha256 must be a string")
+    if not isinstance(expected_revision_sha256, str):
+        raise ValueError("expected_revision_sha256 must be a string")
+    return _runtime_workspace(runtime_workspace_dir).restore(
+        kind,
+        relative_path.strip(),
+        revision_id=revision_id.strip(),
+        expected_current_sha256=expected_current_sha256.strip(),
+        expected_revision_sha256=expected_revision_sha256.strip(),
+    )
+
+
+def _workspace_search(
+    input_payload: Dict[str, Any],
+    *,
+    runtime_workspace_dir: str = "",
+) -> Dict[str, Any]:
+    kind = input_payload.get("kind")
+    query = input_payload.get("query")
+    relative_path = input_payload.get("path", ".")
+    if not isinstance(kind, str):
+        raise ValueError("kind must be a string")
+    if not isinstance(query, str) or not query:
+        raise ValueError("query must be a non-empty string")
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("path must be a non-empty string")
+    return _runtime_workspace(runtime_workspace_dir).search(
+        kind,
+        query,
+        relative_path.strip(),
+        max_depth=int(input_payload.get("max_depth", _LIST_FILES_MAX_DEPTH)),
+        limit=int(input_payload.get("limit", 50)),
+        max_bytes=int(input_payload.get("max_bytes", _READ_FILE_MAX_BYTES)),
+    )
+
+
+def _runtime_workspace(runtime_workspace_dir: str = "") -> RuntimeWorkspace:
+    if runtime_workspace_dir.strip():
+        return RuntimeWorkspace(runtime_workspace_dir.strip())
+    for env_var in _RUNTIME_WORKSPACE_DIR_ENV_VARS:
+        configured = os.environ.get(env_var, "").strip()
+        if configured:
+            return RuntimeWorkspace(configured)
+    return RuntimeWorkspace(Path.cwd() / ".kagent" / "runtime-workspace")
+
+
+def _skill_list(
+    _input_payload: Dict[str, Any],
+    *,
+    runtime_skills_dir: str = "",
+) -> Dict[str, Any]:
+    skills = _runtime_skill_registry(runtime_skills_dir).list_skills()
+    return {"skills": skills, "skill_count": len(skills)}
+
+
+def _skill_get(
+    input_payload: Dict[str, Any],
+    *,
+    runtime_skills_dir: str = "",
+) -> Dict[str, Any]:
+    name = input_payload.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("name must be a non-empty string")
+    return _runtime_skill_registry(runtime_skills_dir).get_skill(name.strip())
+
+
+def _runtime_skill_registry(runtime_skills_dir: str = "") -> RuntimeSkillRegistry:
+    if runtime_skills_dir.strip():
+        return RuntimeSkillRegistry(runtime_skills_dir.strip())
+    for env_var in _RUNTIME_SKILLS_DIR_ENV_VARS:
+        configured = os.environ.get(env_var, "").strip()
+        if configured:
+            return RuntimeSkillRegistry(configured)
+    return RuntimeSkillRegistry(Path.cwd() / ".kagent" / "skills")
+
+
+def _memory_put(
+    input_payload: Dict[str, Any],
+    *,
+    redis_url: str,
+    timeout_seconds: float,
+) -> Dict[str, Any]:
+    if not redis_url:
+        raise ValueError("redis memory backend is not configured")
+    _reject_secret_like_memory_payload(input_payload.get("value"))
+    ttl = input_payload.get("ttl_seconds", 0)
+    if isinstance(ttl, bool) or not isinstance(ttl, (int, float)):
+        raise ValueError("ttl_seconds must be a number")
+    if int(ttl) != ttl:
+        raise ValueError("ttl_seconds must be an integer")
+    return RedisShortTermMemory(
+        redis_url,
+        timeout_seconds=timeout_seconds,
+    ).put(
+        namespace=str(input_payload.get("namespace", "")),
+        key=str(input_payload.get("key", "")),
+        value=input_payload.get("value"),
+        ttl_seconds=int(ttl),
+    )
+
+
+def _memory_get(
+    input_payload: Dict[str, Any],
+    *,
+    redis_url: str,
+    timeout_seconds: float,
+) -> Dict[str, Any]:
+    if not redis_url:
+        raise ValueError("redis memory backend is not configured")
+    return RedisShortTermMemory(
+        redis_url,
+        timeout_seconds=timeout_seconds,
+    ).get(
+        namespace=str(input_payload.get("namespace", "")),
+        key=str(input_payload.get("key", "")),
+    )
+
+
+def _memory_upsert(
+    input_payload: Dict[str, Any],
+    *,
+    milvus_url: str,
+    timeout_seconds: float,
+) -> Dict[str, Any]:
+    if not milvus_url:
+        raise ValueError("milvus memory backend is not configured")
+    metadata = input_payload.get("metadata", {})
+    if not isinstance(metadata, dict):
+        raise ValueError("metadata must be an object")
+    _reject_secret_like_memory_payload(
+        {
+            "text": input_payload.get("text", ""),
+            "metadata": metadata,
+        }
+    )
+    return MilvusLongTermMemory(
+        milvus_url,
+        timeout_seconds=timeout_seconds,
+    ).upsert(
+        collection=str(input_payload.get("collection", "")),
+        memory_id=str(input_payload.get("memory_id", "")),
+        text=str(input_payload.get("text", "")),
+        vector=input_payload.get("vector", []),
+        metadata=metadata,
+    )
+
+
+def _memory_search(
+    input_payload: Dict[str, Any],
+    *,
+    milvus_url: str,
+    timeout_seconds: float,
+) -> Dict[str, Any]:
+    if not milvus_url:
+        raise ValueError("milvus memory backend is not configured")
+    limit = input_payload.get("limit", 5)
+    if isinstance(limit, bool) or not isinstance(limit, (int, float)):
+        raise ValueError("limit must be a number")
+    if int(limit) != limit:
+        raise ValueError("limit must be an integer")
+    return MilvusLongTermMemory(
+        milvus_url,
+        timeout_seconds=timeout_seconds,
+    ).search(
+        collection=str(input_payload.get("collection", "")),
+        vector=input_payload.get("vector", []),
+        limit=int(limit),
+    )
+
+
+def _memory_remember(
+    input_payload: Dict[str, Any],
+    *,
+    milvus_url: str,
+    embedding_config: EmbeddingProviderConfig,
+    timeout_seconds: float,
+) -> Dict[str, Any]:
+    if not milvus_url:
+        raise ValueError("milvus memory backend is not configured")
+    _require_embedding_config(embedding_config)
+    metadata = input_payload.get("metadata", {})
+    if not isinstance(metadata, dict):
+        raise ValueError("metadata must be an object")
+    text = str(input_payload.get("text", ""))
+    _reject_secret_like_memory_payload({"text": text, "metadata": metadata})
+    vector = OpenAICompatibleEmbeddingProvider(embedding_config).embed(text)
+    output = MilvusLongTermMemory(
+        milvus_url,
+        timeout_seconds=timeout_seconds,
+    ).upsert(
+        collection=str(input_payload.get("collection", "")),
+        memory_id=str(input_payload.get("memory_id", "")),
+        text=text,
+        vector=vector,
+        metadata=metadata,
+    )
+    return {
+        **output,
+        "embedding_model": embedding_config.model,
+        "vector_dimensions": str(len(vector)),
+    }
+
+
+def _memory_recall(
+    input_payload: Dict[str, Any],
+    *,
+    milvus_url: str,
+    embedding_config: EmbeddingProviderConfig,
+    timeout_seconds: float,
+) -> Dict[str, Any]:
+    if not milvus_url:
+        raise ValueError("milvus memory backend is not configured")
+    _require_embedding_config(embedding_config)
+    limit = input_payload.get("limit", 5)
+    if isinstance(limit, bool) or not isinstance(limit, (int, float)):
+        raise ValueError("limit must be a number")
+    if int(limit) != limit:
+        raise ValueError("limit must be an integer")
+    vector = OpenAICompatibleEmbeddingProvider(embedding_config).embed(
+        str(input_payload.get("query", ""))
+    )
+    output = MilvusLongTermMemory(
+        milvus_url,
+        timeout_seconds=timeout_seconds,
+    ).search(
+        collection=str(input_payload.get("collection", "")),
+        vector=vector,
+        limit=int(limit),
+    )
+    return {
+        **output,
+        "embedding_model": embedding_config.model,
+        "vector_dimensions": str(len(vector)),
+    }
+
+
+def _require_embedding_config(config: EmbeddingProviderConfig) -> None:
+    if not config.base_url:
+        raise ValueError("embedding base_url is not configured")
+    if not config.model:
+        raise ValueError("embedding model is not configured")
+
+
+def _reject_secret_like_memory_payload(value: Any) -> None:
+    if redact_runtime_payload(value) != value:
+        raise ValueError("memory write payload contains secret-like text")
+
+
+def _first_env_value(names: tuple[str, ...]) -> str:
+    for name in names:
+        value = os.environ.get(name, "").strip()
+        if value:
+            return value
+    return ""
+
+
+def _embedding_config(
+    *,
+    base_url: str,
+    api_key: str,
+    model: str,
+    timeout_seconds: float,
+    max_retries: int,
+    retry_backoff_seconds: float,
+) -> EmbeddingProviderConfig:
+    return EmbeddingProviderConfig(
+        base_url=base_url.strip() or _first_env_value(_EMBEDDING_BASE_URL_ENV_VARS),
+        api_key=api_key.strip() or _first_env_value(_EMBEDDING_API_KEY_ENV_VARS),
+        model=model.strip() or _first_env_value(_EMBEDDING_MODEL_ENV_VARS),
+        timeout_seconds=_embedding_timeout_seconds(timeout_seconds),
+        max_retries=_embedding_max_retries(max_retries),
+        retry_backoff_seconds=_embedding_retry_backoff_seconds(
+            retry_backoff_seconds
+        ),
+    )
+
+
+def _embedding_timeout_seconds(default_value: float) -> float:
+    env_value = os.environ.get("KAGENT_EMBEDDING_TIMEOUT_SECONDS", "").strip()
+    value = env_value or str(default_value)
+    try:
+        timeout = float(value)
+    except ValueError as exc:
+        raise ValueError("embedding timeout must be a float") from exc
+    if timeout <= 0:
+        raise ValueError("embedding timeout must be positive")
+    return timeout
+
+
+def _embedding_max_retries(default_value: int) -> int:
+    env_value = os.environ.get(_EMBEDDING_MAX_RETRIES_ENV_VAR, "").strip()
+    value = env_value or str(default_value)
+    try:
+        retries = int(value)
+    except ValueError as exc:
+        raise ValueError("embedding max_retries must be an integer") from exc
+    if retries < 0:
+        raise ValueError("embedding max_retries must be non-negative")
+    return retries
+
+
+def _embedding_retry_backoff_seconds(default_value: float) -> float:
+    env_value = os.environ.get(_EMBEDDING_RETRY_BACKOFF_ENV_VAR, "").strip()
+    value = env_value or str(default_value)
+    try:
+        backoff = float(value)
+    except ValueError as exc:
+        raise ValueError("embedding retry_backoff_seconds must be a float") from exc
+    if backoff < 0:
+        raise ValueError("embedding retry_backoff_seconds must be non-negative")
+    return backoff
+
+
+def _backend_timeout_seconds(default_value: float) -> float:
+    env_value = os.environ.get(_EXTERNAL_BACKEND_TIMEOUT_ENV_VAR, "").strip()
+    value = env_value or str(default_value)
+    try:
+        timeout = float(value)
+    except ValueError as exc:
+        raise ValueError("external backend timeout must be a float") from exc
+    if timeout <= 0:
+        raise ValueError("external backend timeout must be positive")
+    return timeout
+
+
+def _shell_command(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    command = input_payload.get("command")
+    if not isinstance(command, str) or not command.strip():
+        raise ValueError("command must be a non-empty string")
+    normalized_command = command.strip()
+    _validate_shell_command(normalized_command)
+
+    timeout_seconds = float(
+        input_payload.get("timeout_seconds", _SHELL_COMMAND_DEFAULT_TIMEOUT_SECONDS)
+    )
+    max_output_bytes = int(
+        input_payload.get("max_output_bytes", _SHELL_COMMAND_MAX_OUTPUT_BYTES)
+    )
+    workspace_root = Path.cwd().resolve()
+    cwd = _resolve_shell_cwd(workspace_root, input_payload.get("cwd", "."))
+    sandbox_env = _shell_sandbox_env(workspace_root, cwd)
+    sandbox = _shell_sandbox_metadata()
+    started = time.perf_counter()
+    timed_out = False
+    try:
+        sandbox_result = run_shell_sandboxed(
+            normalized_command,
+            workspace_root=workspace_root,
+            cwd=cwd,
+            env=sandbox_env,
+            timeout_seconds=timeout_seconds,
+        )
+        sandbox = sandbox_result.metadata
+        completed = sandbox_result.completed
+        exit_code = completed.returncode
+        stdout = completed.stdout or b""
+        stderr = completed.stderr or b""
+    except subprocess.TimeoutExpired as exc:
+        timed_out = True
+        exit_code = -1
+        stdout = exc.stdout or b""
+        stderr = exc.stderr or b""
+    duration_seconds = time.perf_counter() - started
+    stdout, stderr, truncated = _truncate_shell_output(
+        stdout,
+        stderr,
+        max_output_bytes=max_output_bytes,
+    )
+    return {
+        "command": normalized_command,
+        "cwd": _workspace_output_path(workspace_root, cwd),
+        "sandbox": sandbox,
+        "exit_code": exit_code,
+        "stdout": stdout.decode("utf-8", errors="replace"),
+        "stderr": stderr.decode("utf-8", errors="replace"),
+        "duration_seconds": float(f"{duration_seconds:.4f}"),
+        "timed_out": timed_out,
+        "truncated": truncated,
+    }
+
+
+def _validate_shell_command(command: str) -> None:
+    if "\x00" in command or "\n" in command or "\r" in command:
+        raise ValueError("command must be a single line")
+    if _SHELL_BACKGROUND_PATTERN.search(command):
+        raise ValueError("background shell commands are not supported")
+    for pattern in _SHELL_INTERACTIVE_PATTERNS:
+        if pattern.search(command):
+            raise ValueError("interactive shell commands are not supported")
+    for pattern in _SHELL_DESTRUCTIVE_PATTERNS:
+        if pattern.search(command):
+            raise ValueError("high-risk shell commands are not supported")
+    for pattern in _SHELL_SECRET_EXPOSURE_PATTERNS:
+        if pattern.search(command):
+            raise ValueError("secret-exposing shell commands are not supported")
+    if _SHELL_PIPE_TO_SHELL_PATTERN.search(command):
+        raise ValueError("pipe-to-shell commands are not supported")
+    for pattern in _SHELL_NETWORK_COMMAND_PATTERNS:
+        if pattern.search(command):
+            raise ValueError("network shell commands are not supported; use http_request")
+    for pattern in _SHELL_INLINE_NETWORK_CODE_PATTERNS:
+        if pattern.search(command):
+            raise ValueError("network shell commands are not supported; use http_request")
+
+
+def _shell_sandbox_metadata() -> Dict[str, str]:
+    return {
+        "enabled": "true",
+        "backend": "soft",
+        "enforced": "false",
+        "filesystem": "workspace",
+        "network": "disabled",
+        "env_policy": "minimal",
+    }
+
+
+def _shell_sandbox_env(workspace_root: Path, cwd: Path) -> Dict[str, str]:
+    return {
+        "HOME": str(workspace_root),
+        "LANG": "C.UTF-8",
+        "LC_ALL": "C.UTF-8",
+        "PATH": os.environ.get("PATH", os.defpath),
+        "PWD": str(cwd),
+        "KAGENT_RUNTIME_SANDBOX": "1",
+        "KAGENT_SANDBOX_FILESYSTEM": "workspace",
+        "KAGENT_SANDBOX_NETWORK": "disabled",
+    }
+
+
+def _resolve_shell_cwd(workspace_root: Path, relative_path: Any) -> Path:
+    if relative_path in {"", "."}:
+        return workspace_root
+    if not isinstance(relative_path, str) or not relative_path.strip():
+        raise ValueError("cwd must be a string")
+    cwd = _resolve_workspace_relative_path(workspace_root, relative_path.strip())
+    if not cwd.exists():
+        raise ValueError(f"cwd does not exist: {relative_path}")
+    if not cwd.is_dir():
+        raise ValueError(f"cwd is not a directory: {relative_path}")
+    return cwd
+
+
+def _truncate_shell_output(
+    stdout: bytes,
+    stderr: bytes,
+    *,
+    max_output_bytes: int,
+) -> tuple[bytes, bytes, bool]:
+    remaining = max_output_bytes
+    truncated = False
+    if len(stdout) > remaining:
+        stdout = stdout[:remaining]
+        remaining = 0
+        truncated = True
+    else:
+        remaining -= len(stdout)
+    if len(stderr) > remaining:
+        stderr = stderr[:remaining]
+        truncated = True
+    return stdout, stderr, truncated
+
+
+def _apply_patch(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    patch = input_payload.get("patch")
+    if not isinstance(patch, str) or not patch.strip():
+        raise ValueError("patch must be a non-empty string")
+    operations = _parse_workspace_patch(patch)
+    workspace_root = Path.cwd().resolve()
+    store = PatchCheckpointStore.from_environment()
+    store.recover_prepared(workspace_root)
+    with workspace_transaction(workspace_root):
+        return _stage_and_commit_workspace_patch(workspace_root, operations, store)
+
+
+def _stage_and_commit_workspace_patch(
+    workspace_root: Path,
+    operations: list[_PatchOperation],
+    store: PatchCheckpointStore,
+) -> Dict[str, Any]:
+    staged_contents: dict[Path, str | None] = {}
+    changed_files = []
+
+    for operation in operations:
+        target = _resolve_workspace_relative_path(workspace_root, operation.relative_path)
+        current_content = _staged_or_disk_content(target, staged_contents)
+        if operation.operation == "add":
+            if current_content is not None:
+                raise ValueError(f"file already exists: {operation.relative_path}")
+            next_content: str | None = operation.content
+        elif operation.operation == "update":
+            if current_content is None:
+                raise ValueError(f"file does not exist: {operation.relative_path}")
+            next_content = _apply_update_lines(
+                current_content,
+                operation.lines,
+                operation.relative_path,
+            )
+        elif operation.operation == "delete":
+            if current_content is None:
+                raise ValueError(f"file does not exist: {operation.relative_path}")
+            if target.is_dir():
+                raise ValueError(f"path is a directory: {operation.relative_path}")
+            next_content = None
+        elif operation.operation == "move":
+            if current_content is None:
+                raise ValueError(f"file does not exist: {operation.relative_path}")
+            if target.is_dir():
+                raise ValueError(f"path is a directory: {operation.relative_path}")
+            destination = _resolve_workspace_relative_path(
+                workspace_root,
+                operation.destination_path,
+            )
+            if destination == target:
+                raise ValueError("move destination must differ from source")
+            if _staged_or_disk_content(destination, staged_contents) is not None:
+                raise ValueError(f"file already exists: {operation.destination_path}")
+            next_content = current_content
+            if operation.lines:
+                next_content = _apply_update_lines(
+                    current_content,
+                    operation.lines,
+                    operation.relative_path,
+                )
+            staged_contents[target] = None
+            staged_contents[destination] = next_content
+            encoded = next_content.encode("utf-8")
+            changed_files.append(
+                {
+                    "path": operation.destination_path,
+                    "previous_path": operation.relative_path,
+                    "operation": operation.operation,
+                    "bytes": len(encoded),
+                    "sha256": hashlib.sha256(encoded).hexdigest(),
+                }
+            )
+            continue
+        else:  # pragma: no cover - parser owns the operation enum
+            raise ValueError(f"unsupported patch operation: {operation.operation}")
+
+        staged_contents[target] = next_content
+        encoded = (next_content or "").encode("utf-8")
+        changed_files.append(
+            {
+                "path": operation.relative_path,
+                "operation": operation.operation,
+                "bytes": len(encoded),
+                "sha256": hashlib.sha256(encoded).hexdigest(),
+            }
+        )
+
+    commit_checkpointed_text_changes(
+        store,
+        workspace_root,
+        staged_contents,
+    )
+    return {"changed_files": changed_files, "file_count": len(changed_files)}
+
+
+def _patch_history(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    limit = int(input_payload.get("limit", 20))
+    workspace_root = Path.cwd().resolve()
+    store = PatchCheckpointStore.from_environment()
+    store.recover_prepared(workspace_root)
+    return store.history(workspace_root, limit=limit)
+
+
+def _revert_patch(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    checkpoint_id = input_payload.get("checkpoint_id")
+    paths = input_payload.get("paths")
+    if not isinstance(checkpoint_id, str) or not checkpoint_id.strip():
+        raise ValueError("checkpoint_id must be a non-empty string")
+    if not isinstance(paths, list) or not all(
+        isinstance(path, str) and path for path in paths
+    ):
+        raise ValueError("paths must be a non-empty string array")
+    workspace_root = Path.cwd().resolve()
+    store = PatchCheckpointStore.from_environment()
+    store.recover_prepared(workspace_root)
+    with workspace_transaction(workspace_root):
+        revert = store.load_revert(workspace_root, checkpoint_id.strip())
+        checkpoint_paths = [
+            target.relative_to(workspace_root).as_posix()
+            for target in revert.staged_contents
+        ]
+        if paths != checkpoint_paths:
+            raise ValueError("paths do not match the reviewed checkpoint")
+        for target in revert.staged_contents:
+            _reject_symlink_path_parts(
+                workspace_root,
+                target.relative_to(workspace_root),
+            )
+        current_states = capture_text_states(revert.expected_current)
+        for target, expected_content in revert.expected_current.items():
+            if current_states[target].content != expected_content:
+                relative_path = target.relative_to(workspace_root).as_posix()
+                raise ValueError(
+                    f"current SHA-256 does not match checkpoint: {relative_path}"
+                )
+        new_checkpoint_id = commit_checkpointed_text_changes(
+            store,
+            workspace_root,
+            revert.staged_contents,
+            target_modes=revert.target_modes,
+        )
+    changed_files = []
+    for target, content in revert.staged_contents.items():
+        previous_content = revert.expected_current[target]
+        if previous_content is None:
+            operation = "add"
+        elif content is None:
+            operation = "delete"
+        else:
+            operation = "update"
+        encoded = (content or "").encode("utf-8")
+        changed_files.append(
+            {
+                "path": target.relative_to(workspace_root).as_posix(),
+                "operation": operation,
+                "bytes": len(encoded),
+                "sha256": hashlib.sha256(encoded).hexdigest(),
+            }
+        )
+    return {
+        "checkpoint_id": new_checkpoint_id,
+        "reverted_checkpoint_id": checkpoint_id.strip(),
+        "changed_files": changed_files,
+        "file_count": len(changed_files),
+    }
+
+
+def _parse_workspace_patch(patch: str) -> list[_PatchOperation]:
+    lines = patch.splitlines()
+    if not lines or lines[0] != "*** Begin Patch":
+        raise ValueError("patch must start with *** Begin Patch")
+    if lines[-1] != "*** End Patch":
+        raise ValueError("patch must end with *** End Patch")
+    operations = []
+    index = 1
+    while index < len(lines) - 1:
+        line = lines[index]
+        if line.startswith("*** Add File: "):
+            relative_path = line.removeprefix("*** Add File: ").strip()
+            if not relative_path:
+                raise ValueError("patch file path is required")
+            index += 1
+            content_lines = []
+            while index < len(lines) - 1 and not lines[index].startswith("*** "):
+                content_line = lines[index]
+                content_lines.append(
+                    content_line[1:] if content_line.startswith("+") else content_line
+                )
+                index += 1
+            if not content_lines:
+                raise ValueError("add file patch must contain at least one content line")
+            operations.append(
+                _PatchOperation(
+                    operation="add",
+                    relative_path=relative_path,
+                    content="\n".join(content_lines) + "\n",
+                )
+            )
+            continue
+        if line.startswith("*** Update File: "):
+            relative_path = line.removeprefix("*** Update File: ").strip()
+            if not relative_path:
+                raise ValueError("patch file path is required")
+            index += 1
+            destination_path = ""
+            if index < len(lines) - 1 and lines[index].startswith("*** Move to: "):
+                destination_path = lines[index].removeprefix("*** Move to: ").strip()
+                if not destination_path:
+                    raise ValueError("move destination path is required")
+                index += 1
+            update_lines = []
+            while index < len(lines) - 1 and not lines[index].startswith("*** "):
+                update_line = lines[index]
+                if update_line == "@@":
+                    index += 1
+                    continue
+                update_lines.append(update_line)
+                index += 1
+            if not update_lines and not destination_path:
+                raise ValueError("update file patch must contain at least one change line")
+            if destination_path:
+                operations.append(
+                    _PatchOperation(
+                        operation="move",
+                        relative_path=relative_path,
+                        destination_path=destination_path,
+                        lines=tuple(update_lines),
+                    )
+                )
+                continue
+            operations.append(
+                _PatchOperation(
+                    operation="update",
+                    relative_path=relative_path,
+                    lines=tuple(update_lines),
+                )
+            )
+            continue
+        if line.startswith("*** Delete File: "):
+            relative_path = line.removeprefix("*** Delete File: ").strip()
+            if not relative_path:
+                raise ValueError("patch file path is required")
+            index += 1
+            operations.append(
+                _PatchOperation(operation="delete", relative_path=relative_path)
+            )
+            continue
+        raise ValueError(
+            "only Add File, Update File, Move to, and Delete File patch hunks are supported"
+        )
+    if not operations:
+        raise ValueError("patch must contain at least one file hunk")
+    return operations
+
+
+def _staged_or_disk_content(
+    target: Path,
+    staged_contents: dict[Path, str | None],
+) -> str | None:
+    if target in staged_contents:
+        return staged_contents[target]
+    if not target.exists():
+        return None
+    if target.is_dir():
+        raise ValueError("path is a directory")
+    return target.read_text(encoding="utf-8")
+
+
+def _apply_update_lines(
+    content: str,
+    update_lines: tuple[str, ...],
+    relative_path: str,
+) -> str:
+    old_lines = []
+    new_lines = []
+    for line in update_lines:
+        if line.startswith(" "):
+            value = line[1:]
+            old_lines.append(value)
+            new_lines.append(value)
+            continue
+        if line.startswith("-"):
+            old_lines.append(line[1:])
+            continue
+        if line.startswith("+"):
+            new_lines.append(line[1:])
+            continue
+        raise ValueError("update lines must start with space, -, +, or @@")
+    if old_lines == new_lines:
+        raise ValueError("update file patch must change file content")
+    content_lines = content.splitlines()
+    start = _find_subsequence(content_lines, old_lines)
+    if start is None:
+        raise ValueError(f"update context not found: {relative_path}")
+    next_lines = content_lines[:start] + new_lines + content_lines[start + len(old_lines) :]
+    return "\n".join(next_lines) + "\n"
+
+
+def _find_subsequence(lines: list[str], needle: list[str]) -> int | None:
+    if not needle:
+        return None
+    last_start = len(lines) - len(needle)
+    for index in range(last_start + 1):
+        if lines[index : index + len(needle)] == needle:
+            return index
+    return None
+
+
+def _iter_workspace_entries(root: Path, *, max_depth: int):
+    root_depth = len(root.parts)
+    for path in sorted(root.rglob("*"), key=lambda item: item.relative_to(root).as_posix()):
+        if path.is_symlink():
+            continue
+        depth = len(path.parts) - root_depth
+        if depth > max_depth:
+            continue
+        yield path
+
+
+def _file_entry(workspace_root: Path, path: Path) -> Dict[str, Any]:
+    if path.is_dir():
+        return {
+            "path": _workspace_output_path(workspace_root, path),
+            "type": "directory",
+            "bytes": 0,
+        }
+    return {
+        "path": _workspace_output_path(workspace_root, path),
+        "type": "file",
+        "bytes": path.stat().st_size,
+    }
+
+
+def _workspace_output_path(workspace_root: Path, path: Path) -> str:
+    try:
+        relative = path.relative_to(workspace_root)
+    except ValueError as exc:
+        raise ValueError("path must stay inside the workspace") from exc
+    output = relative.as_posix()
+    return "." if output == "" else output
+
+
+def _resolve_workspace_relative_path(workspace_root: Path, relative_path: str) -> Path:
+    candidate_path = Path(relative_path)
+    if candidate_path.is_absolute():
+        raise ValueError("path must stay inside the workspace")
+    if any(part in {"", ".", ".."} for part in candidate_path.parts):
+        raise ValueError("path must stay inside the workspace")
+    _reject_symlink_path_parts(workspace_root, candidate_path)
+    normalized_path = os.path.normpath(relative_path)
+    target = (workspace_root / normalized_path).resolve()
+    try:
+        target.relative_to(workspace_root)
+    except ValueError as exc:
+        raise ValueError("path must stay inside the workspace") from exc
+    return target
+
+
+def _reject_symlink_path_parts(workspace_root: Path, candidate_path: Path) -> None:
+    current = workspace_root
+    for part in candidate_path.parts:
+        current = current / part
+        if current.is_symlink():
+            raise ValueError("path must not be a symlink")
+        if not current.exists():
+            return
+
+
+def _http_request(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    url = input_payload.get("url")
+    if not isinstance(url, str) or not url.strip():
+        raise ValueError("url must be a non-empty string")
+    normalized_url = url.strip()
+    _validate_http_request_url(normalized_url)
+    max_bytes = int(input_payload.get("max_bytes", _HTTP_REQUEST_MAX_BYTES))
+    request = urllib.request.Request(
+        normalized_url,
+        headers={"User-Agent": "kagent/0.1"},
+        method="GET",
+    )
+    try:
+        with _open_http_request_without_redirects(
+            request,
+            timeout_seconds=_HTTP_REQUEST_TIMEOUT_SECONDS,
+        ) as response:
+            body = response.read(max_bytes + 1)
+            content_type = response.headers.get("Content-Type", "")
+            status_code = int(response.status)
+    except urllib.error.HTTPError as exc:
+        body = exc.read(max_bytes + 1)
+        content_type = exc.headers.get("Content-Type", "")
+        status_code = int(exc.code)
+    except urllib.error.URLError as exc:
+        raise ValueError("http request failed") from exc
+    truncated = len(body) > max_bytes
+    if truncated:
+        body = body[:max_bytes]
+    return {
+        "url": normalized_url,
+        "status_code": status_code,
+        "content_type": content_type,
+        "body_text": body.decode("utf-8", errors="replace"),
+        "bytes": len(body),
+        "truncated": truncated,
+    }
+
+
+def _open_url(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    url = input_payload.get("url")
+    if not isinstance(url, str) or not url.strip():
+        raise ValueError("url must be a non-empty string")
+    normalized_url = url.strip()
+    _validate_open_url(normalized_url)
+    attempts = [
+        (
+            ["osascript", "-e", _chrome_open_location_script(normalized_url)],
+            "Google Chrome",
+            "osascript Google Chrome",
+        ),
+        (["open", "-a", "Google Chrome", normalized_url], "Google Chrome", "open -a Google Chrome"),
+        (["open", normalized_url], "default", "open"),
+    ]
+    last_error: BaseException | None = None
+    for command_args, application, command_label in attempts:
+        try:
+            subprocess.run(
+                command_args,
+                check=True,
+                capture_output=True,
+                text=True,
+                timeout=_OPEN_COMMAND_TIMEOUT_SECONDS,
+            )
+            return {
+                "url": normalized_url,
+                "opened": True,
+                "application": application,
+                "command": command_label,
+            }
+        except subprocess.TimeoutExpired as exc:
+            raise TimeoutError("open url command timed out") from exc
+        except (OSError, subprocess.CalledProcessError) as exc:
+            last_error = exc
+            continue
+    raise ValueError("open url failed") from last_error
+
+
+def _open_app(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    application = input_payload.get("application")
+    if not isinstance(application, str) or not application.strip():
+        raise ValueError("application must be a non-empty string")
+    normalized_application = " ".join(application.strip().split())
+    _validate_open_app_name(normalized_application)
+    try:
+        subprocess.run(
+            ["open", "-a", normalized_application],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=_OPEN_COMMAND_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise TimeoutError("open app command timed out") from exc
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise ValueError("open app failed") from exc
+    return {
+        "application": normalized_application,
+        "opened": True,
+        "command": "open -a",
+    }
+
+
+def _validate_open_app_name(application: str) -> None:
+    if len(application) > _APP_NAME_MAX_LENGTH:
+        raise ValueError("application name is too long")
+    if "\x00" in application or "\n" in application or "\r" in application:
+        raise ValueError("application must be a single line")
+    if application.startswith("-"):
+        raise ValueError("application must not start with -")
+    if "/" in application or "\\" in application:
+        raise ValueError("application must be an app name, not a path")
+    if not _APP_NAME_ALLOWED_PATTERN.match(application):
+        raise ValueError("application contains unsupported characters")
+
+
+def _validate_open_url(url: str) -> None:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("url must start with http:// or https://")
+    if not parsed.hostname:
+        raise ValueError("url host is required")
+    if parsed.username or parsed.password:
+        raise ValueError("url must not contain credentials")
+    _validate_url_without_secret_like_query_or_fragment(parsed)
+
+
+def _chrome_open_location_script(url: str) -> str:
+    escaped_url = _apple_script_string(url)
+    return (
+        'tell application "Google Chrome"\n'
+        "  activate\n"
+        "  if (count of windows) = 0 then make new window\n"
+        "  tell front window\n"
+        f"    make new tab at end of tabs with properties {{URL:{escaped_url}}}\n"
+        "    set active tab index to (count of tabs)\n"
+        "  end tell\n"
+        "end tell"
+    )
+
+
+def _apple_script_string(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def _open_http_request_without_redirects(
+    request: urllib.request.Request,
+    *,
+    timeout_seconds: float,
+):
+    opener = urllib.request.build_opener(_NoRedirectHandler)
+    try:
+        return opener.open(request, timeout=timeout_seconds)
+    except urllib.error.HTTPError as exc:
+        if exc.code in _HTTP_REDIRECT_STATUS_CODES:
+            return exc
+        raise
+
+
+def _validate_http_request_url(url: str) -> None:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("url must start with http:// or https://")
+    if not parsed.hostname:
+        raise ValueError("url host is required")
+    if parsed.username or parsed.password:
+        raise ValueError("url must not contain credentials")
+    _validate_url_without_secret_like_query_or_fragment(parsed)
+    host = parsed.hostname.strip().lower()
+    if host in _BLOCKED_HTTP_HOSTS or host.endswith(".localhost"):
+        raise ValueError("url host is not allowed")
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        _validate_resolved_http_host(host, parsed.port)
+        return
+    if _is_blocked_http_address(address):
+        raise ValueError("url host is not allowed")
+
+
+def _validate_resolved_http_host(host: str, port: int | None) -> None:
+    try:
+        records = socket.getaddrinfo(host, port or 443, type=socket.SOCK_STREAM)
+    except socket.gaierror as exc:
+        raise ValueError("url host could not be resolved") from exc
+    for record in records:
+        sockaddr = record[4]
+        if not sockaddr:
+            continue
+        try:
+            address = ipaddress.ip_address(sockaddr[0])
+        except ValueError as exc:
+            raise ValueError("url host resolved to an invalid address") from exc
+        if _is_blocked_http_address(address):
+            raise ValueError("url host is not allowed")
+
+
+def _validate_url_without_secret_like_query_or_fragment(
+    parsed: urllib.parse.ParseResult,
+) -> None:
+    for item in (parsed.query, parsed.fragment):
+        if _has_secret_like_url_part(item):
+            raise ValueError("url must not contain secret-like query or fragment")
+
+
+def _has_secret_like_url_part(value: str) -> bool:
+    if not value:
+        return False
+    pairs = urllib.parse.parse_qsl(value, keep_blank_values=True)
+    if not pairs:
+        pairs = [(value, "")]
+    for key, item in pairs:
+        normalized_key = key.lower().replace("-", "_")
+        if any(part in normalized_key for part in _URL_SECRET_KEY_PARTS):
+            return True
+        if any(pattern.search(item) for pattern in _URL_SECRET_VALUE_PATTERNS):
+            return True
+    return False
+
+
+def _is_blocked_http_address(address: ipaddress._BaseAddress) -> bool:
+    return (
+        address.is_loopback
+        or address.is_private
+        or address.is_link_local
+        or address.is_multicast
+        or address.is_reserved
+        or address.is_unspecified
+    )
+
+
+def _artifact(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    title = input_payload.get("title")
+    kind = input_payload.get("kind")
+    content = input_payload.get("content")
+    artifact_format = input_payload.get("format", "markdown")
+    tags = input_payload.get("tags", [])
+
+    if not isinstance(title, str) or not title.strip():
+        raise ValueError("title must be a non-empty string")
+    if kind not in _ARTIFACT_KINDS:
+        raise ValueError("kind must be report, plan, decision, data, or message")
+    if not isinstance(content, str) or not content.strip():
+        raise ValueError("content must be a non-empty string")
+    if artifact_format not in _ARTIFACT_FORMATS:
+        raise ValueError("format must be markdown, plain_text, or json")
+    if not isinstance(tags, list):
+        raise ValueError("tags must be an array")
+
+    normalized_title = title.strip()
+    normalized_tags = []
+    for index, tag in enumerate(tags):
+        if not isinstance(tag, str):
+            raise ValueError(f"tag {index} must be a string")
+        normalized_tag = tag.strip()
+        if normalized_tag:
+            normalized_tags.append(normalized_tag)
+
+    artifact_id = _artifact_id(normalized_title, str(kind), str(artifact_format), content)
+    return {
+        "artifact_id": artifact_id,
+        "title": normalized_title,
+        "kind": kind,
+        "format": artifact_format,
+        "content": content,
+        "tags": normalized_tags,
+        "bytes": len(content.encode("utf-8")),
+    }
+
+
+def _artifact_id(title: str, kind: str, artifact_format: str, content: str) -> str:
+    digest = hashlib.sha256(
+        "|".join([title, kind, artifact_format, content]).encode("utf-8")
+    ).hexdigest()
+    return f"artifact_{digest[:12]}"
+
+
+def _decision_matrix(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    question = input_payload.get("question")
+    criteria = input_payload.get("criteria")
+    options = input_payload.get("options")
+
+    if not isinstance(question, str) or not question.strip():
+        raise ValueError("question must be a non-empty string")
+    if not isinstance(criteria, list) or not criteria:
+        raise ValueError("criteria must be a non-empty array")
+    if not isinstance(options, list) or len(options) < 2:
+        raise ValueError("options must contain at least 2 item(s)")
+
+    normalized_criteria = _normalize_decision_criteria(criteria)
+    rankings = _rank_decision_options(options, normalized_criteria)
+    return {
+        "question": question.strip(),
+        "criteria": normalized_criteria,
+        "rankings": rankings,
+        "winner": rankings[0]["name"],
+    }
+
+
+def _normalize_decision_criteria(criteria: list[Any]) -> list[Dict[str, Any]]:
+    normalized = []
+    for index, criterion in enumerate(criteria):
+        if not isinstance(criterion, dict):
+            raise ValueError(f"criterion {index} must be an object")
+        name = criterion.get("name")
+        weight = criterion.get("weight")
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError(f"criterion {index} name must be a non-empty string")
+        if not _is_number(weight):
+            raise ValueError(f"criterion {index} weight must be a number")
+        normalized.append({"name": name.strip(), "weight": float(weight)})
+    return normalized
+
+
+def _rank_decision_options(
+    options: list[Any],
+    criteria: list[Dict[str, Any]],
+) -> list[Dict[str, Any]]:
+    scored_options = []
+    for index, option in enumerate(options):
+        if not isinstance(option, dict):
+            raise ValueError(f"option {index} must be an object")
+        name = option.get("name")
+        scores = option.get("scores")
+        rationale = option.get("rationale", "")
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError(f"option {index} name must be a non-empty string")
+        if not isinstance(scores, list) or len(scores) != len(criteria):
+            raise ValueError(
+                f"option {index} scores must match the number of criteria"
+            )
+        if not isinstance(rationale, str):
+            raise ValueError(f"option {index} rationale must be a string")
+        normalized_scores = []
+        total = 0.0
+        for score_index, score in enumerate(scores):
+            if not _is_number(score):
+                raise ValueError(f"option {index} score {score_index} must be a number")
+            normalized_score = float(score)
+            normalized_scores.append(normalized_score)
+            total += normalized_score * float(criteria[score_index]["weight"])
+        scored_options.append(
+            {
+                "name": name.strip(),
+                "score": round(total, 4),
+                "scores": normalized_scores,
+                "rationale": rationale.strip(),
+            }
+        )
+
+    ranked = sorted(scored_options, key=lambda item: (-item["score"], item["name"]))
+    for index, option in enumerate(ranked, start=1):
+        option["rank"] = index
+    return [
+        {
+            "rank": option["rank"],
+            "name": option["name"],
+            "score": option["score"],
+            "scores": option["scores"],
+            "rationale": option["rationale"],
+        }
+        for option in ranked
+    ]
+
+
+def _validate_tool_input(value: Any, schema: Dict[str, Any], path: str = "input") -> None:
+    expected_type = schema.get("type")
+    if expected_type == "object":
+        _validate_object(value, schema, path)
+    elif expected_type == "array":
+        _validate_array(value, schema, path)
+    elif expected_type == "string":
+        if not isinstance(value, str):
+            raise ValueError(f"{path} must be a string")
+        min_length = schema.get("minLength")
+        if isinstance(min_length, int) and len(value.strip()) < min_length:
+            raise ValueError(
+                f"{path} must contain at least {min_length} character(s)"
+            )
+        max_length = schema.get("maxLength")
+        if isinstance(max_length, int) and len(value) > max_length:
+            raise ValueError(f"{path} must contain at most {max_length} character(s)")
+    elif expected_type == "number":
+        if not _is_number(value):
+            raise ValueError(f"{path} must be a number")
+        minimum = schema.get("minimum")
+        if _is_number(minimum) and value < minimum:
+            raise ValueError(f"{path} must be at least {minimum:g}")
+        maximum = schema.get("maximum")
+        if _is_number(maximum) and value > maximum:
+            raise ValueError(f"{path} must be at most {maximum:g}")
+    elif expected_type == "boolean":
+        if not isinstance(value, bool):
+            raise ValueError(f"{path} must be a boolean")
+
+    enum_values = schema.get("enum")
+    if isinstance(enum_values, list) and value not in enum_values:
+        allowed = ", ".join(str(item) for item in enum_values)
+        raise ValueError(f"{path} must be one of: {allowed}")
+
+
+def _validate_object(value: Any, schema: Dict[str, Any], path: str) -> None:
+    if not isinstance(value, dict):
+        raise ValueError(f"{path} must be an object")
+    properties = schema.get("properties", {})
+    if not isinstance(properties, dict):
+        properties = {}
+    required = schema.get("required", [])
+    if not isinstance(required, list):
+        required = []
+    for key in required:
+        if key not in value:
+            raise ValueError(f"{path}.{key} is required")
+    if schema.get("additionalProperties") is False:
+        for key in value:
+            if key not in properties:
+                raise ValueError(f"{path}.{key} is not allowed")
+    for key, property_schema in properties.items():
+        if key in value and isinstance(property_schema, dict):
+            _validate_tool_input(value[key], property_schema, f"{path}.{key}")
+
+
+def _validate_array(value: Any, schema: Dict[str, Any], path: str) -> None:
+    if not isinstance(value, list):
+        raise ValueError(f"{path} must be an array")
+    min_items = schema.get("minItems")
+    if isinstance(min_items, int) and len(value) < min_items:
+        raise ValueError(f"{path} must contain at least {min_items} item(s)")
+    max_items = schema.get("maxItems")
+    if isinstance(max_items, int) and len(value) > max_items:
+        raise ValueError(f"{path} must contain at most {max_items} item(s)")
+    item_schema = schema.get("items")
+    if isinstance(item_schema, dict):
+        for index, item in enumerate(value):
+            _validate_tool_input(item, item_schema, f"{path}[{index}]")
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _utc_timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _duration_since(started_at: float) -> str:
+    return f"{time.perf_counter() - started_at:.4f}"
+
+
+def _delegate_task(
+    input_payload: Dict[str, Any],
+    *,
+    delegate_runner: Callable[[str, int], Dict[str, Any]] | None,
+) -> Dict[str, Any]:
+    if delegate_runner is None:
+        raise ValueError("delegate runner is not configured")
+    goal = input_payload.get("goal")
+    if not isinstance(goal, str) or not goal.strip():
+        raise ValueError("goal must be a non-empty string")
+    max_iterations = int(input_payload.get("max_iterations", 1))
+    if max_iterations < 1 or max_iterations > _DELEGATE_MAX_ITERATIONS:
+        raise ValueError(
+            f"max_iterations must be between 1 and {_DELEGATE_MAX_ITERATIONS}"
+        )
+    child = delegate_runner(goal.strip(), max_iterations)
+    observations = child.get("observations", [])
+    if not isinstance(observations, list):
+        observations = []
+    return {
+        "child_run_id": str(child.get("run_id", "")),
+        "status": str(child.get("status", "")),
+        "answer": str(child.get("answer", "")),
+        "error_code": str(child.get("error_code", "")),
+        "child_iteration_count": str(child.get("iteration_count", "")),
+        "child_observation_count": str(len(observations)),
+    }
+
+
+def _transform_text(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    text = input_payload.get("text")
+    mode = input_payload.get("mode")
+    if not isinstance(text, str):
+        raise ValueError("text must be a string")
+    if mode == "uppercase":
+        return {"text": text.upper()}
+    if mode == "lowercase":
+        return {"text": text.lower()}
+    if mode == "reverse":
+        return {"text": text[::-1]}
+    if mode == "trim":
+        return {"text": text.strip()}
+    raise ValueError("mode must be uppercase, lowercase, reverse, or trim")
+
+
+def _rubric_score(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    criteria = input_payload.get("criteria")
+    if not isinstance(criteria, list) or not criteria:
+        raise ValueError("criteria must be a non-empty array")
+
+    normalized_criteria = []
+    failed_criteria = []
+    blocking_failures = []
+    passed_count = 0
+    for index, criterion in enumerate(criteria):
+        if not isinstance(criterion, dict):
+            raise ValueError(f"criterion {index} must be an object")
+        name = criterion.get("name")
+        passed = criterion.get("passed")
+        severity = criterion.get("severity", "normal")
+        evidence = criterion.get("evidence", "")
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError(f"criterion {index} name must be a non-empty string")
+        if not isinstance(passed, bool):
+            raise ValueError(f"criterion {index} passed must be a boolean")
+        if severity not in _RUBRIC_SEVERITIES:
+            raise ValueError(f"criterion {index} severity must be low, normal, or blocking")
+        if not isinstance(evidence, str):
+            raise ValueError(f"criterion {index} evidence must be a string")
+
+        normalized_name = name.strip()
+        normalized = {
+            "name": normalized_name,
+            "passed": passed,
+            "severity": severity,
+            "evidence": evidence.strip(),
+        }
+        normalized_criteria.append(normalized)
+        if passed:
+            passed_count += 1
+            continue
+        failed_criteria.append(normalized_name)
+        if severity == "blocking":
+            blocking_failures.append(normalized_name)
+
+    total = len(normalized_criteria)
+    failed_count = total - passed_count
+    return {
+        "criteria": normalized_criteria,
+        "passed": passed_count,
+        "failed": failed_count,
+        "total": total,
+        "score_percent": round((passed_count / total) * 100, 2),
+        "blocking_failures": blocking_failures,
+        "failed_criteria": failed_criteria,
+    }
+
+
+def _task_list(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    items = input_payload.get("items")
+    if not isinstance(items, list) or not items:
+        raise ValueError("items must be a non-empty array")
+
+    normalized_items = []
+    counts = {status: 0 for status in _TASK_STATUSES}
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise ValueError(f"item {index} must be an object")
+        normalized = _normalize_task_item(item, index)
+        normalized_items.append(normalized)
+        counts[normalized["status"]] += 1
+    return {
+        "items": normalized_items,
+        "counts": counts,
+        "total": len(normalized_items),
+    }
+
+
+def _task_transition(input_payload: Dict[str, Any]) -> Dict[str, Any]:
+    state = input_payload.get("state")
+    event = input_payload.get("event")
+    if not isinstance(state, str):
+        raise ValueError("state must be a string")
+    if not isinstance(event, str):
+        raise ValueError("event must be a string")
+    return TaskStateMachine().transition(state, event)
+
+
+def _normalize_task_item(item: Dict[str, Any], index: int) -> Dict[str, Any]:
+    title = item.get("title")
+    if not isinstance(title, str) or not title.strip():
+        raise ValueError(f"item {index} title must be a non-empty string")
+    status = item.get("status", "pending")
+    if status not in _TASK_STATUSES:
+        raise ValueError(
+            f"item {index} status must be pending, in_progress, blocked, done, or failed"
+        )
+    priority = item.get("priority", "normal")
+    if priority not in _TASK_PRIORITIES:
+        raise ValueError(f"item {index} priority must be low, normal, or high")
+
+    normalized = {
+        "title": title.strip(),
+        "status": status,
+        "priority": priority,
+    }
+    for optional_field in ["owner", "due"]:
+        value = item.get(optional_field, "")
+        if value == "":
+            continue
+        if not isinstance(value, str):
+            raise ValueError(f"item {index} {optional_field} must be a string")
+        normalized[optional_field] = value
+    return normalized