talon-agent 1.35.0 → 1.37.0

package/src/storage/sessions.ts

@@ -47,6 +47,43 @@ export type SessionUsage = {
   fastestResponseMs: number;
 };
 
+export type MetricsCounterSet = {
+  queries: number;
+  toolCalls: number;
+  turnsWithTools: number;
+  apiCalls: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  failedTurns: number;
+  flowViolationRetries: number;
+  flowViolationCapExhausted: number;
+  trailingTextDropped: number;
+};
+
+export type MetricsLatencyAgg = {
+  count: number;
+  sumMs: number;
+  minMs: number;
+  maxMs: number;
+};
+
+export type MetricsGrain = {
+  counters: MetricsCounterSet;
+  latency: MetricsLatencyAgg;
+  toolCallsByName: Record<string, number>;
+  backend: Record<string, MetricsCounterSet & { latency: MetricsLatencyAgg }>;
+  cacheHitPercent: MetricsLatencyAgg;
+  toolCallsPerTurn: MetricsLatencyAgg;
+  apiCallsPerTurn: MetricsLatencyAgg;
+};
+
+export type SessionMetrics = {
+  lifetime: MetricsGrain;
+  buckets: Record<string, MetricsGrain>;
+};
+
 export type SessionState = {
   /** Backend server-side session ID. */
   sessionId: string | undefined;
@@ -58,6 +95,8 @@ export type SessionState = {
   createdAt: number;
   /** Cumulative usage stats. */
   usage: SessionUsage;
+  /** Persistent per-session metrics, bucketed by UTC day. */
+  metrics: SessionMetrics;
   /** ID of the last message sent by the bot in this chat. */
   lastBotMessageId?: number;
   /** Descriptive session name derived from first message. */
@@ -249,6 +288,155 @@ const emptyUsage = (): SessionUsage => ({
   fastestResponseMs: Infinity,
 });
 
+const emptyCounters = (): MetricsCounterSet => ({
+  queries: 0,
+  toolCalls: 0,
+  turnsWithTools: 0,
+  apiCalls: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  failedTurns: 0,
+  flowViolationRetries: 0,
+  flowViolationCapExhausted: 0,
+  trailingTextDropped: 0,
+});
+
+const emptyLatency = (): MetricsLatencyAgg => ({
+  count: 0,
+  sumMs: 0,
+  minMs: Infinity,
+  maxMs: 0,
+});
+
+const emptyGrain = (): MetricsGrain => ({
+  counters: emptyCounters(),
+  latency: emptyLatency(),
+  toolCallsByName: {},
+  backend: {},
+  cacheHitPercent: emptyLatency(),
+  toolCallsPerTurn: emptyLatency(),
+  apiCallsPerTurn: emptyLatency(),
+});
+
+export const emptyMetrics = (): SessionMetrics => ({
+  lifetime: emptyGrain(),
+  buckets: {},
+});
+
+function normaliseLatency(raw: unknown): MetricsLatencyAgg {
+  const r = raw as Partial<MetricsLatencyAgg> | undefined;
+  const count =
+    typeof r?.count === "number" && Number.isFinite(r.count) ? r.count : 0;
+  return {
+    count,
+    sumMs:
+      typeof r?.sumMs === "number" && Number.isFinite(r.sumMs) ? r.sumMs : 0,
+    minMs:
+      typeof r?.minMs === "number" && Number.isFinite(r.minMs)
+        ? r.minMs
+        : count > 0
+          ? 0
+          : Infinity,
+    maxMs:
+      typeof r?.maxMs === "number" && Number.isFinite(r.maxMs) ? r.maxMs : 0,
+  };
+}
+
+function normaliseCounters(raw: unknown): MetricsCounterSet {
+  const base = emptyCounters();
+  const r = raw as Partial<MetricsCounterSet> | undefined;
+  for (const key of Object.keys(base) as Array<keyof MetricsCounterSet>) {
+    const value = r?.[key];
+    if (typeof value === "number" && Number.isFinite(value)) base[key] = value;
+  }
+  return base;
+}
+
+function normaliseGrain(raw: unknown): MetricsGrain {
+  const r = raw as Partial<MetricsGrain> | undefined;
+  const grain = emptyGrain();
+  grain.counters = normaliseCounters(r?.counters);
+  grain.latency = normaliseLatency(r?.latency);
+  grain.cacheHitPercent = normaliseLatency(r?.cacheHitPercent);
+  grain.toolCallsPerTurn = normaliseLatency(r?.toolCallsPerTurn);
+  grain.apiCallsPerTurn = normaliseLatency(r?.apiCallsPerTurn);
+  if (r?.toolCallsByName && typeof r.toolCallsByName === "object") {
+    for (const [key, value] of Object.entries(r.toolCallsByName)) {
+      if (typeof value === "number" && Number.isFinite(value)) {
+        grain.toolCallsByName[key] = value;
+      }
+    }
+  }
+  if (r?.backend && typeof r.backend === "object") {
+    for (const [key, value] of Object.entries(r.backend)) {
+      grain.backend[key] = {
+        ...normaliseCounters(value),
+        latency: normaliseLatency((value as { latency?: unknown }).latency),
+      };
+    }
+  }
+  return grain;
+}
+
+/**
+ * Coerce an untrusted/persisted metrics blob into a well-formed
+ * SessionMetrics: missing fields backfilled, non-finite numbers dropped,
+ * JSON's `minMs: null` (Infinity doesn't survive JSON.stringify) restored
+ * to the domain sentinel. Runs once at the load boundary (sessions-repo);
+ * in-memory metrics stay well-formed by construction after that.
+ */
+export function normaliseMetrics(metrics: unknown): SessionMetrics {
+  const raw = metrics as Partial<SessionMetrics> | undefined;
+  const result: SessionMetrics = {
+    lifetime: normaliseGrain(raw?.lifetime),
+    buckets: {},
+  };
+  if (raw?.buckets && typeof raw.buckets === "object") {
+    for (const [day, grain] of Object.entries(raw.buckets)) {
+      if (/^\d{4}-\d{2}-\d{2}$/.test(day))
+        result.buckets[day] = normaliseGrain(grain);
+    }
+  }
+  return result;
+}
+
+function addLatency(agg: MetricsLatencyAgg, value: number): void {
+  if (!Number.isFinite(value)) return;
+  agg.count += 1;
+  agg.sumMs += value;
+  agg.minMs = Math.min(agg.minMs, value);
+  agg.maxMs = Math.max(agg.maxMs, value);
+}
+
+function addCounters(
+  target: MetricsCounterSet,
+  delta: Partial<MetricsCounterSet>,
+): void {
+  for (const [key, value] of Object.entries(delta) as Array<
+    [keyof MetricsCounterSet, number | undefined]
+  >) {
+    if (typeof value === "number" && Number.isFinite(value))
+      target[key] += value;
+  }
+}
+
+/** UTC day key (`YYYY-MM-DD`) used for daily metric buckets. */
+export function todayUtc(now = Date.now()): string {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+function metricBucket(metrics: SessionMetrics, day: string): MetricsGrain {
+  metrics.buckets[day] ??= emptyGrain();
+  const days = Object.keys(metrics.buckets).sort();
+  while (days.length > 30) {
+    const oldest = days.shift();
+    if (oldest) delete metrics.buckets[oldest];
+  }
+  return metrics.buckets[day]!;
+}
+
 /**
  * Normalise a session state object in-place. Migrates fields that
  * pre-date later schema additions (response timing, context fill,
@@ -256,6 +444,9 @@ const emptyUsage = (): SessionUsage => ({
  */
 function normaliseSession(session: SessionState): SessionState {
   if (!session.usage) session.usage = emptyUsage();
+  // Metrics blobs are normalised once when rows are hydrated
+  // (sessions-repo parseMetrics); here only backfill pre-metrics records.
+  if (!session.metrics) session.metrics = emptyMetrics();
   if (!session.createdAt) session.createdAt = session.lastActive;
   if (session.usage.totalResponseMs === undefined)
     session.usage.totalResponseMs = 0;
@@ -285,6 +476,7 @@ export function getSession(chatId: string): SessionState {
       lastActive: now,
       createdAt: now,
       usage: emptyUsage(),
+      metrics: emptyMetrics(),
     };
     cache.set(chatId, session);
     persist(chatId, session);
@@ -292,6 +484,114 @@ export function getSession(chatId: string): SessionState {
   return normaliseSession(session);
 }
 
+export type SessionMetricTurn = {
+  backend: string;
+  durationMs: number;
+  toolCalls?: number;
+  toolCallsByName?: Record<string, number>;
+  apiCalls?: number;
+  failed?: boolean;
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    cacheWrite: number;
+  };
+};
+
+function foldMetricTurn(grain: MetricsGrain, turn: SessionMetricTurn): void {
+  addCounters(grain.counters, {
+    queries: 1,
+    turnsWithTools: turn.toolCalls && turn.toolCalls > 0 ? 1 : 0,
+    apiCalls: turn.apiCalls ?? 0,
+    failedTurns: turn.failed ? 1 : 0,
+    inputTokens: turn.usage?.inputTokens ?? 0,
+    outputTokens: turn.usage?.outputTokens ?? 0,
+    cacheReadTokens: turn.usage?.cacheRead ?? 0,
+    cacheWriteTokens: turn.usage?.cacheWrite ?? 0,
+  });
+  addLatency(grain.latency, turn.durationMs);
+  if (turn.toolCalls !== undefined)
+    addLatency(grain.toolCallsPerTurn, turn.toolCalls);
+  if (turn.apiCalls !== undefined && turn.apiCalls > 0)
+    addLatency(grain.apiCallsPerTurn, turn.apiCalls);
+  if (turn.usage && turn.usage.inputTokens + turn.usage.cacheRead > 0) {
+    addLatency(
+      grain.cacheHitPercent,
+      Math.round(
+        (turn.usage.cacheRead /
+          (turn.usage.inputTokens + turn.usage.cacheRead)) *
+          100,
+      ),
+    );
+  }
+  for (const [name, count] of Object.entries(turn.toolCallsByName ?? {})) {
+    if (Number.isFinite(count))
+      grain.toolCallsByName[name] = (grain.toolCallsByName[name] ?? 0) + count;
+  }
+  const backend = (grain.backend[turn.backend] ??= {
+    ...emptyCounters(),
+    latency: emptyLatency(),
+  });
+  addCounters(backend, {
+    queries: 1,
+    apiCalls: turn.apiCalls ?? 0,
+    failedTurns: turn.failed ? 1 : 0,
+    inputTokens: turn.usage?.inputTokens ?? 0,
+    outputTokens: turn.usage?.outputTokens ?? 0,
+    cacheReadTokens: turn.usage?.cacheRead ?? 0,
+    cacheWriteTokens: turn.usage?.cacheWrite ?? 0,
+  });
+  addLatency(backend.latency, turn.durationMs);
+}
+
+export function recordSessionMetrics(
+  chatId: string,
+  turn: SessionMetricTurn,
+  day = todayUtc(),
+): void {
+  const session = getSession(chatId);
+  foldMetricTurn(session.metrics.lifetime, turn);
+  foldMetricTurn(metricBucket(session.metrics, day), turn);
+  persist(chatId, session);
+}
+
+export function recordSessionMetricEvent(
+  chatId: string,
+  event: Partial<MetricsCounterSet> & {
+    toolName?: string;
+    backend?: string;
+  },
+  day = todayUtc(),
+): void {
+  const session = getSession(chatId);
+  for (const grain of [
+    session.metrics.lifetime,
+    metricBucket(session.metrics, day),
+  ]) {
+    addCounters(grain.counters, event);
+    if (event.toolName && event.toolCalls) {
+      grain.toolCallsByName[event.toolName] =
+        (grain.toolCallsByName[event.toolName] ?? 0) + event.toolCalls;
+    }
+    if (event.backend) {
+      const backend = (grain.backend[event.backend] ??= {
+        ...emptyCounters(),
+        latency: emptyLatency(),
+      });
+      addCounters(backend, event);
+    }
+  }
+  persist(chatId, session);
+}
+
+export function resetAllSessionMetrics(): void {
+  for (const [chatId, session] of cache.entries()) {
+    session.metrics = emptyMetrics();
+    persist(chatId, session);
+  }
+}
+
 export function setSessionId(chatId: string, sessionId: string): void {
   const session = getSession(chatId);
   session.sessionId = sessionId;
@@ -375,10 +675,7 @@ export function getLastBotMessageId(chatId: string): number | undefined {
   return cache.get(chatId)?.lastBotMessageId;
 }
 
-export function resetSession(chatId: string): void {
-  const session = cache.get(chatId);
-  const turns = session?.turns ?? 0;
-  const name = session?.sessionName;
+function removeSessionRow(chatId: string): void {
   cache.delete(chatId);
   clearLiveTurn(chatId);
   try {
@@ -389,18 +686,63 @@ export function resetSession(chatId: string): void {
       `Session delete failed: ${err instanceof Error ? err.message : err}`,
     );
   }
+}
+
+/**
+ * Reset the chat's conversation state (backend session id, turns, usage)
+ * while carrying its metrics forward. Resets fire on /new, model switches
+ * and error recovery — none of which should erase the chat's accounting
+ * history (that's what makes per-session metrics survive anything short
+ * of deleting the chat). Use deleteSession() to drop the chat entirely.
+ */
+export function resetSession(chatId: string): void {
+  const session = cache.get(chatId);
+  const turns = session?.turns ?? 0;
+  const name = session?.sessionName;
+  const metrics = session?.metrics;
+  removeSessionRow(chatId);
+  const hasHistory =
+    metrics &&
+    (metrics.lifetime.counters.queries > 0 ||
+      metrics.lifetime.counters.toolCalls > 0);
+  if (hasHistory) {
+    const now = Date.now();
+    const fresh: SessionState = {
+      sessionId: undefined,
+      turns: 0,
+      lastActive: now,
+      createdAt: now,
+      usage: emptyUsage(),
+      metrics,
+    };
+    cache.set(chatId, fresh);
+    persist(chatId, fresh);
+  }
   log(
     "sessions",
     `[${chatId}] Reset${name ? ` "${name}"` : ""} (${turns} turns)`,
   );
 }
 
+/** Drop the chat entirely — row, cache, live overlay and metrics. */
+export function deleteSession(chatId: string): void {
+  const session = cache.get(chatId);
+  const turns = session?.turns ?? 0;
+  const name = session?.sessionName;
+  removeSessionRow(chatId);
+  log(
+    "sessions",
+    `[${chatId}] Deleted${name ? ` "${name}"` : ""} (${turns} turns)`,
+  );
+}
+
 export type SessionInfo = {
   sessionId: string | undefined;
   turns: number;
   lastActive: number;
   createdAt: number;
   usage: SessionUsage;
+  metrics: SessionMetrics;
   sessionName?: string;
   lastModel?: string;
   /** True when a turn is currently streaming and `usage` includes its live so-far counts. */
@@ -415,6 +757,7 @@ export function getSessionInfo(chatId: string): SessionInfo {
     lastActive: session?.lastActive ?? 0,
     createdAt: session?.createdAt ?? 0,
     usage: withLiveTurn(chatId, session?.usage ?? emptyUsage()),
+    metrics: session?.metrics ?? emptyMetrics(),
     sessionName: session?.sessionName,
     lastModel: session?.lastModel,
     turnInProgress: liveTurns.has(chatId),
@@ -435,6 +778,7 @@ export function getAllSessions(): Array<{ chatId: string; info: SessionInfo }> {
       lastActive: session.lastActive,
       createdAt: session.createdAt,
       usage: withLiveTurn(chatId, session.usage ?? emptyUsage()),
+      metrics: session.metrics ?? emptyMetrics(),
       sessionName: session.sessionName,
       lastModel: session.lastModel,
       turnInProgress: liveTurns.has(chatId),

package/src/storage/sql/db.sql

@@ -9,3 +9,8 @@ PRAGMA wal_checkpoint(TRUNCATE)
 -- attempts this on every open and swallows "duplicate column name" /
 -- "no such table" (fresh databases get the column via schema.sql).
 ALTER TABLE media_index ADD COLUMN content_hash TEXT
+
+-- name: addSessionsMetricsColumn
+-- Column reconciliation for databases that shipped before per-session
+-- metrics existed. Fresh databases get the column via schema.sql.
+ALTER TABLE sessions ADD COLUMN metrics TEXT NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'

package/src/storage/sql/schema.sql

@@ -70,7 +70,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   estimated_cost_usd  REAL    NOT NULL DEFAULT 0,
   total_response_ms   REAL    NOT NULL DEFAULT 0,
   last_response_ms    REAL    NOT NULL DEFAULT 0,
-  fastest_response_ms REAL
+  fastest_response_ms REAL,
+  metrics             TEXT    NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'
 );
 
 -- Chat settings: one JSON document per chat. The access pattern is

package/src/storage/sql/sessions.sql

@@ -7,15 +7,15 @@ INSERT OR REPLACE INTO sessions
    created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
    total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
    context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-   last_response_ms, fastest_response_ms)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+   last_response_ms, fastest_response_ms, metrics)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 
 -- name: all
 SELECT chat_id, session_id, session_name, last_model, turns, last_active,
        created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
        total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
        context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-       last_response_ms, fastest_response_ms
+       last_response_ms, fastest_response_ms, metrics
 FROM sessions
 
 -- name: remove

package/src/storage/sql/statements.generated.ts

@@ -75,7 +75,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   estimated_cost_usd  REAL    NOT NULL DEFAULT 0,
   total_response_ms   REAL    NOT NULL DEFAULT 0,
   last_response_ms    REAL    NOT NULL DEFAULT 0,
-  fastest_response_ms REAL
+  fastest_response_ms REAL,
+  metrics             TEXT    NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'
 );
 
 -- Chat settings: one JSON document per chat. The access pattern is
@@ -277,6 +278,9 @@ export const dbSql = {
 -- attempts this on every open and swallows "duplicate column name" /
 -- "no such table" (fresh databases get the column via schema.sql).
 ALTER TABLE media_index ADD COLUMN content_hash TEXT`,
+  addSessionsMetricsColumn: `-- Column reconciliation for databases that shipped before per-session
+-- metrics existed. Fresh databases get the column via schema.sql.
+ALTER TABLE sessions ADD COLUMN metrics TEXT NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'`,
 } as const;
 
 export const goalsSql = {
@@ -420,13 +424,13 @@ export const sessionsSql = {
    created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
    total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
    context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-   last_response_ms, fastest_response_ms)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+   last_response_ms, fastest_response_ms, metrics)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   all: `SELECT chat_id, session_id, session_name, last_model, turns, last_active,
        created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
        total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
        context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-       last_response_ms, fastest_response_ms
+       last_response_ms, fastest_response_ms, metrics
 FROM sessions`,
   remove: `DELETE FROM sessions WHERE chat_id = ?`,
 } as const;

package/src/util/config.ts

@@ -422,6 +422,16 @@ const configSchema = z.object({
   // Native — local bridge for the Electron companion app (apps/desktop)
   native: nativeConfigSchema.optional(),
 
+  // Native tools — replace the SDK's built-in Read/Write/Edit/Bash/Glob/Grep
+  // with Talon's own MCP equivalents (bash/read/write/edit/glob/search). The
+  // native tools additionally route to the active `teleport` node, so file
+  // and shell operations can transparently run on a companion device. When
+  // true, the built-ins are dropped from the model's tool whitelist and the
+  // native tools take their place. Off by default: enabling swaps the model's
+  // own hands, so the cutover should be deliberate and observed (flip to true
+  // and restart), with an instant rollback by flipping back to false.
+  nativeTools: z.boolean().default(false),
+
   // Display name shown in terminal UI (defaults to "Talon")
   botDisplayName: z.string().default("Talon"),
 

package/src/util/exec-output.ts

@@ -0,0 +1,64 @@
+/**
+ * Exec output guards, shared by the local native tools and the mesh exec
+ * channel. Two independent ceilings:
+ *
+ *  - capture: how much of a child process's stream the daemon will hold in
+ *    memory at all. A runaway `yes` otherwise balloons RSS for the whole
+ *    timeout window before a single byte reaches the model.
+ *  - render: how much of a (possibly device-supplied) stream reaches the
+ *    model/chat. Clamped head+tail — the tail keeps the part of a long log
+ *    where the error usually lives.
+ */
+
+/** In-memory cap while capturing one child-process output stream. */
+export const MAX_EXEC_CAPTURE_BYTES = 4 * 1024 * 1024;
+
+/** Ceiling on each rendered exec stream (stdout, stderr independently). */
+export const MAX_EXEC_RENDER_CHARS = 30_000;
+
+/**
+ * Clamp one output stream for rendering: keep the head and the tail,
+ * elide the middle with an explicit marker so truncation is never silent.
+ */
+export function clampExecOutput(
+  text: string,
+  max = MAX_EXEC_RENDER_CHARS,
+): string {
+  if (text.length <= max) return text;
+  const headLen = Math.floor(max * 0.75);
+  const tailLen = max - headLen;
+  const head = text.slice(0, headLen);
+  const tail = text.slice(-tailLen);
+  const elided = text.length - head.length - tail.length;
+  return `${head}\n…[${elided.toLocaleString()} chars truncated]…\n${tail}`;
+}
+
+/**
+ * Bounded accumulator for a child process's stdout/stderr. Chunks past the
+ * cap are counted, not stored; `value()` appends an explicit drop marker.
+ */
+export function createOutputCapture(cap = MAX_EXEC_CAPTURE_BYTES): {
+  push: (chunk: Buffer | string) => void;
+  value: () => string;
+} {
+  let text = "";
+  let dropped = 0;
+  return {
+    push: (chunk) => {
+      const s = chunk.toString();
+      const room = cap - text.length;
+      if (room <= 0) {
+        dropped += s.length;
+      } else if (s.length <= room) {
+        text += s;
+      } else {
+        text += s.slice(0, room);
+        dropped += s.length - room;
+      }
+    },
+    value: () =>
+      dropped > 0
+        ? `${text}\n…[${dropped.toLocaleString()} more chars dropped — output exceeded the ${Math.round(cap / (1024 * 1024))}MB capture cap]`
+        : text,
+  };
+}