induscode 0.1.0__py3-none-any.whl

induscode/channels/ops.py

@@ -0,0 +1,140 @@
+"""Operation registry — the single declarative source both halves of the link
+consume (port of TS ``src/channels/ops.ts``).
+
+The contract defines :func:`~induscode.channels.contract.define_ops` (freeze a
+record of :class:`~induscode.channels.contract.Op` declarations into an
+:data:`~induscode.channels.contract.OpRegistry`). This module adds the runtime
+face the server needs and the driver leans on: a built registry carries its
+``methods`` list (so a link client can be generated by walking the keys, never
+hand-written) and a ``dispatch`` seam that looks an op up by ``method`` and
+runs its ``handle`` — the data-driven replacement for a copied command switch.
+
+Nothing here knows about transport or framing: dispatch takes the already
+parsed ``method``/``params`` and the shared
+:class:`~induscode.channels.contract.ChannelContext`, runs the op, and returns
+its resolved result (or raises :class:`UnknownOpError` when no op is
+registered). The server frames the outcome into a reply; the driver uses
+``methods`` to build its thunks. One frozen registry drives both.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Callable, Coroutine
+
+from induscode.channels.contract import (
+    OP_ERROR,
+    ChannelContext,
+    Op,
+    OpRegistry,
+    define_ops,
+)
+
+__all__ = [
+    "OpRegistryHandle",
+    "UnknownOpError",
+    "build_ops",
+    "define_ops",
+    "dispatch",
+    "has_op",
+    "methods_of",
+]
+
+
+class UnknownOpError(Exception):
+    """Raised by :func:`dispatch` (and :meth:`OpRegistryHandle.dispatch`) when
+    the requested ``method`` has no registered :class:`Op`.
+
+    Carries the frozen ``OP_ERROR["unknownOp"]`` code so the server can frame
+    it into an error reply without re-deriving the category, and records the
+    offending ``method`` for logging.
+    """
+
+    def __init__(self, method: str) -> None:
+        super().__init__(f"Unknown op: {method}")
+        #: The JSON-RPC error category for an unregistered method.
+        self.code: int = OP_ERROR["unknownOp"]
+        #: The method name that resolved to no operation.
+        self.method: str = method
+
+
+async def dispatch(
+    registry: OpRegistry,
+    method: str,
+    params: Any,
+    ctx: ChannelContext,
+) -> Any:
+    """Run one operation by name against the shared context.
+
+    Looks ``method`` up in ``registry``, then awaits its
+    ``handle(params, ctx)``. The lone dispatch path for the server: there is
+    no per-method branch, only a map lookup. Raises :class:`UnknownOpError`
+    when the method is not registered and propagates whatever the handler
+    raises (the server maps that to an error reply).
+
+    :param registry: the frozen :data:`OpRegistry` to dispatch within
+    :param method: the wire method name to invoke
+    :param params: the already-parsed request payload (passed through verbatim)
+    :param ctx: the shared :class:`ChannelContext`
+    :returns: the operation result
+    """
+    op = registry.get(method)
+    if op is None:
+        raise UnknownOpError(method)
+    return await op.handle(params, ctx)
+
+
+def has_op(registry: OpRegistry, method: str) -> bool:
+    """Whether ``method`` resolves to a registered :class:`Op` in ``registry``."""
+    return method in registry
+
+
+def methods_of(registry: OpRegistry) -> tuple[str, ...]:
+    """The sorted wire method names a registry exposes — the driver's method
+    set."""
+    return tuple(sorted(registry.keys()))
+
+
+@dataclass(frozen=True, slots=True)
+class OpRegistryHandle:
+    """A built registry plus its runtime face: the method list and a bound
+    ``dispatch``.
+
+    ``methods`` is what a generated link client walks to build its thunks;
+    ``dispatch`` is what the server calls per request. Both are bound to the
+    one frozen ``registry``, so the server-side dispatch and the client-side
+    method set can never drift from each other.
+    """
+
+    #: The frozen registry — the single source of truth.
+    registry: OpRegistry
+    #: The sorted method names this registry exposes.
+    methods: tuple[str, ...]
+    #: Invoke an op by name against a context; see :func:`dispatch`.
+    dispatch: Callable[[str, Any, ChannelContext], Coroutine[Any, Any, Any]] = field(repr=False)
+
+
+def build_ops(ops: Mapping[str, Op]) -> OpRegistryHandle:
+    """Build an :class:`OpRegistryHandle` from a record of operation
+    declarations.
+
+    Freezes the input with :func:`define_ops`, then bundles it with its
+    derived method list and a ``dispatch`` bound to that frozen registry. This
+    is the lone sanctioned way to produce the object the server and the driver
+    both consume, so the dispatch map and the driver method set always derive
+    from one source.
+
+    :param ops: a record of method-name → :class:`Op`
+    :returns: the frozen registry handle
+    """
+    registry = define_ops(ops)
+
+    async def bound_dispatch(method: str, params: Any, ctx: ChannelContext) -> Any:
+        return await dispatch(registry, method, params, ctx)
+
+    return OpRegistryHandle(
+        registry=registry,
+        methods=methods_of(registry),
+        dispatch=bound_dispatch,
+    )

induscode/channels/session_ops.py

@@ -0,0 +1,172 @@
+"""Session ops — the concrete operation registry that drives the link
+(port of TS ``src/channels/session-ops.ts``).
+
+This is the single declarative source of every operation the link server
+dispatches and the generated link client is built from. Each op binds a wire
+``method`` name to a ``handle`` that delegates to the
+:class:`~induscode.conductor.contract.SessionConductor` carried on the
+:class:`~induscode.channels.contract.ChannelContext`; there is no per-method
+dispatch ladder and no hand-written parallel client method. Adding a row here
+adds both a server-handled method and a callable driver method.
+
+The ops also own the :data:`~induscode.channels.contract.LinkSnapshot`
+projection: the conductor exposes its internal
+:class:`~induscode.conductor.contract.ConductorState`, and
+:func:`project_snapshot` reshapes that into the flat, serializable wire
+vocabulary a remote driver mirrors without holding a live conductor.
+
+Port notes
+----------
+- Wire method names (``submit`` / ``abort`` / ``snapshot`` / ``resume`` /
+  ``listModels`` / ``cycleModel``) and the snapshot field names/casing are
+  kept **verbatim** from TS for cross-host compatibility.
+- TS param interfaces (``SubmitParams`` etc.) typed the registry statically;
+  the Python handlers index the decoded wire dict directly
+  (``params["input"]``, ``params["sessionId"]``, ``params["modelId"]``).
+- TS ``ctx.conductor.cycleModel?.(…)`` (optional method) becomes a ``getattr``
+  probe for the Python conductor's ``cycle_model`` — same as the conductor
+  contract's own port note for optional members.
+- ``usage`` rides the snapshot through the one app-wide codec
+  (:func:`~induscode.conductor.serialize.message_to_dict`, plan rule 2).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from induscode.channels.contract import (
+    ChannelContext,
+    ConductorState,
+    LinkSnapshot,
+    Op,
+    OpRegistry,
+    ThinkingLevel,
+    define_ops,
+)
+from induscode.conductor.serialize import message_to_dict
+
+__all__ = [
+    "DEFAULT_THINKING",
+    "SESSION_OPS",
+    "project_snapshot",
+]
+
+#: The reasoning effort reported when a snapshot carries none of its own.
+DEFAULT_THINKING: ThinkingLevel = "off"
+
+
+# ---------------------------------------------------------------------------
+# Snapshot projection
+# ---------------------------------------------------------------------------
+
+
+def project_snapshot(
+    state: ConductorState,
+    *,
+    thinking: ThinkingLevel | None = None,
+    sessionFile: str | None = None,
+    autoCondense: bool | None = None,
+    messageCount: int | None = None,
+    queuedCount: int | None = None,
+) -> LinkSnapshot:
+    """Project a conductor :class:`ConductorState` onto the wire
+    :data:`LinkSnapshot`.
+
+    The snapshot is the link vocabulary: flat, serializable, and derived from
+    — not a passthrough of — the conductor state. Busy flags are read off the
+    coarse phase, the model and session identity off the state and its head,
+    and the cumulative usage carried straight through (as its codec dict).
+    Field names/casing are the verbatim TS wire vocabulary; ``sessionFile`` is
+    omitted (not nulled) when absent, exactly as ``JSON.stringify`` dropped
+    the undefined TS field.
+
+    :param state: the immutable conductor state
+    :param thinking: reasoning effort the conductor does not surface on state
+    :param sessionFile: on-disk transcript file backing the session
+    :param autoCondense: whether auto-condense is engaged (default ``True``)
+    :param messageCount: nodes on the active transcript branch (default 0)
+    :param queuedCount: inputs queued behind the in-flight turn (default 0)
+    """
+    snapshot: LinkSnapshot = {
+        "model": state.modelId,
+        "thinking": thinking if thinking is not None else DEFAULT_THINKING,
+        "streaming": state.phase == "streaming" or state.phase == "tooling",
+        "condensing": state.phase == "condensing",
+        "faulted": state.phase == "faulted",
+        "sessionId": state.head.sessionId,
+        "autoCondense": autoCondense if autoCondense is not None else True,
+        "messageCount": messageCount if messageCount is not None else 0,
+        "queuedCount": queuedCount if queuedCount is not None else 0,
+        "usage": message_to_dict(state.usage),
+    }
+    if sessionFile is not None:
+        snapshot["sessionFile"] = sessionFile
+    return snapshot
+
+
+# ---------------------------------------------------------------------------
+# The op set
+# ---------------------------------------------------------------------------
+
+
+async def _submit(params: Any, ctx: ChannelContext) -> LinkSnapshot:
+    """Run a user turn to settlement and reply with a snapshot."""
+    state = await ctx.conductor.submit(params["input"])
+    return project_snapshot(state)
+
+
+async def _abort(params: Any, ctx: ChannelContext) -> LinkSnapshot:
+    """Cancel the in-flight turn and reply with a snapshot."""
+    ctx.conductor.abort()
+    return project_snapshot(ctx.conductor.snapshot())
+
+
+async def _snapshot(params: Any, ctx: ChannelContext) -> LinkSnapshot:
+    """Read the current state, projected to a :data:`LinkSnapshot`."""
+    return project_snapshot(ctx.conductor.snapshot())
+
+
+async def _resume(params: Any, ctx: ChannelContext) -> LinkSnapshot:
+    """Restore a persisted session and reply with a snapshot."""
+    await ctx.conductor.resume(params["sessionId"])
+    return project_snapshot(ctx.conductor.snapshot())
+
+
+async def _list_models(params: Any, ctx: ChannelContext) -> list[dict[str, Any]]:
+    """List the model bound to the session (the active entry). Each row is the
+    wire ``ModelEntry`` shape ``{"id", "active"}``."""
+    active = ctx.conductor.snapshot().modelId
+    return [{"id": active, "active": True}]
+
+
+async def _cycle_model(params: Any, ctx: ChannelContext) -> LinkSnapshot:
+    """Rotate the active model and reply with a snapshot. Probes for the
+    conductor's optional ``cycle_model`` (TS ``cycleModel?.()``)."""
+    cycle = getattr(ctx.conductor, "cycle_model", None)
+    if callable(cycle):
+        cycle(params["modelId"])
+    return project_snapshot(ctx.conductor.snapshot())
+
+
+#: The frozen link op set: every operation a driver can invoke, each
+#: delegating to the conductor on the context.
+#:
+#: - ``submit``     — run a user turn to settlement and reply with a snapshot.
+#: - ``abort``      — cancel the in-flight turn and reply with a snapshot.
+#: - ``snapshot``   — read the current state, projected to a snapshot.
+#: - ``resume``     — restore a persisted session and reply with a snapshot.
+#: - ``listModels`` — list the model bound to the session (the active entry).
+#: - ``cycleModel`` — rotate the active model and reply with a snapshot.
+#:
+#: The map is consumed verbatim by the server (data-driven dispatch) and by
+#: the generated link client (its method set is exactly these keys).
+SESSION_OPS: OpRegistry = define_ops(
+    {
+        "submit": Op(method="submit", handle=_submit),
+        "abort": Op(method="abort", handle=_abort),
+        "snapshot": Op(method="snapshot", handle=_snapshot),
+        "resume": Op(method="resume", handle=_resume),
+        "listModels": Op(method="listModels", handle=_list_models),
+        "cycleModel": Op(method="cycleModel", handle=_cycle_model),
+    }
+)

induscode/conductor/__init__.py

@@ -0,0 +1,240 @@
+"""Conductor — the product-level session orchestration layer (public barrel).
+
+The framework ``Agent`` (:mod:`indusagi.agent`) is a raw LLM conversation
+loop; the conductor wraps exactly one such agent and turns it into a
+*coding-agent session*: a stable product signal stream
+(:data:`SessionSignal`), typed faults (:class:`ConductorFault`), an
+immutable state snapshot (:class:`ConductorState`) maintained by the pure
+:func:`reduce_state` reducer, a branchable on-disk transcript vocabulary
+(:class:`TranscriptEntry` / :class:`SessionHead` /
+:data:`TRANSCRIPT_SCHEMA`), and the :class:`SessionConductor` Protocol the
+interactive console, oneshot/print mode, and JSON-RPC link all drive.
+
+M2 wave-1 surface (this barrel today):
+
+- :mod:`.contract` — the FROZEN type seam: signals, faults, transcript
+  schema, catalog refs/queries, state + reducer, queue/stats/bash shapes,
+  and the :class:`SessionConductor` / :class:`AgentLike` /
+  :class:`CondenseFn` / :class:`RetryPolicy` seams.
+- :mod:`.signal_hub` — the :class:`SignalHub` fan-out bus plus the
+  framework-event → product-signal projector
+  (:func:`translate_agent_event` / :data:`TRANSLATOR_TABLE`).
+- :mod:`.skill_parse` — the re-derived ``<skill …>body</skill>`` block
+  scanner (:func:`parse_skill_invocation`).
+- :mod:`.catalog` / :mod:`.matcher` — the normalized model catalog over the
+  framework registry and the scored-candidate matcher
+  (:class:`ModelCatalog` / :class:`ModelMatcher` / :func:`canonical_id` /
+  :func:`to_card_ref`).
+- :mod:`.transcript_store` / :mod:`.serialize` — the branchable transcript
+  tree store, NDJSON envelope + the one app-wide message⇄dict codec, and the
+  legacy framework-session import (:class:`TranscriptStore` /
+  :func:`memory_backend` / :func:`fs_backend` / :func:`replay` /
+  :func:`message_to_dict` / :func:`message_from_dict`).
+
+M2 wave-2 surface (landed):
+
+- :mod:`.conductor` — the :class:`SessionConductorImpl` turn loop +
+  :func:`create_session_conductor` factory (queue drain, transient-fault
+  retry with injectable sleep, per-message persist tail, condense seam,
+  fork/navigate, ``execute_bash`` on asyncio subprocess, thinking ladder,
+  :func:`noop_condense`, :class:`ConductorDeps`, :data:`DEFAULT_RETRY`, and
+  the lazy live-agent assembly :class:`LazyAgent`).
+"""
+
+from __future__ import annotations
+
+from .contract import (
+    FAULT_KINDS,
+    QUEUE_MODES,
+    SIGNAL_KINDS,
+    TRANSCRIPT_ROLES,
+    TRANSCRIPT_SCHEMA,
+    AgentLike,
+    AgentMessage,
+    AgentStateLike,
+    AgentTool,
+    BashOutcome,
+    CompactedSignal,
+    CondenseFn,
+    ConductorFault,
+    ConductorPhase,
+    ConductorState,
+    ExecuteBashOptions,
+    FaultAction,
+    FaultKind,
+    FaultSignal,
+    HeadAction,
+    IdleSignal,
+    KnownProvider,
+    MatchQuery,
+    Model,
+    ModelAction,
+    ModelCardRef,
+    PersistedSignal,
+    PhaseAction,
+    PromptSignal,
+    QueuedInput,
+    QueueMode,
+    QueueSignal,
+    RetryPolicy,
+    SessionConductor,
+    SessionConductorOptions,
+    SessionHead,
+    SessionSignal,
+    SessionStats,
+    SettledAction,
+    SignalHandler,
+    SignalKind,
+    StateAction,
+    TextSignal,
+    ThinkingLevel,
+    ThinkingSignal,
+    TokenTally,
+    ToolEndSignal,
+    ToolStartSignal,
+    TranscriptEntry,
+    TranscriptRole,
+    TranscriptSchema,
+    TurnEndSignal,
+    Usage,
+    UsageAction,
+    conductor_fault,
+    reduce_state,
+)
+from .catalog import (
+    CatalogCard,
+    CatalogSource,
+    ModelCatalog,
+    canonical_id,
+    to_card_ref,
+)
+from .conductor import (
+    DEFAULT_RETRY,
+    ConductorDeps,
+    LazyAgent,
+    SessionConductorImpl,
+    create_session_conductor,
+    noop_condense,
+)
+from .matcher import ModelMatcher, ResolveInput
+from .serialize import (
+    ParsedSessionFile,
+    branch_to_llm_messages,
+    branch_to_messages,
+    encode_entry,
+    encode_head,
+    import_legacy_file,
+    import_legacy_text,
+    message_from_dict,
+    message_to_dict,
+    parse_session_text,
+    resolve_legacy_messages,
+    role_for_message,
+)
+from .signal_hub import TRANSLATOR_TABLE, SignalHub, translate_agent_event
+from .skill_parse import SkillInvocation, parse_skill_invocation
+from .transcript_store import (
+    TranscriptBackend,
+    TranscriptClock,
+    TranscriptState,
+    TranscriptStore,
+    fs_backend,
+    memory_backend,
+    replay,
+)
+
+__all__ = [
+    "AgentLike",
+    "AgentMessage",
+    "AgentStateLike",
+    "AgentTool",
+    "BashOutcome",
+    "CatalogCard",
+    "CatalogSource",
+    "CompactedSignal",
+    "CondenseFn",
+    "ConductorDeps",
+    "ConductorFault",
+    "ConductorPhase",
+    "ConductorState",
+    "DEFAULT_RETRY",
+    "ExecuteBashOptions",
+    "FAULT_KINDS",
+    "FaultAction",
+    "FaultKind",
+    "FaultSignal",
+    "HeadAction",
+    "IdleSignal",
+    "KnownProvider",
+    "LazyAgent",
+    "MatchQuery",
+    "Model",
+    "ModelAction",
+    "ModelCardRef",
+    "ModelCatalog",
+    "ModelMatcher",
+    "ParsedSessionFile",
+    "PersistedSignal",
+    "PhaseAction",
+    "PromptSignal",
+    "QUEUE_MODES",
+    "QueueMode",
+    "QueueSignal",
+    "QueuedInput",
+    "ResolveInput",
+    "RetryPolicy",
+    "SIGNAL_KINDS",
+    "SessionConductor",
+    "SessionConductorImpl",
+    "SessionConductorOptions",
+    "SessionHead",
+    "SessionSignal",
+    "SessionStats",
+    "SettledAction",
+    "SignalHandler",
+    "SignalHub",
+    "SignalKind",
+    "SkillInvocation",
+    "StateAction",
+    "TRANSCRIPT_ROLES",
+    "TRANSCRIPT_SCHEMA",
+    "TRANSLATOR_TABLE",
+    "TextSignal",
+    "ThinkingLevel",
+    "ThinkingSignal",
+    "TokenTally",
+    "ToolEndSignal",
+    "ToolStartSignal",
+    "TranscriptBackend",
+    "TranscriptClock",
+    "TranscriptEntry",
+    "TranscriptRole",
+    "TranscriptSchema",
+    "TranscriptState",
+    "TranscriptStore",
+    "TurnEndSignal",
+    "Usage",
+    "UsageAction",
+    "branch_to_llm_messages",
+    "branch_to_messages",
+    "canonical_id",
+    "conductor_fault",
+    "create_session_conductor",
+    "encode_entry",
+    "encode_head",
+    "fs_backend",
+    "import_legacy_file",
+    "import_legacy_text",
+    "memory_backend",
+    "message_from_dict",
+    "message_to_dict",
+    "noop_condense",
+    "parse_session_text",
+    "parse_skill_invocation",
+    "reduce_state",
+    "replay",
+    "resolve_legacy_messages",
+    "role_for_message",
+    "to_card_ref",
+    "translate_agent_event",
+]