calfkit-tools 0.1.0__py3-none-any.whl

calfkit_tools/__init__.py

@@ -0,0 +1,20 @@
+"""calfkit-tools — vendored agent tools for the calfkit SDK.
+
+Tools are organised by the upstream source they were vendored from, each as a
+subpackage of ``calfkit_tools``. Import the deployable tool nodes directly from a
+source's ``node`` module::
+
+    from calfkit_tools.hermes.node import HERMES_NODES, terminal, todo, web_search
+    from calfkit_tools.web_fetch.node import web_fetch
+
+Each subpackage keeps its vendored upstream code under ``_vendor`` (and, for
+hermes, app-runtime stand-ins under ``_shims``); provenance for every source
+lives outside the package in ``vendor/<source>/`` (upstream ``LICENSE`` +
+``METADATA.yaml``). See ``THIRD_PARTY_NOTICES.md``.
+
+This module is intentionally side-effect free: importing ``calfkit_tools`` pulls
+in no tool code or optional dependencies. Import the specific ``.node`` module
+for the tools you need.
+"""
+
+__all__: list[str] = []

calfkit_tools/hermes/_shims/agent/auxiliary_client.py

@@ -0,0 +1,11 @@
+"""Shim for hermes-agent ``agent.auxiliary_client``.
+
+``call_llm`` makes a secondary LLM call (used only by approval's "smart approve" path,
+which is non-default). calfkit wires its own LLM elsewhere; this raises so the caller's
+try/except falls back to escalation (the secure direction). Stage D may wire this to
+calfkit's LLM if smart-approve is wanted.
+"""
+
+
+def call_llm(*args, **kwargs):
+    raise RuntimeError("call_llm is not available in the calfkit-tools hermes shim")

calfkit_tools/hermes/_shims/agent/lsp/__init__.py

@@ -0,0 +1,10 @@
+"""Shim for hermes-agent ``agent.lsp`` — LSP-diagnostics-on-edit enrichment.
+
+LSP is a pure enrichment layer for file edits; every call site is gated and try/except'd.
+The shim fails closed: ``get_service`` returns None so file edits proceed without
+post-edit diagnostics. (Port the real ``agent/lsp`` later if diagnostics are wanted.)
+"""
+
+
+def get_service():
+    return None

calfkit_tools/hermes/_shims/agent/lsp/range_shift.py

@@ -0,0 +1,6 @@
+"""Shim for ``agent.lsp.range_shift``. Identity line-shift (no LSP diagnostics)."""
+from typing import Callable, Optional
+
+
+def build_line_shift(pre_text: str, post_text: str) -> Callable[[int], Optional[int]]:
+    return lambda line: line

calfkit_tools/hermes/_shims/agent/lsp/reporter.py

@@ -0,0 +1,11 @@
+"""Shim for ``agent.lsp.reporter``. No diagnostics to report."""
+
+
+def report_for_file(*args, **kwargs) -> str:
+    return ""
+
+
+def truncate(s: str, *, limit: int = 10000) -> str:
+    if s is None:
+        return s
+    return s if len(s) <= limit else s[:limit]

calfkit_tools/hermes/_shims/agent/lsp/servers.py

@@ -0,0 +1,4 @@
+"""Shim for ``agent.lsp.servers``. No LSP servers configured."""
+from typing import List
+
+SERVERS: List = []

calfkit_tools/hermes/_shims/gateway/session_context.py

@@ -0,0 +1,24 @@
+"""Shim for hermes-agent ``gateway.session_context``.
+
+Provides the symbols the vendored tree imports: ``_UNSET``, ``_VAR_MAP``,
+``get_session_env``. Upstream backs these with per-request ContextVars to inject
+session-scoped env vars into subprocesses.
+
+NOTE (Stage D): the real per-tenant isolation lives here. For the adapt stage this is a
+minimal env-backed version so the tree imports and single-tenant behaviour is correct;
+``_VAR_MAP`` is empty so no session vars are injected. Stage D must replace this with the
+real ContextVar mechanism (re-keyed on the calfkit session_key) — see design doc §6, §12.
+"""
+import os
+from typing import Any
+
+_UNSET: Any = object()
+
+# Maps session-var name -> ContextVar upstream; empty here (no injection until Stage D).
+_VAR_MAP: dict = {}
+
+
+def get_session_env(name: str, default: str = "") -> str:
+    """Return a session-scoped env value, falling back to the process environment."""
+    value = os.environ.get(name)
+    return value if value is not None else default

calfkit_tools/hermes/_shims/gateway/status.py

@@ -0,0 +1,28 @@
+"""Shim for hermes-agent ``gateway.status`` (faithful, tiny).
+
+``_pid_exists`` is a cross-platform "is this PID alive" check that does NOT signal the
+target (critical on Windows, where ``os.kill(pid, 0)`` is not a no-op). Used by the
+background-process registry's detached crash-recovery path.
+"""
+import os
+from typing import Optional
+
+
+def _pid_exists(pid: Optional[int]) -> bool:
+    if not pid:
+        return False
+    try:
+        import psutil
+
+        return psutil.pid_exists(pid)
+    except Exception:
+        pass
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True

calfkit_tools/hermes/_shims/hermes_cli/_subprocess_compat.py

@@ -0,0 +1,17 @@
+"""Shim for hermes-agent ``hermes_cli._subprocess_compat`` (faithful, tiny).
+
+``windows_hide_flags`` returns Win32 creationflags that hide a child console window
+(0 on non-Windows). Must return an int (it is passed unconditionally as Popen
+``creationflags=`` in process_registry.py), never None.
+"""
+import platform
+
+_IS_WINDOWS = platform.system() == "Windows"
+
+
+def windows_hide_flags() -> int:
+    if not _IS_WINDOWS:
+        return 0
+    import subprocess
+
+    return getattr(subprocess, "CREATE_NO_WINDOW", 0)

calfkit_tools/hermes/_shims/hermes_cli/auth.py

@@ -0,0 +1,21 @@
+"""Shim for hermes-agent ``hermes_cli.auth``.
+
+``PROVIDER_REGISTRY`` feeds local.py's subprocess secret *blocklist*. Empty here is
+deliberate: Stage D replaces the blocklist with an allowlist env model (design doc
+§6.1), so the blocklist data is moot for the calfkit node.
+
+SECURITY: do NOT read "empty" as "no secrets to block". local.py keeps a static
+blocklist, but it does NOT cover calfkit's own infra secrets (Kafka SASL, etc.). The
+subprocess env is only truly contained by Stage D's allowlist — until then this
+component must not run untrusted commands in a multi-tenant worker (design §6.1, §12).
+
+``resolve_nous_access_token`` is a Nous-portal token resolver, irrelevant to calfkit —
+returns None (callers wrap it in try/except and fail closed).
+"""
+
+# Import-safe stub; real subprocess env hygiene = Stage-D allowlist.
+PROVIDER_REGISTRY: dict = {}
+
+
+def resolve_nous_access_token(*args, **kwargs):
+    return None

calfkit_tools/hermes/_shims/hermes_cli/config.py

@@ -0,0 +1,53 @@
+"""Shim for hermes-agent ``hermes_cli.config`` — only the symbols the vendored tree uses.
+
+``get_hermes_home`` re-exports the vendored real implementation. ``cfg_get`` is the pure
+nested-dict helper (faithful). The config-reading functions return empty defaults: the
+vendored tools all consume them inside try/except with sane fallbacks, and real
+subprocess env hygiene is handled by the Stage-D allowlist (not this blocklist-feeding
+config). ``OPTIONAL_ENV_VARS`` is intentionally empty here for the same reason.
+"""
+import os
+from pathlib import Path
+
+# Re-export the real implementation (lives in the vendored constants module).
+from calfkit_tools.hermes._vendor.hermes_constants import get_hermes_home  # noqa: F401
+
+# Import-safe stub; real env hygiene = Stage-D allowlist (see design doc §6.1, §3.2).
+OPTIONAL_ENV_VARS: dict = {}
+
+
+def cfg_get(cfg, *keys, default=None):
+    """Traverse nested dict keys safely, returning ``default`` on any miss (faithful)."""
+    if not isinstance(cfg, dict):
+        return default
+    node = cfg
+    for key in keys:
+        if not isinstance(node, dict) or key not in node:
+            return default
+        node = node[key]
+    return node
+
+
+def read_raw_config() -> dict:
+    return {}
+
+
+def load_config() -> dict:
+    return {}
+
+
+def save_config(config: dict) -> None:
+    # No-op: persisting host config is not a calfkit-node responsibility.
+    return None
+
+
+def load_env() -> dict:
+    return {}
+
+
+def get_env_value(key: str):
+    return os.environ.get(key)
+
+
+def get_config_path() -> Path:
+    return get_hermes_home() / "config.yaml"

calfkit_tools/hermes/_shims/hermes_cli/nous_account.py

@@ -0,0 +1,13 @@
+"""Shim for hermes-agent ``hermes_cli.nous_account`` (Nous-portal account info).
+
+Irrelevant to calfkit; only referenced by the managed-tool-gateway path inside
+try/except. Safe no-ops.
+"""
+
+
+def get_nous_portal_account_info(*args, **kwargs):
+    return None
+
+
+def format_nous_portal_entitlement_message(*args, **kwargs) -> str:
+    return ""

calfkit_tools/hermes/_shims/hermes_cli/plugins.py

@@ -0,0 +1,10 @@
+"""Shim for hermes-agent ``hermes_cli.plugins``.
+
+``invoke_hook`` dispatches user/project plugin hooks; calfkit has no such plugin
+system here. Returns an empty list of hook results (callers iterate the result).
+"""
+from typing import Any, List
+
+
+def invoke_hook(hook_name: str, **kwargs: Any) -> List[Any]:
+    return []

calfkit_tools/hermes/_shims/hermes_cli/profiles.py

@@ -0,0 +1,8 @@
+"""Shim for hermes-agent ``hermes_cli.profiles``.
+
+Only ``get_active_profile_name`` is used (a Docker container label, inside try/except).
+"""
+
+
+def get_active_profile_name() -> str:
+    return "default"

calfkit_tools/hermes/_shims/model_tools.py

@@ -0,0 +1,64 @@
+"""Shim for hermes-agent ``model_tools`` — only the symbols the vendored tree uses.
+
+- ``_run_async`` / ``_sanitize_tool_error``: faithful pure helpers used by the vendored
+  ``registry.dispatch`` (the shell/file tools register no async handlers, so ``_run_async``
+  is off the hot path here, but it stays behaviour-correct).
+- ``handle_function_call``: the Programmatic-Tool-Calling (PTC) dispatcher used by
+  ``code_execution_tool``'s RPC bridge. The full upstream version layers a tool-search
+  bridge + hooks + guardrails; here it is a thin delegate to the vendored registry's own
+  ``dispatch`` (lookup + async-bridge + error-sanitize), scoped to this node's tools.
+"""
+import asyncio
+import concurrent.futures
+import re
+
+# --- _sanitize_tool_error (constants + body copied verbatim from upstream) ---------
+_TOOL_ERROR_ROLE_TAG_RE = re.compile(
+    r'</?(?:tool_call|function_call|result|response|output|input|system|assistant|user)>',
+    re.IGNORECASE,
+)
+_TOOL_ERROR_FENCE_OPEN_RE = re.compile(r'^\s*```(?:json|xml|html|markdown)?\s*', re.MULTILINE)
+_TOOL_ERROR_FENCE_CLOSE_RE = re.compile(r'\s*```\s*$', re.MULTILINE)
+_TOOL_ERROR_CDATA_RE = re.compile(r'<!\[CDATA\[.*?\]\]>', re.DOTALL)
+_TOOL_ERROR_MAX_LEN = 2000
+
+
+def _sanitize_tool_error(error_msg: str) -> str:
+    """Strip structural framing tokens from a tool error before showing it to the model."""
+    if not error_msg:
+        return "[TOOL_ERROR] "
+    sanitized = _TOOL_ERROR_ROLE_TAG_RE.sub("", error_msg)
+    sanitized = _TOOL_ERROR_FENCE_OPEN_RE.sub("", sanitized)
+    sanitized = _TOOL_ERROR_FENCE_CLOSE_RE.sub("", sanitized)
+    sanitized = _TOOL_ERROR_CDATA_RE.sub("", sanitized)
+    if len(sanitized) > _TOOL_ERROR_MAX_LEN:
+        sanitized = sanitized[: _TOOL_ERROR_MAX_LEN - 3] + "..."
+    return f"[TOOL_ERROR] {sanitized}"
+
+
+def _run_async(coro):
+    """Run a coroutine from sync code (sync->async bridge for async tool handlers).
+
+    Simplified vs. upstream's persistent-loop optimization (which keeps cached async
+    clients alive). The shell/file toolset registers no async handlers, so this is not
+    exercised on the hot path; it stays correct for any future async handler.
+    """
+    try:
+        running = asyncio.get_running_loop()
+    except RuntimeError:
+        running = None
+    if running and running.is_running():
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(lambda: asyncio.run(coro)).result()
+    return asyncio.run(coro)
+
+
+def handle_function_call(function_name, function_args, task_id=None, **kwargs):
+    """PTC dispatcher: route an in-sandbox tool call into the vendored registry.
+
+    Thin delegate to ``registry.dispatch`` (this node's own tools). Imported lazily to
+    avoid an import cycle (registry imports this module for ``_run_async``).
+    """
+    from calfkit_tools.hermes._vendor.tools.registry import registry
+
+    return registry.dispatch(function_name, function_args, task_id=task_id)

calfkit_tools/hermes/_vendor/agent/async_utils.py

@@ -0,0 +1,68 @@
+"""Async/sync bridging helpers.
+
+The codebase has ~30 sites that schedule a coroutine onto an event loop from a
+worker thread via :func:`asyncio.run_coroutine_threadsafe`.  That function can
+raise :class:`RuntimeError` (e.g. the loop was closed during a shutdown race),
+and when it does the coroutine object is never awaited and never closed —
+which triggers a ``"coroutine '<name>' was never awaited"`` RuntimeWarning and
+leaks the coroutine's frame until GC.
+
+:func:`safe_schedule_threadsafe` wraps the call, closes the coroutine on
+scheduling failure, and returns ``None`` (instead of a half-formed future) so
+callers can branch cleanly:
+
+    fut = safe_schedule_threadsafe(coro, loop)
+    if fut is None:
+        return  # or fallback behavior
+    fut.result(timeout=5)
+
+The helper deliberately does NOT also handle ``future.result()`` failures —
+that is a separate concern.  Once the loop has accepted the coroutine, its
+lifecycle belongs to the loop, not the scheduling thread.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from concurrent.futures import Future
+from typing import Any, Coroutine, Optional
+
+
+_DEFAULT_LOGGER = logging.getLogger(__name__)
+
+
+def safe_schedule_threadsafe(
+    coro: Coroutine[Any, Any, Any],
+    loop: Optional[asyncio.AbstractEventLoop],
+    *,
+    logger: Optional[logging.Logger] = None,
+    log_message: str = "Failed to schedule coroutine on loop",
+    log_level: int = logging.DEBUG,
+) -> Optional[Future]:
+    """Schedule ``coro`` on ``loop`` from a sync context, leak-safe.
+
+    Returns the :class:`concurrent.futures.Future` on success, or ``None`` if
+    the loop is missing or :func:`asyncio.run_coroutine_threadsafe` raised
+    (e.g. the loop was closed during a shutdown race).  In all failure paths
+    the coroutine is :meth:`close`-d so it does not trigger
+    ``"coroutine was never awaited"`` warnings or leak its frame.
+
+    Callers retain full control over what to do with the returned future
+    (call ``.result(timeout=...)``, attach ``add_done_callback``, ignore it
+    fire-and-forget, etc.).
+    """
+    log = logger if logger is not None else _DEFAULT_LOGGER
+
+    if loop is None:
+        if asyncio.iscoroutine(coro):
+            coro.close()
+        log.log(log_level, "%s: loop is None", log_message)
+        return None
+
+    try:
+        return asyncio.run_coroutine_threadsafe(coro, loop)
+    except Exception as exc:
+        if asyncio.iscoroutine(coro):
+            coro.close()
+        log.log(log_level, "%s: %s", log_message, exc)
+        return None