induscode 0.1.0__py3-none-any.whl

induscode/boot/runners/session.py

@@ -0,0 +1,549 @@
+"""Boot helper: assemble a :class:`~induscode.conductor.SessionConductor` for
+a runner.
+
+Port of TS ``src/boot/runners/session.ts`` — the agent-assembly choreography
+all three runners share, so none of them re-derives the model id and session
+options:
+
+1. Prime the OAuth adapter registry (explicitly — never at import time) and
+   best-effort export stored vault keys into the provider env vars
+   (:func:`prime_provider_env`). The *primary* credential path is the
+   injected per-call key resolver (:func:`build_key_resolver`); env priming
+   is kept only as the compatibility belt for the framework's env fallback,
+   per the port plan ("prefer resolver injection over env mutation").
+2. Resolve the model id (:func:`resolve_model_id`): an explicit ``--model``
+   wins; else the first authenticated provider's preferred *current* model;
+   else the catalog default.
+3. Select the tool deck (``provision_deck("all")`` filtered by ``--tools`` /
+   ``--no-tools``) and attach ``--mcp`` tools via the framework MCP pool.
+4. Compose the system prompt: ``--system`` replaces the tool-aware briefing,
+   ``--append-system`` appends.
+5. Build the conductor with the cwd-scoped sessions directory
+   (:func:`session_scope_dir`) and the live condense hook
+   (:func:`condense_transcript`).
+
+The conductor itself constructs its framework agent lazily, so no model
+client exists until the first turn runs.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import re
+from collections.abc import Awaitable, Callable, Iterator
+from pathlib import Path
+from typing import Any, Final
+
+from indusagi.mcp import MCPClientPool, MCPClientPoolOptions, createMCPAgentToolFactory, loadMCPConfig
+
+from induscode.briefing import BriefingContext, compose_briefing
+from induscode.capability_deck import DeckContext, provision_deck
+from induscode.conductor import (
+    AgentMessage,
+    AgentTool,
+    ConductorDeps,
+    MatchQuery,
+    ModelCatalog,
+    ModelMatcher,
+    SessionConductor,
+    SessionConductorOptions,
+    ThinkingLevel,
+    create_session_conductor,
+)
+from induscode.launch import register_built_in_oauth_providers
+from induscode.launch.contract import AuthVault
+from induscode.window_budget import BudgetPolicy, condense as condense_slice, plan_slice
+from induscode.workspace import BRAND
+
+from ..auth_vault import create_auth_vault
+from ..contract import BootContext, Invocation
+
+__all__ = [
+    "PREFERRED_DEFAULT",
+    "PROVIDER_ENV",
+    "build_key_resolver",
+    "build_session_conductor",
+    "condense_transcript",
+    "oneshot_prompts",
+    "prime_provider_env",
+    "resolve_model_id",
+    "session_scope_dir",
+]
+
+
+# ---------------------------------------------------------------------------
+# Model resolution
+# ---------------------------------------------------------------------------
+
+
+def _read_auth_data(ctx: BootContext) -> dict[str, Any]:
+    """Parse the raw auth.json map (``{provider: {account: record}}``), or an
+    empty dict on any read/parse failure."""
+    import json
+
+    path = Path(ctx.workspace.auth_path)
+    if not path.exists():
+        return {}
+    parsed = json.loads(path.read_text(encoding="utf-8"))
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def authenticated_providers(ctx: BootContext) -> list[str]:
+    """The provider ids that have at least one stored credential in the
+    on-disk auth vault, in the order they were saved.
+
+    Read straight from the auth.json map so the resolver can prefer a model
+    the user can actually call. Any read/parse failure yields an empty list —
+    the caller then falls back to the catalog default.
+    """
+    try:
+        data = _read_auth_data(ctx)
+        return [
+            provider
+            for provider, accounts in data.items()
+            if len(provider) > 0 and isinstance(accounts, dict) and len(accounts) > 0
+        ]
+    except Exception:
+        return []
+
+
+#: Per-provider preferred default models, in priority order, by bare model id.
+#:
+#: A provider's catalog often lists deprecated models first. When defaulting
+#: a session to an authenticated provider we pick the first of these the
+#: catalog carries, so a fresh launch lands on a current, callable model
+#: rather than a dead one. (TS table verbatim.)
+PREFERRED_DEFAULT: Final[dict[str, tuple[str, ...]]] = {
+    "anthropic": (
+        "claude-sonnet-4-5",
+        "claude-haiku-4-5",
+        "claude-sonnet-4-6",
+        "claude-sonnet-4-0",
+        "claude-opus-4-5",
+    ),
+    "openai": ("gpt-5.1", "gpt-4.1", "gpt-4o"),
+}
+
+
+def _provider_default_model(catalog: ModelCatalog, provider: str) -> str | None:
+    """Choose the default model id for a provider: a preferred current model
+    when the catalog has one, else the last catalog entry (newest by scan
+    order), else the first. ``None`` when the provider contributed no
+    models."""
+    cards = catalog.by_provider(provider)
+    if len(cards) == 0:
+        return None
+    for bare in PREFERRED_DEFAULT.get(provider, ()):
+        wanted = f"{provider}/{bare}"
+        for card in cards:
+            if card.id == wanted:
+                return card.id
+    return cards[-1].id
+
+
+def resolve_model_id(ctx: BootContext) -> str:
+    """Resolve the model id for this run.
+
+    Precedence: an explicit ``--model`` selector wins; otherwise a current
+    model of a provider the user has authenticated for (so a fresh launch
+    lands on a model the stored key can actually call); otherwise the catalog
+    default.
+
+    :param ctx: the boot context carrying the parsed invocation
+    :returns: the canonical model id to bind the session to
+    """
+    explicit = ctx.invocation.model_id
+    if explicit is not None and len(explicit.strip()) > 0:
+        return explicit
+    catalog = ModelCatalog()
+    for provider in authenticated_providers(ctx):
+        id = _provider_default_model(catalog, provider)
+        if id is not None:
+            return id
+    card = ModelMatcher(catalog).resolve(MatchQuery())
+    return card.id if card is not None else ""
+
+
+# ---------------------------------------------------------------------------
+# Credentials
+# ---------------------------------------------------------------------------
+
+#: The environment variable the framework reads a provider's api key from.
+#:
+#: Mirrors the framework's own provider→env mapping. The framework ``Agent``
+#: resolves a key via the injected resolver *or* its env lookup; the app
+#: stores keys in its own vault, so :func:`prime_provider_env` bridges the
+#: two by exporting each stored key into the variable the framework would
+#: look it up under. (TS table verbatim.)
+PROVIDER_ENV: Final[dict[str, str]] = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "azure-openai-responses": "AZURE_OPENAI_API_KEY",
+    "google": "GEMINI_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "cerebras": "CEREBRAS_API_KEY",
+    "xai": "XAI_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+    "vercel-ai-gateway": "AI_GATEWAY_API_KEY",
+    "zai": "ZAI_API_KEY",
+    "mistral": "MISTRAL_API_KEY",
+    "minimax": "MINIMAX_API_KEY",
+    "minimax-cn": "MINIMAX_CN_API_KEY",
+    "opencode": "OPENCODE_API_KEY",
+    "sarvam": "SARVAM_API_KEY",
+    "krutrim": "KRUTRIM_API_KEY",
+    "nvidia": "NVIDIA_API_KEY",
+}
+
+
+def prime_provider_env(ctx: BootContext) -> None:
+    """Best-effort: export every stored credential into the environment the
+    framework reads.
+
+    Walks the on-disk vault and, for each provider with a usable key (an api
+    key, or an OAuth access token), sets the matching env var — unless one is
+    already present (an explicit ``ANTHROPIC_API_KEY=…`` in the shell always
+    wins). This is the *secondary* credential path: the injected per-call
+    resolver (:func:`build_key_resolver`) is primary; env priming only covers
+    framework code paths that consult the environment directly.
+    """
+    try:
+        data = _read_auth_data(ctx)
+        for provider, accounts in data.items():
+            if provider.startswith("_") or not isinstance(accounts, dict):
+                continue
+            env_var = PROVIDER_ENV.get(provider)
+            if env_var is None or os.environ.get(env_var):
+                continue
+            records = [a for a in accounts.values() if isinstance(a, dict)]
+            chosen = next((a for a in records if a.get("isDefault")), None)
+            if chosen is None and records:
+                chosen = records[0]
+            if chosen is None:
+                continue
+            value = chosen.get("key") if chosen.get("kind") == "apiKey" else chosen.get("access")
+            if isinstance(value, str) and len(value) > 0:
+                os.environ[env_var] = value
+    except Exception:
+        # Best-effort: a missing/corrupt vault just leaves the env untouched.
+        pass
+
+
+def build_key_resolver(
+    vault: AuthVault,
+    requested_account: str | None = None,
+) -> Callable[[str], Awaitable[str | None]]:
+    """A per-call credential resolver backed by the on-disk auth vault.
+
+    The framework ``Agent`` calls this for every request. For a provider with
+    a stored account it returns the usable key — an api key, or a browser
+    sign-in access token that
+    :meth:`~induscode.boot.auth_vault.DiskAuthVault.read_usable_key`
+    refreshes on the fly when it has expired. This is the only credential
+    path for OAuth-only providers the framework has no env-var mapping for,
+    and it lets short-lived tokens rotate without restarting the session.
+
+    Returns ``None`` when nothing is stored, which lets the framework fall
+    back to its own environment lookup; never raises (a vault error degrades
+    to the env fallback rather than failing the turn).
+    """
+
+    async def get_api_key(provider: str) -> str | None:
+        try:
+            # Try, in order: the account `--account` requested (when given),
+            # the account flagged default, then the first stored account. The
+            # default/first fallback matters because re-logging into a
+            # provider that already had an account leaves fresh credentials
+            # usable but UNFLAGGED (`isDefault: False`) — without it a
+            # signed-in provider would resolve to no key and the turn would
+            # crash with "No API key for provider".
+            candidates: list[str | None] = [
+                requested_account,
+                await vault.default_account(provider),
+                next(iter(await vault.list_accounts(provider)), None),
+            ]
+            for account in candidates:
+                if account is None:
+                    continue
+                key = await vault.read_usable_key(provider, account)
+                if key:
+                    return key
+            return None
+        except Exception:
+            return None
+
+    return get_api_key
+
+
+# ---------------------------------------------------------------------------
+# Flag application (thinking / system / tools / mcp)
+# ---------------------------------------------------------------------------
+
+#: The reasoning-effort rungs the conductor accepts, for validating
+#: ``--thinking``.
+_THINKING_LEVELS: Final[frozenset[str]] = frozenset(
+    {"off", "minimal", "low", "medium", "high", "xhigh"}
+)
+
+
+def _resolve_thinking_level(raw: str | None) -> ThinkingLevel | None:
+    """Narrow a raw ``--thinking`` value to a ``ThinkingLevel``, ignoring
+    junk."""
+    if raw is not None and raw in _THINKING_LEVELS:
+        return raw  # type: ignore[return-value]  # narrowed by the guard
+    return None
+
+
+def _resolve_text(value: str) -> str:
+    """Resolve a ``--system`` / ``--append-system`` value: read it as a file
+    when it names one on disk, otherwise use it verbatim — matching the
+    reference agent's file-or-literal handling so either a prompt file or
+    inline text works."""
+    try:
+        path = Path(value)
+        if path.exists():
+            return path.read_text(encoding="utf-8")
+    except Exception:
+        # Not a readable file: fall through and treat the value as literal.
+        pass
+    return value
+
+
+def _canon_tool_name(name: str) -> str:
+    """Case-fold a tool id and strip ``_`` / ``-`` so user spellings line up
+    with deck ids (``web_fetch`` matches ``webfetch``)."""
+    return re.sub(r"[_-]", "", name.lower())
+
+
+def select_tools(cwd: str, inv: Invocation) -> list[AgentTool]:
+    """Select the tool deck for the run, honouring ``--no-tools`` (empty) and
+    ``--tools`` (allow-list). Tool ids are matched case-insensitively with
+    ``_`` / ``-`` stripped."""
+    if inv.no_tools:
+        return []
+    all_tools = provision_deck("all", DeckContext(cwd=cwd)).tools()
+    if inv.tools is None or len(inv.tools) == 0:
+        return all_tools
+    allow = {_canon_tool_name(name) for name in inv.tools}
+    return [tool for tool in all_tools if _canon_tool_name(tool.name) in allow]
+
+
+def compose_system(tools: list[AgentTool], inv: Invocation) -> str:
+    """Compose the run's system prompt: ``--system`` replaces the built-in
+    briefing, ``--append-system`` adds a trailing block, and both compose
+    (override then append). With neither, it is the tool-aware built-in
+    briefing."""
+    base = (
+        _resolve_text(inv.system)
+        if inv.system is not None
+        else compose_briefing(BriefingContext(tools=tools))
+    )
+    if inv.append_system is not None:
+        return f"{base}\n\n{_resolve_text(inv.append_system)}"
+    return base
+
+
+@contextlib.contextmanager
+def _silence_mcp_chatter() -> Iterator[None]:
+    """Silence MCP connection chatter for the duration of the load.
+
+    The framework pool reports per-server progress on stdout/stderr and via
+    logging; both would corrupt the console render or the JSON-RPC stdout
+    stream. Per the port plan this is *not* a print monkey-patch: the streams
+    are scope-redirected (:func:`contextlib.redirect_stdout` /
+    ``redirect_stderr``) and logging below ERROR is disabled, both restored
+    on exit. A set ``INDUSAGI_DEBUG`` keeps everything visible.
+    """
+    if os.environ.get(BRAND.env_debug):
+        yield
+        return
+    previous_disable = logging.root.manager.disable
+    logging.disable(logging.ERROR)
+    try:
+        with open(os.devnull, "w", encoding="utf-8") as sink:
+            with contextlib.redirect_stdout(sink), contextlib.redirect_stderr(sink):
+                yield
+    finally:
+        logging.disable(previous_disable)
+
+
+async def load_mcp_tools(inv: Invocation) -> list[AgentTool]:
+    """Connect the ``--mcp`` endpoints and return their tools as the
+    conductor's own ``AgentTool`` type (the framework MCP factory mints a
+    structurally compatible tool, so they concatenate onto the deck with no
+    adapter). Each path is a config file or a cwd to auto-detect under; a
+    server that fails to connect is skipped so the session stays usable.
+    Returns ``[]`` when ``--mcp`` was not given."""
+    paths = inv.mcp if inv.mcp is not None else ()
+    if len(paths) == 0:
+        return []
+
+    tools: list[AgentTool] = []
+    with _silence_mcp_chatter():
+        for path in paths:
+            try:
+                servers = loadMCPConfig(path)
+                if len(servers) == 0:
+                    continue
+                pool = MCPClientPool(MCPClientPoolOptions(servers=servers))
+                await pool.connectAll()
+                for client in pool.getAllClients():
+                    defs = await client.listTools()
+                    for definition in defs:
+                        tools.append(createMCPAgentToolFactory(definition, client)())
+            except Exception:
+                # Skip this endpoint; a bad MCP config must not sink the run.
+                continue
+    return tools
+
+
+# ---------------------------------------------------------------------------
+# Session directory scoping
+# ---------------------------------------------------------------------------
+
+
+def session_scope_dir(sessions_root: str | os.PathLike[str], cwd: str) -> str:
+    """The cwd-scoped session directory under the workspace ``sessions/``
+    root.
+
+    Sessions are partitioned per working directory (so ``--continue`` means
+    "the most recent session in THIS directory"). The cwd is slugged — every
+    non-alphanumeric run collapsed to a single dash — and wrapped in
+    ``--…--`` markers, matching the on-disk layout. Both the conductor
+    (writer) and the :class:`~induscode.sessions.SessionLibrary` (reader)
+    must agree on this, so it lives here and is shared by the repl runner.
+
+    :param sessions_root: the workspace ``sessions/`` directory
+    :param cwd: the run's working directory
+    """
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", cwd).strip("-")
+    return os.path.join(os.fspath(sessions_root), f"--{slug}--")
+
+
+# ---------------------------------------------------------------------------
+# Condense hook
+# ---------------------------------------------------------------------------
+
+#: Auto-compaction policy: condense only once the transcript outgrows a
+#: recent ~6k-token tail, leaving that tail verbatim. Window-relative
+#: defaults (0.75 / 6000 / 2048 — the window-budget defaults).
+AUTO_CONDENSE_POLICY: Final[BudgetPolicy] = BudgetPolicy(
+    trigger_ratio=0.75, keep_recent=6000, reserve_tokens=2048
+)
+
+
+def _last_user_turn_start(messages: list[AgentMessage]) -> int:
+    """Index where the final user turn begins (its ``user`` message), or -1
+    if none."""
+    for i in range(len(messages) - 1, -1, -1):
+        message = messages[i]
+        role = message.get("role") if isinstance(message, dict) else getattr(message, "role", None)
+        if role == "user":
+            return i
+    return -1
+
+
+async def condense_transcript(
+    messages: list[AgentMessage], force: bool = False
+) -> list[AgentMessage]:
+    """The conductor's condense hook — what ``/compact`` (and
+    auto-compaction) run.
+
+    Both fold older turns into one digest message and keep recent turns
+    verbatim; the difference is *how much* they keep:
+
+    - **Manual** (``force``): fold everything before the LAST user turn into
+      the digest, keeping only that final turn. This always reclaims context
+      on a multi-turn session — even a tiny one — which the planner's token
+      tail would leave untouched. Cutting at a user-message boundary keeps
+      tool call/result pairs intact (the prior turns are complete).
+    - **Auto**: budget-gated — fold only the head beyond the recent
+      ~6k-token tail (:data:`AUTO_CONDENSE_POLICY`).
+
+    Network-free by design: the summarizer emits a deterministic local digest
+    when given no model, so compaction never depends on a provider key or a
+    round-trip. Returns the input unchanged when there is nothing older to
+    fold (a single-turn session), so the conductor leaves the transcript
+    as-is.
+    """
+    if force:
+        cut = _last_user_turn_start(messages)
+        if cut <= 0:
+            return messages  # 0 or 1 turn: nothing older to fold
+        summary = await condense_slice(messages[:cut])
+        return [summary.message, *messages[cut:]]
+    plan = plan_slice(messages, AUTO_CONDENSE_POLICY)
+    if plan.cut == 0 or len(plan.dropped) == 0:
+        return messages
+    summary = await condense_slice(list(plan.dropped))
+    return [summary.message, *plan.kept]
+
+
+# ---------------------------------------------------------------------------
+# Conductor assembly
+# ---------------------------------------------------------------------------
+
+
+async def build_session_conductor(ctx: BootContext) -> SessionConductor:
+    """Build the :class:`~induscode.conductor.SessionConductor` the runners
+    drive.
+
+    ``--account`` scopes the credential lookup; ``--tools`` / ``--no-tools``
+    pick the deck; ``--mcp`` attaches external tools; ``--system`` /
+    ``--append-system`` shape the prompt; ``--thinking`` sets the reasoning
+    effort. Each is applied here so the CLI flags actually reach the session
+    rather than being parsed and dropped.
+
+    :param ctx: the boot context (invocation + resolved workspace/resources)
+    :returns: a conductor bound to the resolved model and scoped to the run
+        cwd
+    """
+    # Prime the OAuth adapter registry explicitly (the vault's refresh path
+    # and the key resolver need it; nothing registers at import time).
+    register_built_in_oauth_providers()
+    prime_provider_env(ctx)
+
+    inv = ctx.invocation
+    model_id = resolve_model_id(ctx)
+    workspace = inv.cwd
+    cwd = workspace if workspace is not None else os.getcwd()
+    sessions_dir = session_scope_dir(ctx.workspace.sessions_dir, cwd)
+
+    get_api_key = build_key_resolver(
+        create_auth_vault(ctx.workspace.auth_path), inv.account
+    )
+    tools = [*select_tools(cwd, inv), *(await load_mcp_tools(inv))]
+    system = compose_system(tools, inv)
+    thinking = _resolve_thinking_level(inv.thinking)
+
+    return create_session_conductor(
+        SessionConductorOptions(
+            modelId=model_id,
+            tools=tools,
+            system=system,
+            getApiKey=get_api_key,
+            sessionsDir=sessions_dir,
+            thinking=thinking,
+            workspace=workspace,
+        ),
+        # The live condense hook: `/compact` and auto-compaction fold older
+        # turns into a digest. (Tests that build conductors directly keep the
+        # no-op default.)
+        ConductorDeps(condense=condense_transcript),
+    )
+
+
+def oneshot_prompts(ctx: BootContext) -> list[str]:
+    """The prompts a oneshot run submits: the positional first prompt when
+    present. Empty when the invocation carried no request text (the caller
+    decides what to do then).
+
+    :param ctx: the boot context carrying the parsed invocation
+    """
+    prompts: list[str] = []
+    head = ctx.invocation.prompt
+    if head is not None and len(head) > 0:
+        prompts.append(head)
+    return prompts