linch 1.0.0__tar.gz

linch-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.venv/
+dist/
+build/
+*.egg-info/
+.agent_kit/
+.env
+.claude/
+.codex/
+.linch/
+
+# Vendored reference material (has its own git repo)
+learn-claude-code/

linch-1.0.0/AGENTS.md

@@ -0,0 +1,39 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`linch` is a Python SDK packaged from `src/linch`. Core runtime code lives in modules such as `agent.py`, `loop.py`, `scheduler.py`, `types.py`, and feature packages like `providers/`, `tools/`, `filesystem/`, `memory/`, `sessions/`, `skills/`, `subagents/`, and `observability/`. Tests mirror these areas under `tests/`, with focused subdirectories such as `tests/providers/`, `tests/tools/`, `tests/storage/`, and `tests/integration/`. Runnable examples are grouped by topic under `examples/`, docs live in `docs/`, and utility scripts live in `scripts/`.
+
+## Build, Test, and Development Commands
+
+Install for local development:
+
+```bash
+pip install -e '.[dev,mcp,anthropic,gemini]'
+```
+
+Run the main checks before opening a PR:
+
+```bash
+pytest
+ruff check . && ruff format --check .
+pyright
+```
+
+Use targeted tests while iterating, for example `pytest tests/tools/test_function_tools.py` or `pytest -k context`. Auto-fix style issues with `ruff check --fix . && ruff format .`. Live API tests require relevant credentials, such as `OPENAI_API_KEY`; unit tests must not depend on live services.
+
+## Coding Style & Naming Conventions
+
+Target Python 3.10+. Ruff enforces imports and lint rules (`E`, `F`, `I`, `UP`, `B`) with a 100-character line length. Use 4-space indentation, type annotations for public surfaces, and `slots=True` on new dataclasses following existing primitives. Keep runtime/provider paths async; avoid blocking I/O in `loop.py`, `scheduler.py`, `compaction.py`, and provider modules. Tool classes are duck-typed; do not introduce base-class inheritance where protocols are expected.
+
+## Testing Guidelines
+
+Tests use `pytest` with `pytest-asyncio` in auto mode. Name files `test_*.py` and keep assertions focused on one behavior. Prefer fake providers and `InMemorySessionStore` for loop tests. Live provider coverage belongs in integration tests and must skip cleanly without credentials. Some hardening tests reload `linch`; in affected tests, import `Agent`, `Session`, and related content types inside test functions rather than at module scope.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short imperative commit subjects, sometimes with a conventional prefix such as `chore:`. Examples: `Harden SDK from whole-codebase review` and `chore: exclude .claude and .codex from version control`. PRs should include a concise description, linked issue or motivation, behavioral notes, and the checks run. Add screenshots or logs only when they clarify UI, CLI, or observability changes.
+
+## Security & Configuration Tips
+
+Never commit `.env`, API keys, local caches, or generated private state. Keep provider-specific wire formats inside `src/linch/providers/`; shared loop code should consume normalized provider events only.

linch-1.0.0/CLAUDE.md

@@ -0,0 +1,198 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install for development (all extras)
+pip install -e '.[dev,mcp,anthropic]'
+
+# Run all tests
+pytest
+
+# Run a single test file
+pytest tests/test_agent_loop.py
+
+# Run a single test by name
+pytest tests/test_agent_loop.py::test_function_name
+
+# Lint
+ruff check .
+
+# Format check
+ruff format --check .
+
+# Auto-fix lint/format
+ruff check --fix . && ruff format .
+
+# Type check
+pyright
+```
+
+## Architecture
+
+Linch is a Python SDK for embedding a software engineering agent loop in applications. It is async-first, event-driven, and provider-agnostic.
+
+### Core flow
+
+```
+Agent (config) → Session (state) → run_loop() → Events → caller
+```
+
+1. **Agent** (`agent.py`) — holds immutable config: model, provider, tools, permissions, session_store, system prompt, compaction strategy.
+2. **Session** (`session.py`) — per-conversation state: `provider_view` (trimmed for LLM context), `full_history` (complete record), `workers` (live `WorkerHandle` objects keyed by worker_id), `pending_notifications` (background worker `<task-notification>` Messages drained at top of each turn). Call `session.run(prompt)` to get an `AsyncIterator[Event]`.
+3. **run_loop / stream_turn** (`loop/`) — the main agent loop, split by responsibility: `loop/runner.py` (`run_loop`, `resume_loop`, the turn loop), `loop/streaming.py` (`stream_turn` + ContextLengthError recovery), `loop/request.py` (user message / context / `ProviderRequest` assembly), `loop/terminals.py` (terminal event tails + closed-loop gates), `loop/checkpoint.py` (event persistence + checkpoint serialization), `loop/dispatch.py` (per-lifecycle `HookDispatcher.dispatch` wrappers, bound into the runner via `functools.partial`), `loop/finalize.py` (terminal-answer finalization — the final-tool/final-text gate+hook+tail logic, driven through a `FinalizeCtx`/`TerminalOutcome` pair). Each turn: build user message → run `ContextBuilder` → call `provider.stream()` → collect text/tool-use blocks → check permissions → execute tools (via `scheduler.py`) → emit events → repeat if more tool calls; stop on text-only response. The public surface is re-exported from `loop/__init__.py`, so `from linch.loop import ...` is unchanged.
+4. **Events** (`events.py`) — all communication from the loop is through events: `UserEvent`, `ContextBuildEvent`, `AssistantEvent`, `ToolCallStartEvent`, `ToolCallEndEvent`, `PermissionRequestEvent`, `UsageEvent`, `ResultEvent`, `ErrorEvent`, `CompactionEvent`, `LoopGuardEvent`, skill/subagent events, and `BackgroundWorkerEvent` (`worker_id`, `status`, `display_name`; emitted when a background worker completes).
+
+### Providers (`providers/`)
+
+Abstract interface (`BaseProvider`) with three methods: `context_window(model)`, `stream(req) → AsyncIterator[StreamEvent]`, and `capabilities(model) → ProviderCapabilities`. Implementations:
+- `OpenAIChatCompletionsProvider` — standard OpenAI Chat API; also drives OpenAI-compatible endpoints (e.g. DeepSeek) via `base_url`
+- `OpenAIResponsesProvider` — OpenAI o1/o3 Responses API (with reasoning tokens)
+- `AnthropicProvider` — Anthropic Claude; full streaming with tool use, thinking blocks, and prompt caching (`prompt_cache=True`, `structured_output=False`)
+- `GeminiProvider` — Google Gemini (optional `[gemini]` extra); cross-chunk tool-call dedup
+- `LlamaCppProvider` — local llama.cpp server; inherits the Chat-Completions streaming path
+- `with_retry` — wraps any provider callable with exponential-backoff retry
+
+`providers/catalog.py` exposes static model metadata for the built-in direct providers: `list_provider_models(provider_id=None)`, `get_provider_model_info(model, provider_id=None)`, and the `ProviderModelInfo` record (`context_window`, `capabilities`, `pricing`). It intentionally excludes OpenAI-compatible/local models whose model lists depend on external config.
+
+`ProviderCapabilities` declares per-provider feature support (`parallel_tool_calls`, `structured_output`, `tool_choice`, `prompt_cache`, `context_window`). `apply_provider_capabilities(req, caps)` in `loop/request.py` downgrades a `ProviderRequest` before each call — clears `cache_prompt`/`cache_ttl` for non-caching providers, strips `output_schema` when native structured output is unsupported. Duck-typed test providers that don't implement `capabilities()` are safely skipped via `hasattr` guard.
+
+### Loop Guard (`loop_guard/`)
+
+`LoopGuard` detects obvious agentic loops without extra LLM calls:
+- **Repeated identical tool calls** — same name+input called ≥ `max_identical_tool_calls` times (default 3).
+- **Consecutive failure streaks** — every tool in a batch fails for ≥ `max_consecutive_failures` turns (default 3).
+
+The guard is **on by default** at `Agent()` construction. Disable with `Agent(loop_guard=None)`. When tripped it emits a `LoopGuardEvent` and either stops immediately (default) or runs one final tools-disabled turn (`force_final_answer=True`). Max-turns exhaustion also emits a `LoopGuardEvent(reason="max_turns")` for clarity alongside the existing `ErrorEvent(TurnLimitError)`.
+
+### Verification (`verification.py`)
+
+Opt-in closed-loop gates evaluated when the loop is about to return a final answer (text-only response). All default-off; with defaults the loop is byte-identical to before.
+
+- **Structured-output repair**: `Agent(structured_output_retries=N)` — when the final text fails `output_schema` parsing/validation, the error is injected back as a system-reminder user message and the loop runs another turn (up to N times) instead of terminating with `structured_error`. Default `0` = legacy single-attempt.
+- **Verifier protocol**: `Agent(verifiers=[...], max_verification_retries=2)` — a `Verifier` is duck-typed (`name` + `verify(ctx) -> Verdict`, sync or async). `Verdict.action` is `"pass"` (accept), `"retry"` (inject `Verdict.feedback`, run another turn), or `"stop"` (fail the run with an error `ResultEvent`). First non-pass verdict wins; a verifier that raises is treated as passing (mirrors the observer contract). Each gate action emits a `VerificationEvent` (`verifier`, `action` ∈ retry/stop/exhausted, `feedback`, `attempt`). When retries are exhausted, the answer is accepted as-is with an `action="exhausted"` event.
+- **`ScorerVerifier`**: lifts an output-based evals scorer (`text_contains`, `schema_valid`) into a live verifier (`ScorerVerifier(scorer, feedback=..., on_fail="retry"|"stop")`). Event-based scorers get no events in a live run — write a custom verifier for those.
+- **`RunOptions.stop_when`**: a `(session) -> bool` predicate checked before each provider turn; `True` ends the run gracefully (success result, final text = last assistant text). A raising predicate counts as `False`.
+
+Gates are skipped on a loop-guard `force_final` turn so a guard-tripped run is never bounced back into the loop. Verification retries count toward `max_turns` and the run budget, so a strict verifier cannot loop unboundedly. Retry counters are per-run and not checkpointed — a resumed run starts fresh. The schema-repair gate runs before custom verifiers; gate evaluation lives in `_evaluate_terminal_gates` (`loop/terminals.py`), wired at the same chokepoint as the loop guard.
+
+### Tools (`tools/`)
+
+Tools are **protocols** (duck-typed), not subclasses. Each tool has: `name`, `description`, `input_schema`, `scope`, `parallel_safe`, and methods `validate()`, `execute()`, `summarize()`. V2 tools may also expose `parallel`, `resources(input)`, `tags`, `capabilities`, and `cost_hint`. Built-ins: `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`. The `ToolRegistry` holds available tools; `default_tools()` returns the standard set.
+
+**Function tools (`tools/function.py`)**: the `@tool` decorator wraps a plain (sync or async) Python function into a protocol-compatible `FunctionTool` — it infers a minimal JSON schema from the signature/annotations, injects `ToolContext` when the function declares a `ctx` parameter, and accepts `scope`, `parallel`, `tags`, `summary`, `resources`, `retryable`, and `execution_timeout_ms` overrides. No base-class inheritance; the result drops straight into a `ToolRegistry`.
+
+**Execution backends (`tools/execution.py`)**: `ExecutionBackend` is a duck-typed protocol (`run(command, *, cwd, timeout_s, signal) → ExecResult`). `LocalBackend` (default) runs a subprocess shell with process-group kill and abort-aware communicate; `DockerBackend` runs inside `docker run --rm` (guarded by `shutil.which`, no Docker SDK), with configurable network/mount/read-only/user. Inject via `Agent(execution_backend=...)`, which replaces only the `Bash` tool (never adds one to a registry that excludes it). Both backends route timeout/abort through `_communicate_with_timeout_and_abort` so `session.abort()` interrupts in-flight commands.
+
+`ToolContext` is passed to every `execute()` call and provides: `cwd`, `session_id`, `run_id`, `session_store`, `signal` (abort), `file_read_tracker`, `filesystem` (virtual `FileBackend` when the filesystem subsystem is enabled).
+
+Read tools with `parallel=True` may run concurrently. Write and exec tools serialize by default. Optional `ResourceAccess` declarations prevent overlapping read/write conflicts on the same resource. Concurrency limit: `Agent(max_tool_concurrency=...)` or `AGENTKIT_MAX_TOOL_CONCURRENCY` env var (default: CPU count).
+
+**Timeouts**: `Agent(tool_timeout_ms=N)` sets an agent-wide execution deadline (env `AGENTKIT_TOOL_TIMEOUT_MS`). A tool may override with a class-level `execution_timeout_ms` attribute; `0` opts out. Default `None` = no timeout (zero-overhead, backward compatible). A timed-out tool returns `is_error=True` with an actionable message; the run continues. Implemented via `asyncio.wait_for` catching `asyncio.TimeoutError` (Python 3.10 safe). `ToolTimeoutError` (`kind="tool_timeout"`, `retryable=True`) is the typed exception for observer/policy use.
+
+**Retry**: `Agent(tool_retry=RetryOptions(max_attempts=..., base_delay_ms=...))` enables opt-in exponential-backoff retry. Gated by scope: read-scope tools retry any exception (idempotent); write/exec tools only retry when the tool sets `retryable = True`. `AbortError` is never retried.
+
+`ToolResult` supports plain `content` plus `summary`, `metadata`, `citations`, `attachments`, `duration_ms`, and `truncated`. The model receives the compact `content`; host apps can use the richer fields for RAG provenance and UI rendering.
+
+### Context (`context/`)
+
+Use `ContextBuilder.build(turn) -> ContextBuildResult` for RAG, memory recall, ephemeral system blocks, budget trimming, and request-scoped tool selection. Builder output is appended only to the provider request and does not mutate `session.provider_view`. The legacy `context_hooks.py` API has been removed.
+
+### Memory (`memory/`)
+
+`MemoryStore` is a protocol for app-owned memory backends. Core includes `MemoryItem`, `MemorySearchResult`, `InMemoryKeywordMemoryStore`, `SqliteMemoryStore`, `MemoryContextBuilder`, `MemorySearchTool`, and `MemoryUpsertTool`. Do not add vector DB or embedding dependencies to core; adapters should implement the protocol or live in examples/recipes.
+
+`TieredMemoryStore` is itself a `MemoryStore` — a deterministic router/merge over three sub-stores (`working`/`episodic`/`semantic`), routing writes by `item.metadata["tier"]` (default `working`) and fanning `search()` across all tiers, then merging by the canonical `(score, item.id)` key and slicing to the global `limit`. Optional `tier_limits` is a **hard per-tier cap** applied before the merge; leave it unset for a pure global top-N. `MemoryContextBuilder(group_by_tier=True)` renders results under tier subheadings (default output is byte-identical). An optional `PostgresMemoryStore` adapter (`[postgres]` extra) mirrors `SqliteMemoryStore`'s full-scan keyword search.
+
+### Virtual Filesystem (`filesystem/`)
+
+`FileBackend` is a duck-typed protocol for a virtual, session-scoped filesystem that is separate from the real `cwd` on disk. Four implementations ship: `StateFileBackend` (in-memory, per-session default), `DiskFileBackend` (real files sandboxed under a root, default `.linch/offload`), `SqliteFileBackend` (persistent across sessions), and `CompositeFileBackend` (routes paths by prefix, e.g. `/memories/` → `SqliteFileBackend`).
+
+**Auto-offload**: `Agent(result_offload=OffloadConfig())` enables automatic offloading of tool results that exceed `threshold_tokens` (default 20,000). The scheduler calls `maybe_offload()` at the single result chokepoint in `_execute_one` (`scheduler.py`). The full payload is written to the backend; `ToolResult.content` is replaced with a preview + path hint before the `ToolResultBlock` enters `provider_view`. The full `ToolResult` still travels on `ToolCallEndEvent.tool_result` for observers. `maybe_offload` never raises — a backend write failure silently returns the original result.
+
+**Four tools** register automatically when a backend is configured (`Agent(filesystem=...)` or `Agent(result_offload=...)`): `ls`, `read_file` (supports `offset`/`limit` line windowing), `write_file`, `edit_file`. These are in `OffloadConfig.skip_tools` by default so reading back a large file cannot trigger a recursive re-offload. A filesystem-aware system-prompt block is also added automatically.
+
+`FeatureFlags(filesystem=False)` disables the subsystem even when a backend is passed.
+
+### Permissions (`permissions/`)
+
+`PermissionEngine` evaluates each tool call against configured rules before execution. Modes: `"default"` (prompt user), `"acceptEdits"` (auto-allow file edits), `"skip-dangerous"` (allow all). Rules: `ToolRule`, `BashRule`, `PathRule`. `BashRule` matches via fnmatch-glob and token-prefix (no substring matching); `PathRule` translates globs to anchored regexes where `*`/`?` do **not** cross `/` and `**` does (`permissions/rules.py`). When a tool call is not auto-approved, a `PermissionRequestEvent` is emitted and the loop pauses until the caller responds.
+
+**Durable HITL**: resolved decisions are persisted into the run checkpoint (`RunCheckpoint.permission_decisions`, keyed by `permission_decision_key(tool_name, input)` in `permissions/keys.py` — stable across provider calls, unlike `tool_use_id`). On resume the scheduler replays a stored allow/deny instead of re-invoking the callback (Seam A); only explicit allow/deny are persisted (Seam B) — abort/callback-failure denials are not. A corrupt stored decision falls through to a fresh prompt.
+
+### Sessions & Storage (`sessions/`)
+
+`SessionStore` is a protocol. Implementations: `InMemorySessionStore` (ephemeral) and `SqliteSessionStore` (persistent). The store also handles task management (`Task`, `TaskPatch`, status tracking) used by the `TaskCreate/List/Get/Update` tools.
+
+`run_store.py` provides `SqliteRunStore` and `RunCheckpoint` for durable run checkpointing, enabling deep-agent runs to resume across process restarts. The persisted wire format is versioned: `SCHEMA_VERSION` (exported as `linch.RUN_SCHEMA_VERSION`) stamps every serialized checkpoint (`checkpoint_to_dict` → `"schema_version"`); `checkpoint_from_dict` reads field-by-field with defaults so a checkpoint from a newer binary round-trips its known fields, and `load_events` skips an event row it cannot decode (a future event type) instead of aborting the resume. See `docs/versioning.md` for the semver contract.
+
+### Deep agent preset (`deep_agent/`)
+
+`create_deep_agent(*, model, durable, coordinator, cwd, ...)` is a factory in `deep_agent/factory.py` that assembles a fully-configured `Agent` with task tools, a built-in subagent roster (researcher, planner, implementer defined in `deep_agent/subagents.py` as `DEEP_AGENT_SUBAGENTS`), durable SQLite stores, a `/memories` filesystem partition, and a deepened system prompt.
+
+- **`coordinator=True`** — strips heavy tools (`Edit`, `Write`, `Bash`, `Grep`, `Glob`, `Read`) from the parent agent, injects `COORDINATOR_SYSTEM_PROMPT` (from `deep_agent/prompts.py`), and registers `TaskStopTool`. Workers still receive full tool access.
+- **`durable=True`** — sets `SqliteSessionStore`, `SqliteRunStore`, and `CompositeFileBackend` with a persistent `/memories` partition backed by `SqliteFileBackend`, enabling cross-process resume.
+- `DEEP_AGENT_SYSTEM_PROMPT` and `COORDINATOR_SYSTEM_PROMPT` live in `deep_agent/prompts.py`.
+- `DEEP_AGENT_SUBAGENTS` in `deep_agent/subagents.py` defines researcher, planner, and implementer subagent definitions used by default.
+
+### MCP Integration (`mcp/`)
+
+`connect_mcp_servers()` connects to external MCP servers (stdio or HTTP) and returns an `McpConnection` that exposes MCP tools as Linch tools. MCP tool names are normalized via `mcp/naming.py`.
+
+### Skills & Subagents (`skills/`, `subagents/`)
+
+**Skills** are slash-commands defined as `SKILL.md` files (YAML frontmatter + markdown body) loaded from `.linch/skills/*/SKILL.md`. The skill system supports argument substitution and system-reminder injection.
+
+**Subagents** are specialized agent roles defined in `.linch/agents.yaml`. The subagent registry resolves agent definitions; `runner.py` executes them with their own tool overlays and prompts.
+
+**Worker lifecycle and fork/continue**: `SubagentTool` passes `retain=True` in `RunSubagentArgs` so child sessions remain alive in `agent._sessions` after the initial run. `_drive_child` is a shared helper used by both `run_subagent` and `continue_subagent` to drive a child session. `SubagentContinueTool` (schema: `{to, message}`) re-engages a retained worker by worker_id or display_name, resuming with its full prior `provider_view`. `TaskStopTool` (schema: `{task_id, reason}`) cancels a running background worker task; the handle remains continuable. `WorkerHandle` (`subagents/workers.py`) is a dataclass tracking `worker_id`, `child_session_id`, `display_name`, `definition`, `status`, `task`, and `last_result_text` for each live worker. Parent session exposes `session.workers: dict[str, WorkerHandle]`.
+
+**Background workers**: `SubagentTool` with `run_in_background=True` spawns `asyncio.create_task` and returns an ack immediately without blocking the turn. On completion the worker appends a `<task-notification>` XML `Message` to `session.pending_notifications`. The next `session.run()` call drains all pending notifications as `UserEvent`s at the top of the turn via `_drain_pending_notifications` in `loop/runner.py`. `session.abort()` cancels all running background worker tasks; `agent.close()` also cancels them and clears `_sessions`.
+
+### Compaction (`compaction.py`)
+
+When the provider's context window approaches its limit, the compaction strategy summarizes old messages to free space. This is transparent to the caller; a `CompactionEvent` is emitted.
+
+**Compaction ladder (opt-in)**: `Agent(compaction_ladder=CompactionLadder())` adds LLM-free recovery rungs. Rung 1 — `micro_compact`: copy-on-write elision of `ToolResultBlock` contents older than `keep_recent_turns` (blocks are shared with `full_history`, so changed messages are rebuilt, never mutated; `tool_use_id` pairing preserved). Runs proactively in `maybe_compact` and reactively on `ContextLengthError` (once per turn). Rung 2 — forced compaction capped at `max_forced_compactions` per run (circuit breaker), then the error surfaces. With the default `compaction_ladder=None`, behavior is byte-identical to the legacy single-retry path (`_stream_turn_with_compaction_retry` vs `_stream_turn_with_ladder` in `loop/streaming.py`).
+
+### Budgets (`budget.py`)
+
+`RunBudget(max_tokens=..., max_cost_usd=...)` caps spending for a run **and its whole subagent tree** — children inherit the parent's budget object by reference (`run_subagent` copies `parent_session.active_budget` into `child_session.inherited_budget`). Resolution in `run_loop`: `RunOptions.budget` > `inherited_budget` > `Agent(budget=...)`. The loop charges after every provider turn and checks before each one; exhaustion emits `BudgetEvent(kind="exceeded")` → `ErrorEvent(BudgetExceededError)` → `ResultEvent(subtype="error")` and stops gracefully. `BudgetEvent(kind="warning")` fires once per budget object at `warn_ratio` (default 0.9). Unknown-model turns charge $0 — only the token limit binds for unpriced models.
+
+### Workflows (`workflow/`)
+
+`agent.run_workflow(fn, *, budget=None, run_id=None, max_concurrency=4, on_event=None)` runs a deterministic "fleet loop": *fn* is a plain async function receiving a `WorkflowContext` (`wf`) with `await wf.agent(prompt, name=..., label=..., tools=...) -> str` (runs a subagent via `run_subagent`; failure raises `WorkflowError`), `await wf.parallel(thunks)` (semaphore-capped, order-preserving), `await wf.pipeline(items, *stages)` (per-item chaining, no barrier), `await wf.phase(title)`, and `wf.budget` (the shared `RunBudget`). With `Agent(run_store=...)` + `run_id`, each `wf.agent` result is journaled as a persisted `WorkflowEvent(kind="agent_end")`; re-running the same `run_id` replays the unchanged prefix from `WorkflowJournal.from_stored_events` (`kind="agent_replayed"`, no provider call). Calls are keyed by `sha256(subagent_type, prompt)` + occurrence counter (`workflow/journal.py`). Workflow functions must be deterministic for resume to be correct.
+
+### Observability (`observability/`)
+
+`RunObserver` is a vendor-neutral protocol with nine span-hook methods (`on_run_start/end`, `on_turn_start/end`, `on_provider_call_start/end`, `on_tool_start/end`) plus an `on_event` catch-all. Methods may be sync or async.
+
+`ObserverDispatcher` fans out hook calls to a list of observers, awaits async results, and swallows exceptions — a faulty observer never crashes a run. Zero-overhead when no observers are attached.
+
+Stdlib reference observers: `LoggingObserver` (one log line per span) and `SpanCollector` (in-memory span list for tests). `OpenTelemetryObserver` is the production integration point, behind the optional `[otel]` extra (lazily imported, `pip install 'linch[otel]'`). Langfuse, LangSmith, Honeycomb, and Datadog are all reached via the OTel adapter — no vendor-specific code in core.
+
+Observers attach through the unified hooks layer, not a dedicated `observers=` parameter: wrap them in the adapter hook — `Agent(hooks=[RunTelemetryHook([...])])`. The same pattern bridges the other legacy protocols into the single `HookDispatcher` runtime: `ToolMiddlewareHook(middleware)`, `FinalAnswerVerifierHook(verifiers)`, `StopPredicateHook(predicate)`, and `ContextInjectionHook(builder)` (all in `hooks/adapters.py`). `normalize_hooks` does **not** auto-detect a raw observer/verifier/middleware — always wrap via the matching adapter. Passing one unwrapped is unsupported and misbehaves: a few method names overlap (e.g. `RunObserver.on_turn_start`/`on_provider_call_start` collide with the hook dispatch methods), so those fire with the wrong context type while the rest are ignored. The legacy `RunObserver`/`Verifier`/middleware protocols remain exported for implementing your own; the loop dispatches everything through hooks, and `RunTelemetryHook` drives the wrapped observers via `ObserverDispatcher` (the single fan-out implementation — the adapter does not re-roll its own).
+
+### Evals (`evals/`)
+
+A lightweight, deterministic harness for grading agent behavior offline. `ScriptedProvider` (with `TextTurn`/`ToolUseTurn`) replays a fixed turn sequence without a live model. `run_eval(agent_factory, cases, scorers)` runs an agent over a list of `EvalCase`s and returns `EvalResult`/`CaseResult` with per-scorer pass/fail/None. Built-in scorers (`evals/scorers.py`) each return `True`/`False`/`None`: `text_contains`, `tool_called`, `schema_valid`, `cost_under`, plus long-run scorers `context_selected_tool`, `context_not_trimmed`, `context_metadata_contains`, `memory_recalled`, `recovery_succeeded`, and `run_completed`. Each case session is popped from `agent._sessions` and aborted in a `finally`, so a long eval run does not leak sessions.
+
+### Run reports (`reports.py`)
+
+`build_run_report(events, run=None)` folds an event stream (live `Event`s or persisted `StoredRunEvent`s) into a `RunReport` dataclass: tool calls, permission requests, context builds, loop guards, errors, usage, final result, checkpoint, and a `long_run` summary (selected-tool counts, peak context tokens, memory tier/namespace/citation rollups) plus a flat `timeline`. `load_run_report(store, run_id)` reconstructs one from a `RunStore`. Pure read model — it never mutates session state.
+
+## Key design constraints
+
+- All async — no blocking I/O anywhere in the core loop.
+- `provider_view` vs `full_history` are kept separately; only `provider_view` is sent to the LLM. Compaction modifies `provider_view` only.
+- Tool protocol is duck-typed — avoid inheriting from a base class when adding tools; implement the protocol attributes directly.
+- The loop continues as long as the response contains tool calls; it stops when the model returns a text-only response (or hits a stop condition).
+- No vendor observability stack in core — observability backends (Langfuse, LangSmith, etc.) are reached via the OpenTelemetry seam, never as direct dependencies.
+- Tool timeouts default to `None` (off) and use `asyncio.wait_for` + `asyncio.TimeoutError` (not the 3.11+ unified builtin) to stay Python 3.10 compatible. Timeouts convert to `is_error=True` results; they never raise out of `_execute_one` so parallel-lane siblings are unaffected.
+- Tool retry is side-effect gated: read-scope tools only, or tools that explicitly set `retryable = True`. Write/exec tools are never retried by default.
+- Virtual filesystem is opt-in (`Agent(filesystem=...)` or `Agent(result_offload=...)`); zero overhead when unset. `DiskFileBackend` defaults to `.linch/offload` (gitignored). `maybe_offload` is a no-op on error results and filesystem-tool results. A backend write failure silently returns the original result — storage errors never crash a run.
+- Background workers use `asyncio.create_task` detached from the current turn; `session.abort()` cancels them and `agent.close()` also cancels and clears `_sessions`. `_cancel_background_workers` is called in both `except AbortError` and `except Exception` branches so orphaned tasks never write into a dead session. Both `session.abort()` and `agent.close()` also cancel detached background-*tool* tasks (`session.background_tasks`), so closing an agent never orphans an in-flight background tool.
+- Multi-tenant safe: no process-global mutable state — each `Agent` builds its own tool registry, sessions dict, permission engine, and extension state (the one module-level singleton, `default_compaction`, is immutable). N agents run concurrently in one process without cross-talk.
+- Public API contract: the supported surface is exactly `linch.__all__` (import from the top-level package; submodule paths and underscore names are private). `tests/test_public_api.py` guards it; `docs/versioning.md` is the semver policy. The event stream (`session.run()`) is a plain async-generator chain — it applies natural backpressure (a slow consumer throttles the producer); see `docs/usage/events.md`.

linch-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skawld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.