indusagi-coding-agent 0.2.8 → 0.2.9

package/src/insight/channel.ts

@@ -0,0 +1,88 @@
+/**
+ * Signal channel — the in-memory pipe between the recorder and the sinks.
+ */
+import type { Signal, SignalChannel, SignalEmit, SignalStream } from "./contract.js";
+
+interface Subscriber {
+  buffer: Signal[];
+  waiter: ((value: { value: Signal; done: false } | { value: undefined; done: true }) => void) | null;
+  done: boolean;
+}
+
+export function createChannel(): SignalChannel {
+  const subscribers = new Set<Subscriber>();
+  let closed = false;
+
+  function deliver(sub: Subscriber, signal: Signal): void {
+    if (sub.waiter !== null) {
+      const resolve = sub.waiter;
+      sub.waiter = null;
+      resolve({ value: signal, done: false });
+    } else {
+      sub.buffer.push(signal);
+    }
+  }
+
+  const emit: SignalEmit = (signal) => {
+    if (closed) return;
+    for (const sub of subscribers) {
+      deliver(sub, signal);
+    }
+  };
+
+  function close(): void {
+    if (closed) return;
+    closed = true;
+    for (const sub of subscribers) {
+      sub.done = true;
+      if (sub.waiter !== null && sub.buffer.length === 0) {
+        const resolve = sub.waiter;
+        sub.waiter = null;
+        resolve({ value: undefined, done: true });
+      }
+    }
+  }
+
+  function stream(): SignalStream {
+    const sub: Subscriber = { buffer: [], waiter: null, done: closed };
+    subscribers.add(sub);
+    const iterator = {
+      next(): Promise<{ value: Signal; done: false } | { value: undefined; done: true }> {
+        const buffered = sub.buffer.shift();
+        if (buffered !== undefined) {
+          return Promise.resolve({ value: buffered, done: false });
+        }
+        if (sub.done) {
+          subscribers.delete(sub);
+          return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve) => {
+          sub.waiter = resolve;
+        });
+      },
+      return(): Promise<{ value: undefined; done: true }> {
+        subscribers.delete(sub);
+        sub.waiter = null;
+        sub.buffer.length = 0;
+        return Promise.resolve({ value: undefined, done: true });
+      },
+    };
+    return {
+      [Symbol.asyncIterator]() {
+        return iterator;
+      },
+    };
+  }
+
+  return {
+    emit,
+    stream,
+    get size(): number {
+      return subscribers.size;
+    },
+    get closed(): boolean {
+      return closed;
+    },
+    close,
+  };
+}

package/src/insight/contract.ts

@@ -0,0 +1,185 @@
+/**
+ * Insight contract — the FROZEN type surface of the unified tracing system.
+ */
+
+export type TrailId = string & { readonly __brand: "TrailId" };
+export type ProbeId = string & { readonly __brand: "ProbeId" };
+
+export const ID_WIDTHS = {
+  trail: 16,
+  probe: 8,
+} as const;
+
+export function asTrailId(raw: string): TrailId {
+  return raw as TrailId;
+}
+
+export function asProbeId(raw: string): ProbeId {
+  return raw as ProbeId;
+}
+
+export type ProbeKind = "run" | "turn" | "tool" | "model" | "custom";
+
+export const PROBE_KINDS: readonly ProbeKind[] = ["run", "turn", "tool", "model", "custom"];
+
+export type ProbeStatus = "open" | "ok" | "error";
+export type ProbeOutcome = "ok" | "error";
+
+export interface ProbeFault {
+  readonly message: string;
+  readonly name?: string;
+  readonly stack?: string;
+}
+
+export type ProbeAttributes = Readonly<Record<string, unknown>>;
+
+export interface Probe {
+  readonly id: ProbeId;
+  readonly trailId: TrailId;
+  readonly parentId: ProbeId | null;
+  readonly kind: ProbeKind;
+  readonly name: string;
+  readonly startedAt: number;
+  readonly endedAt?: number;
+  readonly status: ProbeStatus;
+  readonly attributes: ProbeAttributes;
+  readonly fault?: ProbeFault;
+}
+
+export interface ClosedProbe extends Probe {
+  readonly endedAt: number;
+  readonly status: ProbeOutcome;
+}
+
+export function isClosedProbe(probe: Probe): probe is ClosedProbe {
+  return probe.status !== "open" && typeof probe.endedAt === "number";
+}
+
+export interface ProbeHandle {
+  readonly trailId: TrailId;
+  readonly id: ProbeId;
+  readonly sampled: boolean;
+  note(attributes: ProbeAttributes): void;
+  child(kind: ProbeKind, name: string, attributes?: ProbeAttributes): ProbeHandle;
+  fail(error: unknown): void;
+  close(outcome?: ProbeOutcome): void;
+}
+
+export const NOOP_HANDLE: ProbeHandle = Object.freeze({
+  trailId: "" as TrailId,
+  id: "" as ProbeId,
+  sampled: false,
+  note(): void {
+    /* no-op */
+  },
+  child(): ProbeHandle {
+    return NOOP_HANDLE;
+  },
+  fail(): void {
+    /* no-op */
+  },
+  close(): void {
+    /* no-op */
+  },
+});
+
+export type SignalPhase = "open" | "update" | "close";
+
+export interface OpenSignal {
+  readonly phase: "open";
+  readonly probe: Probe;
+  readonly at: number;
+}
+
+export interface UpdateSignal {
+  readonly phase: "update";
+  readonly probe: Probe;
+  readonly at: number;
+}
+
+export interface CloseSignal {
+  readonly phase: "close";
+  readonly probe: ClosedProbe;
+  readonly at: number;
+}
+
+export type Signal = OpenSignal | UpdateSignal | CloseSignal;
+
+export function isCloseSignal(signal: Signal): signal is CloseSignal {
+  return signal.phase === "close";
+}
+
+export type SignalEmit = (signal: Signal) => void;
+
+export interface SampleGate {
+  admit(rootName: string): boolean;
+}
+
+export interface FixedGates {
+  readonly always: SampleGate;
+  readonly never: SampleGate;
+}
+
+export type SignalStream = AsyncIterable<Signal>;
+
+export interface Sink {
+  readonly id: string;
+  drain(stream: SignalStream): Promise<void>;
+}
+
+export interface OpenTrailInput {
+  readonly name: string;
+  readonly kind?: ProbeKind;
+  readonly trailId?: TrailId;
+  readonly attributes?: ProbeAttributes;
+}
+
+export interface Recorder {
+  readonly service: string;
+  readonly enabled: boolean;
+  openTrail(input: OpenTrailInput): ProbeHandle;
+  scope(trailId: TrailId): TrailRecorder;
+  flush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+export interface TrailRecorder {
+  readonly trailId: TrailId;
+  readonly sampled: boolean;
+  open(kind: ProbeKind, name: string, attributes?: ProbeAttributes): ProbeHandle;
+  child(parentId: ProbeId, kind: ProbeKind, name: string, attributes?: ProbeAttributes): ProbeHandle;
+}
+
+export const REDACTED_TOKEN = "[insight:scrubbed]" as const;
+export type RedactedToken = typeof REDACTED_TOKEN;
+
+export interface RedactionRule {
+  readonly id: string;
+  readonly key?: string | RegExp;
+  readonly value?: RegExp;
+}
+
+export interface RedactionOptions {
+  readonly maxStringLength?: number;
+  readonly omitKeys?: readonly string[];
+}
+
+export interface SecretRedactor {
+  readonly rules: readonly RedactionRule[];
+  scrubValue(value: unknown): unknown;
+  scrubAttributes(attributes: ProbeAttributes): ProbeAttributes;
+  scrub(probe: Probe): Probe;
+}
+
+export const PASSTHRU_REDACTOR: SecretRedactor = Object.freeze({
+  rules: Object.freeze([]),
+  scrubValue(value: unknown): unknown {
+    return value;
+  },
+  scrubAttributes(attributes: ProbeAttributes): ProbeAttributes {
+    return attributes;
+  },
+  scrub(probe: Probe): Probe {
+    return probe;
+  },
+});

package/src/insight/index.ts

@@ -0,0 +1,110 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Insight subsystem — public barrel.
+ *
+ * `insight/` is the agent's single observability plane. It re-exports the FROZEN
+ * contract: the id model ({@link TrailId} / {@link ProbeId}), the immutable
+ * {@link Probe} value and its functional {@link ProbeHandle} (with the shared
+ * sampled-out {@link NOOP_HANDLE}), the wire {@link Signal} union, the
+ * {@link SampleGate} admission contract, the {@link Sink} drain interface, the
+ * {@link Recorder} / {@link TrailRecorder} facades, and the
+ * {@link SecretRedactor} attribute processor (with its {@link REDACTED_TOKEN}).
+ *
+ * Behaviour modules (the recorder, the flush buffer, the console / file / stream
+ * sinks, the redactor implementation, the agent and stream bridges, the session
+ * rehydrator, the ledger, and the dashboard panel) are added to this barrel as
+ * they land; consumers import the insight surface from `src/insight` rather than
+ * reaching into individual modules.
+ */
+export type {
+  TrailId,
+  ProbeId,
+  ProbeKind,
+  ProbeStatus,
+  ProbeOutcome,
+  ProbeFault,
+  ProbeAttributes,
+  Probe,
+  ClosedProbe,
+  ProbeHandle,
+  SignalPhase,
+  OpenSignal,
+  UpdateSignal,
+  CloseSignal,
+  Signal,
+  SignalEmit,
+  SampleGate,
+  FixedGates,
+  SignalStream,
+  Sink,
+  OpenTrailInput,
+  Recorder,
+  TrailRecorder,
+  RedactedToken,
+  RedactionRule,
+  RedactionOptions,
+  SecretRedactor,
+} from "./contract.js";
+export {
+  ID_WIDTHS,
+  asTrailId,
+  asProbeId,
+  PROBE_KINDS,
+  isClosedProbe,
+  NOOP_HANDLE,
+  isCloseSignal,
+  REDACTED_TOKEN,
+  PASSTHRU_REDACTOR,
+} from "./contract.js";
+export {
+  alwaysGate,
+  neverGate,
+  ratioGate,
+  isRatioGate,
+  hash32,
+  trailScore,
+  FIXED_GATES,
+  type RatioGate,
+} from "./sampling.js";
+export { createChannel, type SignalChannel } from "./channel.js";
+export {
+  createRecorder,
+  mintTrailId,
+  mintProbeId,
+  faultOf,
+  type RecorderOptions,
+  type InsightRecorder,
+} from "./recorder.js";
+export { createRedactor, DEFAULT_REDACTOR, DEFAULT_REDACTION_RULES } from "./redaction.js";
+export {
+  encodeRecord,
+  decodeRecord,
+  signalToRecord,
+  recordIsClose,
+  RECORD_VERSION,
+  LINE_FEED,
+  type TraceRecord,
+} from "./serialize.js";
+export {
+  createConsoleSink,
+  createFileSink,
+  createStreamSink,
+  createCollectorSink,
+  type ConsoleSinkOptions,
+  type LineWriter,
+  type FileSinkOptions,
+  type StreamSinkOptions,
+  type SignalWriter,
+  type CollectorSink,
+} from "./sinks/index.js";
+export {
+  readLines,
+  readRecords,
+  replaySignals,
+  replayProbes,
+  replayTrails,
+  type ChunkSource,
+  type ReplayOptions,
+  type ReplayedTrail,
+} from "./replay.js";

package/src/insight/recorder.ts

@@ -0,0 +1,213 @@
+/**
+ * Recorder — the trail/probe factory at the head of the pipeline.
+ */
+import { randomBytes } from "node:crypto";
+import { createChannel, type SignalChannel } from "./channel.js";
+import {
+  asProbeId,
+  asTrailId,
+  ID_WIDTHS,
+  NOOP_HANDLE,
+  PASSTHRU_REDACTOR,
+  type OpenTrailInput,
+  type Probe,
+  type ProbeAttributes,
+  type ProbeFault,
+  type ProbeHandle,
+  type ProbeId,
+  type ProbeKind,
+  type ProbeOutcome,
+  type Recorder,
+  type SampleGate,
+  type SecretRedactor,
+  type Signal,
+  type Sink,
+  type TrailId,
+  type TrailRecorder,
+} from "./contract.js";
+import { alwaysGate, isRatioGate, neverGate } from "./sampling.js";
+
+export function mintTrailId(): TrailId {
+  return asTrailId(randomBytes(ID_WIDTHS.trail).toString("hex"));
+}
+
+export function mintProbeId(): ProbeId {
+  return asProbeId(randomBytes(ID_WIDTHS.probe).toString("hex"));
+}
+
+export interface RecorderOptions {
+  readonly service?: string;
+  readonly enabled?: boolean;
+  readonly gate?: SampleGate;
+  readonly redactor?: SecretRedactor;
+  readonly sinks?: readonly Sink[];
+  readonly now?: () => number;
+}
+
+export interface InsightRecorder extends Recorder {
+  readonly channel: SignalChannel;
+}
+
+export function faultOf(error: unknown): ProbeFault {
+  if (error instanceof Error) {
+    const fault: { message: string; name?: string; stack?: string } = {
+      message: error.message,
+      name: error.name,
+    };
+    if (typeof error.stack === "string") {
+      fault.stack = error.stack;
+    }
+    return Object.freeze(fault);
+  }
+  return Object.freeze({ message: String(error) });
+}
+
+export function createRecorder(options: RecorderOptions = {}): InsightRecorder {
+  const service = options.service ?? "insight";
+  const enabled = options.enabled ?? true;
+  const gate: SampleGate = enabled ? options.gate ?? alwaysGate : neverGate;
+  const redactor = options.redactor ?? PASSTHRU_REDACTOR;
+  const now = options.now ?? Date.now;
+  const channel = createChannel();
+  const drains: Promise<void>[] = [];
+  for (const sink of options.sinks ?? []) {
+    drains.push(sink.drain(channel.stream()));
+  }
+
+  const route = (signal: Signal): void => {
+    const scrubbed = redactor.scrub(signal.probe);
+    if (scrubbed === signal.probe) {
+      channel.emit(signal);
+      return;
+    }
+    if (signal.phase === "close") {
+      channel.emit({
+        phase: "close",
+        probe: scrubbed as Probe & { endedAt: number; status: ProbeOutcome },
+        at: signal.at,
+      });
+    } else {
+      channel.emit({ phase: signal.phase, probe: scrubbed, at: signal.at });
+    }
+  };
+
+  function admit(trailId: TrailId, rootName: string): boolean {
+    if (!enabled) return false;
+    if (isRatioGate(gate)) return gate.verdict(trailId);
+    return gate.admit(rootName);
+  }
+
+  function openProbe(
+    trailId: TrailId,
+    parentId: ProbeId | null,
+    kind: ProbeKind,
+    name: string,
+    attributes: ProbeAttributes,
+  ): ProbeHandle {
+    const id = mintProbeId();
+    const startedAt = now();
+    interface Cell {
+      probe: Probe;
+      closed: boolean;
+    }
+    const cell: Cell = {
+      probe: Object.freeze({
+        id,
+        trailId,
+        parentId,
+        kind,
+        name,
+        startedAt,
+        status: "open" as const,
+        attributes: Object.freeze({ ...attributes }),
+      }),
+      closed: false,
+    };
+    route({ phase: "open", probe: cell.probe, at: startedAt });
+    const handle: ProbeHandle = {
+      trailId,
+      id,
+      sampled: true,
+      note(extra: ProbeAttributes): void {
+        if (cell.closed) return;
+        cell.probe = Object.freeze({
+          ...cell.probe,
+          attributes: Object.freeze({ ...cell.probe.attributes, ...extra }),
+        });
+        route({ phase: "update", probe: cell.probe, at: now() });
+      },
+      child(childKind: ProbeKind, childName: string, childAttrs: ProbeAttributes = {}): ProbeHandle {
+        if (cell.closed) return NOOP_HANDLE;
+        return openProbe(trailId, id, childKind, childName, childAttrs);
+      },
+      fail(error: unknown): void {
+        if (cell.closed) return;
+        cell.probe = Object.freeze({
+          ...cell.probe,
+          status: "error" as const,
+          fault: faultOf(error),
+        });
+        route({ phase: "update", probe: cell.probe, at: now() });
+      },
+      close(outcome?: ProbeOutcome): void {
+        if (cell.closed) return;
+        cell.closed = true;
+        const endedAt = now();
+        const status: ProbeOutcome =
+          outcome ?? (cell.probe.status === "error" ? "error" : "ok");
+        const closed = Object.freeze({
+          ...cell.probe,
+          endedAt,
+          status,
+        });
+        cell.probe = closed;
+        route({ phase: "close", probe: closed, at: endedAt });
+      },
+    };
+    return handle;
+  }
+
+  function openTrail(input: OpenTrailInput): ProbeHandle {
+    const trailId = input.trailId ?? mintTrailId();
+    if (!admit(trailId, input.name)) {
+      return NOOP_HANDLE;
+    }
+    return openProbe(trailId, null, input.kind ?? "run", input.name, input.attributes ?? {});
+  }
+
+  function scope(trailId: TrailId): TrailRecorder {
+    const sampled = admit(trailId, service);
+    return {
+      trailId,
+      sampled,
+      open(kind: ProbeKind, name: string, attrs: ProbeAttributes = {}): ProbeHandle {
+        if (!sampled) return NOOP_HANDLE;
+        return openProbe(trailId, null, kind, name, attrs);
+      },
+      child(parentId: ProbeId, kind: ProbeKind, name: string, attrs: ProbeAttributes = {}): ProbeHandle {
+        if (!sampled) return NOOP_HANDLE;
+        return openProbe(trailId, parentId, kind, name, attrs);
+      },
+    };
+  }
+
+  async function flush(): Promise<void> {
+    await Promise.resolve();
+  }
+
+  async function shutdown(): Promise<void> {
+    await flush();
+    channel.close();
+    await Promise.allSettled(drains);
+  }
+
+  return {
+    service,
+    enabled,
+    channel,
+    openTrail,
+    scope,
+    flush,
+    shutdown,
+  };
+}