induscode 0.1.0__py3-none-any.whl

induscode/channels/link/driver.py

@@ -0,0 +1,308 @@
+"""Link driver — the generated client over the JSON-RPC link
+(port of TS ``src/channels/link/driver.ts``).
+
+The driver is the mirror of the server: it writes framed requests and reads
+framed replies. Crucially it is *generated*, not hand-written — there is no
+per-op client method. The TS ``Proxy`` becomes a ``__getattr__`` trap: any
+attribute access on the client yields a thunk that frames ``{id, method,
+params} -> awaits {id, result | error}``, so the client mirrors whatever op
+registry the server dispatches with a single body. Adding an op to the
+registry adds a callable method to the driver for free.
+
+The driver owns the single reader over the inbound stream. Every decoded
+frame is one of: a correlated reply (settles the pending request under its
+id), an uncorrelated signal (fanned out to the ``on_signal`` hook), or an ask
+(handed to the ``on_ask`` answerer that posts an answer back). One reader,
+three routes — no competing consumers of the transport.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Callable, Coroutine
+
+from induscode.channels.contract import (
+    PROTOCOL_VERSION,
+    REQUEST_ID_PREFIX,
+    Ask,
+    ChannelTimings,
+    NdjsonFramer,
+    OpError,
+    ReadableChunks,
+    RequestId,
+    Signal,
+    WritableLine,
+    mint_wire_id,
+    resolve_timings,
+)
+from induscode.channels.framer import ndjson_framer
+
+__all__ = [
+    "LinkClient",
+    "LinkDriverHandle",
+    "LinkDriverIo",
+    "LinkRequestError",
+    "create_link_driver",
+]
+
+
+# ---------------------------------------------------------------------------
+# Transport seams
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class LinkDriverIo:
+    """The injectable transport pair the driver writes to and reads from.
+
+    (TS named the inbound field ``in``; that is a Python keyword, hence
+    ``in_``.)
+    """
+
+    #: Sink the driver writes framed requests to (the child stdin in production).
+    out: WritableLine
+    #: Source the driver reads framed replies / signals from (the child stdout).
+    in_: ReadableChunks
+
+
+@dataclass(frozen=True, slots=True)
+class _PendingRequest:
+    """A pending request awaiting its correlated reply."""
+
+    future: asyncio.Future[Any]
+    timer: asyncio.TimerHandle
+
+
+class LinkRequestError(Exception):
+    """A failed reply turned into a raisable error that carries the wire code."""
+
+    def __init__(self, error: OpError) -> None:
+        super().__init__(error.message)
+        #: The JSON-RPC error code from the :class:`OpError`.
+        self.code: int = error.code
+        #: The structured detail, when the server supplied any.
+        self.data: Any = error.data
+
+
+# ---------------------------------------------------------------------------
+# Frame classification
+# ---------------------------------------------------------------------------
+
+
+def _is_reply_frame(frame: Any) -> bool:
+    """Whether a decoded frame is a correlated reply."""
+    return (
+        isinstance(frame, Mapping)
+        and "id" in frame
+        and ("result" in frame or "error" in frame)
+    )
+
+
+def _is_signal_frame(frame: Any) -> bool:
+    """Whether a decoded frame is an uncorrelated signal."""
+    return isinstance(frame, Mapping) and frame.get("type") == "signal"
+
+
+def _is_ask_frame(frame: Any) -> bool:
+    """Whether a decoded frame is a server-initiated ask."""
+    return (
+        isinstance(frame, Mapping)
+        and frame.get("type") == "ask"
+        and isinstance(frame.get("id"), str)
+    )
+
+
+# ---------------------------------------------------------------------------
+# Generated client
+# ---------------------------------------------------------------------------
+
+
+class LinkClient:
+    """The generated client: every attribute access is a request thunk.
+
+    The TS ``Proxy`` trap becomes ``__getattr__``: reading attribute ``m``
+    yields a thunk ``(params=None) -> awaitable result`` that round-trips the
+    method named ``m`` through the link. No method is hand-written; the op
+    registry on the server side is the single source of the callable surface
+    (an unregistered name simply rejects with the JSON-RPC ``unknownOp``
+    error, exactly as the TS proxy did).
+    """
+
+    __slots__ = ("_request",)
+
+    def __init__(
+        self, request: Callable[[str, Any], Coroutine[Any, Any, Any]]
+    ) -> None:
+        object.__setattr__(self, "_request", request)
+
+    def __getattr__(self, name: str) -> Callable[..., Coroutine[Any, Any, Any]]:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        request = self._request
+
+        def thunk(params: Any = None) -> Coroutine[Any, Any, Any]:
+            return request(name, params)
+
+        thunk.__name__ = name
+        return thunk
+
+
+# ---------------------------------------------------------------------------
+# Driver handle
+# ---------------------------------------------------------------------------
+
+
+class LinkDriverHandle:
+    """A live driver: the generated client plus its lifecycle.
+
+    ``client`` is the ``__getattr__``-generated :class:`LinkClient`; ``done``
+    resolves when the inbound stream ends; :meth:`close` rejects every
+    still-pending request and stops accepting replies.
+    """
+
+    __slots__ = ("client", "done", "_close")
+
+    def __init__(
+        self,
+        client: LinkClient,
+        done: asyncio.Task[None],
+        close: Callable[[str], None],
+    ) -> None:
+        #: The generated, registry-mirroring client.
+        self.client = client
+        #: Resolves when the reader loop drains (the inbound stream ended).
+        self.done = done
+        self._close = close
+
+    def close(self, reason: str = "link driver closed by caller") -> None:
+        """Reject all pending requests with ``reason`` and stop accepting
+        replies."""
+        self._close(reason)
+
+
+def create_link_driver(
+    io: LinkDriverIo,
+    *,
+    framer: NdjsonFramer | None = None,
+    timings: Mapping[str, int] | None = None,
+    on_signal: Callable[[Signal], None] | None = None,
+    on_ask: Callable[[Ask], Any] | None = None,
+) -> LinkDriverHandle:
+    """Build a :class:`LinkDriverHandle` over an injected transport.
+
+    The returned ``client`` generates a thunk per attribute access: calling
+    ``client.m(params)`` mints an id (prefixed with
+    :data:`REQUEST_ID_PREFIX`), writes the framed request, and resolves when
+    the matching reply arrives (or raises on an error reply or timeout). The
+    reader loop classifies inbound frames into replies, signals, and asks and
+    routes each. Must be called with a running event loop (the pump task
+    starts immediately).
+
+    :param io: the injected request sink + reply source
+    :param framer: override the NDJSON framer (defaults to the shared one)
+    :param timings: override any subset of the channel timings
+    :param on_signal: invoked for every uncorrelated signal the server streams
+    :param on_ask: invoked when the server asks a question; returns the answer
+        value (sync or awaitable). When omitted the driver dismisses every ask
+        (posts ``None``), so a non-interactive driver never wedges the server.
+    """
+    the_framer = framer if framer is not None else ndjson_framer
+    the_timings: ChannelTimings = resolve_timings(timings)
+
+    pending: dict[RequestId, _PendingRequest] = {}
+    state = {"seq": 0, "closed": False}
+
+    def next_id() -> str:
+        state["seq"] += 1
+        return mint_wire_id(REQUEST_ID_PREFIX, int(time.time() * 1000), state["seq"])
+
+    async def request(method: str, params: Any = None) -> Any:
+        if state["closed"]:
+            raise RuntimeError("link driver is closed")
+        request_id = next_id()
+        frame: dict[str, Any] = {"jsonrpc": PROTOCOL_VERSION, "id": request_id, "method": method}
+        if params is not None:  # JSON.stringify dropped the undefined params
+            frame["params"] = params
+
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[Any] = loop.create_future()
+
+        def on_timeout() -> None:
+            pending.pop(request_id, None)
+            if not future.done():
+                future.set_exception(TimeoutError(f"link request timed out: {method}"))
+
+        timer = loop.call_later(the_timings.requestMs / 1000, on_timeout)
+        pending[request_id] = _PendingRequest(future=future, timer=timer)
+        io.out.write(the_framer.encode_line(frame))
+        return await future
+
+    def settle_reply(reply: Mapping[str, Any]) -> None:
+        entry = pending.pop(reply["id"], None)
+        if entry is None:
+            return
+        entry.timer.cancel()
+        if entry.future.done():
+            return
+        if "result" in reply:
+            entry.future.set_result(reply["result"])
+        else:
+            error = reply.get("error")
+            wire = error if isinstance(error, Mapping) else {}
+            entry.future.set_exception(
+                LinkRequestError(
+                    OpError(
+                        code=int(wire.get("code", 0)),
+                        message=str(wire.get("message", "")),
+                        data=wire.get("data"),
+                    )
+                )
+            )
+
+    async def answer_ask(frame: Mapping[str, Any]) -> None:
+        ask = Ask(id=frame["id"], kind=str(frame.get("kind", "")), payload=frame.get("payload"))
+        value: Any = None
+        if on_ask is not None:
+            value = on_ask(ask)
+            if inspect.isawaitable(value):
+                value = await value
+        io.out.write(the_framer.encode_line({"type": "answer", "id": ask.id, "value": value}))
+
+    def reject_all(reason: str) -> None:
+        for entry in pending.values():
+            entry.timer.cancel()
+            if not entry.future.done():
+                entry.future.set_exception(RuntimeError(reason))
+        pending.clear()
+
+    async def pump() -> None:
+        try:
+            async for frame in the_framer.decode_lines(io.in_):
+                if _is_reply_frame(frame):
+                    settle_reply(frame)
+                    continue
+                if _is_signal_frame(frame):
+                    if on_signal is not None:
+                        on_signal(Signal(name=str(frame.get("name", "")), body=frame.get("body")))
+                    continue
+                if _is_ask_frame(frame):
+                    await answer_ask(frame)
+                    continue
+                # Unknown frame shape: forward-compatible no-op.
+        finally:
+            state["closed"] = True
+            reject_all("link closed before reply")
+
+    def close(reason: str) -> None:
+        state["closed"] = True
+        reject_all(reason)
+
+    return LinkDriverHandle(
+        client=LinkClient(request),
+        done=asyncio.create_task(pump()),
+        close=close,
+    )

induscode/channels/link/server.py

@@ -0,0 +1,217 @@
+"""Link server — the data-driven JSON-RPC 2.0 dispatch loop
+(port of TS ``src/channels/link/server.ts``).
+
+The server owns the single reader over the inbound stream. For each framed
+line it decides what the frame is and routes it: a request frame is
+dispatched through the :data:`~induscode.channels.contract.OpRegistry` (a map
+lookup, not a command switch) and its outcome is framed back as a reply; an
+inbound answer frame is routed to the dialog bridge to settle a suspended
+``ask``. One round of the protocol is ``{id, method, params} -> {id,
+result | error}``.
+
+Everything that touches the outside world is injected: the request source,
+the reply sink, the framer, and the conductor all arrive through the context
+and options, so a test serves the link over an in-memory pipe pair with no
+stdio. The dispatch itself is delegated to
+:func:`~induscode.channels.ops.dispatch` from the ops module, so the server
+holds no per-method knowledge.
+
+Concurrency pin (plan rule 8): a request handler may itself suspend on a
+dialog ``ask``, whose answer arrives as a later inbound frame **on this very
+stream**. So requests are dispatched as concurrent ``asyncio`` tasks (tracked
+in a set, gathered at stream end) rather than awaited in line — otherwise the
+reader would block on a handler that needs the reader to make progress,
+deadlocking the round trip. Answer frames are always delivered immediately so
+a suspended ``ask`` can settle.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from induscode.channels.contract import (
+    OP_ERROR,
+    PROTOCOL_VERSION,
+    AskAnswer,
+    ChannelContext,
+    NdjsonFramer,
+    OpError,
+    OpRegistry,
+    ReadableChunks,
+    RequestId,
+    SessionConductor,
+    WritableLine,
+    resolve_timings,
+)
+from induscode.channels.framer import ndjson_framer
+from induscode.channels.link.dialog import (
+    DialogBridgeDeps,
+    LinkedDialogBridge,
+    create_dialog_bridge,
+)
+from induscode.channels.ops import UnknownOpError, dispatch
+
+__all__ = [
+    "LinkServer",
+    "LinkServerIo",
+    "create_link_server",
+]
+
+
+# ---------------------------------------------------------------------------
+# Transport seams
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class LinkServerIo:
+    """The injectable transport pair the server reads from and writes to.
+
+    Bundles the inbound request source and the outbound reply/signal sink so
+    tests pass in-memory pipes and production passes stdin / stdout adapters.
+    (TS named the inbound field ``in``; that is a Python keyword, hence
+    ``in_``.)
+    """
+
+    #: Framed inbound request / answer lines (stdin in production).
+    in_: ReadableChunks
+    #: Framed outbound reply / signal / dialog sink (stdout in production).
+    out: WritableLine
+
+
+@dataclass(frozen=True, slots=True)
+class LinkServer:
+    """A running server: a task that settles when the inbound stream ends."""
+
+    #: Resolves when the request stream is exhausted and the loop has drained.
+    done: asyncio.Task[None]
+    #: The dialog bridge the running server feeds inbound answers to.
+    dialog: LinkedDialogBridge
+
+
+# ---------------------------------------------------------------------------
+# Frame classification
+# ---------------------------------------------------------------------------
+
+
+def _is_request_frame(frame: Any) -> bool:
+    """Whether a decoded frame looks like a JSON-RPC request (``method``
+    present as a string)."""
+    return isinstance(frame, Mapping) and isinstance(frame.get("method"), str)
+
+
+def _is_answer_frame(frame: Any) -> bool:
+    """Whether a decoded frame is an inbound answer to a suspended ``ask``."""
+    return (
+        isinstance(frame, Mapping)
+        and frame.get("type") == "answer"
+        and isinstance(frame.get("id"), str)
+    )
+
+
+def _to_op_error(error: BaseException) -> OpError:
+    """Map a raised exception to a framed :class:`OpError`, preserving a
+    known code."""
+    if isinstance(error, UnknownOpError):
+        return OpError(code=error.code, message=str(error), data={"method": error.method})
+    return OpError(code=OP_ERROR["handlerFailed"], message=str(error))
+
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+
+
+def create_link_server(
+    registry: OpRegistry,
+    conductor: SessionConductor,
+    io: LinkServerIo,
+    *,
+    framer: NdjsonFramer | None = None,
+    timings: Mapping[str, int] | None = None,
+) -> LinkServer:
+    """Start a link server over an op registry, a conductor, and an injected
+    transport.
+
+    Builds the shared :class:`ChannelContext` (conductor + framer + the
+    freshly wired dialog bridge), then consumes the inbound stream with a
+    single ``async for`` loop. Each frame is classified:
+
+    - an answer frame is delivered to the dialog bridge;
+    - a request frame is dispatched through ``registry`` as a concurrent
+      task; a request carrying an ``id`` gets exactly one correlated reply
+      (result or error); a notification (no ``id``) is dispatched for its
+      effect and never replied to;
+    - any other frame is ignored (a forward-compatible no-op).
+
+    Must be called with a running event loop (the pump task starts
+    immediately — the analogue of the TS promise returned by ``pump()``).
+
+    :param registry: the frozen :data:`OpRegistry` that drives dispatch
+    :param conductor: the session every op delegates to
+    :param io: the injected request source + reply sink
+    :param framer: override the NDJSON framer (defaults to the shared one)
+    :param timings: override any subset of the channel timings
+    :returns: a handle whose ``done`` resolves when the inbound stream ends
+    """
+    the_framer = framer if framer is not None else ndjson_framer
+    the_timings = resolve_timings(timings)
+
+    dialog = create_dialog_bridge(
+        DialogBridgeDeps(out=io.out, framer=the_framer, timings=the_timings)
+    )
+
+    ctx = ChannelContext(conductor=conductor, out=io.out, framer=the_framer, dialog=dialog)
+
+    def write_reply(reply: Mapping[str, Any]) -> None:
+        io.out.write(the_framer.encode_line(reply))
+
+    def reply_ok(request_id: RequestId, result: Any) -> None:
+        write_reply({"jsonrpc": PROTOCOL_VERSION, "id": request_id, "result": result})
+
+    def reply_err(request_id: RequestId, error: OpError) -> None:
+        wire_error: dict[str, Any] = {"code": error.code, "message": error.message}
+        if error.data is not None:
+            wire_error["data"] = error.data
+        write_reply({"jsonrpc": PROTOCOL_VERSION, "id": request_id, "error": wire_error})
+
+    async def handle_request(frame: Mapping[str, Any]) -> None:
+        wants_reply = "id" in frame
+        try:
+            result = await dispatch(registry, frame["method"], frame.get("params"), ctx)
+            if wants_reply:
+                reply_ok(frame["id"], result)
+        except Exception as error:  # noqa: BLE001 — every handler fault frames as a reply
+            if wants_reply:
+                reply_err(frame["id"], _to_op_error(error))
+
+    async def pump() -> None:
+        # A request handler may itself suspend on a dialog `ask`, whose answer
+        # arrives as a later inbound frame on this very stream. So requests
+        # are dispatched concurrently (their tasks tracked) rather than
+        # awaited in line — otherwise the reader would block on a handler
+        # that needs the reader to make progress, deadlocking the round trip.
+        # Answer frames are always delivered immediately so a suspended `ask`
+        # can settle.
+        inflight: set[asyncio.Task[None]] = set()
+        try:
+            async for frame in the_framer.decode_lines(io.in_):
+                if _is_answer_frame(frame):
+                    dialog.deliver(AskAnswer(id=frame["id"], value=frame.get("value")))
+                    continue
+                if _is_request_frame(frame):
+                    task = asyncio.create_task(handle_request(frame))
+                    inflight.add(task)
+                    task.add_done_callback(inflight.discard)
+                    continue
+                # Unknown frame shape: forward-compatible no-op.
+            # Let any still-running handlers settle before the loop reports done.
+            if inflight:
+                await asyncio.gather(*inflight)
+        finally:
+            dialog.drain()
+
+    return LinkServer(done=asyncio.create_task(pump()), dialog=dialog)

induscode/channels/oneshot.py

@@ -0,0 +1,178 @@
+"""Oneshot channel — a single non-interactive run to settlement
+(port of TS ``src/channels/oneshot.ts``).
+
+Replaces the print mode. Given a
+:class:`~induscode.channels.contract.ChannelContext` and a
+:class:`~induscode.channels.contract.OneshotRequest`, it submits every prompt
+to the conductor in order, streams the answer to the channel sink, and
+resolves a process exit code.
+
+The shape (clean final text vs a streamed NDJSON event log) is chosen by
+selecting an :class:`~induscode.channels.contract.OneshotStrategy` object
+rather than branching on a flag through the runner body: each strategy
+supplies an optional ``on_start``, an optional ``on_signal``, and a mandatory
+``finish`` that turns the settled state into the exit code. The runner itself
+is shape-agnostic — it subscribes the strategy to the conductor signal
+stream, runs the prompts, and hands the final state to ``finish``.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Final, Mapping
+
+from induscode.channels.contract import (
+    ChannelContext,
+    ConductorState,
+    DialogBridge,
+    OneshotRequest,
+    OneshotShape,
+    OneshotStrategy,
+    signal_to_wire,
+)
+from induscode.conductor.contract import SessionSignal
+from induscode.conductor.serialize import message_to_dict
+
+__all__ = [
+    "inert_dialog",
+    "run_oneshot",
+]
+
+
+class _InertDialog:
+    """A dialog bridge for a non-interactive oneshot run: no driver is
+    attached to answer a question, so every ``ask`` resolves immediately with
+    its caller-supplied fallback and every ``tell`` is dropped. Keeps the
+    agent from wedging on a prompt during a headless single run while never
+    writing dialog frames to the sink."""
+
+    async def ask(self, kind: str, payload: Any, fallback: Any) -> Any:
+        return fallback
+
+    def tell(self, kind: str, payload: Any = None) -> None:
+        # Fire-and-forget with no listener: intentionally discarded.
+        return None
+
+
+#: The shared inert bridge instance (TS frozen ``inertDialog``).
+inert_dialog: Final[DialogBridge] = _InertDialog()
+
+
+#: Exit code for a clean settlement.
+_EXIT_OK: Final[int] = 0
+
+#: Exit code for a faulted settlement.
+_EXIT_FAULT: Final[int] = 1
+
+
+def _exit_code_for(state: ConductorState) -> int:
+    """Pick the exit code from a settled :class:`ConductorState`: a faulted
+    phase is a failure, anything else is success. Shared by both strategies so
+    the success rule lives in one place."""
+    return _EXIT_FAULT if state.phase == "faulted" else _EXIT_OK
+
+
+def _text_strategy() -> OneshotStrategy:
+    """The text strategy: accumulate streamed answer text and emit it once,
+    clean.
+
+    ``on_signal`` collects every ``text`` delta into a buffer; ``finish``
+    writes the accumulated answer as a single trailing line (so a caller
+    capturing stdout gets the final answer, not a token-by-token dribble) and
+    returns the exit code. Thinking deltas, tool frames, and bookkeeping
+    signals are ignored.
+    """
+    parts: list[str] = []
+
+    def on_signal(signal: SessionSignal, ctx: ChannelContext) -> None:
+        if signal.kind == "text":
+            parts.append(signal.delta)  # type: ignore[union-attr]
+
+    def finish(state: ConductorState, ctx: ChannelContext) -> int:
+        answer = "".join(parts)
+        ctx.out.write(answer if answer.endswith("\n") else answer + "\n")
+        return _exit_code_for(state)
+
+    return OneshotStrategy(finish=finish, on_signal=on_signal)
+
+
+def _ndjson_strategy() -> OneshotStrategy:
+    """The NDJSON strategy: stream every conductor signal as one framed line.
+
+    ``on_start`` emits an opening frame announcing the run; ``on_signal``
+    frames each :data:`SessionSignal` (projected through ``signal_to_wire``)
+    via the shared framer; ``finish`` emits a closing frame carrying the
+    settled phase and usage, then returns the exit code. Every line is
+    separator-safe by construction (the framer escapes the two Unicode line
+    separators).
+    """
+
+    def on_start(ctx: ChannelContext) -> None:
+        ctx.out.write(ctx.framer.encode_line({"type": "signal", "name": "start", "body": {}}))
+
+    def on_signal(signal: SessionSignal, ctx: ChannelContext) -> None:
+        ctx.out.write(
+            ctx.framer.encode_line(
+                {"type": "signal", "name": signal.kind, "body": signal_to_wire(signal)}
+            )
+        )
+
+    def finish(state: ConductorState, ctx: ChannelContext) -> int:
+        body: dict[str, Any] = {
+            "phase": state.phase,
+            "usage": message_to_dict(state.usage),
+        }
+        # TS framed `fault: undefined` away via JSON.stringify; omit None here.
+        if state.fault is not None:
+            body["fault"] = message_to_dict(state.fault)
+        ctx.out.write(ctx.framer.encode_line({"type": "signal", "name": "end", "body": body}))
+        return _exit_code_for(state)
+
+    return OneshotStrategy(finish=finish, on_start=on_start, on_signal=on_signal)
+
+
+#: The strategy table: one entry per :data:`OneshotShape`. Selecting a shape
+#: is looking up its row, not threading an ``if`` through the runner.
+_STRATEGIES: Final[Mapping[OneshotShape, Any]] = {
+    "text": _text_strategy,
+    "ndjson": _ndjson_strategy,
+}
+
+
+async def run_oneshot(ctx: ChannelContext, opts: OneshotRequest) -> int:
+    """Run one non-interactive request to settlement.
+
+    Selects the :class:`OneshotStrategy` for ``opts.shape``, subscribes it to
+    the conductor signal stream, runs ``on_start``, then submits each prompt
+    in order and awaits its settlement. The state from the final prompt is
+    handed to the strategy's ``finish``, whose return value is the resolved
+    exit code. The subscription is always torn down before returning.
+
+    :param ctx: the channel context (conductor, sink, framer, dialog) — fully
+        injected
+    :param opts: the request: output shape, the prompts to run, and any images
+    :returns: the process exit code (0 on a clean settlement, 1 on a fault)
+    """
+    strategy: OneshotStrategy = _STRATEGIES[opts.shape]()
+
+    def relay(signal: SessionSignal) -> None:
+        if strategy.on_signal is not None:
+            strategy.on_signal(signal, ctx)
+
+    unsubscribe = ctx.conductor.subscribe(relay)
+    try:
+        if strategy.on_start is not None:
+            started = strategy.on_start(ctx)
+            if inspect.isawaitable(started):
+                await started
+
+        state: ConductorState = ctx.conductor.snapshot()
+        for prompt in opts.prompts:
+            state = await ctx.conductor.submit(prompt)
+
+        finished = strategy.finish(state, ctx)
+        if inspect.isawaitable(finished):
+            finished = await finished
+        return int(finished)
+    finally:
+        unsubscribe()