indusagi-coding-agent 0.2.5 → 0.2.9

package/src/transcript-export/template.ts

@@ -0,0 +1,272 @@
+/**
+ * Template — the HTML page shell, inlined styles, and client renderer for the
+ * self-contained transcript export.
+ */
+
+export const SHELL_SLOTS: Readonly<Record<string, string>> = Object.freeze({
+  themeVars: "THEME_VARS",
+  pageSurface: "PAGE_SURFACE",
+  cardSurface: "CARD_SURFACE",
+  noteSurface: "NOTE_SURFACE",
+  styles: "STYLES",
+  script: "SCRIPT",
+  payload: "PAYLOAD",
+  markedLib: "MARKED_LIB",
+  highlightLib: "HIGHLIGHT_LIB",
+});
+
+const PAGE_STYLES = `
+:root { color-scheme: dark light; }
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+body {
+  background: var(--x-page-surface);
+  color: var(--x-ink);
+  font: 15px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+.xscript {
+  max-width: 56rem;
+  margin: 0 auto;
+  padding: 2.5rem 1.25rem 6rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+}
+.xscript-head {
+  border-bottom: 1px solid var(--x-border);
+  padding-bottom: 1rem;
+  margin-bottom: 0.5rem;
+}
+.xscript-head h1 {
+  margin: 0;
+  font-size: 1.35rem;
+  font-weight: 650;
+  letter-spacing: -0.01em;
+}
+.xscript-head .xscript-meta {
+  margin-top: 0.35rem;
+  color: var(--x-ink-muted);
+  font-size: 0.85rem;
+}
+.turn {
+  background: var(--x-card-surface);
+  border: 1px solid var(--x-border);
+  border-radius: 0.65rem;
+  padding: 1rem 1.15rem;
+  overflow: hidden;
+}
+.turn[data-role="user"] { border-left: 3px solid var(--x-user-role); }
+.turn[data-role="agent"] { border-left: 3px solid var(--x-agent-role); }
+.turn[data-role="tool"] { border-left: 3px solid var(--x-tool-role); }
+.turn-tag {
+  display: inline-block;
+  font-size: 0.72rem;
+  font-weight: 650;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  margin-bottom: 0.6rem;
+  color: var(--x-ink-muted);
+}
+.turn[data-role="user"] .turn-tag { color: var(--x-user-role); }
+.turn[data-role="agent"] .turn-tag { color: var(--x-agent-role); }
+.turn[data-role="tool"] .turn-tag { color: var(--x-tool-role); }
+.turn-body { word-break: break-word; }
+.turn-body > :first-child { margin-top: 0; }
+.turn-body > :last-child { margin-bottom: 0; }
+.turn-body a { color: var(--x-accent); text-decoration: none; }
+.turn-body a:hover { text-decoration: underline; }
+.turn-body p { margin: 0.6rem 0; }
+.turn-body img { max-width: 100%; border-radius: 0.4rem; }
+.turn-body code {
+  font-family: ui-monospace, "SF Mono", "JetBrains Mono", Menlo, monospace;
+  font-size: 0.88em;
+  background: var(--x-note-surface);
+  padding: 0.1em 0.35em;
+  border-radius: 0.3rem;
+}
+.turn-body pre {
+  background: var(--x-note-surface);
+  border: 1px solid var(--x-border);
+  border-radius: 0.5rem;
+  padding: 0.9rem 1rem;
+  overflow-x: auto;
+  margin: 0.75rem 0;
+}
+.turn-body pre code { background: none; padding: 0; }
+.tool-frame {
+  font-family: ui-monospace, "SF Mono", "JetBrains Mono", Menlo, monospace;
+  font-size: 0.85rem;
+  background: var(--x-note-surface);
+  border: 1px solid var(--x-border);
+  border-radius: 0.5rem;
+  padding: 0.85rem 1rem;
+  margin: 0.5rem 0;
+  overflow-x: auto;
+  white-space: pre-wrap;
+}
+.aside-note {
+  background: var(--x-note-surface);
+  border: 1px dashed var(--x-border);
+  border-radius: 0.5rem;
+  padding: 0.75rem 1rem;
+  color: var(--x-ink-muted);
+  font-size: 0.9rem;
+}
+.sgr-bold { font-weight: 700; }
+.sgr-dim { opacity: 0.72; }
+.sgr-italic { font-style: italic; }
+.sgr-underline { text-decoration: underline; }
+.sgr-strike { text-decoration: line-through; }
+.sgr-underline.sgr-strike { text-decoration: underline line-through; }
+.sgr-blink { animation: x-blink 1.1s steps(2, start) infinite; }
+.sgr-hidden { visibility: hidden; }
+@keyframes x-blink { 50% { opacity: 0; } }
+.xhl-keyword { color: var(--x-accent); }
+.xhl-string { color: var(--x-user-role); }
+.xhl-comment { color: var(--x-ink-muted); font-style: italic; }
+.xhl-number, .xhl-literal { color: var(--x-tool-role); }
+`.trim();
+
+const CLIENT_SCRIPT = `
+(function () {
+  "use strict";
+  var root = document.getElementById("xscript-root");
+  if (!root) return;
+
+  var raw;
+  try {
+    raw = JSON.parse(decodeURIComponent(escape(atob(window.__XSCRIPT_PAYLOAD__ || ""))));
+  } catch (err) {
+    root.textContent = "Unable to decode transcript payload.";
+    return;
+  }
+
+  function hl(code, lang) {
+    try {
+      if (lang && window.hljs && window.hljs.getLanguage(lang)) {
+        return window.hljs.highlight(code, { language: lang }).value;
+      }
+      if (window.hljs) return window.hljs.highlightAuto(code).value;
+    } catch (e) {}
+    return null;
+  }
+
+  if (window.marked && window.marked.setOptions) {
+    window.marked.setOptions({
+      gfm: true,
+      breaks: false,
+      highlight: function (code, lang) {
+        var out = hl(code, lang);
+        return out == null ? code : out;
+      },
+    });
+  }
+
+  function md(text) {
+    try {
+      if (window.marked && window.marked.parse) {
+        return window.marked.parse(text, { async: false });
+      }
+    } catch (e) {}
+    var div = document.createElement("div");
+    div.textContent = text;
+    return div.innerHTML;
+  }
+
+  function el(tag, cls) {
+    var node = document.createElement(tag);
+    if (cls) node.className = cls;
+    return node;
+  }
+
+  function renderTurn(turn) {
+    if (turn.kind === "note") {
+      var note = el("div", "aside-note");
+      note.innerHTML = turn.html != null ? turn.html : md(turn.text || "");
+      return note;
+    }
+    var card = el("section", "turn");
+    card.setAttribute("data-role", turn.role || "agent");
+    var tag = el("span", "turn-tag");
+    tag.textContent = turn.label || turn.role || "";
+    card.appendChild(tag);
+    var body = el("div", "turn-body");
+    if (turn.html != null) {
+      body.innerHTML = turn.html;
+    } else if (turn.frame) {
+      var frame = el("div", "tool-frame");
+      frame.innerHTML = turn.frame;
+      body.appendChild(frame);
+    } else {
+      body.innerHTML = md(turn.text || "");
+    }
+    card.appendChild(body);
+    return card;
+  }
+
+  var turns = Array.isArray(raw.turns) ? raw.turns : [];
+  for (var i = 0; i < turns.length; i++) {
+    root.appendChild(renderTurn(turns[i]));
+  }
+})();
+`.trim();
+
+const PAGE_SHELL = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Session Transcript</title>
+<style>
+:root {
+{{THEME_VARS}}
+  --x-page-surface: {{PAGE_SURFACE}};
+  --x-card-surface: {{CARD_SURFACE}};
+  --x-note-surface: {{NOTE_SURFACE}};
+}
+{{STYLES}}
+</style>
+</head>
+<body>
+<main class="xscript">
+  <header class="xscript-head">
+    <h1>Session Transcript</h1>
+    <div class="xscript-meta">Self-contained HTML export</div>
+  </header>
+  <div id="xscript-root"></div>
+</main>
+<script>
+/* {{MARKED_LIB}} */
+</script>
+<script>
+/* {{HIGHLIGHT_LIB}} */
+</script>
+<script>
+window.__XSCRIPT_PAYLOAD__ = "{{PAYLOAD}}";
+</script>
+<script>
+{{SCRIPT}}
+</script>
+</body>
+</html>
+`;
+
+export { PAGE_STYLES, CLIENT_SCRIPT, PAGE_SHELL };
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function fill(
+  template: string,
+  values: Readonly<Record<string, string>>,
+): string {
+  let out = template;
+  for (const token of Object.values(SHELL_SLOTS)) {
+    const value = values[token] ?? "";
+    const marker = new RegExp(`\\{\\{${escapeRegExp(token)}\\}\\}`, "g");
+    out = out.replace(marker, () => value);
+  }
+  return out;
+}

package/src/transcript-export/theme-bridge.ts

@@ -0,0 +1,150 @@
+/**
+ * ThemeBridge — the color service behind the HTML transcript export.
+ */
+import { FALLBACK_EXPORT_THEME, type ExportTheme } from "../briefing/contract.js";
+
+export function buildLuminanceLut(): Float64Array {
+  const lut = new Float64Array(256);
+  for (let v = 0; v < 256; v++) {
+    const s = v / 255;
+    lut[v] = s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  }
+  return lut;
+}
+
+interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+
+function expandShortHex(body: string): string {
+  if (body.length === 3 || body.length === 4) {
+    return body
+      .slice(0, 3)
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+  return body.slice(0, 6);
+}
+
+function parseColor(color: string): Rgb | null {
+  const text = color.trim().toLowerCase();
+  if (text.startsWith("#")) {
+    const body = expandShortHex(text.slice(1));
+    if (!/^[0-9a-f]{6}$/.test(body)) return null;
+    return {
+      r: parseInt(body.slice(0, 2), 16),
+      g: parseInt(body.slice(2, 4), 16),
+      b: parseInt(body.slice(4, 6), 16),
+    };
+  }
+  const fn = text.match(/^rgba?\(([^)]+)\)$/);
+  if (fn) {
+    const parts = fn[1].split(/[,\s/]+/).filter((p) => p.length > 0);
+    if (parts.length < 3) return null;
+    const channel = (p: string): number => {
+      const n = p.endsWith("%") ? (parseFloat(p) / 100) * 255 : parseFloat(p);
+      return Number.isNaN(n) ? 0 : clampByte2(n);
+    };
+    return { r: channel(parts[0]), g: channel(parts[1]), b: channel(parts[2]) };
+  }
+  return null;
+}
+
+function clampByte2(value: number): number {
+  if (value <= 0) return 0;
+  if (value >= 255) return 255;
+  return Math.round(value);
+}
+
+function formatColor(rgb: Rgb): string {
+  const hex = (v: number): string => clampByte2(v).toString(16).padStart(2, "0");
+  return `#${hex(rgb.r)}${hex(rgb.g)}${hex(rgb.b)}`;
+}
+
+function luminanceOf(rgb: Rgb, lut: Float64Array): number {
+  const lr = lut[clampByte2(rgb.r)] ?? 0;
+  const lg = lut[clampByte2(rgb.g)] ?? 0;
+  const lb = lut[clampByte2(rgb.b)] ?? 0;
+  return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+}
+
+function contrastRatio(a: number, b: number): number {
+  const hi = Math.max(a, b);
+  const lo = Math.min(a, b);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+function stepChannels(rgb: Rgb, amount: number): Rgb {
+  return {
+    r: clampByte2(rgb.r + amount),
+    g: clampByte2(rgb.g + amount),
+    b: clampByte2(rgb.b + amount),
+  };
+}
+
+const LUMINANCE_LUT: Float64Array = buildLuminanceLut();
+const MODE_THRESHOLD = 0.18;
+const THEME_TOKENS = [
+  "pageSurface",
+  "cardSurface",
+  "noteSurface",
+  "ink",
+  "inkMuted",
+  "accent",
+  "border",
+  "userRole",
+  "agentRole",
+  "toolRole",
+] as const;
+
+export class DefaultThemeBridge {
+  readonly theme: ExportTheme;
+  readonly lut: Float64Array;
+
+  constructor(
+    theme: ExportTheme = FALLBACK_EXPORT_THEME,
+    lut: Float64Array = LUMINANCE_LUT,
+  ) {
+    this.theme = theme;
+    this.lut = lut;
+  }
+
+  luminance(color: string): number {
+    const rgb = parseColor(color);
+    return rgb === null ? 0 : luminanceOf(rgb, this.lut);
+  }
+
+  mode(): "light" | "dark" {
+    return this.luminance(this.theme.pageSurface) >= MODE_THRESHOLD ? "light" : "dark";
+  }
+
+  deriveSurface(base: string, amount: number): string {
+    const rgb = parseColor(base);
+    if (rgb === null) return this.theme.cardSurface;
+    return formatColor(stepChannels(rgb, amount));
+  }
+
+  readableInk(background: string): string {
+    const bg = this.luminance(background);
+    const ink = this.luminance(this.theme.ink);
+    const muted = this.luminance(this.theme.inkMuted);
+    return contrastRatio(ink, bg) >= contrastRatio(muted, bg)
+      ? this.theme.ink
+      : this.theme.inkMuted;
+  }
+
+  toCssVars(): Record<string, string> {
+    const vars: Record<string, string> = {};
+    for (const token of THEME_TOKENS) {
+      vars[token] = this.theme[token];
+    }
+    return vars;
+  }
+}
+
+export function createThemeBridge(theme?: ExportTheme): DefaultThemeBridge {
+  return new DefaultThemeBridge(theme ?? FALLBACK_EXPORT_THEME);
+}

package/src/window-budget/budget/estimate.ts

@@ -0,0 +1,135 @@
+/**
+ * Token estimation — the heuristic "meter stick" for the window-budget
+ * subsystem.
+ *
+ * Before we can decide whether the transcript is over budget (gate.ts) or where
+ * to slice it (slice.ts), we need a cheap, deterministic estimate of how many
+ * tokens each {@link AgentMessage} occupies. We do *not* call a tokenizer; we
+ * walk the serialized content and apply a small, transparent weighting model.
+ */
+import type { AgentMessage } from "../contract.js";
+
+const CHARS_PER_TOKEN = 3.6;
+const IMAGE_TOKENS = 1024;
+const MESSAGE_FRAMING_TOKENS = 4;
+const BLOCK_FRAMING_TOKENS = 2;
+const TOOLCALL_ENVELOPE_TOKENS = 6;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function weighBlock(block: unknown): { chars: number; images: number } {
+  if (typeof block === "string") return { chars: block.length, images: 0 };
+  if (!isRecord(block)) return { chars: 0, images: 0 };
+  switch (block.type) {
+    case "text":
+      return { chars: typeof block.text === "string" ? block.text.length : 0, images: 0 };
+    case "thinking":
+      return { chars: typeof block.thinking === "string" ? block.thinking.length : 0, images: 0 };
+    case "image":
+      return { chars: 0, images: 1 };
+    case "toolCall": {
+      const name = typeof block.name === "string" ? block.name.length : 0;
+      const args = block.arguments === undefined ? 0 : safeStringify(block.arguments).length;
+      return { chars: name + args, images: 0 };
+    }
+    default:
+      return { chars: safeStringify(block).length, images: 0 };
+  }
+}
+
+function weighMessage(message: unknown): { chars: number; images: number; framing: number } {
+  if (!isRecord(message)) {
+    return { chars: safeStringify(message).length, images: 0, framing: MESSAGE_FRAMING_TOKENS };
+  }
+  let chars = 0;
+  let images = 0;
+  let framing = MESSAGE_FRAMING_TOKENS;
+  switch (message.role) {
+    case "user": {
+      const content = message.content;
+      if (typeof content === "string") {
+        chars += content.length;
+        framing += BLOCK_FRAMING_TOKENS;
+      } else if (Array.isArray(content)) {
+        for (const block of content) {
+          const w = weighBlock(block);
+          chars += w.chars;
+          images += w.images;
+          framing += BLOCK_FRAMING_TOKENS;
+        }
+      }
+      return { chars, images, framing };
+    }
+    case "assistant": {
+      const content = Array.isArray(message.content) ? message.content : [];
+      for (const block of content) {
+        const w = weighBlock(block);
+        chars += w.chars;
+        images += w.images;
+        framing += BLOCK_FRAMING_TOKENS;
+        if (isRecord(block) && block.type === "toolCall") framing += TOOLCALL_ENVELOPE_TOKENS;
+      }
+      if (typeof message.errorMessage === "string") chars += message.errorMessage.length;
+      return { chars, images, framing };
+    }
+    case "toolResult": {
+      if (typeof message.toolName === "string") chars += message.toolName.length;
+      const content = Array.isArray(message.content) ? message.content : [];
+      for (const block of content) {
+        const w = weighBlock(block);
+        chars += w.chars;
+        images += w.images;
+        framing += BLOCK_FRAMING_TOKENS;
+      }
+      framing += TOOLCALL_ENVELOPE_TOKENS;
+      return { chars, images, framing };
+    }
+    default: {
+      chars += safeStringify(message).length;
+      framing += BLOCK_FRAMING_TOKENS;
+      return { chars, images, framing };
+    }
+  }
+}
+
+/**
+ * Estimate the token cost of one message in isolation. Exposed so the slice
+ * planner can build a prefix-sum without re-deriving the per-message weight.
+ */
+export function estimateMessageTokens(message: AgentMessage): number {
+  const { chars, images, framing } = weighMessage(message);
+  const textTokens = Math.ceil(chars / CHARS_PER_TOKEN);
+  return textTokens + framing + images * IMAGE_TOKENS;
+}
+
+/**
+ * Estimate the total token cost of a transcript: the sum of every message's
+ * {@link estimateMessageTokens}.
+ */
+export function estimateTokens(messages: AgentMessage[]): number {
+  let total = 0;
+  for (const message of messages) total += estimateMessageTokens(message);
+  return total;
+}
+
+/**
+ * Build a FORWARD prefix-sum array of per-message token estimates.
+ */
+export function prefixTokens(messages: AgentMessage[]): number[] {
+  const prefix = new Array<number>(messages.length + 1);
+  prefix[0] = 0;
+  for (let i = 0; i < messages.length; i++) {
+    prefix[i + 1] = prefix[i] + estimateMessageTokens(messages[i]);
+  }
+  return prefix;
+}

package/src/window-budget/budget/gate.ts

@@ -0,0 +1,33 @@
+/**
+ * Budget gate — the trigger predicate for the window-budget subsystem.
+ *
+ * {@link isOverBudget} answers the single question "is the transcript large
+ * enough that we should condense before the next turn?" by comparing a token
+ * estimate against a window-relative threshold derived from the model's
+ * `contextWindow` and the caller-supplied {@link BudgetPolicy}.
+ */
+import type { AgentMessage, BudgetPolicy, Model } from "../contract.js";
+import type { Api } from "indusagi/ai";
+import { estimateTokens } from "./estimate.js";
+
+/**
+ * Compute the absolute token limit at which condensing should fire for a given
+ * model and policy.
+ */
+export function budgetLimit(model: Model<Api>, policy: BudgetPolicy): number {
+  const reserve = policy.reserveTokens ?? 0;
+  const usable = Math.max(0, model.contextWindow - reserve);
+  return usable * policy.triggerRatio;
+}
+
+/**
+ * Decide whether the transcript is over budget for the given model and policy.
+ */
+export function isOverBudget(
+  messages: AgentMessage[],
+  model: Model<Api>,
+  policy: BudgetPolicy,
+): boolean {
+  const estimate = estimateTokens(messages);
+  return estimate > budgetLimit(model, policy);
+}

package/src/window-budget/budget/index.ts

@@ -0,0 +1,16 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Window-budget / budget — pure budget math.
+ *
+ * The arithmetic core of the window-budget subsystem, free of I/O, prompts, and
+ * model calls:
+ *   - {@link estimateTokens} / {@link estimateMessageTokens} / {@link prefixTokens}
+ *     — heuristic token measurement and the forward cumulative-token array.
+ *   - {@link isOverBudget} / {@link budgetLimit} — the window-relative trigger.
+ *   - {@link planSlice} — forward prefix-sum + binary-search cut planning that
+ *     never splits a tool_call from its tool_result.
+ */
+export { estimateMessageTokens, estimateTokens, prefixTokens } from "./estimate.js";
+export { budgetLimit, isOverBudget } from "./gate.js";
+export { planSlice } from "./slice.js";

package/src/window-budget/budget/slice.ts

@@ -0,0 +1,56 @@
+/**
+ * Slice planner — decides *where* to cut the transcript when it is over budget.
+ */
+import type { AgentMessage, BudgetPolicy, CondensePlan } from "../contract.js";
+import { prefixTokens } from "./estimate.js";
+
+function isRecord2(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isLegalTailStart(message: AgentMessage): boolean {
+  return !(isRecord2(message) && (message as { role?: string }).role === "toolResult");
+}
+
+function snapForward(messages: AgentMessage[], candidate: number): number {
+  let cut = candidate;
+  while (cut < messages.length && !isLegalTailStart(messages[cut])) cut++;
+  return cut;
+}
+
+function lowerBound(prefix: number[], threshold: number): number {
+  let lo = 0;
+  let hi = prefix.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (prefix[mid] >= threshold) hi = mid;
+    else lo = mid + 1;
+  }
+  return lo;
+}
+
+/**
+ * Plan the condense slice for a transcript under a {@link BudgetPolicy}.
+ */
+export function planSlice(messages: AgentMessage[], policy: BudgetPolicy): CondensePlan {
+  const n = messages.length;
+  if (n === 0) {
+    return { cut: 0, kept: [], dropped: [] };
+  }
+  const prefix = prefixTokens(messages);
+  const total = prefix[n];
+  if (total <= policy.keepRecent) {
+    return { cut: 0, kept: messages.slice(0), dropped: [] };
+  }
+  const threshold = total - policy.keepRecent;
+  const ideal = lowerBound(prefix, threshold);
+  const cut = snapForward(messages, ideal);
+  if (cut >= n) {
+    return { cut: 0, kept: messages.slice(0), dropped: [] };
+  }
+  return {
+    cut,
+    kept: messages.slice(cut),
+    dropped: messages.slice(0, cut),
+  };
+}