linch 1.0.0__py3-none-any.whl

linch/__init__.py

@@ -0,0 +1,487 @@
+"""Public API for linch."""
+
+from ._version import get_version
+from .agent import Agent, AgentOptions
+from .budget import RunBudget
+from .compaction import CompactionLadder, DefaultCompaction, DetailedCompaction
+from .config import FeatureFlags, SystemPromptConfig, SystemPromptSection
+from .context import (
+    ContextBudget,
+    ContextBuilder,
+    ContextBuilderChain,
+    ContextBuildResult,
+    ContextBuildTurn,
+)
+from .coordination.mailbox import Correlator, InMemoryMailbox, Mailbox, MailboxMessage
+from .coordination.scheduling import (
+    InMemoryScheduleStore,
+    Schedule,
+    SchedulerLoop,
+    ScheduleStore,
+    SqliteScheduleStore,
+    cron_matches,
+    next_cron_time,
+    schedule_tools,
+    validate_cron,
+)
+from .deep_agent import DEEP_AGENT_SYSTEM_PROMPT, create_deep_agent
+from .errors import (
+    AbortError,
+    AuthError,
+    ConfigError,
+    ContextLengthError,
+    LinchError,
+    PermissionDeniedError,
+    ProviderError,
+    RateLimitError,
+    SkillError,
+    ToolExecutionError,
+    ToolTimeoutError,
+)
+from .events import (
+    AssistantEvent,
+    BudgetEvent,
+    CompactionEvent,
+    ContextBuildEvent,
+    ErrorEvent,
+    Event,
+    HookEventRecord,
+    LoopGuardEvent,
+    ModelFallbackEvent,
+    PartialAssistantEvent,
+    PermissionRequestEvent,
+    ResultEvent,
+    ScheduleEvent,
+    SkillCompletedEvent,
+    SkillInvokedEvent,
+    SkillsLoadedEvent,
+    SubagentEvent,
+    SystemEvent,
+    ToolCallEndEvent,
+    ToolCallStartEvent,
+    UsageEvent,
+    UserEvent,
+    VerificationEvent,
+    WorkflowEvent,
+    is_budget_event,
+    is_context_build_event,
+    is_hook_event,
+    is_loop_guard_event,
+    is_subagent_event,
+    is_verification_event,
+    is_workflow_event,
+)
+from .filesystem import (
+    CompositeFileBackend,
+    DiskFileBackend,
+    FileBackend,
+    OffloadConfig,
+    SqliteFileBackend,
+    StateFileBackend,
+    filesystem_tools,
+)
+from .hooks import (
+    AfterProviderCallContext,
+    BeforeFinalAnswerContext,
+    BeforeProviderCallContext,
+    ContextInjectionHook,
+    FinalAnswerVerifierHook,
+    HookContext,
+    HookDispatcher,
+    HookDispatchResult,
+    HookEvent,
+    HookResult,
+    MemoryExtractionHook,
+    PostCompactContext,
+    PostToolUseContext,
+    PostToolUseFailureContext,
+    PreCompactContext,
+    PreToolUseContext,
+    RunTelemetryHook,
+    StopContext,
+    StopPredicateHook,
+    SubagentStartContext,
+    SubagentStopContext,
+    ToolMiddlewareHook,
+    UserPromptSubmitContext,
+    normalize_hooks,
+)
+from .loop import apply_provider_capabilities
+from .loop_guard import (
+    LoopGuard,
+    LoopGuardDecision,
+    LoopGuardState,
+    evaluate_loop_guard,
+    normalize_loop_guard,
+)
+from .mcp import (
+    McpHttpServerConfig,
+    McpServerConfig,
+    McpStdioServerConfig,
+    connect_mcp_servers,
+)
+from .memory import (
+    ConsolidationGate,
+    InMemoryKeywordMemoryStore,
+    MemoryContextBuilder,
+    MemoryExtractionContext,
+    MemoryExtractor,
+    MemoryItem,
+    MemorySearchResult,
+    MemorySearchTool,
+    MemoryStore,
+    MemoryUpsertTool,
+    PostgresMemoryStore,
+    SqliteMemoryStore,
+    TieredMemoryStore,
+)
+from .middleware import (
+    AgentMiddleware,
+    MiddlewareContext,
+    ToolCallMiddlewareInput,
+    ToolCallMiddlewareResult,
+)
+from .observability import (
+    BaseObserver,
+    LoggingObserver,
+    ObserverDispatcher,
+    OpenTelemetryObserver,
+    ProviderCallInfo,
+    ProviderCallResult,
+    RunInfo,
+    RunObserver,
+    RunResultInfo,
+    Span,
+    SpanCollector,
+    ToolInfo,
+    ToolResultInfo,
+    TurnInfo,
+    normalize_observers,
+)
+from .openai_responses import OpenAIOptions, OpenAIReasoning
+from .providers import (
+    AnthropicProvider,
+    AnthropicProviderOptions,
+    BaseProvider,
+    GeminiProvider,
+    GeminiProviderOptions,
+    LlamaCppProvider,
+    LlamaCppProviderOptions,
+    OpenAIChatCompletionsProvider,
+    OpenAIChatProviderOptions,
+    OpenAIResponsesProvider,
+    OpenAIResponsesProviderOptions,
+    ProviderCapabilities,
+    ProviderModelInfo,
+    SGLangProvider,
+    SGLangProviderOptions,
+    VLLMProvider,
+    VLLMProviderOptions,
+    get_provider_model_info,
+    list_provider_models,
+)
+from .providers.retry import RetryOptions
+from .reports import RunReport, build_run_report, load_run_report
+from .run_store import (
+    SCHEMA_VERSION as RUN_SCHEMA_VERSION,
+)
+from .run_store import (
+    InMemoryRunStore,
+    RunCheckpoint,
+    RunRecord,
+    RunStore,
+    SqliteRunStore,
+    StoredRunEvent,
+)
+from .session import RunOptions, Session
+from .subagents import (
+    CreatedSubagentDefinition,
+    GeneratedSubagentDefinition,
+    create_subagent_definition,
+    generate_subagent_definition,
+    render_subagent_markdown,
+    write_subagent_definition,
+)
+from .tools import (
+    AskUserHandler,
+    AskUserOption,
+    AskUserQuestion,
+    AskUserRequest,
+    AskUserResponse,
+    AskUserTool,
+    Citation,
+    FileReadTracker,
+    FunctionTool,
+    ResourceAccess,
+    ResourceMode,
+    Tool,
+    ToolContext,
+    ToolRegistry,
+    ToolResult,
+    default_tools,
+    tool,
+)
+from .tools.isolation import IsolationBackend, TempDirIsolation
+from .tools.registry import empty_tools, tools_from_defaults
+from .types import (
+    ContentBlock,
+    ImageBlock,
+    Message,
+    ModelId,
+    OutputSchema,
+    PermissionMode,
+    RedactedThinkingBlock,
+    StopReason,
+    TextBlock,
+    ThinkingBlock,
+    ToolChoice,
+    ToolResultBlock,
+    ToolUseBlock,
+    Usage,
+)
+from .verification import (
+    ScorerVerifier,
+    Verdict,
+    VerificationContext,
+    Verifier,
+    evaluate_verifiers,
+    normalize_verifiers,
+)
+from .workflow import WorkflowContext, WorkflowError, WorkflowJournal
+
+defaultTools = default_tools
+__version__ = get_version()
+
+__all__ = [
+    "AbortError",
+    "AskUserHandler",
+    "AskUserOption",
+    "AskUserQuestion",
+    "AskUserRequest",
+    "AskUserResponse",
+    "AskUserTool",
+    "Agent",
+    "LinchError",
+    "AgentOptions",
+    "RunBudget",
+    "BudgetEvent",
+    "is_budget_event",
+    "WorkflowContext",
+    "WorkflowError",
+    "WorkflowEvent",
+    "WorkflowJournal",
+    "is_workflow_event",
+    "ScheduleEvent",
+    "Schedule",
+    "ScheduleStore",
+    "InMemoryScheduleStore",
+    "SqliteScheduleStore",
+    "SchedulerLoop",
+    "schedule_tools",
+    "cron_matches",
+    "next_cron_time",
+    "validate_cron",
+    "AgentMiddleware",
+    "ContextBudget",
+    "ContextBuilder",
+    "ContextBuilderChain",
+    "ContextBuildEvent",
+    "ContextBuildResult",
+    "ContextBuildTurn",
+    "CompactionLadder",
+    "DefaultCompaction",
+    "DetailedCompaction",
+    "DEEP_AGENT_SYSTEM_PROMPT",
+    "FeatureFlags",
+    "CompositeFileBackend",
+    "DiskFileBackend",
+    "FileBackend",
+    "OffloadConfig",
+    "SqliteFileBackend",
+    "StateFileBackend",
+    "filesystem_tools",
+    "InMemoryKeywordMemoryStore",
+    "InMemoryRunStore",
+    "SystemPromptConfig",
+    "SystemPromptSection",
+    "OutputSchema",
+    "ToolChoice",
+    "empty_tools",
+    "tools_from_defaults",
+    "AssistantEvent",
+    "CompactionEvent",
+    "ContentBlock",
+    "ErrorEvent",
+    "Event",
+    "HookEvent",
+    "HookEventRecord",
+    "HookResult",
+    "HookContext",
+    "HookDispatchResult",
+    "HookDispatcher",
+    "UserPromptSubmitContext",
+    "BeforeProviderCallContext",
+    "AfterProviderCallContext",
+    "PreToolUseContext",
+    "PostToolUseContext",
+    "PostToolUseFailureContext",
+    "PreCompactContext",
+    "PostCompactContext",
+    "BeforeFinalAnswerContext",
+    "StopContext",
+    "SubagentStartContext",
+    "SubagentStopContext",
+    "ContextInjectionHook",
+    "ToolMiddlewareHook",
+    "FinalAnswerVerifierHook",
+    "StopPredicateHook",
+    "RunTelemetryHook",
+    "MemoryExtractionHook",
+    "normalize_hooks",
+    "is_hook_event",
+    "ImageBlock",
+    "AuthError",
+    "ConfigError",
+    "ContextLengthError",
+    "CreatedSubagentDefinition",
+    "Citation",
+    "FileReadTracker",
+    "FunctionTool",
+    "GeneratedSubagentDefinition",
+    "McpHttpServerConfig",
+    "McpServerConfig",
+    "McpStdioServerConfig",
+    "ConsolidationGate",
+    "MemoryContextBuilder",
+    "MemoryExtractionContext",
+    "MemoryExtractor",
+    "MemoryItem",
+    "MemorySearchResult",
+    "MemorySearchTool",
+    "MemoryStore",
+    "MemoryUpsertTool",
+    "MiddlewareContext",
+    "Message",
+    "ModelId",
+    "OpenAIOptions",
+    "OpenAIReasoning",
+    "PartialAssistantEvent",
+    "PermissionMode",
+    "PermissionDeniedError",
+    "PermissionRequestEvent",
+    "ProviderError",
+    "PostgresMemoryStore",
+    "RateLimitError",
+    "RedactedThinkingBlock",
+    "ResultEvent",
+    "RunOptions",
+    "ResourceAccess",
+    "ResourceMode",
+    "SkillCompletedEvent",
+    "SkillError",
+    "ThinkingBlock",
+    "SkillInvokedEvent",
+    "SkillsLoadedEvent",
+    "StopReason",
+    "SubagentEvent",
+    "SystemEvent",
+    "Session",
+    "SqliteMemoryStore",
+    "TieredMemoryStore",
+    "TextBlock",
+    "Tool",
+    "ToolCallEndEvent",
+    "ToolCallMiddlewareInput",
+    "ToolCallMiddlewareResult",
+    "ToolCallStartEvent",
+    "ToolContext",
+    "ToolExecutionError",
+    "ToolTimeoutError",
+    "ToolRegistry",
+    "ToolResultBlock",
+    "ToolResult",
+    "ToolUseBlock",
+    "tool",
+    "Usage",
+    "UsageEvent",
+    "UserEvent",
+    "AnthropicProvider",
+    "AnthropicProviderOptions",
+    "BaseProvider",
+    "GeminiProvider",
+    "GeminiProviderOptions",
+    "LlamaCppProvider",
+    "LlamaCppProviderOptions",
+    "OpenAIChatCompletionsProvider",
+    "OpenAIChatProviderOptions",
+    "OpenAIResponsesProvider",
+    "OpenAIResponsesProviderOptions",
+    "ProviderCapabilities",
+    "ProviderModelInfo",
+    "RetryOptions",
+    "SGLangProvider",
+    "SGLangProviderOptions",
+    "RunReport",
+    "RUN_SCHEMA_VERSION",
+    "RunCheckpoint",
+    "RunRecord",
+    "RunStore",
+    "SqliteRunStore",
+    "StoredRunEvent",
+    "VLLMProvider",
+    "VLLMProviderOptions",
+    "apply_provider_capabilities",
+    "build_run_report",
+    "create_subagent_definition",
+    "LoopGuard",
+    "LoopGuardDecision",
+    "LoopGuardEvent",
+    "Correlator",
+    "InMemoryMailbox",
+    "Mailbox",
+    "MailboxMessage",
+    "IsolationBackend",
+    "TempDirIsolation",
+    "ModelFallbackEvent",
+    "LoopGuardState",
+    "evaluate_loop_guard",
+    "normalize_loop_guard",
+    "ScorerVerifier",
+    "Verdict",
+    "VerificationContext",
+    "VerificationEvent",
+    "Verifier",
+    "evaluate_verifiers",
+    "is_verification_event",
+    "normalize_verifiers",
+    "connect_mcp_servers",
+    "create_deep_agent",
+    "defaultTools",
+    "default_tools",
+    "get_version",
+    "__version__",
+    "is_context_build_event",
+    "get_provider_model_info",
+    "generate_subagent_definition",
+    "is_loop_guard_event",
+    "is_subagent_event",
+    "list_provider_models",
+    "load_run_report",
+    "BaseObserver",
+    "LoggingObserver",
+    "ObserverDispatcher",
+    "OpenTelemetryObserver",
+    "ProviderCallInfo",
+    "ProviderCallResult",
+    "RunInfo",
+    "RunObserver",
+    "RunResultInfo",
+    "Span",
+    "SpanCollector",
+    "ToolInfo",
+    "ToolResultInfo",
+    "TurnInfo",
+    "normalize_observers",
+    "render_subagent_markdown",
+    "write_subagent_definition",
+]

linch/_blocking.py

@@ -0,0 +1,71 @@
+"""Bounded, daemon-thread offload for blocking work.
+
+The core loop must never run blocking disk/DB/CPU work directly on the event
+loop thread.  ``asyncio.to_thread`` dispatches onto the default executor whose
+*non-daemon* worker threads can keep the interpreter (and the managed test
+sandbox) alive at teardown, and an unbounded ``threading.Thread`` per call has
+no backpressure.
+
+``run_blocking`` threads the needle: each call runs on a fresh *daemon* thread
+(never blocks teardown) and a per-loop semaphore caps how many run at once
+(backpressure).  Wakeup is via ``loop.call_soon_threadsafe`` so the awaiting
+coroutine resumes reliably.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+# Cap on concurrently-offloaded blocking calls per event loop.  Mirrors the
+# default thread-pool sizing intent without sharing a global pool across loops.
+_MAX_CONCURRENCY = 32
+
+
+def _loop_semaphore(loop: asyncio.AbstractEventLoop) -> asyncio.Semaphore:
+    sem = getattr(loop, "_linch_blocking_sem", None)
+    if sem is None:
+        sem = asyncio.Semaphore(_MAX_CONCURRENCY)
+        try:
+            loop._linch_blocking_sem = sem  # type: ignore[attr-defined]
+        except Exception:
+            pass
+    return sem
+
+
+async def run_blocking(fn: Callable[..., T], *args: Any, **kwargs: Any) -> T:
+    """Run ``fn(*args, **kwargs)`` on a bounded daemon thread; return its result.
+
+    Propagates any exception ``fn`` raises to the awaiter.  If the awaiting
+    coroutine is cancelled the daemon thread still runs to completion (the same
+    contract as ``asyncio.to_thread``), but it never blocks interpreter exit.
+    """
+    loop = asyncio.get_running_loop()
+    sem = _loop_semaphore(loop)
+    async with sem:
+        fut: asyncio.Future[T] = loop.create_future()
+
+        def _target() -> None:
+            try:
+                value = fn(*args, **kwargs)
+            except BaseException as exc:  # noqa: BLE001 - propagated to awaiter
+                loop.call_soon_threadsafe(_safe_set_exception, fut, exc)
+                return
+            loop.call_soon_threadsafe(_safe_set_result, fut, value)
+
+        threading.Thread(target=_target, name="linch-blocking", daemon=True).start()
+        return await fut
+
+
+def _safe_set_result(fut: asyncio.Future[Any], value: Any) -> None:
+    if not fut.done():
+        fut.set_result(value)
+
+
+def _safe_set_exception(fut: asyncio.Future[Any], exc: BaseException) -> None:
+    if not fut.done():
+        fut.set_exception(exc)

linch/_http_errors.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+
+def error_status(err: Exception) -> int | None:
+    value = getattr(err, "status_code", None) or getattr(err, "status", None)
+    return int(value) if isinstance(value, int) else None
+
+
+def error_body(err: Exception) -> Any:
+    body = getattr(err, "body", None)
+    if body is not None:
+        return body
+    response = getattr(err, "response", None)
+    if response is not None:
+        body = getattr(response, "body", None)
+        if body is not None:
+            return body
+        try:
+            return response.json()
+        except Exception:
+            return None
+    return None
+
+
+def nested_error(err: Exception) -> dict[str, Any]:
+    body = error_body(err)
+    if isinstance(body, dict):
+        raw = body.get("error", body)
+        if isinstance(raw, dict):
+            return raw
+    raw_error = getattr(err, "error", None)
+    if isinstance(raw_error, dict):
+        return raw_error
+    return {}
+
+
+def error_code(err: Exception) -> str | None:
+    raw = nested_error(err).get("code") or nested_error(err).get("type")
+    return str(raw) if isinstance(raw, str) and raw else None
+
+
+def error_message(err: Exception) -> str:
+    raw = nested_error(err).get("message")
+    if isinstance(raw, str) and raw:
+        return raw
+    return str(err)
+
+
+def retry_after_seconds(err: Exception) -> float | None:
+    response = getattr(err, "response", None)
+    headers = getattr(response, "headers", None)
+    if not headers:
+        headers = getattr(err, "headers", None)
+    if not headers:
+        return None
+    raw = None
+    for key in ("retry-after", "Retry-After", "retry_after"):
+        try:
+            raw = headers.get(key)
+        except Exception:
+            raw = None
+        if raw is not None:
+            break
+    if raw is None:
+        return None
+    if isinstance(raw, (int, float)):
+        return max(0.0, float(raw))
+    text = str(raw).strip()
+    try:
+        return max(0.0, float(text))
+    except ValueError:
+        pass
+    try:
+        dt = parsedate_to_datetime(text)
+    except (TypeError, ValueError, IndexError, OverflowError):
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return max(0.0, (dt - datetime.now(timezone.utc)).total_seconds())
+
+
+def is_prompt_length_error(err: Exception) -> bool:
+    code = error_code(err)
+    if code == "context_length_exceeded":
+        return True
+    message = error_message(err).lower()
+    clear_phrases = (
+        "prompt is too long",
+        "maximum context length",
+        "context length exceeded",
+        "input is too long",
+    )
+    if any(phrase in message for phrase in clear_phrases):
+        return True
+    return "tokens" in message and "maximum" in message and "prompt" in message