indusagi-coding-agent 0.2.5 → 0.2.9

package/src/insight/redaction.ts

@@ -0,0 +1,157 @@
+/**
+ * Secret redaction — the attribute processor the pipeline runs before a sink.
+ */
+import {
+  REDACTED_TOKEN,
+  type Probe,
+  type ProbeAttributes,
+  type ProbeFault,
+  type RedactionOptions,
+  type RedactionRule,
+  type SecretRedactor,
+} from "./contract.js";
+
+const SECRET_KEY_FRAGMENTS = [
+  "apikey",
+  "api_key",
+  "secret",
+  "password",
+  "passwd",
+  "authorization",
+  "auth_token",
+  "access_token",
+  "refresh_token",
+  "session_token",
+  "private_key",
+  "credential",
+  "cookie",
+  "set-cookie",
+  "bearer",
+];
+
+const SECRET_KEY_PATTERN = new RegExp(`(${SECRET_KEY_FRAGMENTS.join("|")})`, "i");
+
+const SECRET_VALUE_PATTERNS: RegExp[] = [
+  /\b(?:Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{8,}/g,
+  /\b[a-z]{1,5}-(?:live|test|proj)?[-_]?[A-Za-z0-9]{16,}\b/g,
+  /\b(?:gh[opsu]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g,
+  /\bAKIA[0-9A-Z]{12,}\b/g,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+  /-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?-----END[ A-Z]*PRIVATE KEY-----/g,
+];
+
+export const DEFAULT_REDACTION_RULES: readonly RedactionRule[] = Object.freeze([
+  Object.freeze({ id: "secret-key", key: SECRET_KEY_PATTERN }),
+  ...SECRET_VALUE_PATTERNS.map((value, i) =>
+    Object.freeze({ id: `secret-value-${i + 1}`, value }),
+  ),
+]);
+
+const DEFAULT_MAX_STRING_LENGTH = 4096;
+const TRUNCATION_SUFFIX = "...[insight:truncated]";
+
+function keyMatches(rule: RedactionRule, key: string): boolean {
+  const matcher = rule.key;
+  if (matcher === undefined) return false;
+  if (typeof matcher === "string") {
+    return key.toLowerCase().includes(matcher.toLowerCase());
+  }
+  return matcher.test(key);
+}
+
+function applyValueRules(rules: readonly RedactionRule[], text: string): string {
+  let out = text;
+  for (const rule of rules) {
+    const pattern = rule.value;
+    if (pattern === undefined) continue;
+    if (pattern.global || pattern.sticky) pattern.lastIndex = 0;
+    out = out.replace(pattern, REDACTED_TOKEN);
+  }
+  return out;
+}
+
+export function createRedactor(
+  rules: readonly RedactionRule[] = DEFAULT_REDACTION_RULES,
+  options: RedactionOptions = {},
+): SecretRedactor {
+  const frozenRules = Object.freeze([...rules]);
+  const maxLen = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
+  const omit = new Set((options.omitKeys ?? []).map((k) => k.toLowerCase()));
+
+  function isOmitted(key: string): boolean {
+    return omit.has(key.toLowerCase());
+  }
+
+  function isSecretKey(key: string): boolean {
+    for (const rule of frozenRules) {
+      if (keyMatches(rule, key)) return true;
+    }
+    return false;
+  }
+
+  function capLength(text: string): string {
+    if (text.length <= maxLen) return text;
+    return text.slice(0, maxLen) + TRUNCATION_SUFFIX;
+  }
+
+  function scrubNode(value: unknown, key: string | undefined): unknown {
+    if (key !== undefined && isSecretKey(key)) {
+      return REDACTED_TOKEN;
+    }
+    if (typeof value === "string") {
+      return capLength(applyValueRules(frozenRules, value));
+    }
+    if (Array.isArray(value)) {
+      return Object.freeze(value.map((item) => scrubNode(item, undefined)));
+    }
+    if (value !== null && typeof value === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (isOmitted(k)) continue;
+        out[k] = scrubNode(v, k);
+      }
+      return Object.freeze(out);
+    }
+    return value;
+  }
+
+  function scrubValue(value: unknown): unknown {
+    return scrubNode(value, undefined);
+  }
+
+  function scrubAttributes(attributes: ProbeAttributes): ProbeAttributes {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(attributes)) {
+      if (isOmitted(k)) continue;
+      out[k] = scrubNode(v, k);
+    }
+    return Object.freeze(out);
+  }
+
+  function scrubFault(fault: ProbeFault): ProbeFault {
+    const scrubbed: { message: string; name?: string; stack?: string } = {
+      message: capLength(applyValueRules(frozenRules, fault.message)),
+    };
+    if (fault.name !== undefined) scrubbed.name = fault.name;
+    if (fault.stack !== undefined) scrubbed.stack = capLength(applyValueRules(frozenRules, fault.stack));
+    return Object.freeze(scrubbed);
+  }
+
+  function scrub(probe: Probe): Probe {
+    const next: Probe = {
+      ...probe,
+      attributes: scrubAttributes(probe.attributes),
+      ...(probe.fault !== undefined ? { fault: scrubFault(probe.fault) } : {}),
+    };
+    return Object.freeze(next);
+  }
+
+  return Object.freeze({
+    rules: frozenRules,
+    scrubValue,
+    scrubAttributes,
+    scrub,
+  });
+}
+
+export const DEFAULT_REDACTOR: SecretRedactor = createRedactor();

package/src/insight/replay.ts

@@ -0,0 +1,158 @@
+/**
+ * Replay — read an NDJSON trace file back into probes and trails.
+ */
+import {
+  isClosedProbe,
+  type Probe,
+  type ProbeId,
+  type Signal,
+  type TrailId,
+} from "./contract.js";
+import { decodeRecord, LINE_FEED, RECORD_VERSION, type TraceRecord } from "./serialize.js";
+
+export type ChunkSource = AsyncIterable<string | Uint8Array> | Iterable<string | Uint8Array>;
+
+export interface ReplayOptions {
+  readonly strict?: boolean;
+}
+
+const TEXT_DECODER = new TextDecoder();
+
+function chunkToText(chunk: string | Uint8Array): string {
+  return typeof chunk === "string" ? chunk : TEXT_DECODER.decode(chunk, { stream: true });
+}
+
+export async function* readLines(
+  source: ChunkSource,
+): AsyncGenerator<string, void, unknown> {
+  let buffer = "";
+  for await (const chunk of source) {
+    buffer += chunkToText(chunk);
+    let at = buffer.indexOf(LINE_FEED);
+    while (at !== -1) {
+      const line = buffer.slice(0, at);
+      buffer = buffer.slice(at + 1);
+      if (line.trim().length > 0) yield line;
+      at = buffer.indexOf(LINE_FEED);
+    }
+  }
+  buffer += TEXT_DECODER.decode();
+  if (buffer.trim().length > 0) yield buffer;
+}
+
+function isValidRecord(value: unknown): value is TraceRecord {
+  if (value === null || typeof value !== "object") return false;
+  const r = value as Record<string, unknown>;
+  return (
+    r.v === RECORD_VERSION &&
+    (r.phase === "open" || r.phase === "update" || r.phase === "close") &&
+    typeof r.at === "number" &&
+    r.probe !== null &&
+    typeof r.probe === "object"
+  );
+}
+
+export async function* readRecords(
+  source: ChunkSource,
+  options: ReplayOptions = {},
+): AsyncGenerator<TraceRecord, void, unknown> {
+  for await (const line of readLines(source)) {
+    let record: TraceRecord;
+    try {
+      record = decodeRecord(line);
+    } catch (error) {
+      if (options.strict) throw error;
+      continue;
+    }
+    if (!isValidRecord(record)) {
+      if (options.strict) {
+        throw new Error("insight replay: malformed trace record");
+      }
+      continue;
+    }
+    yield record;
+  }
+}
+
+export async function* replaySignals(
+  source: ChunkSource,
+  options: ReplayOptions = {},
+): AsyncGenerator<Signal, void, unknown> {
+  for await (const record of readRecords(source, options)) {
+    const frozen = Object.freeze({ ...record.probe });
+    if (record.phase === "close") {
+      yield { phase: "close", probe: frozen as Probe & { endedAt: number; status: "ok" | "error" }, at: record.at };
+    } else {
+      yield { phase: record.phase, probe: frozen, at: record.at };
+    }
+  }
+}
+
+export async function replayProbes(
+  source: ChunkSource,
+  options: ReplayOptions = {},
+): Promise<Map<ProbeId, Probe>> {
+  const byId = new Map<ProbeId, Probe>();
+  for await (const record of readRecords(source, options)) {
+    byId.set(record.probe.id, Object.freeze({ ...record.probe }));
+  }
+  return byId;
+}
+
+export interface ReplayedTrail {
+  readonly trailId: TrailId;
+  readonly root: Probe | null;
+  readonly probes: ReadonlyMap<ProbeId, Probe>;
+  readonly children: ReadonlyMap<ProbeId | null, readonly ProbeId[]>;
+  readonly complete: boolean;
+}
+
+async function* finalProbes(
+  source: ChunkSource,
+  options: ReplayOptions,
+): AsyncGenerator<Probe, void, unknown> {
+  const final = await replayProbes(source, options);
+  for (const probe of final.values()) yield probe;
+}
+
+function buildTrail(
+  trailId: TrailId,
+  probes: ReadonlyMap<ProbeId, Probe>,
+): ReplayedTrail {
+  const children = new Map<ProbeId | null, ProbeId[]>();
+  let root: Probe | null = null;
+  let complete = true;
+  for (const probe of probes.values()) {
+    const key = probe.parentId;
+    const bucket = children.get(key);
+    if (bucket === undefined) children.set(key, [probe.id]);
+    else bucket.push(probe.id);
+    if (probe.parentId === null) root = probe;
+    if (!isClosedProbe(probe)) complete = false;
+  }
+  return {
+    trailId,
+    root,
+    probes,
+    children,
+    complete,
+  };
+}
+
+export async function replayTrails(
+  source: ChunkSource,
+  options: ReplayOptions = {},
+): Promise<ReplayedTrail[]> {
+  const probesByTrail = new Map<TrailId, Map<ProbeId, Probe>>();
+  const order: TrailId[] = [];
+  for await (const probe of finalProbes(source, options)) {
+    let bucket = probesByTrail.get(probe.trailId);
+    if (bucket === undefined) {
+      bucket = new Map();
+      probesByTrail.set(probe.trailId, bucket);
+      order.push(probe.trailId);
+    }
+    bucket.set(probe.id, probe);
+  }
+  return order.map((trailId) => buildTrail(trailId, probesByTrail.get(trailId) ?? new Map()));
+}

package/src/insight/sampling.ts

@@ -0,0 +1,70 @@
+/**
+ * Sampling — the admission gate that decides which trails are recorded.
+ */
+import type { FixedGates, SampleGate, TrailId } from "./contract.js";
+
+export const alwaysGate: SampleGate = Object.freeze({
+  admit(): boolean {
+    return true;
+  },
+});
+
+export const neverGate: SampleGate = Object.freeze({
+  admit(): boolean {
+    return false;
+  },
+});
+
+export const FIXED_GATES: FixedGates = Object.freeze({
+  always: alwaysGate,
+  never: neverGate,
+});
+
+const FNV_OFFSET_BASIS = 2166136261;
+const UINT32_SPAN = 4294967296;
+
+export function hash32(text: string): number {
+  let h = FNV_OFFSET_BASIS;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h >>> 0;
+}
+
+export function trailScore(trailId: TrailId): number {
+  return hash32(trailId) / UINT32_SPAN;
+}
+
+function clampFraction(fraction: number): number {
+  if (Number.isNaN(fraction)) return 0;
+  if (fraction <= 0) return 0;
+  if (fraction >= 1) return 1;
+  return fraction;
+}
+
+export interface RatioGate extends SampleGate {
+  readonly fraction: number;
+  verdict(trailId: TrailId): boolean;
+}
+
+export function ratioGate(fraction: number): RatioGate {
+  const clamped = clampFraction(fraction);
+  return Object.freeze({
+    fraction: clamped,
+    verdict(trailId: TrailId): boolean {
+      if (clamped <= 0) return false;
+      if (clamped >= 1) return true;
+      return trailScore(trailId) < clamped;
+    },
+    admit(rootName: string): boolean {
+      if (clamped <= 0) return false;
+      if (clamped >= 1) return true;
+      return hash32(rootName) / UINT32_SPAN < clamped;
+    },
+  });
+}
+
+export function isRatioGate(gate: SampleGate): gate is RatioGate {
+  return typeof (gate as Partial<RatioGate>).verdict === "function";
+}

package/src/insight/serialize.ts

@@ -0,0 +1,50 @@
+/**
+ * Serialization — the on-disk NDJSON record shape shared by the file sink and
+ * the replay reader.
+ */
+import type { ClosedProbe, Probe, Signal, SignalPhase } from "./contract.js";
+
+export const RECORD_VERSION = 1 as const;
+
+export interface TraceRecord {
+  readonly v: typeof RECORD_VERSION;
+  readonly phase: SignalPhase;
+  readonly probe: Probe;
+  readonly at: number;
+}
+
+export const LINE_FEED = "\n";
+const LINE_SEPARATOR_ESCAPE = "\\u2028";
+const PARAGRAPH_SEPARATOR_ESCAPE = "\\u2029";
+const SEPARATOR_PATTERN = /[\u2028\u2029]/g;
+
+function escapeSeparators(json: string): string {
+  return json.replace(
+    SEPARATOR_PATTERN,
+    (ch) =>
+      ch.charCodeAt(0) === 0x2028 ? LINE_SEPARATOR_ESCAPE : PARAGRAPH_SEPARATOR_ESCAPE,
+  );
+}
+
+export function signalToRecord(signal: Signal): TraceRecord {
+  return {
+    v: RECORD_VERSION,
+    phase: signal.phase,
+    probe: signal.probe,
+    at: signal.at,
+  };
+}
+
+export function encodeRecord(signal: Signal): string {
+  return escapeSeparators(JSON.stringify(signalToRecord(signal))) + LINE_FEED;
+}
+
+export function decodeRecord(line: string): TraceRecord {
+  return JSON.parse(line) as TraceRecord;
+}
+
+export function recordIsClose(
+  record: TraceRecord,
+): record is TraceRecord & { probe: ClosedProbe } {
+  return record.phase === "close";
+}

package/src/insight/sinks/console.ts

@@ -0,0 +1,64 @@
+/**
+ * Console sink — drains signals to a writable, one human-readable line each.
+ */
+import type { Sink } from "../contract.js";
+
+export interface LineWriter {
+  write(chunk: string): unknown;
+  readonly isTTY?: boolean;
+}
+
+export interface ConsoleSinkOptions {
+  readonly writer?: LineWriter;
+  readonly color?: boolean;
+  readonly id?: string;
+}
+
+const SGR = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  cyan: "\x1B[36m",
+};
+
+function paint(on: boolean, code: string, text: string): string {
+  return on ? code + text + SGR.reset : text;
+}
+
+function label(probe: { kind: string; name: string }): string {
+  return probe.kind + "/" + probe.name;
+}
+
+function formatSignal(
+  signal: import("../contract.js").Signal,
+  color: boolean,
+): string {
+  const p = signal.probe;
+  const ids = p.trailId.slice(0, 8) + ":" + p.id.slice(0, 6);
+  if (signal.phase === "close") {
+    const closed = p;
+    const ms = (closed.endedAt ?? 0) - closed.startedAt;
+    const ok = closed.status === "ok";
+    const tag = paint(color, ok ? SGR.green : SGR.red, closed.status);
+    const dur = paint(color, SGR.dim, `${ms}ms`);
+    return `close ${tag} ${label(closed)} ${dur} ${ids}`;
+  }
+  const head = paint(color, SGR.cyan, signal.phase);
+  const body = paint(color, SGR.dim, `${label(p)} ${ids}`);
+  return `${head} ${body}`;
+}
+
+export function createConsoleSink(options: ConsoleSinkOptions = {}): Sink {
+  const writer: LineWriter = options.writer ?? (process.stdout as unknown as LineWriter);
+  const color = options.color ?? writer.isTTY ?? false;
+  const id = options.id ?? "console";
+  return {
+    id,
+    async drain(stream) {
+      for await (const signal of stream) {
+        writer.write(formatSignal(signal, color) + "\n");
+      }
+    },
+  };
+}

package/src/insight/sinks/file.ts

@@ -0,0 +1,40 @@
+/**
+ * File sink — drains signals to an append-only NDJSON trace file.
+ */
+import { mkdir, open } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { Sink } from "../contract.js";
+import { encodeRecord } from "../serialize.js";
+
+export interface FileSinkOptions {
+  readonly path: string;
+  readonly id?: string;
+  readonly mkdirp?: boolean;
+  readonly truncate?: boolean;
+}
+
+export function createFileSink(options: FileSinkOptions): Sink {
+  const id = options.id ?? "file";
+  const mode = options.truncate ? "w" : "a";
+  return {
+    id,
+    async drain(stream) {
+      let handle: Awaited<ReturnType<typeof open>> | null = null;
+      try {
+        for await (const signal of stream) {
+          if (handle === null) {
+            if (options.mkdirp ?? true) {
+              await mkdir(dirname(options.path), { recursive: true });
+            }
+            handle = await open(options.path, mode);
+          }
+          await handle.write(encodeRecord(signal));
+        }
+      } finally {
+        if (handle !== null) {
+          await handle.close();
+        }
+      }
+    },
+  };
+}

package/src/insight/sinks/index.ts

@@ -0,0 +1,24 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Sinks barrel — the terminal consumers of a {@link Signal} stream.
+ *
+ * Three concrete {@link Sink} factories, each of which drains an independent
+ * {@link SignalStream} obtained from the recorder's channel:
+ *
+ *   - {@link createConsoleSink} — one human line per signal to a TTY / writer;
+ *   - {@link createFileSink} — append-only NDJSON to a path (durable);
+ *   - {@link createStreamSink} — NDJSON forwarded to an injected byte writer;
+ *   - {@link createCollectorSink} — an in-memory array (tests / inspection).
+ *
+ * All four are framework-agnostic and share the record format in `serialize.ts`.
+ */
+export { createConsoleSink, type ConsoleSinkOptions, type LineWriter } from "./console.js";
+export { createFileSink, type FileSinkOptions } from "./file.js";
+export {
+  createStreamSink,
+  createCollectorSink,
+  type StreamSinkOptions,
+  type SignalWriter,
+  type CollectorSink,
+} from "./stream.js";

package/src/insight/sinks/stream.ts

@@ -0,0 +1,54 @@
+/**
+ * Stream sink — forwards signals to a network/byte stream, or collects them.
+ */
+import type { Signal, Sink } from "../contract.js";
+import { encodeRecord } from "../serialize.js";
+
+export interface SignalWriter {
+  write(line: string): unknown | Promise<unknown>;
+  end?(): unknown | Promise<unknown>;
+}
+
+export interface StreamSinkOptions {
+  readonly writer: SignalWriter;
+  readonly id?: string;
+  readonly endOnFinish?: boolean;
+}
+
+export function createStreamSink(options: StreamSinkOptions): Sink {
+  const id = options.id ?? "stream";
+  const endOnFinish = options.endOnFinish ?? true;
+  return {
+    id,
+    async drain(stream) {
+      try {
+        for await (const signal of stream) {
+          await options.writer.write(encodeRecord(signal));
+        }
+      } finally {
+        if (endOnFinish && options.writer.end !== undefined) {
+          await options.writer.end();
+        }
+      }
+    },
+  };
+}
+
+export interface CollectorSink extends Sink {
+  readonly signals: readonly Signal[];
+}
+
+export function createCollectorSink(id: string = "collector"): CollectorSink {
+  const signals: Signal[] = [];
+  return {
+    id,
+    get signals(): readonly Signal[] {
+      return signals;
+    },
+    async drain(stream) {
+      for await (const signal of stream) {
+        signals.push(signal);
+      }
+    },
+  };
+}