lisa-pack-core 0.1.0__tar.gz

lisa_pack_core-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_pack_core-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: lisa-pack-core
+Version: 0.1.0
+Summary: Lisa core pack - baseline modes, operations, and authored content
+Requires-Python: >=3.11
+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_pack_core-0.1.0/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_pack_core-0.1.0/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_pack_core-0.1.0/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_pack_core-0.1.0/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_pack_core-0.1.0/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_pack_core-0.1.0/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_pack_core-0.1.0/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}

lisa_pack_core-0.1.0/src/sdk/packs/core/content/prompts/system-prompt.md

@@ -0,0 +1,9 @@
+# Lisa Harness
+
+Operate according to the session context.
+Everything before `## User Query` is session context.
+
+## Capabilities
+
+If the request asks for an action no available operation or tool enacts,
+and no mode routing hint satisfies, say so.

lisa_pack_core-0.1.0/src/sdk/packs/core/content/prompts/thread_manifest_hint.md

@@ -0,0 +1,37 @@
+# Thread manifest hint
+
+The manifest above is a table of contents of **past** turns.
+Each row is a resolved exchange — do not re-raise, re-narrate, or continue issues from earlier rows.
+The row marked `← current` is the turn the user is responding to; treat the rest as history.
+
+## When to pull prior turns
+
+Pull prior turns when:
+
+- The user references prior work ("that thing we did earlier", "the fix from yesterday").
+- You need to verify a past decision before acting on a related request.
+- The current query does not make sense without getting prior context.
+
+## How to find the right turns
+
+- **Within this manifest window**: scan the table for queries matching the current topic. Use `thread_read_range` for the relevant turn numbers.
+- **Tool results from earlier turns**: pass `include_transcript: true` to get tool call/result previews. Large values carry a `ref`, head/tail excerpts, and an omitted-character count; they are not full results. Use `thread_read_content(ref=...)` to expand only the value you need instead of calling the original tool again.
+- **Beyond this manifest window** (turns older than the last 30): use `thread_search` with a keyword or phrase, then read the matching turns. Do not scan the whole thread to find a specific result.
+- **Continue a read**: responses contain `entries`, `next_cursor`, and `has_more`. Follow `next_cursor` using the same tool and inputs. Expansion pages use `next_offset_chars` with the same `ref`; offsets count Unicode characters after redaction. The complete permitted content remains recoverable from the lossless archive.
+- **Find specific evidence**: `thread_search` accepts `tool_name`, `path`, `task_id`, and turn-range filters and searches tool arguments/results too. Its matches contain references and offsets into the permitted content. Use `thread_find_content(ref=..., query=...)` to locate text inside one large result, then expand only the matching span.
+- **Live or resumed results**: large tool results are previews with durable `r...` references. Expand or search them with the same thread tools; full output is not lost. Under context pressure, an `inventory_ref` replaces complete older tool groups and lists their arguments and result references. Retrieve only the evidence needed for the current task.
+- **Resume a task**: call `thread_task_view` first. It returns recorded objective/latest previews, blocking status, modes, receipt effects with artifact IDs, and expandable archive evidence references. If `history_may_be_incomplete` is true, the scan may omit the original objective or earlier work; retrieve older evidence with task-filtered `thread_search`. Truncation flags mark omitted content; expand references rather than using abbreviated identities as full task or approval IDs.
+
+## What not to do
+
+- Do not re-raise, re-narrate, or continue resolved issues from earlier rows.
+
+## Cross-checking memory
+
+Memories surfaced by `memory.search` are distilled claims, not observations.
+They summarize what past turns proved, but they can be stale, imprecise, or
+superseded. When a recalled memory conflicts with live tool output or with a
+thread turn you can read via `thread_read_range`, **the thread and the tool
+win** — cite the turn you verified against. Use the memory's `source_turn`
+pointer (rendered as "learned around turn N") to pull the originating turn
+before acting on a recalled claim that matters.

lisa_pack_core-0.1.0/src/sdk/packs/core/content/redaction_patterns.yml

@@ -0,0 +1,46 @@
+# Pack-contributed thread redaction patterns
+#
+# Packs ship this file at `content/redaction_patterns.yml` to contribute
+# recommended redaction patterns as a best-practice set. The host scans
+# all active pack content roots at startup, merges every pack's patterns
+# with the framework defaults, and compiles them into a single
+# ThreadRedactionPolicy.
+#
+# Each entry is a raw regex string applied at read-time to thread
+# `response_text` and `query` fields before they enter model context.
+# Matched substrings are replaced with a strikethrough marker; the raw
+# thread log is never mutated.
+#
+# Patterns should target harness-authored or model-self-reported text
+# that contaminates subsequent turns — e.g. cap-fire diagnostics, stale
+# budget claims, or mode-specific self-reports that the model
+# pattern-matches against the current turn's lifecycle briefing.
+#
+# Convention: patterns are anchored on the distinctive prose of the
+# message, not on variable parts like mode names or counts, so they
+# generalize across modes and turn numbers. Use `[^\n]*` to extend to
+# end-of-line rather than `.*` (which would eat across line breaks and
+# redact unrelated content).
+
+patterns:
+  # Model-authored: "I've hit my iteration budget in <mode> (...)."
+  - "I've hit my iteration budget[^\\n]*"
+
+  # Model-authored: "I've hit my iteration budget for this turn. ..."
+  - "I've hit my iteration budget for this turn[^\\n]*"
+
+  # Harness-fabricated capability-cap yield: "I've reached a resource
+  # budget for this turn. ..." — b79ba861's fallback question text. The
+  # 2026-10-17 turns 873/874 incident showed the claim persisting
+  # unredacted (none of the older phrasings match it), so the model read
+  # its own false exhaustion report back as ground truth.
+  - "I've reached a resource budget[^\\n]*"
+
+  # Harness pause diagnostic: "stuck in <mode> for N iterations (cap)"
+  - "stuck in \\w+ for \\d+ iterations \\(cap\\)[^\\n]*"
+
+  # Harness yield: "iteration cap N reached"
+  - "iteration cap \\d+ reached[^\\n]*"
+
+  # Harness yield: "turn budget exhausted"
+  - "turn budget exhausted[^\\n]*"

lisa_pack_core-0.1.0/src/sdk/packs/core/modes/default/_mode.md

@@ -0,0 +1,17 @@
+---
+mode_id: default
+mode_provider_id: lisa-pack-core
+mode_kind: chat
+routable: true
+priority: 10
+description: "General conversational mode."
+---
+# Default Chat
+
+Act on the most reasonable interpretation of the request.
+State the interpretation in one line, then do the work.
+Seek clarification when the request is ambiguous or the intention is unclear.
+
+When you lack a capability,
+hand off: call `transition_stage` toward a mode whose tools fit the request.
+Only stop to ask the operator when no mode in the catalog provides it either.

lisa_pack_core-0.1.0/src/sdk/packs/core/modes/explainer/_mode.md

@@ -0,0 +1,43 @@
+---
+mode_id: explainer
+mode_provider_id: lisa-pack-core
+mode_kind: chat
+routable: true
+command_pattern: '^(?:/)?explain(?:er)?(?:[\s,:;]+(?P<query>.+))?$'
+priority: 1
+fast_path_patterns:
+  - "\\bexplain(?:er)?\\b"
+  - "\\bsummarize\\b"
+routing_intent_tags: [explain, expound, summarize, capture]
+satisfies_intents: [explain, expound, summarize, capture]
+routing_intent_keywords:
+  explain:
+    - capture
+    - explain
+    - expound
+    - summarize
+allowed_operation_ids: [markdown_forge_document, recall_memory, synthesize_and_store_learning]
+description: "Terminal last-resort mode that expounds the work and analysis done so far into a durable markdown artifact. Used by the forced-transition-before-cap path to guarantee every turn ends productively."
+---
+
+# Explainer Mode
+
+You are the terminal capture mode. You are reached when another mode
+exhausted its budget without producing a verified write. Your only job is
+to synthesize the work and analysis done so far into a durable markdown
+document so the turn ends productively.
+
+Do not perform new research. Do not explore the codebase. Do not search
+the web. Use `recall_memory` to retrieve what was captured during the
+prior turns, then call `markdown_forge_document` to write a synthesis
+document.
+
+The document must include:
+
+- A header naming the workflow and the modes that ran.
+- A summary of what was accomplished.
+- The key findings or analysis produced.
+- Any open items or next steps the prior mode did not complete.
+
+When `markdown_forge_document` succeeds, the turn is complete. Do not
+call `transition_stage` or `yield` — this is a terminal stage.

lisa_pack_core-0.1.0/src/sdk/packs/core/modes/planner/_mode.md

@@ -0,0 +1,41 @@
+---
+mode_id: planner
+mode_provider_id: lisa-pack-core
+mode_kind: action
+routable: true
+priority: 11
+fast_path_patterns:
+  - "\\bplan(?:ner)?\\b"
+  - "\\bprioritize\\b"
+  - "\\bmulti.?step\\b"
+routing_intent_tags: [plan]
+satisfies_intents: [plan]
+routing_intent_keywords:
+  plan:
+    - plan
+    - prioritize
+    - workflow
+    - multi-step
+    - orchestrate
+entry_operation_ids: [plan_workflow]
+entry_op_kind: routing
+command_pattern: '^(?:/)?plan(?:er)?(?:[\s,:;]+(?P<query>.+))?$'
+needs_full_mode_catalog: true
+description: "Orchestrates tasks, breaks down intent, uses fork to dispatch parallel sub-tasks."
+---
+
+# Planner Mode
+
+Analyze the user's request and produce a visible multi-step plan.
+
+Call `plan_workflow` to produce the plan. The operation returns a `steps`
+array (one entry per detected step, in execution order) and a
+`target_stage_id` (the first step's `mode_id`). The kernel renders the
+plan as a markdown block shown to the user, persists it as a
+`WorkflowInstance`, and drives the handoff itself — do **not** call
+`transition_stage`; the framework hands off, fans out, or chains the
+next step automatically from the plan result.
+
+When `plan_workflow` returns an empty `target_stage_id` and no `steps`
+(no routable mode matched, no model wiring, or a parse failure), respond
+to the user directly.

lisa_pack_core-0.1.0/src/sdk/packs/core/operations/__init__.py

@@ -0,0 +1 @@
+"""Bundled ``lisa-pack-core`` operations."""

lisa_pack_core-0.1.0/src/sdk/packs/core/operations/delegation/__init__.py

@@ -0,0 +1 @@
+"""Delegation operations shipped with ``lisa-pack-core``."""

lisa_pack_core-0.1.0/src/sdk/packs/core/operations/delegation/delegate.md

@@ -0,0 +1,61 @@
+# Delegate operation instruction
+
+## Purpose
+
+Delegate a sequential sub-turn to another mode. The parent turn stays
+alive, waits for the child's structured result, and can use the child's
+output to make further decisions. This is the sequential counterpart to
+the `fork` operation (which fans out in parallel and returns all
+children's results to the parent for synthesis).
+
+## When to call
+
+Call `delegate` when:
+
+- You need another mode's capability and want to use its result in the
+  same turn (e.g. delegate to `search` for evidence, then synthesize).
+- You want to build a multi-step agent workflow where each step's output
+  feeds the next.
+- You need recursive delegation (a delegate child can itself delegate,
+  bounded by `DELEGATE_MAX_DEPTH`).
+
+Do NOT call `delegate` when:
+
+- You just need to hand off to another mode and end your turn. Use
+  `transition_stage` for that.
+- You need parallel fan-out to multiple modes. Call the `fork` operation
+  for that.
+
+## Available Modes
+
+The target `target_mode_id` must be a routable mode from the installed
+catalog. Non-routable modes cannot be delegated to.
+
+## Parameters
+
+- `target_mode_id` (required): The routable mode to delegate to.
+- `query` (required): The scoped input text for the child. This is the
+  child's user query — not your full query. Scope it tightly.
+- `stage_id` (optional): A stage within the target mode. Defaults to the
+  mode's start stage.
+- `max_tool_iterations` (optional): Per-child iteration cap. 0 means use
+  the kernel default.
+- `model_alias` (optional): Model override for the child. Empty means
+  use the target mode's resolved model.
+
+## Result
+
+The operation returns a `DelegationResult` with:
+
+- `status`: one of `ok`, `no_tools`, `timeout`, `error`, `cancelled`,
+  `interrupted`, `model_yield`, `max_depth`.
+- `output_text`: the child's response text.
+- `tool_call_count` and `called_tool_names`: what the child actually did.
+- `error_message`: present when `status` is not `ok`.
+- `yield_action`: present when the child yielded (asked a question).
+
+Inspect `status` before acting on the result. `no_tools` means the
+child completed without invoking its action tools — its reported success
+is unverified. `interrupted` means the child hit its iteration cap before
+finishing. `max_depth` means the delegation chain exceeded the recursion
+limit.

lisa_pack_core-0.1.0/src/sdk/packs/core/operations/delegation/delegate.py

@@ -0,0 +1,198 @@
+"""Delegate operation — sequential sub-turn delegation to another mode.
+
+A thin pack-level handler that reads authored content, resolves the target
+mode from the installed catalog, builds a :class:`DelegationSpec` from
+LLM-supplied parameters, calls the injected ``ctx.host.delegate``, and
+returns the :class:`DelegationResult` as the operation's structured
+output.
+
+The handler owns no routing or framework state. The kernel wires
+``delegate_fn`` into the :class:`OperationHost` (``ctx.host``) at turn
+start; the default implementation (``_default_delegate_fn``) runs
+``run_turn`` recursively as a ``sub_turn_kind="delegate"`` child. A host
+may override ``TurnHooks.delegate_fn`` to inject a custom delegation
+backend without touching this handler.
+
+Per the pack-content rule, the model-facing instruction prose lives in
+authored Markdown (``operations/delegation/delegate.md``) loaded through
+``ctx.host.read_authored_text``. This module contains only path
+constants, the structured ``Parameters`` model, and substitution glue.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from kernel.delegation import DelegationResult, DelegationSpec
+from kernel.ipsar_fsm import get_workflow_catalog
+from kernel.models import OperationExecutionContext, OperationResult
+from pydantic import BaseModel, Field, ValidationError
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["Parameters", "execute"]
+
+_DELEGATE_INSTRUCTION_PATH = "operations/delegation/delegate.md"
+
+
+class Parameters(BaseModel):
+    """User-supplied inputs for the delegate operation."""
+
+    target_mode_id: str = Field(
+        ...,
+        description=(
+            "The routable mode_id to delegate to. Must be one of the "
+            "Available Modes listed in the operation instruction."
+        ),
+    )
+    query: str = Field(
+        ...,
+        description=(
+            "The scoped input text for the delegated child. This is the "
+            "child turn's user query — not the parent's full query."
+        ),
+    )
+    stage_id: str = Field(
+        default="",
+        description=(
+            "Optional stage_id for the target mode. Defaults to the "
+            "mode's start_stage_id when empty."
+        ),
+    )
+    max_tool_iterations: int = Field(
+        default=0,
+        description=(
+            "Optional per-child iteration cap override. 0 means use the "
+            "kernel default (DELEGATE_CHILD_MAX_TOOL_ITERATIONS)."
+        ),
+        ge=0,
+    )
+    model_alias: str = Field(
+        default="",
+        description=(
+            "Optional model alias override for the child turn. Empty "
+            "means use the target mode's resolved model."
+        ),
+    )
+
+
+def _resolve_parameters(ctx: OperationExecutionContext) -> Parameters:
+    """Build a :class:`Parameters` from the operation context.
+
+    Validates the LLM-supplied ``ctx.params`` dict against the schema. A
+    ``ValidationError`` surfaces a clear error to the model via the
+    returned ``OperationResult`` rather than crashing the turn.
+    """
+    raw = ctx.params or {}
+    # Allow the caller to pass the query via ctx.query when the operation
+    # is invoked as an entry operation (no explicit ``query`` param).
+    if not raw.get("query") and ctx.query:
+        raw = {**raw, "query": ctx.query}
+    return Parameters.model_validate(raw)
+
+
+def _render_result_text(result: DelegationResult) -> str:
+    """Render a :class:`DelegationResult` as a human-readable text block.
+
+    The parent mode reads this from ``output_text``. The structured
+    payload (including ``status``, ``tool_call_count``, and
+    ``called_tool_names``) is in ``output_json``.
+    """
+    lines: list[str] = [
+        f"## Delegation to `{result.target_mode_id}`",
+        "",
+        f"- **Status**: `{result.status}`",
+        f"- **Duration**: {result.duration_ms} ms",
+        f"- **Tool calls**: {result.tool_call_count}",
+    ]
+    if result.called_tool_names:
+        lines.append(f"- **Tools called**: {', '.join(result.called_tool_names)}")
+    if result.error_message:
+        lines.append("")
+        lines.append(f"**Error**: {result.error_message}")
+    if result.output_text:
+        lines.append("")
+        lines.append("### Child output")
+        lines.append("")
+        lines.append(result.output_text)
+    return "\n".join(lines)
+
+
+async def execute(ctx: OperationExecutionContext) -> OperationResult:
+    """Delegate a sub-turn to another mode and return the structured result.
+
+    Builds a :class:`DelegationSpec` from the validated parameters, calls
+    the injected ``ctx.host.delegate``, and returns the
+    :class:`DelegationResult` as both ``output_text`` (rendered) and
+    ``output_json`` (structured).
+
+    Fails loudly when ``delegate`` is not wired on the host (the host has
+    not enabled delegation) or the target mode is not in the installed
+    catalog — per the pack-content rule, no silent fallback.
+    """
+    try:
+        params = _resolve_parameters(ctx)
+    except ValidationError as exc:
+        return OperationResult(
+            output_text=f"delegate parameter validation failed: {exc}",
+            output_json={"status": "error", "error_message": str(exc)},
+        )
+
+    # Resolve the target mode against the live catalog so the operation
+    # fails loudly on an unknown mode_id rather than handing the kernel
+    # an invalid target.
+    catalog = get_workflow_catalog()
+    target_config = catalog.get(params.target_mode_id)
+    if target_config is None:
+        return OperationResult(
+            output_text=(
+                f"delegate target mode '{params.target_mode_id}' is not in "
+                "the installed catalog; cannot delegate."
+            ),
+            output_json={
+                "target_mode_id": params.target_mode_id,
+                "status": "error",
+                "error_message": f"unknown target mode: {params.target_mode_id}",
+            },
+        )
+
+    host = getattr(ctx, "host", None)
+    if host is None or getattr(host, "delegate", None) is None:
+        return OperationResult(
+            output_text=(
+                "ctx.host.delegate is not wired; the host has not enabled "
+                "delegation. Cannot delegate."
+            ),
+            output_json={
+                "target_mode_id": params.target_mode_id,
+                "status": "error",
+                "error_message": "host.delegate not wired",
+            },
+        )
+
+    spec = DelegationSpec(
+        target_mode_id=params.target_mode_id,
+        query=params.query,
+        stage_id=params.stage_id,
+        max_tool_iterations=params.max_tool_iterations,
+        model_alias=params.model_alias,
+    )
+
+    result = await host.delegate(spec)
+    if not isinstance(result, DelegationResult):
+        return OperationResult(
+            output_text=(
+                "runtime.delegate returned an unexpected result type "
+                f"({type(result).__name__}); expected DelegationResult."
+            ),
+            output_json={
+                "target_mode_id": params.target_mode_id,
+                "status": "error",
+                "error_message": f"unexpected result type: {type(result).__name__}",
+            },
+        )
+
+    return OperationResult(
+        output_text=_render_result_text(result),
+        output_json=result.model_dump(mode="json"),
+    )

lisa_pack_core-0.1.0/src/sdk/packs/core/operations/delegation/delegate.yml

@@ -0,0 +1,14 @@
+operation_id: delegate
+description: >
+  Delegate a sequential sub-turn to another mode, wait for its structured
+  result, and return it to the parent. Unlike fork (parallel fan-out),
+  delegate keeps the parent turn alive so it can use the child's output
+  and make further decisions. The child runs as a sub_turn_kind="delegate"
+  turn with its own budget and action-tool validation.
+pack_id: lisa-pack-core
+effect: read
+execution_kind: runtime
+timeout_seconds: 300
+max_calls_per_turn: 5
+preferred_model_id: default
+exportable: true