monoid-agent-kernel 0.16.1__py3-none-any.whl

monoid_agent_kernel/__init__.py

@@ -0,0 +1,11 @@
+"""Monoid Agent Kernel: the stable contracts and core engine entrypoints.
+
+The top-level package mirrors ``monoid_agent_kernel.contracts``. Helper kit,
+provider, recorder, MCP, observability, and reference implementations are imported
+from their explicit modules.
+"""
+
+from monoid_agent_kernel import contracts as contracts
+from monoid_agent_kernel.contracts import *  # noqa: F401,F403
+
+__all__ = [*contracts.__all__]

monoid_agent_kernel/_policy_util.py

@@ -0,0 +1,40 @@
+"""Shared coercion helpers for execution-boundary dataclasses.
+
+Used by permission and runtime execution parsers to keep JSON array handling
+consistent. Internal helper.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Callable
+
+
+def str_tuple(
+    value: Any,
+    *,
+    type_error: str,
+    empty_error: str | None = None,
+    normalize: bool = False,
+    error: Callable[[str], Exception] = ValueError,
+) -> tuple[str, ...]:
+    """Coerce a JSON array into a tuple of strings.
+
+    A bare string (or any non-array) is rejected with ``type_error``. With
+    ``normalize=True`` each item is stripped, lowercased, and empties are
+    dropped (domain lists). Otherwise, when ``empty_error`` is given, an
+    empty/whitespace item raises it. ``error`` selects the exception type.
+    """
+    if isinstance(value, str) or not isinstance(value, (list, tuple)):
+        raise error(type_error)
+    items = tuple(str(item) for item in value)
+    if normalize:
+        return tuple(item.strip().lower() for item in items if item.strip())
+    if empty_error is not None and any(not item.strip() for item in items):
+        raise error(empty_error)
+    return items
+
+
+def dedupe(values: Iterable[str]) -> tuple[str, ...]:
+    """Order-preserving de-duplication."""
+    return tuple(dict.fromkeys(values))

monoid_agent_kernel/_proc.py

@@ -0,0 +1,86 @@
+"""Low-level process and filesystem primitives shared by shell and jobs.
+
+Domain-neutral helpers that both the foreground shell runner (``shell.py``) and
+the background job manager (``jobs.py``) depend on. Internal only; not part of
+the supported public surface.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from pathlib import Path
+from typing import IO
+
+
+def file_size(path: Path) -> int:
+    """Size of ``path`` in bytes, or ``0`` if it does not exist."""
+    try:
+        return path.stat().st_size
+    except FileNotFoundError:
+        return 0
+
+
+def proc_group_kwargs() -> dict[str, object]:
+    """Platform kwargs that put a child in its own process group so the whole tree can
+    be terminated together by :func:`terminate_process`. Shared by the sync ``Popen`` and
+    the asyncio (``create_subprocess_exec``) spawn paths so they behave identically."""
+    if os.name == "nt":
+        return {"creationflags": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)}
+    return {"preexec_fn": os.setsid}
+
+
+def spawn_process(
+    argv: list[str],
+    *,
+    cwd: Path,
+    env: dict[str, str],
+    stdout: IO[bytes],
+    stderr: IO[bytes],
+) -> subprocess.Popen[bytes]:
+    """Start ``argv`` in its own process group with stdin disabled.
+
+    A new process group (Windows ``CREATE_NEW_PROCESS_GROUP`` / POSIX
+    ``setsid``) lets the whole child tree be terminated together by
+    :func:`terminate_process`.
+    """
+    return subprocess.Popen(
+        argv,
+        cwd=cwd,
+        env=env,
+        stdin=subprocess.DEVNULL,
+        stdout=stdout,
+        stderr=stderr,
+        **proc_group_kwargs(),  # type: ignore[arg-type]
+    )
+
+
+# The external group-killer (``taskkill``) is itself a spawned process; under load/AV its
+# spawn can stall. Bound it so a stalled kill can never block the caller — the foreground
+# shell loop or the background job monitor thread — indefinitely.
+_TERMINATE_TIMEOUT_S = 10.0
+
+
+def terminate_process(process: subprocess.Popen[bytes]) -> None:
+    """Terminate ``process`` and its group, falling back to a direct ``kill`` on error or if
+    the group kill does not return promptly. The group kill (Windows ``taskkill``) is bounded
+    by a timeout so a stalled killer escalates to ``process.kill()`` instead of hanging."""
+    try:
+        if os.name == "nt":
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(process.pid)],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=False,
+                timeout=_TERMINATE_TIMEOUT_S,
+            )
+        else:
+            os.killpg(process.pid, signal.SIGTERM)
+    except Exception:
+        # taskkill timed out / failed, or killpg failed: terminate the child handle directly.
+        try:
+            process.kill()
+        except Exception:
+            pass

monoid_agent_kernel/builder.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+import click
+
+from monoid_agent_kernel.core.agents import (
+    AgentDefinition,
+    AgentRuntimeConfig,
+    ToolBinding,
+    collect_runtime_config_issues,
+)
+from monoid_agent_kernel.skills import SkillProvider, load_skill_definitions
+from monoid_agent_kernel.subagent_loader import load_subagent_definitions
+from monoid_agent_kernel.tool_loader import load_tool_provider
+from monoid_agent_kernel.tools.base import ToolRegistry, ToolSpec
+from monoid_agent_kernel.tools.builtin import agent_spawn_tool
+from monoid_agent_kernel.tools.tool_ids import list_builtin_tools
+
+
+@click.group("builder")
+def builder_group() -> None:
+    """Scaffold and inspect Monoid builder configuration."""
+
+
+@builder_group.command("init")
+@click.option("--target", type=click.Path(path_type=Path), required=True)
+@click.option("--force", is_flag=True, help="Overwrite existing scaffold files.")
+@click.option("--custom-tool-template", is_flag=True, help="Also write a tools.py provider template.")
+def builder_init(target: Path, force: bool, custom_tool_template: bool) -> None:
+    """Create minimal files for a local monoid run."""
+    target.mkdir(parents=True, exist_ok=True)
+    files: dict[str, str] = {
+        "runtime-config.json": _pretty_json(_default_runtime_config()),
+        "run-spec.json": _pretty_json(_default_run_spec()),
+    }
+    if custom_tool_template:
+        files["tools.py"] = _CUSTOM_TOOLS_TEMPLATE
+
+    paths = {name: target / name for name in files}
+    if not force:
+        collisions = [path for path in paths.values() if path.exists()]
+        if collisions:
+            names = ", ".join(str(path) for path in collisions)
+            raise click.ClickException(f"{names} already exists; pass --force to overwrite")
+
+    written: list[Path] = []
+    for name, content in files.items():
+        path = paths[name]
+        path.write_text(content, encoding="utf-8")
+        written.append(path)
+
+    for path in written:
+        click.echo(f"created: {path}")
+
+
+@builder_group.group("config")
+def builder_config_group() -> None:
+    """Inspect and validate builder config files."""
+
+
+@builder_config_group.command("validate")
+@click.option("--runtime-config-file", type=click.Path(path_type=Path), default=None)
+@click.option("--agent-definition-file", type=click.Path(path_type=Path), default=None)
+@click.option("--tool-module", multiple=True, help="Load custom tools from path.py:function.")
+@click.option(
+    "--skills-directory",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Load Agent Skills from a directory.",
+)
+@click.option(
+    "--agents-directory",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Load subagent definitions from a directory.",
+)
+@click.option("--json", "json_output", is_flag=True, help="Print machine-readable JSON.")
+@click.pass_context
+def builder_config_validate(
+    ctx: click.Context,
+    *,
+    runtime_config_file: Path | None,
+    agent_definition_file: Path | None,
+    tool_module: tuple[str, ...],
+    skills_directory: Path | None,
+    agents_directory: Path | None,
+    json_output: bool,
+) -> None:
+    """Validate a runtime config against the tools the run would register."""
+    try:
+        config = _load_agent_runtime_config(runtime_config_file, agent_definition_file)
+        registry, registration_issues, skill_bindings = _build_tool_registry(
+            tool_modules=tool_module,
+            skills_directory=skills_directory,
+            agents_directory=agents_directory,
+        )
+        effective_config = (
+            replace(config, tools=config.tools + skill_bindings) if skill_bindings else config
+        )
+        issues = registration_issues + collect_runtime_config_issues(effective_config, registry)
+    except click.ClickException:
+        raise
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    payload = {
+        "ok": not issues,
+        "definition_id": config.definition_id,
+        "tool_count": len(registry.specs()),
+        "bound_tool_count": len(effective_config.tools)
+        + (1 if effective_config.tool_search.enabled else 0),
+        "issues": issues,
+    }
+    if json_output:
+        click.echo(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+    elif issues:
+        click.echo("invalid")
+        for issue in issues:
+            click.echo(f"- {issue}")
+    else:
+        click.echo("valid")
+
+    if issues:
+        ctx.exit(1)
+
+
+@builder_group.group("tools")
+def builder_tools_group() -> None:
+    """Inspect available builder tools."""
+
+
+@builder_tools_group.command("list")
+@click.option("--tool-module", multiple=True, help="Load custom tools from path.py:function.")
+@click.option(
+    "--skills-directory",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Load Agent Skills from a directory.",
+)
+@click.option(
+    "--runtime-config-file",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Mark tools bound by a runtime config.",
+)
+@click.option("--json", "json_output", is_flag=True, help="Print machine-readable JSON.")
+def builder_tools_list(
+    *,
+    tool_module: tuple[str, ...],
+    skills_directory: Path | None,
+    runtime_config_file: Path | None,
+    json_output: bool,
+) -> None:
+    """List builtin, custom, and skill tools."""
+    try:
+        registry, registration_issues, skill_bindings = _build_tool_registry(
+            tool_modules=tool_module,
+            skills_directory=skills_directory,
+            agents_directory=None,
+        )
+        if registration_issues:
+            raise click.ClickException("; ".join(registration_issues))
+        config = _load_runtime_config_file(runtime_config_file) if runtime_config_file else None
+        effective_config = (
+            replace(config, tools=config.tools + skill_bindings)
+            if config is not None and skill_bindings
+            else config
+        )
+    except click.ClickException:
+        raise
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    binding_ids_by_tool = _binding_ids_by_tool(effective_config)
+    tools = [
+        _tool_payload(spec, binding_ids_by_tool.get(spec.id, ()))
+        for spec in sorted(registry.specs(), key=lambda item: item.id)
+    ]
+    payload = {"tools": tools}
+    if json_output:
+        click.echo(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+        return
+
+    for tool in tools:
+        marker = " [bound]" if tool["bound"] else ""
+        click.echo(f"{tool['id']}{marker} - {tool['description']}")
+
+
+def _load_agent_runtime_config(
+    runtime_config_file: Path | None,
+    agent_definition_file: Path | None,
+) -> AgentRuntimeConfig:
+    if runtime_config_file is not None and agent_definition_file is not None:
+        raise click.ClickException("--runtime-config-file and --agent-definition-file are mutually exclusive")
+    if runtime_config_file is None and agent_definition_file is None:
+        raise click.ClickException("--runtime-config-file or --agent-definition-file is required")
+    if runtime_config_file is not None:
+        return _load_runtime_config_file(runtime_config_file)
+
+    assert agent_definition_file is not None
+    try:
+        payload = json.loads(agent_definition_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"invalid agent config JSON: {exc.msg}") from exc
+    try:
+        return AgentRuntimeConfig.from_definition(AgentDefinition.from_json(payload))
+    except Exception as exc:
+        raise click.ClickException(f"failed to load agent runtime config: {exc}") from exc
+
+
+def _load_runtime_config_file(path: Path) -> AgentRuntimeConfig:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"invalid agent config JSON: {exc.msg}") from exc
+    try:
+        return AgentRuntimeConfig.from_json(payload)
+    except Exception as exc:
+        raise click.ClickException(f"failed to load agent runtime config: {exc}") from exc
+
+
+def _build_tool_registry(
+    *,
+    tool_modules: tuple[str, ...],
+    skills_directory: Path | None,
+    agents_directory: Path | None,
+) -> tuple[ToolRegistry, list[str], tuple[ToolBinding, ...]]:
+    registry = ToolRegistry()
+    issues: list[str] = []
+    skill_bindings: tuple[ToolBinding, ...] = ()
+    subagents: dict[str, Any] = {}
+
+    _register_many(registry, list_builtin_tools(), issues)
+
+    for item in tool_modules:
+        provider = load_tool_provider(item)
+        _register_many(registry, provider.get_tools(None), issues)  # type: ignore[arg-type]
+
+    if skills_directory is not None:
+        skill_definitions = load_skill_definitions(skills_directory)
+        if skill_definitions:
+            skill_provider = SkillProvider(skill_definitions)
+            skill_tools = tuple(skill_provider.get_tools(None))
+            _register_many(registry, skill_tools, issues)
+            skill_bindings = skill_provider.tool_bindings()
+            subagents.update(skill_provider.subagent_definitions())
+
+    if agents_directory is not None:
+        subagents.update(load_subagent_definitions(agents_directory))
+    if subagents:
+        _register_many(
+            registry,
+            [agent_spawn_tool({name: definition.description for name, definition in subagents.items()})],
+            issues,
+        )
+
+    return registry, issues, skill_bindings
+
+
+def _register_many(registry: ToolRegistry, specs: Any, issues: list[str]) -> None:
+    for spec in specs:
+        try:
+            registry.register(spec)
+        except ValueError as exc:
+            issues.append(str(exc))
+
+
+def _binding_ids_by_tool(config: AgentRuntimeConfig | None) -> dict[str, tuple[str, ...]]:
+    if config is None:
+        return {}
+    bindings: dict[str, list[str]] = {}
+    for binding in config.tools:
+        bindings.setdefault(binding.ref.tool_id, []).append(binding.binding_id)
+    if config.tool_search.enabled:
+        bindings.setdefault("tool.search", []).append(config.tool_search.binding_id)
+    return {tool_id: tuple(ids) for tool_id, ids in bindings.items()}
+
+
+def _tool_payload(spec: ToolSpec, binding_ids: tuple[str, ...]) -> dict[str, Any]:
+    return {
+        "id": spec.id,
+        "exported_name": spec.exported_name,
+        "capability": spec.capability,
+        "side_effect": spec.side_effect,
+        "description": spec.description.split("\n", 1)[0],
+        "bound": bool(binding_ids),
+        "binding_ids": list(binding_ids),
+    }
+
+
+def _default_runtime_config() -> dict[str, Any]:
+    return {
+        "definition_id": "builder-agent",
+        "config_version": 1,
+        "model": {
+            "provider": "gateway",
+            "model": "gpt-5.5",
+            "gateway_url": "http://127.0.0.1:8080/internal/llm/turns",
+            "reasoning": {"effort": "low", "summary": "off"},
+        },
+        "prompt": {
+            "persona_segments": ["Work directly in the workspace and keep changes focused."],
+            "runtime_segments": [],
+        },
+        "tools": [
+            {"binding_id": "read_file", "model_name": "read_file", "ref": {"kind": "registry", "tool_id": "fs.read"}},
+            {
+                "binding_id": "write_file",
+                "model_name": "write_file",
+                "ref": {"kind": "registry", "tool_id": "fs.write"},
+            },
+            {"binding_id": "finish", "model_name": "finish", "ref": {"kind": "registry", "tool_id": "run.finish"}},
+        ],
+        "tool_search": {"enabled": True, "top_k": 5},
+    }
+
+
+def _default_run_spec() -> dict[str, Any]:
+    return {
+        "workspace_root": ".",
+        "run_root": "runs",
+        "mode": "propose",
+        "workspace_backend": "overlay",
+        "limits": {"max_steps": 30},
+    }
+
+
+def _pretty_json(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+
+
+_CUSTOM_TOOLS_TEMPLATE = '''from __future__ import annotations
+
+from monoid_agent_kernel import tool
+
+
+@tool(id="custom.word_count", side_effect="read")
+def word_count(text: str) -> dict:
+    """Count words in a text string."""
+    words = [part for part in text.split() if part]
+    return {"words": len(words)}
+
+
+def get_tools(context) -> list:
+    del context
+    return [word_count]
+'''