induscode 0.1.0__py3-none-any.whl

induscode/entry.py

@@ -0,0 +1,108 @@
+"""Process entry point — the console script ``pindus`` / ``induscode``
+launches (port of TS ``src/entry.ts``).
+
+Responsibilities, in order:
+
+1. Install exactly one logging filter that suppresses the transport-layer
+   ``[MCP]`` noise the MCP stack emits (unless the brand's debug env var is
+   set, in which case nothing is filtered).
+2. Hand the sliced ``argv`` to :func:`induscode.boot.boot` and adopt its
+   resolved exit code.
+
+Port notes
+----------
+- The TS entry set ``process.title`` to the primary bin name; Python has no
+  portable process titling without a third-party dependency
+  (``setproctitle``), so it is deliberately skipped (same decision as the
+  framework port).
+- The TS ``import.meta`` program-entry guard (so importing the module does
+  not boot) is the console-script boundary here: importing
+  :mod:`induscode.entry` runs nothing; only the ``[project.scripts]`` shim
+  :func:`run` boots.
+- The TS console filter wrapped ``console.log`` / ``console.error``; the
+  Python entry installs a :class:`logging.Filter` on the root logger instead
+  (no monkey-patching). Stream-level chatter during ``--mcp`` connects is
+  scope-silenced by the session assembly
+  (:mod:`induscode.boot.runners.session`).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+from collections.abc import Sequence
+from typing import Final
+
+from induscode.workspace import BRAND
+
+__all__ = ["main", "run"]
+
+#: Substring marking a transport-layer MCP log line we filter from the logs.
+_MCP_NOISE_MARKER: Final[str] = "[MCP]"
+
+
+class _McpNoiseFilter(logging.Filter):
+    """Drops any log record whose rendered message carries the
+    :data:`_MCP_NOISE_MARKER`, keeping the user's terminal clean of MCP
+    transport chatter."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        try:
+            return _MCP_NOISE_MARKER not in record.getMessage()
+        except Exception:
+            return True
+
+
+#: One-shot guard so repeated calls (or a re-import) install the filter once.
+_noise_filter_installed: bool = False
+
+
+def _install_mcp_noise_filter() -> None:
+    """Install the single, idempotent ``[MCP]`` log-noise filter on the root
+    logger. When the brand's debug env var is set the install is a no-op
+    (everything passes), so diagnostics are never hidden during debugging."""
+    global _noise_filter_installed
+    if _noise_filter_installed:
+        return
+    _noise_filter_installed = True
+
+    if os.environ.get(BRAND.env_debug):
+        return
+    logging.getLogger().addFilter(_McpNoiseFilter())
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Process-level entry. Returns the exit code instead of raising
+    ``SystemExit`` so tests can call it directly.
+
+    :param argv: the already-sliced argument vector; defaults to
+        ``sys.argv[1:]``
+    """
+    args = list(argv) if argv is not None else sys.argv[1:]
+    _install_mcp_noise_filter()
+
+    # Imported here (not at module top) so `import induscode.entry` stays
+    # side-effect-light; the boot package pulls in the full launch surface.
+    from induscode.boot import boot
+
+    return asyncio.run(boot(args))
+
+
+def run() -> None:
+    """The ``[project.scripts]`` shim — translate :func:`main` into an exit.
+
+    A ``BrokenPipeError`` (the reader of our stdout — e.g. ``| head`` — went
+    away) is treated as a clean early-terminated run, matching the Node
+    entry's silent-EPIPE behavior: stdout is parked on ``/dev/null`` so the
+    interpreter's shutdown flush cannot re-raise, and the process exits 0.
+    """
+    try:
+        code = main()
+        sys.stdout.flush()
+    except BrokenPipeError:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        code = 0
+    sys.exit(code)

induscode/insight/__init__.py

@@ -0,0 +1,153 @@
+"""Insight subsystem — public barrel.
+
+``insight/`` is the agent's single observability plane, built as a **thin
+wrapper over** ``indusagi.tracing`` (locked plan decision; analysis 05 §3) —
+not a re-port of the 2.5k-LOC TS subsystem. Three modules:
+
+- :mod:`~induscode.insight.wrapper` — the app vocabulary aliased onto the
+  framework: ``Probe``/``ProbeHandle``/``Signal`` over ``Segment``/
+  ``SegmentHandle``/``TraceSignal`` (kind map ``turn→inference``,
+  ``tool→action``, ``model→recall``), :func:`create_recorder` with an
+  injectable clock, the framework-delegating sampling gates (FNV-1a parity
+  verified), and the ``SecretScrubber``-backed redactor pinned to the app
+  token ``"[insight:scrubbed]"`` and the 4096-char cap;
+- :mod:`~induscode.insight.collector` — the in-memory collector sink the
+  framework lacks (ported);
+- :mod:`~induscode.insight.replay` — NDJSON replay readers over the
+  *framework's* record schema (ported; the framework has no reader).
+
+The framework transport and terminal sinks are re-exported here unchanged
+(``SignalChannel``, ``Sink``, ``ConsoleSink``, ``FileSink``, ``StreamSink``)
+so consumers import the whole insight surface from :mod:`induscode.insight`
+rather than reaching into ``indusagi.tracing`` or individual modules.
+"""
+
+from indusagi.tracing.channel.signal import SignalChannel
+from indusagi.tracing.redaction.secret_scrubber import SecretPattern
+from indusagi.tracing.sinks import (
+    ConsoleSink,
+    ConsoleSinkOptions,
+    FileSink,
+    FileSinkOptions,
+    Sink,
+    StreamSink,
+    StreamSinkOptions,
+)
+
+from .collector import CollectorSink, create_collector_sink
+from .replay import (
+    ChunkSource,
+    ReplayedTrail,
+    decode_record,
+    read_lines,
+    read_records,
+    record_to_probe,
+    replay_probes,
+    replay_signals,
+    replay_trails,
+)
+from .wrapper import (
+    APP_SECRET_PATTERNS,
+    DEFAULT_MAX_STRING_LENGTH,
+    DEFAULT_REDACTOR,
+    ID_WIDTHS,
+    KIND_TO_SEGMENT,
+    NOOP_HANDLE,
+    PASSTHRU_REDACTOR,
+    PROBE_KINDS,
+    REDACTED_TOKEN,
+    SEGMENT_TO_KIND,
+    TRUNCATION_SUFFIX,
+    CloseSignal,
+    InsightRecorder,
+    OpenSignal,
+    Probe,
+    ProbeAttributes,
+    ProbeFault,
+    ProbeHandle,
+    ProbeId,
+    ProbeKind,
+    ProbeOutcome,
+    ProbeStatus,
+    RatioGate,
+    SecretRedactor,
+    Signal,
+    SignalPhase,
+    TrailId,
+    TrailRecorder,
+    UpdateSignal,
+    always_gate,
+    create_recorder,
+    create_redactor,
+    fault_of,
+    is_close_signal,
+    is_closed_probe,
+    mint_probe_id,
+    mint_trail_id,
+    never_gate,
+    probe_from_segment,
+    ratio_gate,
+)
+
+__all__ = [
+    "APP_SECRET_PATTERNS",
+    "ChunkSource",
+    "CloseSignal",
+    "CollectorSink",
+    "ConsoleSink",
+    "ConsoleSinkOptions",
+    "DEFAULT_MAX_STRING_LENGTH",
+    "DEFAULT_REDACTOR",
+    "FileSink",
+    "FileSinkOptions",
+    "ID_WIDTHS",
+    "InsightRecorder",
+    "KIND_TO_SEGMENT",
+    "NOOP_HANDLE",
+    "OpenSignal",
+    "PASSTHRU_REDACTOR",
+    "PROBE_KINDS",
+    "Probe",
+    "ProbeAttributes",
+    "ProbeFault",
+    "ProbeHandle",
+    "ProbeId",
+    "ProbeKind",
+    "ProbeOutcome",
+    "ProbeStatus",
+    "REDACTED_TOKEN",
+    "RatioGate",
+    "ReplayedTrail",
+    "SEGMENT_TO_KIND",
+    "SecretPattern",
+    "SecretRedactor",
+    "Signal",
+    "SignalChannel",
+    "SignalPhase",
+    "Sink",
+    "StreamSink",
+    "StreamSinkOptions",
+    "TRUNCATION_SUFFIX",
+    "TrailId",
+    "TrailRecorder",
+    "UpdateSignal",
+    "always_gate",
+    "create_collector_sink",
+    "create_recorder",
+    "create_redactor",
+    "decode_record",
+    "fault_of",
+    "is_close_signal",
+    "is_closed_probe",
+    "mint_probe_id",
+    "mint_trail_id",
+    "never_gate",
+    "probe_from_segment",
+    "ratio_gate",
+    "read_lines",
+    "read_records",
+    "record_to_probe",
+    "replay_probes",
+    "replay_signals",
+    "replay_trails",
+]

induscode/insight/collector.py

@@ -0,0 +1,73 @@
+"""Collector sink — the in-memory test/inspection sink.
+
+Ported from the TS ``sinks/stream.ts`` ``createCollectorSink`` because the
+framework ships console/file/stream sinks but **no collector**. It is a
+regular framework :class:`~indusagi.tracing.sinks.base.Sink`: it drains a
+framework ``SignalChannel`` and appends **every** signal (open / update /
+close — unlike the file and stream sinks, which persist closes only) to an
+in-memory list, in arrival order.
+
+What it stores are the raw framework ``TraceSignal`` values that rode the
+channel; :attr:`CollectorSink.close_records` and :meth:`CollectorSink.probes`
+offer the cooked views (terminal records, and app-vocabulary
+:class:`~induscode.insight.wrapper.Probe` values) most tests want.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from indusagi.tracing.channel.signal import CloseSignal as FwCloseSignal, TraceSignal
+from indusagi.tracing.signal.segment import TraceRecord
+from indusagi.tracing.sinks.base import Sink
+
+from .wrapper import Probe, probe_from_segment
+
+if TYPE_CHECKING:
+    from indusagi.tracing.channel.signal import SignalChannel
+
+__all__ = [
+    "CollectorSink",
+    "create_collector_sink",
+]
+
+
+class CollectorSink(Sink):
+    """A :class:`Sink` that accumulates every drained signal in memory.
+
+    The handiest sink for tests and one-shot inspection: drain a recorder's
+    channel through it, then read :attr:`signals`.
+    """
+
+    __slots__ = ("id", "_signals")
+
+    def __init__(self, id: str = "collector") -> None:
+        # A short identifier used in diagnostics (TS Sink.id).
+        self.id = id
+        self._signals: list[TraceSignal] = []
+
+    @property
+    def signals(self) -> tuple[TraceSignal, ...]:
+        """Every signal drained so far, in arrival order."""
+        return tuple(self._signals)
+
+    @property
+    def close_records(self) -> tuple[TraceRecord, ...]:
+        """The terminal records carried by the drained close signals."""
+        return tuple(
+            signal.record for signal in self._signals if isinstance(signal, FwCloseSignal)
+        )
+
+    def probes(self) -> tuple[Probe, ...]:
+        """App-vocabulary probe views of the drained close records."""
+        return tuple(probe_from_segment(record) for record in self.close_records)
+
+    async def drain(self, channel: "SignalChannel") -> None:
+        """Pull every signal from ``channel`` into the in-memory list."""
+        async for signal in channel:
+            self._signals.append(signal)
+
+
+def create_collector_sink(id: str = "collector") -> CollectorSink:
+    """Build an in-memory :class:`CollectorSink` (TS ``createCollectorSink``)."""
+    return CollectorSink(id)

induscode/insight/replay.py

@@ -0,0 +1,305 @@
+"""Replay — read an NDJSON trace file back into probes and trails.
+
+The framework has ``TraceRecord`` (the terminal segment value its sinks
+persist) but **no reader**; this module ports the TS ``replay.ts`` readers
+against the **framework's record schema** rather than the TS one.
+
+**Schema choice (documented per plan risk 4).** This is a fresh ecosystem —
+no TS-era NDJSON files will ever be read — so the wire format is whatever the
+framework ``FileSink``/``StreamSink`` actually write
+(``indusagi.tracing.sinks.base._record_to_json``): one flat camelCase JSON
+object per line carrying the terminal record fields directly::
+
+    {"id": "...", "traceId": "...", "parentId": null, "kind": "action",
+     "name": "...", "startedAt": 1001, "endedAt": 1002, "status": "ok",
+     "attributes": {...}, "error": {"message": "..."}?}
+
+Differences from the TS ``serialize.ts`` schema, accepted by the locked
+wrapper decision:
+
+- there is **no envelope** — no ``v`` version stamp, no ``phase``, no ``at``
+  emission clock; the record *is* the probe;
+- only **close** signals are persisted (the framework sinks skip
+  ``open``/``update`` chatter), so a healthy trace replays as terminal
+  probes; :func:`replay_signals` derives the phase from the record itself
+  (terminal → ``close`` at ``endedAt``, otherwise ``open`` at ``startedAt``)
+  so a foreign writer that persists open records still replays;
+- kinds on disk are **framework** kinds (``inference``/``action``/``recall``);
+  the readers map them back to the app vocabulary (``turn``/``tool``/``model``).
+
+As in TS, a malformed line is skipped rather than fatal by default, so a
+trace truncated by a crash still yields everything written before the break.
+"""
+
+from __future__ import annotations
+
+import codecs
+import json
+from collections.abc import AsyncIterable, Iterable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import AsyncIterator, TypeAlias
+
+from .wrapper import (
+    FAULT_NAME_KEY,
+    FAULT_STACK_KEY,
+    SEGMENT_TO_KIND,
+    CloseSignal,
+    OpenSignal,
+    Probe,
+    ProbeFault,
+    ProbeId,
+    Signal,
+    TrailId,
+    _fault_from_record,
+)
+
+__all__ = [
+    "ChunkSource",
+    "ReplayedTrail",
+    "decode_record",
+    "read_lines",
+    "read_records",
+    "record_to_probe",
+    "replay_probes",
+    "replay_signals",
+    "replay_trails",
+]
+
+#: A source of raw text/byte chunks (a file read, stdin, a list of lines).
+ChunkSource: TypeAlias = AsyncIterable[str | bytes] | Iterable[str | bytes]
+
+#: One decoded NDJSON line — a plain dict in the framework's record schema.
+TraceRecordDict: TypeAlias = dict[str, object]
+
+_LINE_FEED = "\n"
+
+# --------------------------------------------------------------------------
+# Line + record decoding
+# --------------------------------------------------------------------------
+
+
+async def _iter_chunks(source: ChunkSource) -> AsyncIterator[str | bytes]:
+    """Iterate a chunk source uniformly, whether sync or async."""
+    if hasattr(source, "__aiter__"):
+        async for chunk in source:  # type: ignore[union-attr]
+            yield chunk
+    else:
+        for chunk in source:  # type: ignore[union-attr]
+            yield chunk
+
+
+async def read_lines(source: ChunkSource) -> AsyncIterator[str]:
+    """Split a chunk source into complete, non-blank text lines.
+
+    Buffers across chunks, splits on ``\\n`` only, reassembles multi-byte
+    runes split across byte chunks, and emits a trailing unterminated line at
+    end-of-stream so a final non-newline frame is not dropped.
+    """
+    decoder = codecs.getincrementaldecoder("utf-8")()
+    buffer = ""
+    async for chunk in _iter_chunks(source):
+        buffer += chunk if isinstance(chunk, str) else decoder.decode(chunk)
+        at = buffer.find(_LINE_FEED)
+        while at != -1:
+            line = buffer[:at]
+            buffer = buffer[at + 1 :]
+            if line.strip():
+                yield line
+            at = buffer.find(_LINE_FEED)
+    buffer += decoder.decode(b"", final=True)
+    if buffer.strip():
+        yield buffer
+
+
+def decode_record(line: str) -> TraceRecordDict:
+    """Parse one NDJSON line into a record dict (the framework schema).
+
+    Raises ``json.JSONDecodeError`` on invalid JSON; callers validate the
+    shape before trusting it (see :func:`read_records`).
+    """
+    return json.loads(line)
+
+
+def _is_valid_record(value: object) -> bool:
+    """Whether a parsed value is a structurally plausible framework record."""
+    if not isinstance(value, dict):
+        return False
+    if not isinstance(value.get("id"), str) or not value["id"]:
+        return False
+    if not isinstance(value.get("traceId"), str) or not value["traceId"]:
+        return False
+    parent = value.get("parentId")
+    if parent is not None and not isinstance(parent, str):
+        return False
+    if value.get("kind") not in SEGMENT_TO_KIND:
+        return False
+    if not isinstance(value.get("name"), str):
+        return False
+    if not isinstance(value.get("startedAt"), (int, float)):
+        return False
+    ended = value.get("endedAt")
+    if ended is not None and not isinstance(ended, (int, float)):
+        return False
+    if value.get("status") not in ("open", "ok", "error"):
+        return False
+    if not isinstance(value.get("attributes"), dict):
+        return False
+    return True
+
+
+async def read_records(
+    source: ChunkSource,
+    *,
+    strict: bool = False,
+) -> AsyncIterator[TraceRecordDict]:
+    """Decode a chunk source into a stream of validated record dicts.
+
+    Malformed JSON or a record failing the shape check is skipped, or
+    rethrown when ``strict``.
+    """
+    async for line in read_lines(source):
+        try:
+            record = decode_record(line)
+        except json.JSONDecodeError:
+            if strict:
+                raise
+            continue
+        if not _is_valid_record(record):
+            if strict:
+                raise ValueError("insight replay: malformed trace record")
+            continue
+        yield record
+
+
+def record_to_probe(record: TraceRecordDict) -> Probe:
+    """Project a validated record dict onto an app-vocabulary :class:`Probe`.
+
+    The fault's error ``name`` and ``stack`` ride the reserved attribute keys
+    the recorder writes at close (the framework's on-disk ``error`` carries only
+    ``message``); they are lifted back onto :attr:`Probe.fault` here and stripped
+    from the exposed attribute bag, so a failed probe round-trips its full fault
+    (message + name + stack) through NDJSON — matching the TS ``TraceRecord``.
+    """
+    attributes = dict(record["attributes"])  # type: ignore[arg-type]
+    error = record.get("error")
+    message: str | None = None
+    if isinstance(error, dict) and isinstance(error.get("message"), str):
+        message = error["message"]
+    fault: ProbeFault | None = _fault_from_record(message, attributes)
+    # Strip the reserved fault keys so name/stack surface only on the fault.
+    attributes.pop(FAULT_NAME_KEY, None)
+    attributes.pop(FAULT_STACK_KEY, None)
+    ended = record.get("endedAt")
+    return Probe(
+        id=record["id"],  # type: ignore[arg-type]
+        trail_id=record["traceId"],  # type: ignore[arg-type]
+        parent_id=record.get("parentId"),  # type: ignore[arg-type]
+        kind=SEGMENT_TO_KIND[record["kind"]],  # type: ignore[index]
+        name=record["name"],  # type: ignore[arg-type]
+        started_at=int(record["startedAt"]),  # type: ignore[arg-type]
+        ended_at=int(ended) if ended is not None else None,  # type: ignore[arg-type]
+        status=record["status"],  # type: ignore[arg-type]
+        attributes=MappingProxyType(attributes),
+        fault=fault,
+    )
+
+
+# --------------------------------------------------------------------------
+# Probe / signal recovery
+# --------------------------------------------------------------------------
+
+
+async def replay_signals(
+    source: ChunkSource,
+    *,
+    strict: bool = False,
+) -> AsyncIterator[Signal]:
+    """Reconstruct the :data:`Signal` stream from a chunk source, in file order.
+
+    The framework schema carries no phase, so it is derived per record: a
+    terminal record (``status`` not ``open`` and a numeric ``endedAt``) yields
+    a :class:`CloseSignal` at ``endedAt``; anything else yields an
+    :class:`OpenSignal` at ``startedAt``.
+    """
+    async for record in read_records(source, strict=strict):
+        probe = record_to_probe(record)
+        if probe.status != "open" and probe.ended_at is not None:
+            yield CloseSignal(probe=probe, at=probe.ended_at)
+        else:
+            yield OpenSignal(probe=probe, at=probe.started_at)
+
+
+async def replay_probes(
+    source: ChunkSource,
+    *,
+    strict: bool = False,
+) -> dict[ProbeId, Probe]:
+    """Collapse a trace into the final value of each probe, keyed by id.
+
+    The last record for an id wins; the returned dict preserves first-seen
+    insertion order (Python dict semantics match the TS ``Map.set`` here).
+    """
+    by_id: dict[ProbeId, Probe] = {}
+    async for record in read_records(source, strict=strict):
+        probe = record_to_probe(record)
+        by_id[probe.id] = probe
+    return by_id
+
+
+# --------------------------------------------------------------------------
+# Trail tree
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ReplayedTrail:
+    """One reconstructed trail: its root probe plus the parent→children index."""
+
+    trail_id: TrailId
+    # The root probe (parent_id is None), or None if the root was never seen.
+    root: Probe | None
+    # Every probe in the trail, keyed by id, in first-seen order.
+    probes: Mapping[ProbeId, Probe]
+    # Child probe ids per parent id; roots are listed under the None key.
+    children: Mapping[ProbeId | None, tuple[ProbeId, ...]]
+    # Whether every probe in the trail reached a terminal state.
+    complete: bool
+
+
+def _build_trail(trail_id: TrailId, probes: dict[ProbeId, Probe]) -> ReplayedTrail:
+    """Assemble one :class:`ReplayedTrail` from its collapsed probe map."""
+    children: dict[ProbeId | None, list[ProbeId]] = {}
+    root: Probe | None = None
+    complete = True
+    for probe in probes.values():
+        children.setdefault(probe.parent_id, []).append(probe.id)
+        if probe.parent_id is None:
+            root = probe
+        if probe.status == "open" or probe.ended_at is None:
+            complete = False
+    return ReplayedTrail(
+        trail_id=trail_id,
+        root=root,
+        probes=MappingProxyType(probes),
+        children=MappingProxyType({k: tuple(v) for k, v in children.items()}),
+        complete=complete,
+    )
+
+
+async def replay_trails(
+    source: ChunkSource,
+    *,
+    strict: bool = False,
+) -> list[ReplayedTrail]:
+    """Group a trace into per-trail trees, in first-probe-seen order.
+
+    Each :class:`ReplayedTrail` carries its probes, a parent→children
+    adjacency map, the located root, and a completeness flag.
+    """
+    probes_by_trail: dict[TrailId, dict[ProbeId, Probe]] = {}
+    for probe in (await replay_probes(source, strict=strict)).values():
+        probes_by_trail.setdefault(probe.trail_id, {})[probe.id] = probe
+    return [
+        _build_trail(trail_id, bucket) for trail_id, bucket in probes_by_trail.items()
+    ]