lisa-harness-sdk 0.1.0__tar.gz

lisa_harness_sdk-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_sdk-0.1.0/.instructions.md

@@ -0,0 +1,12 @@
+---
+name: Lisa SDK Package
+applyTo: "sdk/**/*.py"
+description: Package-specific guidance for SDK work.
+---
+
+# SDK package guidance
+
+- Keep SDK helpers generic and dependency-light. They should stay reusable rather than embedding host-specific behavior.
+- Preserve the existing boundary between SDK domain logic and first-party MCP transport facades.
+- Keep file and fetch primitives explicit about sandboxing and policy rather than relying on callers to enforce it.
+- Prefer simple, import-safe helpers with explicit parameters over environment-driven behavior.

lisa_harness_sdk-0.1.0/AUTHORING.md

@@ -0,0 +1,371 @@
+# Operation Authoring Guide
+
+This guide walks through creating operations for the Lisa Harness. For the conceptual
+overview and lifecycle details see [kernel dispatch contracts](../kernel/README.md#dispatch-and-operation-contracts).
+
+## Choose your operation kind
+
+For the package layout and a complete local greeting pack, start with
+[pack authoring](../docs/PACK_AUTHORING_GUIDE.md). This guide covers the
+operation-specific contract.
+
+| Use case | Kind | Format |
+| --- | --- | --- |
+| Deterministic Python logic — read state, validate, format | **Runtime** | `.yml` + `.py` |
+| LLM task — synthesize, research, reflect, guided tool use | **Declarative (prompt)** | `.operation.md` (optionally + `.py` response model) |
+
+When in doubt, start declarative. Reach for a runtime operation only when branching,
+validation, retry logic, or non-LLM data shaping makes a markdown instruction
+impractical to maintain.
+
+## Prerequisites
+
+Operations live in `operations/` subdirectories within any content root. A content root
+is any directory registered via the `lisa.extensions.content_roots` entry point in your
+pack's `pyproject.toml`, or via the `SDK_CONTENT_ROOTS` environment variable. The
+`lisa-catalog` MCP server discovers the catalog; you never register individual files.
+
+```toml
+# pyproject.toml
+[project.entry-points."lisa.extensions.content_roots"]
+my_pack = "my_pack:get_content_root"
+```
+
+```python
+# my_pack/__init__.py
+from pathlib import Path
+
+
+def get_content_root() -> Path:
+    return Path(__file__).parent
+```
+
+## Runtime operation
+
+### Directory shape
+
+```plaintext
+my_pack/
+  operations/
+    my_feature/
+      my_operation.yml   ← required metadata
+      my_operation.py    ← required implementation
+```
+
+### Metadata file (`.yml`)
+
+```yaml
+operation_id: my_operation
+description: One clear sentence describing what this operation does.
+mode_allowlist: [my_mode]
+tool_ids: []           # list tools this operation may call; empty is fine
+timeout_seconds: 30    # default 30; 0 disables timeout (tool/operation self-bounds)
+max_calls_per_turn: 1  # default 0 (unlimited)
+preferred_model_id: default   # optional; omit to inherit mode default
+```
+
+**Required:** `operation_id`, `description`.
+
+**Optional:** `mode_allowlist` (default allows all modes), `tool_ids`, `timeout_seconds`,
+`max_calls_per_turn`, `preferred_model_id`.
+
+`mode_allowlist` can also be omitted — the operation will then be allowed for every
+mode unless `tools_authoritative: true` is set on the mode and the operation is not
+listed there.
+
+### Implementation (`.py`)
+
+```python
+from kernel.models import OperationExecutionContext, OperationResult
+
+
+async def execute(ctx: OperationExecutionContext) -> OperationResult:
+    """Execute the operation and return a structured result."""
+    return OperationResult(output_text=f"Received: {ctx.query}")
+```
+
+The module must export `async def execute(ctx: OperationExecutionContext) -> OperationResult`.
+No other exports are required.
+
+### Optional `Parameters` class
+
+If you want the model to supply structured arguments when calling the operation as a
+tool, export a Pydantic `Parameters` class. The catalog loader detects it automatically
+and builds the function-tool schema from it.
+
+```python
+from pydantic import BaseModel, Field
+from kernel.models import OperationExecutionContext, OperationResult
+
+
+class Parameters(BaseModel):
+    limit: int = Field(default=10, ge=1, le=100, description="Max items to return.")
+
+
+async def execute(ctx: OperationExecutionContext) -> OperationResult:
+    limit = int(ctx.params.get("limit", 10))
+    # use limit ...
+    return OperationResult(output_text=f"Returning up to {limit} items.")
+```
+
+### Calling tools from a runtime operation
+
+List the tools in `tool_ids` and call them via `ctx.host.execute_tool`:
+
+```python
+from kernel.models import OperationExecutionContext, OperationResult, ToolExecutionContext
+
+
+async def execute(ctx: OperationExecutionContext) -> OperationResult:
+    tool_ctx = ToolExecutionContext(
+        tool_id="read_file",
+        workspace_id=ctx.workspace_id,
+        user_id=ctx.user_id,
+        query=ctx.query,
+        parameters={"path": "status.txt"},
+    )
+    result = await ctx.host.execute_tool("read_file", tool_ctx)
+    return OperationResult(output_text=result.output_text)
+```
+
+Matching YAML:
+
+```yaml
+operation_id: read_status_file
+description: Read a status file from storage.
+tool_ids: [read_file]
+mode_allowlist: [my_mode]
+```
+
+### The `OperationHost` typed seam
+
+Operations interact with the host (LLM calls, tool execution, authored
+content, model resolution) through a single typed seam: `ctx.host`. The
+`OperationHost` Protocol (defined in `kernel/seams/protocols.py`) declares
+the methods operations may call:
+
+| Method | Purpose |
+| --- | --- |
+| `await ctx.host.complete(messages=..., model_def=..., max_tokens=..., temperature=..., tools=..., response_format=...)` | Call the host's LLM. Returns a `CompletionResult` with `.content`, `.tool_calls`, `.finish_reason`, and `.truncated`. |
+| `ctx.host.resolve_model(model_id)` | Resolve a model id to a `ModelRef` (provider, model_id, capabilities). |
+| `ctx.host.read_authored_text(path)` | Load authored Markdown content shipped as package data. Raises on missing. |
+| `await ctx.host.execute_tool(tool_id, tool_ctx)` | Execute a tool by id. Returns a `ToolResult`. |
+| `await ctx.host.execute_operation(op_id, op_ctx)` | Execute a sub-operation. |
+| `await ctx.host.generate_image(...)` | Generate an image (when wired). |
+| `ctx.host.introspect(...)` | Introspect live runtime state (when wired). |
+
+The `truncated` field on the completion result is the **provider-owned
+truncation signal**: `True` = the model stopped mid-output (hit token
+budget), `False` = clean stop, `None` = adapter cannot tell. Operations
+that synthesize long-form output use this to decide whether to issue a
+continuation pass. This replaces the old heuristic of guessing from
+`finish_reason` strings.
+
+### Reading cached state
+
+```python
+from kernel.models import OperationExecutionContext, OperationResult, UnifiedState
+
+
+async def execute(ctx: OperationExecutionContext) -> OperationResult:
+    state: UnifiedState | None = ctx.state_provider() if ctx.state_provider else None
+    if state is None:
+        return OperationResult(output_text="No cached state available.")
+    items = [item for item in state.context_items if item.source == "my_service"]
+    if not items:
+        return OperationResult(output_text="No evidence yet.")
+    return OperationResult(output_text="\n".join(item.body for item in items))
+```
+
+## Declarative (prompt) operation
+
+### Directory shape
+
+```plaintext
+my_pack/
+  operations/
+    research/
+      briefing.operation.md   ← metadata + instructions in one file
+      briefing.py             ← optional Pydantic response model (no execute())
+```
+
+### Markdown file (`.operation.md`)
+
+```markdown
+---
+operation_id: research_briefing
+description: Produce a grounded research summary from web results.
+tool_ids: [web_search]
+mode_allowlist: [research]
+timeout_seconds: 60
+max_calls_per_turn: 1
+completion_max_tokens: 2000
+completion_temperature: 0.2
+response_format_model_path: my_pack.operations.research.briefing.BriefingOutput
+response_output_text_field: summary
+---
+
+# Research Briefing
+
+You are a grounded research analyst. Use `web_search` to gather evidence, then
+synthesize only from the tool results.
+
+## Rules
+
+1. Run 2–3 independent searches.
+2. Never invent URLs or facts.
+3. If no grounded results are available, set `summary` to the search error and leave
+   other fields empty.
+
+## Output
+
+Return one JSON object matching the declared schema.
+```
+
+**Required front-matter fields:** `operation_id`, `description`.
+
+**Optional fields:**
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `tool_ids` | `[]` | Tools the model may call in the instruction loop |
+| `mode_allowlist` | (all modes) | Modes allowed to invoke this operation |
+| `timeout_seconds` | `60` | Wall-clock limit for the full instruction loop |
+| `max_calls_per_turn` | `0` | Max times this operation can be called in one turn (`0` = unlimited) |
+| `completion_max_tokens` | `declarative_completion_max_tokens` setting (default `1500`) | Token budget for the model completion |
+| `completion_temperature` | `declarative_completion_temperature` setting (default `0.2`) | Temperature for the model completion |
+| `preferred_model_id` | (mode default) | Model alias to use for this operation |
+| `response_format_model_path` | (none) | Dotted path to a Pydantic response model class |
+| `response_output_text_field` | `"output_text"` | Field name to extract as `OperationResult.output_text` |
+| `response_output_json_passthrough` | `{}` | Dotted-path mappings to copy from last tool output into result |
+
+### Optional response-format model (`.py`)
+
+```python
+from pydantic import BaseModel, Field
+
+
+class BriefingOutput(BaseModel):
+    summary: str = Field(default="", description="Full markdown briefing.")
+    sources: list[str] = Field(default_factory=list, description="Grounded URLs from tool results.")
+    key_points: list[str] = Field(default_factory=list, description="Bullet-point highlights.")
+```
+
+When `response_format_model_path` is set, the declarative runtime:
+
+1. Passes the model class to `ctx.host.complete` as `response_format`.
+2. On a parse failure or a provider rejection (`structured_output_unsupported`), appends
+   a JSON-only retry instruction and retries without the `response_format` parameter.
+3. Extracts `response_output_text_field` from the parsed model for `OperationResult.output_text`.
+
+If you omit the response model, the operation returns the model's raw text.
+
+## Binding operations to a mode
+
+Operations are invoked by the turn runner when a mode declares them in its
+`_mode.md` front matter:
+
+```yaml
+---
+mode_id: my_mode
+mode_kind: chat
+entry_operation_ids: [load_context]          # run once on mode entry
+pre_turn_operation_ids: [research_briefing]  # run before every model completion
+allowed_operation_ids: [recall, summarize]   # model can call these as tools
+post_turn_operation_ids: [synthesize_notes]  # run after every turn
+---
+```
+
+Listing an operation in any of these four lists automatically grants it permission for
+the mode, regardless of the operation's own `mode_allowlist`. Mode-owned bindings are
+the authoritative source; `mode_allowlist` in the operation's metadata is a secondary
+grant.
+
+## Discovery rules and precedence
+
+- `sdk.content.build_operation_catalog_json` scans `operations/` recursively.
+- Markdown operations (`.operation.md`) are loaded first and take precedence.
+- If a directory has both `my_op.operation.md` and `my_op.py`, the `.py` file is
+  treated as the response-format model only — its `execute` function (if any) is
+  ignored.
+- Python runtime operations must have a sibling `.yml` file with matching `operation_id`
+  or the catalog loader skips them with a warning.
+- Module paths for Python modules are inferred automatically from their location
+  relative to the package root. Use `module_path` in the `.yml` only when auto-inference
+  is wrong.
+
+## Testing
+
+### Import boundary test (required)
+
+Every pack must verify it imports cleanly without private app modules:
+
+```python
+# tests/test_import_boundaries.py
+import importlib
+
+
+def test_pack_imports_cleanly() -> None:
+    importlib.import_module("my_pack")
+```
+
+### Catalog discovery test (recommended)
+
+```python
+# tests/test_catalog.py
+from pathlib import Path
+from sdk.content import build_operation_catalog_json
+import json
+
+
+def test_my_operation_discovered() -> None:
+    import my_pack
+
+    root = my_pack.get_content_root() / "operations"
+    catalog = json.loads(build_operation_catalog_json([root]))
+    assert "my_operation" in catalog
+    op = catalog["my_operation"]
+    assert op["description"]
+    assert "my_mode" in op["mode_allowlist"]
+
+
+def test_tool_ids_declared() -> None:
+    import my_pack
+
+    root = my_pack.get_content_root() / "operations"
+    catalog = json.loads(build_operation_catalog_json([root]))
+    assert catalog["read_status_file"]["tool_ids"] == ["read_file"]
+```
+
+### Validate against live modes
+
+After source tests pass, install/activate the pack through a compatible
+host and inspect `/modes` and `/operations`, then invoke its mode command.
+The framework workspace does not install `lisa`; use the external
+[CLI reference](https://github.com/Lisa-Harness/lisa-cli) for its command
+syntax. `SDK_CONTENT_ROOTS` discovers content but does not make arbitrary
+Python modules importable.
+
+## Pre-merge checklist
+
+- `packstest.catalog.validate_pack(<pack-path>)` passes from source (entry points load, every tool/operation YAML parses, all implementation modules import in-process).
+- `operation_id` is unique across all packs you intend to load simultaneously.
+- `description` is a non-empty one-line summary.
+- Every entry in `tool_ids` is registered in the tool catalog.
+- `mode_allowlist` lists at least one mode, or the operation is intentionally global.
+- For declarative operations: the front-matter body is non-empty and
+  `response_format_model_path` resolves to a real Pydantic class.
+- The pack imports cleanly with no host or private app imports.
+- Catalog discovery test passes without live services.
+
+## Common errors
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `OperationValidationError: … missing execute(ctx)` | Python module has no `execute` function | Add `async def execute(ctx)` |
+| `OperationValidationError: … references unknown tool 'X'` | `tool_ids` entry not in tool catalog | Register the tool in your pack's `tools/` dir or remove the entry |
+| `OperationExecutionError: … is not allowed for mode 'Y'` | Mode doesn't bind the operation and `mode_allowlist` doesn't include it | Add operation to `allowed_operation_ids` in the mode's `_mode.md` |
+| `OperationExecutionError: cannot call undeclared tool 'X'` | Declarative operation called a tool not in `tool_ids` | Add the tool to `tool_ids` in the front matter |
+| `CatalogCollisionError: duplicate operation_id 'X'` | Two packs define the same `operation_id` | Use `LISA_SESSION_PROVIDER_SELECTIONS` or rename one operation |
+| `validate_pack`: `module … not importable` | Tool/operation module missing or unimportable from the content root | Add the missing `__init__.py` (every package level) or fix the `module_path` |
+| `validate_pack`: `provider id unresolved` | Tool YAML has no `pack_id`/provider and the content root has no readable `pyproject.toml` | Set `tool_provider_id`/`pack_id` in the YAML; keep the distribution `pyproject.toml` at the pack root |

lisa_harness_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: lisa-harness-sdk
+Version: 0.1.0
+Summary: Lisa SDK — reusable operations, modes, signal connector shims, and domain models for Lisa-powered bots
+Requires-Python: >=3.11
+Requires-Dist: cel-python>=0.5.0
+Requires-Dist: diskcache>=5.6
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lisa-harness-kernel
+Requires-Dist: openai>=1.59.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: sqlite-vec>=0.1.9
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: wcmatch>=8.5
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.34; extra == 'bedrock'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'

lisa_harness_sdk-0.1.0/README.md

@@ -0,0 +1,79 @@
+# SDK
+
+`lisa-harness-sdk` (`sdk`) is the reusable content-discovery, customization-parsing, and repository-facing helper layer of the Lisa Harness. It sits between the runtime-neutral `kernel` and the concrete runtime that packs compose: the kernel owns contracts and the turn loop, the SDK owns the catalog scanners, model router, provider gateways, and the memory/thread/guard/storage/fetch primitives that first-party MCP servers expose.
+
+## Design Philosophy
+
+The SDK holds **domain logic for everything the first-party MCP servers expose**, plus the pluggable runtime backends (providers, routers) that hosts discover through entry points. `mcp_server` stays a thin transport facade over these modules.
+
+Key principles:
+
+- **Generic and dependency-light**: SDK abstractions must work for any runtime. The SDK may import from `kernel`, never from `runtime`.
+- **Import-safe public helpers**: no registration, environment reads, or I/O at module import time. Resolved configuration is accepted explicitly.
+- **Server boundary**: file I/O goes through the storage sandbox (relative paths only, deny-glob policy); SSRF protections and the response-size ceiling in the fetch primitive are non-bypassable. Environment translation belongs in host or tool adapters, not in the primitives.
+- **Namespace package**: `sdk` is a PEP 420 namespace shared with the bundled packs under `sdk/packs/`, which ship their own wheels. The `sdk` content root is exported from [`src/sdk/_content_root.py`](src/sdk/_content_root.py).
+
+See [architecture](../docs/BOUNDARIES.md), [memory](../docs/MEMORY_ARCHITECTURE.md),
+[storage](../docs/STORAGE.md), and the [documentation index](../docs/README.md)
+for cross-package contracts.
+
+## Module Map
+
+### Catalog, Content & Context
+
+| Module | Responsibility |
+| --- | --- |
+| `content/` | Content catalog and authored-text reading: mode/operation/tool catalog JSON builders, content-root resolution, `ContentReader`, path safety, Copilot customization discovery/parsing (applyTo globbing). Powers the `lisa-content` and `lisa-catalog` MCP servers. |
+| `context/` | Entry-point-aware extension item building: discovers `lisa.extensions.context_items` entry points and feeds extension evidence into the session-owned context mapper via `ContextSeams.extension_item_builder`. |
+| `config.py` | Public runtime `Settings` (pydantic-settings) for packs/extensions — deliberately narrower than root app config, with owned-source filtering so packs only consume env keys they declare. |
+| `pack_settings.py` | `OwnedSettingsSource` / `build_owned_settings_sources`; importable by external packs without depending on `sdk_packs`. |
+| `layout.py` | Single source of truth for the canonical data-dir categories (`config/`, `state/`, `data/`, `cache/`, `logs/`, `run/`) shared by hosts, SDK, MCP servers, and packs. |
+
+### State & Memory Primitives
+
+| Module | Responsibility |
+| --- | --- |
+| `memory/` | SQLite-backed memory store library (vec0 embeddings, backups). The `lisa-memory` MCP server wraps it. |
+| `thread/` | Lossless, segmented conversation-thread store (`ThreadStore`): three-tier layout (active/sealed segments + sparse index) with zstd sidecars and redaction policy. Owns the read path; the write path stays in `runtime.thread`. |
+| `storage/` | Sandboxed file I/O: `StorageBackend` owns the files sandbox, deny-glob policy, and model-manifest read/write. The `lisa-storage` MCP server wraps it. |
+| `workproducts.py` | Typed, pack-neutral `WorkProduct` contract plus `WorkProductStore` protocol — durable, approvable units of work shared across packs (cross-pack imports are forbidden, so the contract sits on neutral SDK ground). The host injects the file-based implementation. |
+
+### Safety & Fetch
+
+| Module | Responsibility |
+| --- | --- |
+| `guard/` | Content-safety validation backends: `GuardBackend` protocol, default `PassthroughGuardBackend`, result formatting, blocked-check audit logging. The `lisa-guard` MCP server owns transport. |
+| `mcp_host/` | Pure config construction for first-party MCP servers (`build_content_mcp_config`, `build_catalog_mcp_config`). Pool lifecycle is deliberately host-owned because anyio cancel scopes bind to the host's event loop. |
+
+### Pluggable Runtime Backends
+
+| Module | Responsibility |
+| --- | --- |
+| `providers/` | Reference `ProviderGatewayProvider` implementations for OpenAI, Azure OpenAI, Anthropic, Google Gemini, and AWS Bedrock, registered via `lisa.extensions.provider_gateways`. Explicitly not a pack — a pluggable runtime backend. |
+| `router/` | The built-in `lisa-router`: a pure-Python CEL/rules engine that selects a model per turn-loop iteration from the manifest's `router.rules` block with zero model calls, registered via `lisa.extensions.model_routers`. See [`src/sdk/router/README.md`](src/sdk/router/README.md). |
+
+### Shared Infrastructure
+
+| Module | Responsibility |
+| --- | --- |
+| `logging_setup.py` | Shared stdlib-logging infrastructure for all hosts and first-party MCP servers: `JSONFormatter`, `RateLimitFilter`, `configure_logging`, `emit_structured_event`. Stdlib-only so subprocesses need not import the kernel. |
+| `workspace.py` | Single shared `resolve_workspace_root` with explicit strictness (`require_git` knob) so packs no longer derive the user's project root independently. |
+
+## Bundled Packs
+
+The `sdk/packs/` subtree contains the bundled reference packs — `core`, `memory`, `introspect`, `recovery` — which ship as their own distributions and are excluded from the `lisa-harness-sdk` wheel. For pack structure, mode front matter, operations, signal connectors, and the testing workflow, see:
+
+- [docs/PACK_AUTHORING_GUIDE.md](../docs/PACK_AUTHORING_GUIDE.md) — pack anatomy, mode files, extension entry points, and the hello-world walkthrough.
+- [AUTHORING.md](AUTHORING.md) — the operation authoring deep-dive (runtime vs. declarative, metadata fields, the `execute(ctx)` contract).
+- The [lisa-packs](https://github.com/Lisa-Harness/lisa-packs) repo — the public external packs, their installation, and the per-pack submodule workflow for authoring real integration packs.
+
+## Testing
+
+```bash
+uv run pytest sdk/tests sdk/src/sdk/context/tests sdk/src/sdk/guard/tests sdk/src/sdk/memory/tests sdk/src/sdk/storage/tests -m "not live" -q
+```
+
+Run from the workspace root; this selects SDK tests, not bundled pack suites.
+See [testing](../docs/TESTING.md) for the complete CI selection.
+
+Markers: `live` (hits real external signal or provider APIs), `integration` (multi-module in-process; may require Azurite on localhost:10000), `eval` (deterministic agent regression evals — no model calls, no I/O). Pack validation itself belongs to the `packstest` harness; see [`../packstest/README.md`](../packstest/README.md).

lisa_harness_sdk-0.1.0/packs/.instructions.md

@@ -0,0 +1,12 @@
+---
+name: SDK Packs
+applyTo: "sdk/packs/**/*.py"
+description: Package-specific guidance for pack development.
+---
+
+# Pack development guidance
+
+- Keep packs self-contained and host-neutral. Prefer thin runtime handlers over embedding orchestration concerns.
+- Preserve the existing discovery and registration pattern for operations and tools.
+- Keep pack content and runtime behavior aligned so the catalog can discover operations without side effects.
+- Avoid cross-pack imports; promote shared helpers into the SDK when needed.

lisa_harness_sdk-0.1.0/packs/README.md

@@ -0,0 +1,47 @@
+# Bundled reference packs
+
+These are independently packaged distributions in the shared `sdk.packs`
+namespace, not submodules included in the SDK wheel.
+
+| Pack | Role | Activation |
+| --- | --- | --- |
+| [core](core/) | Default, planner, and explainer modes; delegation/planning operations, fetch tool, shared prompts, default session | Host-mandatory |
+| [introspect](introspect/) | Operational self-model and reflective assessment | Host-mandatory |
+| [memory](memory/) | Scoped recall/learning operations, memory backend manifest, consolidation/mining slice | Optional |
+| [recovery](recovery/src/sdk/packs/recovery/README.md) | Inspect, retry, skip/cancel stalled dispatches and resume yielded turns | Optional |
+
+All four are runtime dependencies. That does not make every optional pack
+active in every session. Host policy, pack lock state, and the session plan
+control activation. Use `/pack`, `/modes`, `/operations`, and `/tools` to
+inspect the active catalog.
+
+## Authoring and ownership
+
+Packs export content roots and other extension entry points. They provide
+workflow and application capability, not the host's transport or durable
+service implementation. New packs should depend on kernel/SDK contracts
+and injected services, not runtime internals or another pack.
+
+- [Pack authoring](../../docs/PACK_AUTHORING_GUIDE.md)
+- [Operation authoring](../AUTHORING.md)
+- [Session selection](../../docs/SESSION_CONTEXT_AUTHORING_GUIDE.md)
+- [Memory architecture](../../docs/MEMORY_ARCHITECTURE.md)
+- [External pack registry](https://github.com/Lisa-Harness/lisa-packs)
+
+Bundled pack prompts/modes are part of behavior and are held to the same
+[test assurances](../../docs/CODING_WORKFLOW.md#test-assurances) as code.
+Editing a prompt is not automatically a documentation-only change.
+
+## Verification
+
+From the workspace root:
+
+```sh
+uv run pytest sdk/packs/core/tests sdk/packs/memory/tests sdk/packs/recovery/tests -m "not live" -q
+```
+
+Run [packstest](../../packstest/README.md) from source before testing an
+installed wheel. Bundled packs use its
+[explicit-root scan](../../packstest/README.md#source-layout-packs);
+warning-only root discovery is not catalog coverage. Workflows also need opt-in
+[whole-runtime scenarios](../../e2etest/README.md).

lisa_harness_sdk-0.1.0/packs/core/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+# sdk.packs.core lives under the shared sdk namespace; hatchling includes
+# all files in the package dir by default (no package-data globs needed).
+packages = ["src/sdk"]
+only-include = ["src/sdk/packs/core"]
+
+[project]
+name = "lisa-pack-core"
+version = "0.1.0"
+description = "Lisa core pack - baseline modes, operations, and authored content"
+requires-python = ">=3.11"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=6.0.0",
+    "pytest-mock>=3.14.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 Azurite on localhost:10000",
+    "eval: deterministic agent regression evals (no model calls, no I/O)",
+]
+
+[project.entry-points."lisa.extensions.content_roots"]
+core = "sdk.packs.core:get_content_root"

lisa_harness_sdk-0.1.0/packs/core/src/sdk/packs/core/__init__.py

@@ -0,0 +1,14 @@
+"""Core baseline pack for Lisa.
+
+Contains the shipped baseline modes, authored markdown assets, and reusable operations
+that the host runtime loads through pack discovery.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def get_content_root() -> Path:
+    """Return the content root directory for this pack."""
+    return Path(__file__).parent

lisa_harness_sdk-0.1.0/packs/core/src/sdk/packs/core/content/prompts/sub_turn/budget_exhausted.md

@@ -0,0 +1,3 @@
+# Sub-turn budget-exhausted tail
+
+BUDGET EXHAUSTED — call an action tool now or yield.

lisa_harness_sdk-0.1.0/packs/core/src/sdk/packs/core/content/prompts/sub_turn/delegate_contract.md

@@ -0,0 +1,8 @@
+# Delegate-child sub-turn contract body
+
+Subroutine child: success REQUIRES calling at least one of: [{tools_list}].
+Read-only calls do NOT count. If the budget exhausts without a write, return
+status=no_tools so your parent can decide — do not claim success.
+
+{remaining_iterations} iterations remain to produce a write; reads are
+scaffolding, not progress.

lisa_harness_sdk-0.1.0/packs/core/src/sdk/packs/core/content/prompts/sub_turn/fork_contract.md

@@ -0,0 +1,8 @@
+# Fork-child sub-turn contract body
+
+Fork child: success REQUIRES calling at least one of: [{tools_list}]. Read-only
+calls do NOT count. If the budget exhausts without a write, your output is
+discarded as unverified — do not claim success.
+
+{remaining_iterations} iterations remain to produce a write; reads are
+scaffolding, not progress.

lisa_harness_sdk-0.1.0/packs/core/src/sdk/packs/core/content/prompts/sub_turn/midpoint_write_nudge.md

@@ -0,0 +1,6 @@
+# Sub-turn midpoint write-nudge body
+
+You are past the midpoint of your budget with zero writes. Call one of:
+[{action_list}] eminently to complete your work, or call `yield` to hand back
+honestly. Continuing to read without writing will result in your output being
+discarded.

lisa_harness_sdk-0.1.0/packs/core/src/sdk/packs/core/content/prompts/sub_turn/no_write_warning.md

@@ -0,0 +1,4 @@
+# No-verified-write warning footnote
+
+⚠️ This response produced no verified write;
+available actions on the last turn were: {action_names}