induscode 0.1.0__py3-none-any.whl

induscode/boot/boot.py

@@ -0,0 +1,210 @@
+"""Boot orchestrator — the single function the OS entry point calls.
+
+Port of TS ``src/boot/boot.ts``. :func:`boot` owns the whole launch arc, in
+VERBATIM TS routing order:
+
+1. **Credential command** (``signin`` / ``signout`` / ``login`` / ``logout``
+   as ``argv[0]``) → :func:`~induscode.launch.run_credential_command` over
+   the disk vault; exits.
+2. **Package command** (``install`` / ``remove`` / ``update`` / ``list`` /
+   ``config`` as ``argv[0]``) →
+   :func:`~induscode.launch.run_package_command` over the preference store;
+   exits.
+3. **Meta short-circuits**: ``--help`` (usage from the one declarative flag
+   table), ``--version``, ``--list-models [filter]`` — all before any stage
+   runs or any directory is touched.
+4. **Stage pipeline** :func:`~.stages.run_stages` (immutable context fold).
+5. **Runner dispatch** via :func:`~.runners.select_runner`; the ``finally``
+   drains :attr:`~.contract.BootContext.closables` latest-registered first,
+   swallowing teardown errors.
+
+:func:`boot` itself never raises to its caller for an expected failure — it
+maps problems to a non-zero exit code so the entry point can simply adopt it.
+"""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from collections.abc import Sequence
+from typing import Final
+
+from induscode.launch import (
+    CatalogFilter,
+    format_credential_fault,
+    print_model_catalog,
+    register_built_in_oauth_providers,
+    render_usage,
+    run_credential_command,
+    run_package_command,
+)
+from induscode.settings import PreferenceStore
+from induscode.workspace import BRAND, VERSION, create_workspace
+
+from .auth_vault import create_auth_vault
+from .contract import BootContext
+from .invocation import tokenize_invocation, wants_help, wants_version
+from .runners import select_runner
+from .stages import run_stages
+
+__all__ = ["boot"]
+
+#: Exit code for a clean run.
+_EXIT_OK: Final[int] = 0
+
+#: Exit code for an unexpected failure during boot.
+_EXIT_FAILURE: Final[int] = 1
+
+#: Exit code returned when a handled credential command did not complete.
+_EXIT_CREDENTIAL_FAULT: Final[int] = 1
+
+
+def _seed_context(argv: Sequence[str]) -> BootContext:
+    """Build the seed :class:`~.contract.BootContext` from the sliced
+    ``argv``.
+
+    Resolves the workspace (pure path computation — directories are
+    materialised later by the pipeline) and the brand, parses the command
+    line once up front so the meta-request check can run before the pipeline,
+    and seeds an empty closables list. The pipeline re-parses the invocation
+    in its ``build-invocation`` stage; seeding it here keeps the context
+    fully-typed and lets ``--help`` / ``--version`` short-circuit without
+    running any stage.
+    """
+    return BootContext(
+        argv=tuple(argv),
+        workspace=create_workspace(),
+        brand=BRAND,
+        invocation=tokenize_invocation(argv),
+        closables=[],
+    )
+
+
+def _render_help() -> None:
+    """Render the help banner to stdout. Delegates to the launch
+    :func:`~induscode.launch.render_usage`, which generates the full option
+    reference from the single declarative flag table — so the help text can
+    never drift from what the parser accepts."""
+    sys.stdout.write(f"{render_usage()}\n")
+
+
+def _render_version() -> None:
+    """Render the version string to stdout: the brand name and the
+    single-source :data:`~induscode.workspace.VERSION`."""
+    sys.stdout.write(f"{BRAND.name} {VERSION}\n")
+
+
+async def _drain_closables(ctx: BootContext) -> None:
+    """Drain every teardown callback, latest-registered first, swallowing
+    individual failures so one bad closer cannot mask the run's exit code or
+    strand the rest."""
+    for close in reversed(list(ctx.closables)):
+        try:
+            result = close()
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            # Teardown failures are non-fatal; the exit code already
+            # reflects the run.
+            pass
+
+
+async def _run_credential(ctx: BootContext) -> int | None:
+    """Route a ``signin`` / ``signout`` credential command, if this
+    invocation is one.
+
+    Hands the raw argv to the launch
+    :func:`~induscode.launch.run_credential_command` over a disk-backed vault
+    scoped to the resolved workspace. Returns the process exit code when the
+    command was handled (zero on success, non-zero with a printed fault
+    otherwise), or ``None`` when the leading token was not a credential verb
+    so the caller proceeds to a normal launch.
+
+    The OAuth adapter registry is primed explicitly here (never at import
+    time) so the OAuth-capable sign-in routes are available.
+    """
+    register_built_in_oauth_providers()
+    result = await run_credential_command(
+        list(ctx.argv),
+        vault=create_auth_vault(ctx.workspace.auth_path),
+        profile_dir=str(ctx.workspace.profile_dir),
+    )
+    if not result.handled:
+        return None
+    if result.fault is not None:
+        sys.stderr.write(f"{format_credential_fault(result.fault)}\n")
+        return _EXIT_CREDENTIAL_FAULT
+    return _EXIT_OK
+
+
+async def _run_package(ctx: BootContext) -> int | None:
+    """Route an ``install`` / ``remove`` / ``update`` / ``list`` / ``config``
+    package command, if this invocation is one.
+
+    Hands the raw argv to the launch
+    :func:`~induscode.launch.run_package_command` over a settings store
+    resolved from the workspace, so the configured extension-package sources
+    persist through the same two-tier store the rest of the app reads.
+    Returns the process exit code when the command was handled, or ``None``
+    when the leading token was not a package subcommand.
+    """
+    result = await run_package_command(
+        list(ctx.argv),
+        store=PreferenceStore.from_workspace(ctx.workspace, ctx.invocation.cwd),
+    )
+    if not result.handled:
+        return None
+    return result.code if result.code is not None else _EXIT_OK
+
+
+async def boot(argv: Sequence[str]) -> int:
+    """Boot the agent: resolve everything, dispatch to the chosen runner, and
+    return the process exit code.
+
+    :param argv: the arguments the launch was invoked with, already sliced
+        (no interpreter / script path)
+    :returns: the exit code the process should adopt
+    """
+    seeded = _seed_context(argv)
+
+    # The credential command owns the invocation when the leading token is a
+    # signin / signout verb; it falls through (handled: False) otherwise.
+    credential = await _run_credential(seeded)
+    if credential is not None:
+        return credential
+
+    # The package command owns the invocation when the leading token is an
+    # install / remove / update / list / config verb; it falls through
+    # otherwise.
+    package = await _run_package(seeded)
+    if package is not None:
+        return package
+
+    # Meta requests short-circuit before any stage runs or any directory is
+    # touched.
+    if wants_help(seeded.invocation):
+        _render_help()
+        return _EXIT_OK
+    if wants_version(seeded.invocation):
+        _render_version()
+        return _EXIT_OK
+    # `--list-models [filter]` prints the catalog and exits — no session, no
+    # directory side effects — mirroring `--help` / `--version`.
+    if seeded.invocation.list_models:
+        filter = seeded.invocation.list_models_filter
+        print_model_catalog(
+            None,
+            CatalogFilter(search=filter) if filter is not None else CatalogFilter(),
+        )
+        return _EXIT_OK
+
+    ctx = await run_stages(seeded)
+    try:
+        runner = select_runner(ctx.invocation)
+        return await runner.run(ctx)
+    except Exception as error:  # noqa: BLE001 — expected failures become exit 1
+        message = str(error) if str(error) else type(error).__name__
+        sys.stderr.write(f"{BRAND.name}: {message}\n")
+        return _EXIT_FAILURE
+    finally:
+        await _drain_closables(ctx)

induscode/boot/contract.py

@@ -0,0 +1,223 @@
+"""Boot-layer contract — the FROZEN type surface between the OS entry point
+and everything that turns a command line into a running coding agent.
+
+Port of TS ``src/boot/contract.ts``. It declares *only* shapes — no behavior,
+no I/O, no literals beyond the narrow string unions that pin the public modes.
+Every other boot module (stage pipeline, invocation projection, runner
+registry, upgrade driver) is written against the names declared here, so this
+file is intentionally small, append-mostly, and stable.
+
+Design stance (kept from TS):
+
+- One immutable :class:`BootContext` is threaded through an ordered list of
+  :class:`Stage` transforms; a stage returns the next context (or the same
+  one) and never mutates in place. Successors are produced with
+  :func:`dataclasses.replace` (the Python analogue of the TS spread).
+- All branding lives in the single :class:`~induscode.workspace.Brand` record
+  and all on-disk paths in the single :class:`~induscode.workspace.Workspace`
+  record — both re-exported here so ``induscode.boot`` is a one-stop import
+  site, exactly as the TS barrel was.
+- Where the rebuilt framework / app already owns a concept, the
+  resolved-resource graph is typed against the published type rather than
+  re-declared: framework ``Settings`` for the user-tunable config shape and
+  the conductor :class:`~induscode.conductor.ModelCatalog` for the model
+  registry (the TS anchors were ``indusagi/shell-app`` ``Settings`` and
+  ``indusagi/ai`` ``ModelRegistry``; the port plan routes the catalog through
+  the conductor's normalized view).
+
+Port notes
+----------
+- TS interfaces ``Stage`` / ``Runner`` were satisfied by frozen object
+  literals; the Python equivalents are frozen dataclasses whose ``apply`` /
+  ``accepts`` / ``run`` members are plain callable *fields* (no ``self``
+  binding), so a stage/runner row is still data, not a class hierarchy.
+- TS optional-absent fields become explicit ``None`` defaults; readonly
+  arrays become tuples. ``closables`` stays a *mutable list* shared across
+  ``dataclasses.replace`` successors — accumulation is its purpose.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Literal, TypeAlias, Union
+
+from indusagi.ai import ThinkingLevel
+from indusagi.shell_app import Settings
+
+from induscode.conductor import ModelCatalog
+from induscode.workspace import Brand, Workspace
+
+__all__ = [
+    "BootContext",
+    "Brand",
+    "Closable",
+    "CredentialGraph",
+    "Invocation",
+    "Runner",
+    "RunnerId",
+    "Stage",
+    "StartupResources",
+    "ThinkingLevel",
+    "Workspace",
+]
+
+
+# ---------------------------------------------------------------------------
+# Invocation
+# ---------------------------------------------------------------------------
+
+#: The three top-level execution modes the boot layer can dispatch to.
+#:
+#: - ``repl``    — interactive terminal session.
+#: - ``oneshot`` — single non-interactive request to stdout (text or JSON).
+#: - ``link``    — headless JSON-RPC link for a driving parent process.
+RunnerId: TypeAlias = Literal["repl", "oneshot", "link"]
+
+
+@dataclass(frozen=True, slots=True)
+class Invocation:
+    """The parsed command line, reduced to what the boot layer needs to choose
+    and configure a :class:`Runner`.
+
+    This is the thin *routing* shape (the launch layer owns the rich parse —
+    :class:`induscode.launch.Invocation`); raw un-consumed tokens survive in
+    :attr:`rest` and loosely-typed switches in :attr:`flags` so nothing is
+    lost between the two. Field names are the mechanical snake_case renames of
+    the TS members (``modelId`` → ``model_id``, ``continueLatest`` →
+    ``continue_latest``).
+    """
+
+    #: Resolved execution mode.
+    mode: RunnerId
+    #: Parsed switches, keyed by canonical flag name (values intentionally loose).
+    flags: Mapping[str, object]
+    #: Positional / pass-through tokens not consumed as flags.
+    rest: tuple[str, ...]
+    #: First user message / request text, when supplied positionally.
+    prompt: str | None = None
+    #: Explicit model selector from the command line (``--model`` / ``-m``).
+    model_id: str | None = None
+    #: Working directory the run is scoped to; ``None`` means the process cwd.
+    cwd: str | None = None
+    #: Named credential account to authenticate with (``--account``).
+    account: str | None = None
+    #: Reasoning effort (``--thinking``): off/minimal/low/medium/high/xhigh.
+    thinking: str | None = None
+    #: Replacement system prompt (``--system``); path-or-literal.
+    system: str | None = None
+    #: Extra text appended after the system prompt (``--append-system``).
+    append_system: str | None = None
+    #: Allow-list of built-in tool names (``--tools``); ``None`` = full deck.
+    tools: tuple[str, ...] | None = None
+    #: Disable every built-in tool (``--no-tools``).
+    no_tools: bool = False
+    #: External MCP endpoint config paths to attach (``--mcp``).
+    mcp: tuple[str, ...] | None = None
+    #: Open the resume picker before the session starts (``--resume`` / ``-r``).
+    resume: bool | None = None
+    #: Auto-resume the most recent session in the cwd (``--continue`` / ``-c``).
+    continue_latest: bool | None = None
+    #: Print the model catalog and exit (``--list-models``).
+    list_models: bool | None = None
+    #: Optional substring filter for ``--list-models``.
+    list_models_filter: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Resolved startup resources
+# ---------------------------------------------------------------------------
+
+#: Placeholder for the resolved per-account credential graph (the TS
+#: forward-declared indexable bag). The concrete multi-account vault lives in
+#: :mod:`induscode.boot.auth_vault`; this stays a loose mapping so the
+#: resource stage can attach it without coupling to the vault module.
+CredentialGraph: TypeAlias = Mapping[str, object]
+
+
+@dataclass(frozen=True, slots=True)
+class StartupResources:
+    """The resolved settings / auth / model-registry graph assembled during
+    startup.
+
+    ``settings`` is typed against the framework's published ``Settings``
+    shape (degrading to an empty mapping when the framework piece cannot be
+    loaded — the *shape* is what later phases depend on); ``models`` is the
+    conductor's normalized :class:`~induscode.conductor.ModelCatalog` (the
+    port-plan replacement for the TS framework ``ModelRegistry``)."""
+
+    #: Merged user settings (framework-owned shape; empty mapping on degrade).
+    settings: Settings | Mapping[str, object]
+    #: Resolved credentials per account (app-owned placeholder bag).
+    auth: CredentialGraph
+    #: The resolved model catalog.
+    models: ModelCatalog
+
+
+# ---------------------------------------------------------------------------
+# Boot context & pipeline
+# ---------------------------------------------------------------------------
+
+#: One teardown callback drained on shutdown. May be sync or async; failures
+#: are swallowed by the drain.
+Closable: TypeAlias = Callable[[], Union[Awaitable[None], None]]
+
+
+@dataclass(frozen=True, slots=True)
+class BootContext:
+    """The immutable value threaded through the :class:`Stage` pipeline.
+
+    Each stage receives a context and returns the next one; treat every field
+    as read-only and produce successors via :func:`dataclasses.replace` rather
+    than mutating. The resolved-resource graph is ``None`` until the resource
+    stage runs. :attr:`closables` accumulates teardown callbacks (open files,
+    servers, MCP clients) that the orchestrator drains in reverse on exit —
+    it is deliberately a shared mutable list across context successors.
+    """
+
+    #: The process arguments the launch was invoked with (already sliced).
+    argv: tuple[str, ...]
+    #: Resolved on-disk layout.
+    workspace: Workspace
+    #: Resolved identity literals.
+    brand: Brand
+    #: Parsed command line.
+    invocation: Invocation
+    #: Resolved settings/auth/model graph; absent until the resource stage runs.
+    resources: StartupResources | None = None
+    #: Teardown callbacks to drain on shutdown (latest-registered first).
+    closables: list[Closable] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class Stage:
+    """One step of the launch pipeline: a named, pure-ish transform over a
+    :class:`BootContext`.
+
+    ``apply`` may return its result synchronously or as an awaitable. It must
+    not mutate its input; it returns the next context. ``name`` is used for
+    tracing and error attribution. (TS interface → frozen dataclass row whose
+    ``apply`` is a plain callable field.)
+    """
+
+    #: Stable identifier for tracing and error messages.
+    name: str
+    #: Transform the context, yielding its successor.
+    apply: Callable[[BootContext], Union[BootContext, Awaitable[BootContext]]]
+
+
+@dataclass(frozen=True, slots=True)
+class Runner:
+    """A terminal execution strategy for one :data:`RunnerId` mode.
+
+    The runner registry asks each runner whether it ``accepts`` a parsed
+    :class:`Invocation`; the first match runs. ``run`` drives the selected
+    mode to completion and resolves to the process exit code.
+    """
+
+    #: The mode this runner serves.
+    id: RunnerId
+    #: Whether this runner handles the given invocation.
+    accepts: Callable[[Invocation], bool]
+    #: Execute the mode; resolves to the process exit code.
+    run: Callable[[BootContext], Awaitable[int]]

induscode/boot/invocation.py

@@ -0,0 +1,117 @@
+"""Invocation reader for the boot layer — the adapter that drives the full
+declarative launch flag grammar and projects its rich result down onto the
+thin boot :class:`~.contract.Invocation` the runner pipeline routes on.
+
+Port of TS ``src/boot/invocation.ts``. The parsing itself is not owned here:
+:func:`induscode.launch.read_invocation` walks the single declarative flag
+table and produces the full launch :class:`~induscode.launch.Invocation`;
+this module's job is purely the *projection* — map the launch
+:data:`~induscode.launch.OutputMode` onto the boot
+:data:`~.contract.RunnerId`, rename the resolved fields the boot layer reads
+(``model`` → ``model_id``, ``positionals`` → ``rest``), and carry the loose
+flag bag through so the meta checks (``--help`` / ``--version``) and the
+oneshot output-shape probe (``json``) keep reading the same canonical keys.
+
+- mode: ``text`` → ``repl``, ``json`` → ``oneshot``, ``rpc`` → ``link``.
+
+The parse is total and never raises: the launch reader tolerates unknown
+``--flags`` as switches in the flag bag rather than rejecting them, so
+nothing is silently dropped before a later phase can reinterpret it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from induscode.launch import Invocation as LaunchInvocation
+from induscode.launch import OutputMode, read_invocation
+
+from .contract import Invocation, RunnerId
+
+__all__ = [
+    "to_runner_id",
+    "tokenize_invocation",
+    "wants_help",
+    "wants_version",
+]
+
+
+def to_runner_id(mode: OutputMode) -> RunnerId:
+    """Map a launch :data:`OutputMode` onto the boot :data:`RunnerId` the
+    runner registry dispatches on. The two vocabularies are deliberately
+    one-to-one:
+
+    - ``text`` — the interactive terminal session → ``repl``.
+    - ``json`` — a single non-interactive request to stdout → ``oneshot``.
+    - ``rpc``  — the headless line protocol for a driving parent → ``link``.
+    """
+    if mode == "rpc":
+        return "link"
+    if mode == "json":
+        return "oneshot"
+    return "repl"
+
+
+def _project_invocation(launch: LaunchInvocation) -> Invocation:
+    """Project a fully-parsed launch invocation down onto the thin boot
+    :class:`~.contract.Invocation`.
+
+    The boot layer only needs the routing mode, the prompt, the explicit
+    model and cwd, the leftover positionals, and the loose flag bag; the
+    richer launch fields (attachments, typed tool roster, …) stay available
+    on the launch result for later phases.
+    """
+    # `--list-models` is a string flag (its value is an optional substring
+    # filter), so "present" means set to anything other than False; a
+    # non-empty string value becomes the filter.
+    list_models_raw = launch.flags.get("list-models")
+    list_models = list_models_raw is not None and list_models_raw is not False
+    list_models_filter = (
+        list_models_raw
+        if isinstance(list_models_raw, str) and len(list_models_raw) > 0
+        else None
+    )
+
+    return Invocation(
+        mode=to_runner_id(launch.mode),
+        prompt=launch.prompt,
+        model_id=launch.model,
+        cwd=launch.cwd,
+        account=launch.account,
+        thinking=launch.thinking,
+        system=launch.system,
+        append_system=launch.append_system,
+        tools=launch.tools,
+        no_tools=bool(launch.no_tools),
+        mcp=launch.mcp if len(launch.mcp) > 0 else None,
+        resume=True if launch.flags.get("resume") is True else None,
+        continue_latest=True if launch.flags.get("continue") is True else None,
+        list_models=True if list_models else None,
+        list_models_filter=list_models_filter,
+        flags=launch.flags,
+        rest=tuple(launch.positionals),
+    )
+
+
+def tokenize_invocation(argv: Sequence[str]) -> Invocation:
+    """Read a sliced ``argv`` into the boot :class:`~.contract.Invocation`.
+
+    Delegates the actual grammar to the launch
+    :func:`~induscode.launch.read_invocation` (the one declarative flag
+    table), then projects its result onto the boot shape — help, parsing, and
+    routing share one parser and can never drift.
+
+    :param argv: the already-sliced argument vector (no interpreter / script
+        path)
+    """
+    return _project_invocation(read_invocation(argv))
+
+
+def wants_help(inv: Invocation) -> bool:
+    """Whether the parsed invocation is asking for the help banner."""
+    return inv.flags.get("help") is True
+
+
+def wants_version(inv: Invocation) -> bool:
+    """Whether the parsed invocation is asking for the version string."""
+    return inv.flags.get("version") is True

induscode/boot/runners/__init__.py

@@ -0,0 +1,42 @@
+"""Runners subsystem — public barrel (port of TS ``src/boot/runners``).
+
+Surfaces the runner registry and the individual runners. Boot consumers
+dispatch through :func:`select_runner` / :data:`RUNNERS`; the named runners
+are exported for tests and for explicit wiring, along with the session
+assembly helpers (:func:`build_session_conductor`, :func:`session_scope_dir`)
+and the repl console-mount seam M5 plugs into.
+"""
+
+from __future__ import annotations
+
+from .link_runner import link_runner
+from .oneshot_runner import oneshot_runner
+from .registry import RUNNERS, select_runner
+from .repl_runner import ConsoleMount, ReplServices, repl_runner, set_console_mount
+from .session import (
+    build_key_resolver,
+    build_session_conductor,
+    condense_transcript,
+    oneshot_prompts,
+    prime_provider_env,
+    resolve_model_id,
+    session_scope_dir,
+)
+
+__all__ = [
+    "ConsoleMount",
+    "RUNNERS",
+    "ReplServices",
+    "build_key_resolver",
+    "build_session_conductor",
+    "condense_transcript",
+    "link_runner",
+    "oneshot_prompts",
+    "oneshot_runner",
+    "prime_provider_env",
+    "repl_runner",
+    "resolve_model_id",
+    "select_runner",
+    "session_scope_dir",
+    "set_console_mount",
+]

induscode/boot/runners/link_runner.py

@@ -0,0 +1,82 @@
+"""Runner: ``link`` — headless JSON-RPC link for a driving parent process.
+
+Port of TS ``src/boot/runners/link-runner.ts``. Drives the link channel: it
+assembles a :class:`~induscode.conductor.SessionConductor` for the invocation
+and serves the declarative :data:`~induscode.channels.SESSION_OPS` registry
+over the process stdio pair via
+:func:`~induscode.channels.create_link_server`. Every framed request is
+dispatched through the registry (data-driven, not a command switch) and the
+reply is framed back; the runner resolves the success exit code once the
+inbound stream ends.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import AsyncIterator
+from typing import Final
+
+from induscode.channels import SESSION_OPS, WritableLine, create_link_server
+from induscode.channels.link import LinkServerIo
+
+from ..contract import BootContext, Invocation, Runner
+from .session import build_session_conductor
+
+__all__ = ["link_runner"]
+
+#: Exit code returned once the link stream ends cleanly.
+_EXIT_OK: Final[int] = 0
+
+
+class _Stdout:
+    """A :class:`~induscode.channels.WritableLine` backed by the process
+    standard output stream (flushed per frame — a driving parent reads the
+    pipe line by line)."""
+
+    def write(self, chunk: str) -> object:
+        sys.stdout.write(chunk)
+        sys.stdout.flush()
+        return True
+
+
+#: The shared stdout sink.
+STDOUT: Final[WritableLine] = _Stdout()
+
+
+async def _stdin_chunks() -> AsyncIterator[bytes]:
+    """The process stdin as an async chunk stream (the
+    :data:`~induscode.channels.ReadableChunks` shape). Blocking reads are
+    pushed onto the default executor so the event loop — and with it the
+    concurrently-dispatched request handlers — keeps running between
+    frames."""
+    loop = asyncio.get_running_loop()
+    stdin = sys.stdin.buffer
+    while True:
+        chunk = await loop.run_in_executor(None, stdin.read1, 65536)
+        if not chunk:
+            return
+        yield chunk
+
+
+def _accepts(inv: Invocation) -> bool:
+    return inv.mode == "link"
+
+
+async def _run(ctx: BootContext) -> int:
+    """Assemble the conductor, start a link server reading framed requests
+    from stdin and writing framed replies to stdout, and resolve the success
+    exit code when the inbound stream is exhausted."""
+    conductor = await build_session_conductor(ctx)
+    server = create_link_server(
+        SESSION_OPS,
+        conductor,
+        LinkServerIo(in_=_stdin_chunks(), out=STDOUT),
+    )
+    await server.done
+    return _EXIT_OK
+
+
+#: The headless-link runner row: accepts invocations whose resolved mode is
+#: ``link``.
+link_runner: Final[Runner] = Runner(id="link", accepts=_accepts, run=_run)