lisa-harness-runtime 0.1.0__tar.gz

lisa_harness_runtime-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+
+# Virtual environments
+.venv/
+
+# IDE
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.import_linter_cache/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.lisa-tmp/
+coverage/
+.coverage
+.coverage.*
+htmlcov/
+
+# Outputs
+artifacts/
+.e2e/

lisa_harness_runtime-0.1.0/.instructions.md

@@ -0,0 +1,12 @@
+---
+name: runtime — Shared Host Runtime
+applyTo: "runtime/**/*.py"
+description: Package-specific guidance for host runtime work.
+---
+
+# Host runtime guidance
+
+- Keep the host runtime transport-neutral. Do not introduce transport-specific rendering logic into the shared runtime layer.
+- Preserve the existing separation between configuration, runtime state, and callback delivery.
+- Keep lifecycle and MCP integration explicit so resources are started and closed in the correct event loop.
+- Prefer focused modules and thin dispatch paths over growing one large handler.

lisa_harness_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: lisa-harness-runtime
+Version: 0.1.0
+Summary: Transport-neutral host runtime for Lisa Harness hosts
+Requires-Python: >=3.11
+Requires-Dist: cel-python>=0.5.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lisa-harness-kernel
+Requires-Dist: lisa-harness-mcp-servers
+Requires-Dist: lisa-harness-sdk
+Requires-Dist: lisa-pack-core
+Requires-Dist: lisa-pack-introspect
+Requires-Dist: lisa-pack-memory
+Requires-Dist: lisa-pack-recovery
+Requires-Dist: openai>=1.30.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: zstandard>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'

lisa_harness_runtime-0.1.0/README.md

@@ -0,0 +1,138 @@
+# Runtime
+
+`lisa-harness-runtime` is an abstract runtime, i.e., host for the Lisa Harness kernel.
+It offers a transport-neutral but otherwise near complete runtime implementation.
+The separate [lisa-cli host](https://github.com/Lisa-Harness/lisa-cli) builds
+on it to create a concrete running host.
+
+See [host integration](../docs/HOST_INTEGRATION.md), [configuration](../docs/CONFIGURATION.md),
+and the [documentation index](../docs/README.md) for maintained task guides.
+
+## Design Philosophy
+
+The host owns **runtime integration, process boundaries, and environment-specific wiring** — nothing more. Domain logic lives in the kernel or SDK; rendering lives in the transport.
+
+Key principles:
+
+- **Transport-neutral**: `runtime` never imports Rich, Typer, aiohttp, or any transport-specific package. Transports implement `TransportCallbacks` at their edge to receive stage updates, streamed text, final responses, debug context, and errors.
+- **Typed composition root**: `HostConfig` is the frozen configuration; `HostRuntime` is its mutable counterpart, grouping responsibilities into five focused sub-objects (`paths`, `providers`, `resources`, `session`, `services`) so call sites name the domain they touch.
+- **Single message entry point**: all transports call `handle_message(runtime, text, transport)` — host command dispatch, approval resume, model-turn routing, and turn execution live behind it.
+- **Runtime invariants**: MCP resources start and close in the same task and event loop that runs turns. Housekeeping is slice-budgeted — no `cron`, `sched`, or wall-clock background schedulers.
+
+## Usage
+
+```python
+from runtime import NullTransport, handle_message
+from runtime.bootstrap import build_runtime
+
+runtime = build_runtime(host_kind="headless", data_dir="./agent-data", user_slug="local-user")
+try:
+    await runtime.start()
+    result = await handle_message(runtime, "/help", NullTransport())
+finally:
+    await runtime.aclose()
+```
+
+This fragment runs inside one async task with a configured model manifest.
+`HostRuntime(config)` alone does not perform the bootstrap/wiring sequence.
+For a complete program and an observable production transport, see
+[host integration](../docs/HOST_INTEGRATION.md).
+
+## Module Map
+
+### Composition Root
+
+| Module | Responsibility |
+| --- | --- |
+| `config.py` | `HostConfig` — typed, frozen configuration built once at startup from CLI args, env vars, or direct construction. Owns surface identity defaults and per-lane context budgets. |
+| `runtime.py` | `HostRuntime` — the typed composition root replacing the old `_RUNTIME_STATE` dict. Owns `config`, `session_plan`, `execution_policy`, and the five sub-objects. `RuntimeResources` implements the async MCP lifecycle beside the object that owns its event loop. |
+| `bootstrap.py` | Shared composition root: builds a `HostRuntime` from CLI args + env vars. |
+| `handle_message.py` | Transport-neutral message dispatcher. Owns host command dispatch (`/help`, `/settings`, `/tokens`, `/debug`, `/consolidate`, `/intake`, `/pack`, `/models`, `/modes`, `/operations`, `/tools`), implicit approve/deny resume, and the model-turn pipeline. |
+| `types.py` | Transport-neutral `Protocol` callable shapes that `HostRuntime` and `handle_message` depend on. |
+| `runtime_paths.py` | `HostPaths` — frozen, pure value object projecting the host's derived filesystem layout (threads, state, logs, scratch). |
+| `paths.py` | Framework root, venv root, and packs-venv resolution that works both in a repo checkout and a `uv tool install` environment. |
+
+### Turn Wiring
+
+| Module | Responsibility |
+| --- | --- |
+| `turn_hooks_builder.py` | Builds the kernel's `TurnHooks` dataclass from a `HostRuntime`, replacing the old closure-based factory. |
+| `turn_hooks/` | Turn-hook factory submodules — each owns one cohesive group of hooks (e.g. `_auto_capture.py`). |
+| `context_assembly.py` | Transport-neutral system prompt and user context assembly. Pure / parameterized functions. |
+| `token_accounting.py` | Token/latency ledger and session usage tracking. |
+| `turn_logging.py` | Structured log-record assembly for the JSONL turn log and runtime event log. |
+| `state_provider.py` | Transport-neutral state provider and slice compaction. |
+| `operator_signal.py` | Typed `OperatorSignal` enum for host↔kernel communication, polled once per iteration. |
+
+### Providers & Models
+
+| Module | Responsibility |
+| --- | --- |
+| `providers.py` | `ProviderRegistry` — lazily-populated per-provider SDK client cache (Azure OpenAI, Azure Responses, OpenAI, Anthropic HTTP, Ollama, OpenRouter). |
+| `gateway_provider.py` | Host-side `ProviderGatewayProvider` — the kernel's single live completion path routes through it. |
+| `provider_endpoints.py` | Single source of truth for each provider's direct base URL, used when no proxy route is active. |
+| `model_runtime.py` | Model-runtime resolution helpers. |
+| `model_manifest.py` | Host-side model manifest handling. |
+| `model_discovery/` | Provider capability probing and manifest generation (`probes/` per provider, `classify.py`, `discover.py`, `yaml_emit.py`, `redact.py`, `enrichment`). Backs the `/models discover` command. |
+
+### MCP Integration
+
+| Module | Responsibility |
+| --- | --- |
+| `mcp_pool.py` | Compiles MCP server configurations from the host manifest (`mcp_servers.yaml`) and pack-contributed declarations. |
+| `mcp_servers.yaml` | The host's first-party MCP server manifest (shipped as package data). |
+| `memory_aliases.py` | Registers the generic `memory.*` synthetic aliases on a started MCP pool. |
+
+### Approvals, Policy & Recovery
+
+| Module | Responsibility |
+| --- | --- |
+| `approval/` | Transport-neutral exact-action approval flow: identity rebuild, affirmative resume, policy auto-continue, post-approval continuation (`presentation.py`, `orchestration.py`). |
+| `approvals.py` | File-backed host implementation of the kernel approval service. |
+| `policy.py` | Host-owned approval policy engine — the only place the "does this action need operator approval?" decision lives (mode dial, allow/ask/deny). |
+| `policy_service.py` | `PolicyApprovalService` — decorates the durable file-backed service with the policy engine. |
+| `execution_policy.py` | Host-side execution policy defaults and resolution. |
+| `recovery.py` | File-backed host implementation of the kernel recovery service. |
+
+### Session & Content
+
+| Module | Responsibility |
+| --- | --- |
+| `session_context.py` | Resolves a session-context reference into a strict v2 `SessionPlan`. |
+| `session_from_resolver.py` | Host-layer `from:`/`body:` directive resolver for session contexts. |
+| `content_roots.py` | Content root and pack activation discovery (packs venv injection, installed-pack deduplication). |
+| `pack_autoinstall.py` | Startup auto-install of session-required packs not importable at host boot. |
+
+### Services, Intake & Introspection
+
+| Module | Responsibility |
+| --- | --- |
+| `services.py` | `HostServices` — the host's durable service handles (approval, recovery, etc.) reachable by any turn or command. |
+| `intake.py` | Intake tick — one-shot signal collection, processing, and state write driven by a systemd timer or cron. |
+| `introspect.py` | Live Python-level introspection: process memory, asyncio task count, MCP pool health, token usage trends. |
+| `code_artifacts.py` | Atomic file-backed storage for pack-neutral WorkProducts. |
+
+### Commands & Thread
+
+| Module | Responsibility |
+| --- | --- |
+| `commands/` | Transport-neutral slash-command handlers that do not require the model (`_mcp.py`, `_packs.py`, `_models.py`, `_policy.py`, `_routing.py`, `_slice.py`, `_lists.py`, `_log.py`, `_render.py`, `_simple.py`). |
+| `host_commands.py` | Dynamic registry of slash-command prefixes that are host control directives, not conversational content. |
+| `thread/` | Per-user segmented thread store (`_store.py` — paths, segment index, zstd compression, sealing; `_excerpt.py`). |
+| `testing/` | `runtime_factory.py` — builds a test `HostRuntime` with injected fakes and a seeded model manifest. |
+
+## Data Directory Precedence
+
+`HostConfig.from_env` resolves the data root in this order: CLI arg > `LISA_DATA_DIR` > `LISA_PROFILE` > `~/.lisa`. `LISA_PROFILE=name` resolves to `<base>/profiles/<name>` while the packs venv stays the base's. Export only one of the two variables.
+
+## Testing
+
+```bash
+uv run pytest runtime/tests runtime/src/runtime/model_discovery/tests -m "not live" -q
+```
+
+Run from the workspace root; see [testing](../docs/TESTING.md) for full gates.
+
+Test through `HostConfig` and `HostRuntime` with injected fakes (via `runtime/testing/runtime_factory.py`) rather than monkeypatching module-level interfaces. A test `HostRuntime` needs a seeded model manifest with `mode_models`, not only a `models` list.
+
+Architecture boundaries for this package are defined in [.github/instructions/architecture/runtime.instructions.md](../.github/instructions/architecture/runtime.instructions.md).

lisa_harness_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runtime"]
+
+[project]
+name = "lisa-harness-runtime"
+version = "0.1.0"
+description = "Transport-neutral host runtime for Lisa Harness hosts"
+requires-python = ">=3.11"
+dependencies = [
+    "lisa-harness-kernel",
+    "lisa-harness-sdk",
+    "lisa-harness-mcp-servers",
+    "lisa-pack-memory",
+    "lisa-pack-core",
+    "lisa-pack-introspect",
+    "lisa-pack-recovery",
+    "cel-python>=0.5.0",
+    "openai>=1.30.0",
+    "pyyaml>=6.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.7.0",
+    "zstandard>=0.23.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.8.0",
+    "types-PyYAML>=6.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+markers = [
+    "live: hits real external signal or provider APIs and prints a tester-visible summary",
+    "integration: multi-module in-process test; may require local services",
+    "eval: deterministic agent regression evals (no model calls, no I/O)",
+]
+
+# Ruff/pytest/vulture configuration lives in the workspace root pyproject.toml;
+# member-level [tool.ruff] sections would shadow the root per-file-ignores.

lisa_harness_runtime-0.1.0/src/runtime/__init__.py

@@ -0,0 +1,92 @@
+"""host — transport-neutral host runtime for Lisa Harness hosts.
+
+This package owns the shared runtime that ``hosts/cli``
+builds on. It wires the kernel's ``TurnHooks`` with
+manifest-driven model resolution, MCP pool compilation, provider completion,
+context assembly, thread persistence, and host-command dispatch — all without
+importing Rich, Typer, aiohttp, or any transport-specific code.
+
+Transport hosts inject a ``TransportCallbacks`` implementation to receive
+stage updates, streamed text, final responses, debug context, and errors.
+The runtime never writes to a console, browser, or editor directly.
+
+Public surface::
+
+    from runtime import HostConfig, HostRuntime, TransportCallbacks, handle_message
+
+    config = HostConfig.from_env()
+    runtime = HostRuntime(config)
+    await runtime.start()           # starts MCP pool in the host's event loop
+    result = await handle_message(runtime, "/search test", transport)
+    await runtime.aclose()
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from runtime.callbacks import DelegatingTransport, NullTransport, TransportCallbacks
+from runtime.config import HostConfig, SliceConfig, StreamingConfig, default_data_dir
+from runtime.types import (
+    CompletionProvider,
+    HostCommandResult,
+    ModelResolver,
+    ToolExecutor,
+)
+
+if TYPE_CHECKING:
+    # ``runtime.runtime`` is the heaviest submodule (pulls
+    # ``kernel.ipsar_fsm`` + ``openai`` via ``session_context``). It is
+    # resolved lazily by ``__getattr__`` below so importing
+    # ``HostConfig`` / ``callbacks`` / ``types`` from the package does not
+    # drag it in. The ``TYPE_CHECKING`` alias keeps these names visible to
+    # type checkers for annotation use without an eager runtime import.
+    from runtime.runtime import HostRuntime as HostRuntime
+    from runtime.runtime import TokenCounters as TokenCounters
+    from runtime.runtime import TurnContext as TurnContext
+
+__all__ = [
+    "CompletionProvider",
+    "DelegatingTransport",
+    "HostCommandResult",
+    "HostConfig",
+    "HostRuntime",
+    "ModelResolver",
+    "NullTransport",
+    "SliceConfig",
+    "StreamingConfig",
+    "TokenCounters",
+    "ToolExecutor",
+    "TransportCallbacks",
+    "TurnContext",
+    "default_data_dir",
+    "handle_message",
+]
+
+
+def __getattr__(name: str) -> Any:  # PEP 562 lazy module attribute
+    """Lazy-import the heavy runtime symbols on first attribute access.
+
+    ``runtime.runtime`` is the heaviest submodule in the package (it
+    pulls in ``openai``, ``mcp``, and ``kernel.ipsar_fsm`` via
+    ``session_context``); ``handle_message`` is the heaviest *function*
+    (the turn dispatcher). Deferring both keeps ``from runtime import
+    HostConfig`` / ``HostRuntime`` / ``TransportCallbacks`` (used by
+    ``--version``, ``modes``, ``models``, ``verify``) from paying the
+    ~2s runtime or ~3s turn-execution import cost. Direct submodule
+    imports (``from runtime.runtime import HostRuntime``, ``from
+    runtime.handle_message import handle_message``) are unaffected and
+    remain the fast path for code that actually needs the symbol.
+    """
+    if name == "handle_message":
+        from runtime.handle_message import handle_message as _handle_message
+
+        globals()["handle_message"] = _handle_message
+        return _handle_message
+    if name in {"HostRuntime", "TokenCounters", "TurnContext"}:
+        from runtime import runtime as _runtime
+
+        value = getattr(_runtime, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

lisa_harness_runtime-0.1.0/src/runtime/approval/__init__.py

@@ -0,0 +1,93 @@
+"""Host approval flow — transport-neutral approval and resume machinery.
+
+This package owns the host side of the exact-action approval contract.
+It was extracted from ``handle_message.py`` so the dispatcher shrinks back
+to its documented three-phase pipeline (command dispatch → approval resume
+→ model turn) instead of embedding a 600-line approval subsystem.
+
+Dependency direction
+--------------------
+``approval`` ← ``handle_message.py`` / transport hosts  (callers import
+from approval; approval never imports handle_message — it receives
+``route_model_turn`` as an injected callable)
+
+``approval`` → ``runtime.approval.presentation``, ``runtime.runtime``,
+``runtime.policy``, ``runtime.thread``, ``kernel.approval``,
+``kernel.recovery``  (approval imports these; none of them import approval)
+
+The two modules
+---------------
+- :mod:`runtime.approval.presentation` — pure, side-effect-free text and
+  payload rendering (:func:`redact_parameters`,
+  :func:`unresolved_approval_text`, ...).
+- :mod:`runtime.approval.orchestration` — the durable-state flow: identity
+  rebuild, affirmative-resume detection, policy auto-continue, thread
+  record + synthesis turn, paired-recovery settlement, the typed core
+  :func:`decide_approval`, and its slash-grammar parse adapter
+  :func:`handle_approval_command`.
+
+Public surface
+--------------
+- :func:`approval_identity`
+- :func:`build_approval_data`
+- :func:`decide_approval`
+- :func:`handle_approval_command`
+- :func:`is_affirmative_resume`
+- :func:`maybe_auto_continue_approval`
+- :func:`try_affirmative_approval_resume`
+- :func:`settle_paired_recovery_record`
+- :func:`redact_parameters`
+- :func:`approval_result_text`
+- :func:`same_session_scope`
+- :func:`unresolved_approval_text`
+- :func:`decision_state_text`
+- :func:`approval_action_receipt`
+
+.. note::
+   ``decide_approval``, ``handle_approval_command``,
+   ``try_affirmative_approval_resume``, and
+   ``maybe_auto_continue_approval`` take a ``route_model_turn`` callable.
+   ``runtime.handle_message`` injects its own ``_route_model_turn`` so the
+   post-approval synthesis turn reuses the single-turn machinery without
+   a circular import. ``decide_approval`` is the typed seam (values in, no
+   command string); ``handle_approval_command`` is its slash-grammar parse
+   adapter for the string dispatcher.
+"""
+
+from __future__ import annotations
+
+from runtime.approval.orchestration import (
+    approval_identity,
+    build_approval_data,
+    decide_approval,
+    handle_approval_command,
+    is_affirmative_resume,
+    maybe_auto_continue_approval,
+    settle_paired_recovery_record,
+    try_affirmative_approval_resume,
+)
+from runtime.approval.presentation import (
+    approval_action_receipt,
+    approval_result_text,
+    decision_state_text,
+    redact_parameters,
+    same_session_scope,
+    unresolved_approval_text,
+)
+
+__all__ = [
+    "approval_action_receipt",
+    "approval_identity",
+    "approval_result_text",
+    "build_approval_data",
+    "decide_approval",
+    "decision_state_text",
+    "handle_approval_command",
+    "is_affirmative_resume",
+    "maybe_auto_continue_approval",
+    "redact_parameters",
+    "same_session_scope",
+    "settle_paired_recovery_record",
+    "try_affirmative_approval_resume",
+    "unresolved_approval_text",
+]