@gmickel/gno 2.4.0 → 2.6.0

package/src/sessions/format.ts

@@ -0,0 +1,191 @@
+/**
+ * Text renderings of session receipts and status, shared by every text
+ * surface (CLI terminal output, MCP text content).
+ *
+ * @module src/sessions/format
+ */
+
+import type {
+  SessionAutomationRunResult,
+  SessionAutomationStatus,
+  SessionImportReceipt,
+  SessionsStatus,
+} from "./types";
+
+/** Plain-text import receipt shared by the CLI and MCP. */
+export function formatImportReceiptText(receipt: SessionImportReceipt): string {
+  const c = receipt.counts;
+  const lines = [
+    `Session import ${receipt.dryRun ? "(dry run, nothing written) " : ""}${receipt.status}`,
+    `threads: ${c.imported} imported, ${c.updated} updated, ${c.unchanged} unchanged, ${c.skippedPolicy} skipped by policy`,
+    `units: ${c.incomplete} incomplete, ${c.failed} failed, ${c.unsupported} unsupported${receipt.deferredUnits > 0 ? `, ${receipt.deferredUnits} deferred by limit` : ""}`,
+    `turns: ${receipt.turns.human} human, ${receipt.turns.assistant} assistant, ${receipt.turns.redactions} redactions, ${receipt.turns.injectedSkipped} injected skipped`,
+    `lexical: ${receipt.lexical.status}${receipt.lexical.error ? ` (${receipt.lexical.error})` : ""}; embedding backlog: ${receipt.embedding.backlog ?? "n/a"}`,
+  ];
+  const notable = receipt.units.filter(
+    (unit) =>
+      unit.outcome !== "unchanged" &&
+      unit.outcome !== "imported" &&
+      unit.outcome !== "updated"
+  );
+  for (const unit of notable.slice(0, 20)) {
+    lines.push(
+      `- ${unit.sourceId} ${unit.locator}: ${unit.outcome}${unit.reason ? ` (${unit.reason})` : ""}`
+    );
+  }
+  for (const warning of receipt.warnings) lines.push(`warning: ${warning}`);
+  return lines.join("\n");
+}
+
+/** Plain-text archive status shared by the CLI and MCP. */
+export function formatStatusText(status: SessionsStatus): string {
+  const lines = [`Session archive (index ${status.index})`];
+  for (const collection of status.collections) {
+    lines.push(
+      `- collection ${collection.name}: ${collection.threads} threads`
+    );
+  }
+  for (const source of status.sources) {
+    lines.push(
+      `- source ${source.id} (${source.harness} -> ${source.collection}): ${source.available ? "available" : "UNAVAILABLE"}; units ${source.units.complete} complete, ${source.units.incomplete} incomplete, ${source.units.failed} failed, ${source.units.pending} pending; last import ${source.lastImportAt ?? "never"}`
+    );
+    if (source.sourceUnavailable > 0) {
+      lines.push(
+        `  ${source.sourceUnavailable} archived units no longer have a source (archive retained${source.staleParser > 0 ? `, ${source.staleParser} from an older parser` : ""})`
+      );
+    }
+  }
+  lines.push(...formatAutomationLines(status.automation));
+  for (const warning of status.warnings) lines.push(`warning: ${warning}`);
+  return lines.join("\n");
+}
+
+/**
+ * When a failed run is retried. Only a running daemon retries, so without one
+ * no time is promised, and a due time already passed is not shown as upcoming.
+ */
+export function retryWording(
+  retryAt: string | null,
+  daemonRunning: boolean,
+  now: Date,
+  at: (iso: string | null) => string
+): string | null {
+  if (!retryAt) return null;
+  if (!daemonRunning) {
+    return "retried when the daemon runs, or run the profile again yourself";
+  }
+  return Date.parse(retryAt) <= now.getTime()
+    ? "retry due on the daemon's next tick"
+    : `retried automatically at ${at(retryAt)}`;
+}
+
+/** UTC instant shown in the reader's timezone, e.g. `2026-09-24 15:04:05`. */
+export function formatLocalTime(iso: string | null, timezone: string): string {
+  if (!iso) return "never";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return date.toLocaleString("sv-SE", { timeZone: timezone });
+}
+
+function daemonLine(
+  automation: SessionAutomationStatus,
+  at: (iso: string | null) => string
+): string {
+  if (automation.daemon.state === "running") {
+    return `daemon running (heartbeat ${at(automation.daemon.heartbeatAt)})`;
+  }
+  if (automation.daemon.state === "stale") {
+    return `daemon stale (last heartbeat ${at(automation.daemon.heartbeatAt)})`;
+  }
+  return "not running: no daemon";
+}
+
+function formatAutomationLines(automation: SessionAutomationStatus): string[] {
+  if (automation.profiles.length === 0) {
+    return ["Automation: off (manual imports only)"];
+  }
+  const at = (iso: string | null) => formatLocalTime(iso, automation.timezone);
+  const lines = [
+    `Automation (${daemonLine(automation, at)}; times in ${automation.timezone})`,
+  ];
+  for (const profile of automation.profiles) {
+    const hookMissing =
+      profile.hook?.enabled && profile.hook.installed === false
+        ? " (entry missing)"
+        : "";
+    const hook = profile.hook
+      ? `hook ${profile.hook.harness} ${profile.hook.enabled ? "on" : "off"}${hookMissing}`
+      : "hook off";
+    let schedule = "schedule off";
+    if (profile.schedule?.enabled) {
+      let next = "not running: no daemon";
+      if (profile.schedule.nextDueAt) {
+        next = `next ${at(profile.schedule.nextDueAt)}`;
+      } else if (automation.daemon.state === "running") {
+        next = "due time set on the daemon's next tick";
+      }
+      schedule = `schedule every ${profile.schedule.cadence}, ${next}`;
+    }
+    lines.push(
+      `- profile ${profile.id}: ${profile.state}; sources ${profile.sources.join(", ")} -> ${profile.collections.join(", ") || "(none)"}; ${hook}; ${schedule}`
+    );
+    // A failure awaiting correction is shown by state and action, not as
+    // queued work.
+    if (profile.pending && profile.state !== "failed") {
+      const wording = retryWording(
+        profile.retryAt,
+        automation.daemon.state === "running",
+        new Date(),
+        at
+      );
+      const retry = wording ? `; ${wording}` : "";
+      lines.push(
+        `  pending since ${at(profile.pending.since)} (${profile.pending.triggers.join(", ") || "continuation"})${retry}`
+      );
+    }
+    if (profile.running) {
+      lines.push(`  running since ${at(profile.running.startedAt)}`);
+    }
+    if (profile.lastRun) {
+      const run = profile.lastRun;
+      lines.push(
+        `  last run ${at(run.finishedAt)}: ${run.outcome}${run.reason ? ` (${run.reason})` : ""}; threads ${run.threads.imported} imported, ${run.threads.updated} updated; units ${run.units.incomplete} incomplete, ${run.units.failed} failed, ${run.units.deferred} deferred`
+      );
+    }
+    lines.push(`  last success ${at(profile.lastSuccessAt)}`);
+    if (profile.recovery) lines.push(`  action: ${profile.recovery}`);
+  }
+  return lines;
+}
+
+/** What follows a run: remaining work, or the next step after a failure. */
+const RETRYABLE_REASONS = new Set(["busy", "runtime_error", "interrupted"]);
+
+export function runTail(result: SessionAutomationRunResult): string {
+  if (result.outcome === "failed") {
+    return RETRYABLE_REASONS.has(result.reason ?? "")
+      ? "; a running daemon retries it, or run it again once the archive is free (see gno sessions status)"
+      : "; see gno sessions status for the recovery action";
+  }
+  return result.pending ? "; more work is pending" : "";
+}
+
+/** Plain-text automation run result shared by the CLI and MCP. */
+export function formatAutomationRunText(
+  result: SessionAutomationRunResult
+): string {
+  if (!result.ran) {
+    return `Automation profile ${result.profileId}: not started (${result.reason ?? "unknown"})${result.pending ? "; work stays pending" : ""}`;
+  }
+  const lines = [
+    `Automation profile ${result.profileId}: ${result.outcome}${result.reason ? ` (${result.reason})` : ""}${runTail(result)}`,
+  ];
+  for (const receipt of result.receipts) {
+    const deferred =
+      receipt.deferredUnits > 0 ? `, ${receipt.deferredUnits} deferred` : "";
+    lines.push(
+      `- ${receipt.sourceIds.join(", ")}: ${receipt.status}; ${receipt.counts.imported} imported, ${receipt.counts.updated} updated, ${receipt.counts.unchanged} unchanged; ${receipt.counts.incomplete} incomplete, ${receipt.counts.failed} failed${deferred}`
+    );
+  }
+  return lines.join("\n");
+}

package/src/sessions/import-child-env.ts

@@ -0,0 +1,8 @@
+/**
+ * Environment flag a compiled executable sets when it re-runs itself as the
+ * session import child. Dependency-free so the CLI entry can check it
+ * without loading the sessions service.
+ *
+ * @module src/sessions/import-child-env
+ */
+export const IMPORT_CHILD_ENV = "GNO_INTERNAL_SESSION_IMPORT_CHILD";

package/src/sessions/import-child.ts

@@ -0,0 +1,152 @@
+/**
+ * Run a registered-source import in a child process.
+ *
+ * Parsing, sanitizing and above all the index sync of thousands of archive
+ * records are CPU-bound and synchronous (each archive file syncs in one
+ * SQLite transaction), so a long-lived server that imported in-process would
+ * stop answering every request until the import finished. `gno serve` runs
+ * the same `SessionsService.import` here instead, in a child with its own
+ * store connection: the archive import lock, receipts and error codes are
+ * unchanged.
+ *
+ * The child reads one request from stdin and writes one JSON result line to
+ * stdout. The request carries the caller's loaded config: the child opens
+ * the index without syncing any config into it and imports with exactly the
+ * config the server holds. From source the child runs this module; a
+ * compiled executable re-runs itself with `IMPORT_CHILD_ENV` set, which the
+ * CLI entry routes here before any command runs.
+ *
+ * @module src/sessions/import-child
+ */
+
+import type { Config } from "../config/types";
+import type { SessionImportReceipt } from "./types";
+
+import { getIndexDbPath } from "../app/constants";
+import { isStandaloneExecutable } from "../serve/spa-production-build";
+import { SqliteAdapter } from "../store/sqlite/adapter";
+import { assertSessionBinding } from "./binding";
+import { IMPORT_CHILD_ENV } from "./import-child-env";
+import { SessionsService } from "./service";
+import { type SessionsErrorCode, SessionsError } from "./types";
+
+export interface ImportChildRequest {
+  config: Config;
+  configPath: string;
+  indexName: string;
+  sourceId: string;
+  dryRun: boolean;
+  limit?: number;
+}
+
+type ImportChildResult =
+  | { ok: true; receipt: SessionImportReceipt }
+  | { ok: false; code: SessionsErrorCode | null; message: string };
+
+async function importInThisProcess(
+  request: ImportChildRequest
+): Promise<SessionImportReceipt> {
+  const input = {
+    sourceId: request.sourceId,
+    dryRun: request.dryRun,
+    limit: request.limit,
+  };
+  if (request.dryRun) {
+    return new SessionsService({
+      config: request.config,
+      configPath: request.configPath,
+      indexName: request.indexName,
+    }).import(input, { allowPaths: false });
+  }
+  const dbPath = getIndexDbPath(request.indexName);
+  await assertSessionBinding({
+    config: request.config,
+    configPath: request.configPath,
+    indexName: request.indexName,
+    dbPath,
+  });
+  // The server already projected this config into the index; the child only
+  // opens it (no collection/context sync).
+  const store = new SqliteAdapter();
+  store.setConfigPath(request.configPath);
+  const opened = await store.open(
+    dbPath,
+    request.config.ftsTokenizer,
+    request.config.busyTimeoutMs
+  );
+  if (!opened.ok) throw new Error(opened.error.message);
+  try {
+    return await new SessionsService({
+      config: request.config,
+      configPath: request.configPath,
+      indexName: request.indexName,
+      store,
+    }).import(input, { allowPaths: false });
+  } finally {
+    await store.close();
+  }
+}
+
+/**
+ * Import a registered source without blocking the caller's event loop.
+ * Throws a `SessionsError` for typed failures and a plain `Error` otherwise.
+ */
+export async function importInChildProcess(
+  request: ImportChildRequest
+): Promise<SessionImportReceipt> {
+  // A compiled executable cannot run an external TS entry: it re-runs itself.
+  // Shared check: covers the POSIX `/$bunfs/` and Windows `B:/~BUN/` roots.
+  const compiled = isStandaloneExecutable();
+  const child = Bun.spawn({
+    cmd: compiled ? [process.execPath] : [process.execPath, import.meta.path],
+    env: compiled ? { ...process.env, [IMPORT_CHILD_ENV]: "1" } : process.env,
+    stdin: new Blob([JSON.stringify(request)]),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  const line = stdout.trim().split("\n").at(-1) ?? "";
+  let result: ImportChildResult | null = null;
+  try {
+    result = JSON.parse(line) as ImportChildResult;
+  } catch {
+    result = null;
+  }
+  if (!result) {
+    throw new Error(
+      `session import child exited ${exitCode}: ${stderr.trim().slice(-2000)}`
+    );
+  }
+  if (result.ok) return result.receipt;
+  if (result.code) throw new SessionsError(result.code, result.message);
+  throw new Error(result.message);
+}
+
+/** Child entry: one request on stdin, one JSON result line on stdout. */
+export async function runImportChild(): Promise<void> {
+  // Nothing this child starts may re-enter child mode.
+  delete process.env[IMPORT_CHILD_ENV];
+  let result: ImportChildResult;
+  try {
+    const request = JSON.parse(
+      await new Response(Bun.stdin.stream()).text()
+    ) as ImportChildRequest;
+    result = { ok: true, receipt: await importInThisProcess(request) };
+  } catch (error) {
+    result =
+      error instanceof SessionsError
+        ? { ok: false, code: error.code, message: error.message }
+        : {
+            ok: false,
+            code: null,
+            message: error instanceof Error ? error.message : String(error),
+          };
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (import.meta.main) await runImportChild();

package/src/sessions/parsers/claude-code.ts

@@ -0,0 +1,259 @@
+/**
+ * Claude Code project JSONL parser.
+ *
+ * Verified layouts (2026-09, CLI 2.1.2xx): `projects/<encoded-cwd>/<sessionId>.jsonl`
+ * for the main thread and `.../<sessionId>/subagents/agent-<agentId>.jsonl`
+ * for spawned subagents. Records carry `uuid`, `sessionId`, `timestamp`,
+ * `cwd`, `version`, `type`.
+ *
+ * Human speech is structural: `type=user` records whose `origin.kind` is
+ * `human`. Files written before the `origin` field existed fall back to a
+ * conservative shape test (plain text, not meta, not a compaction summary,
+ * no tool result, no command/notification wrapper). Injected attachments,
+ * system records, compaction summaries, slash-command wrappers, task
+ * notifications and the parent task prompt inside a subagent file are never
+ * human speech. A slash command a person typed (`origin.kind=human`) is
+ * archived as `/name args`. Prompts of SDK / `claude -p` sessions
+ * (`entrypoint=sdk-*`) come from a program and are not attributed to a
+ * person. Assistant turns are the text blocks of `type=assistant` records;
+ * thinking and tool calls are excluded.
+ *
+ * @module src/sessions/parsers/claude-code
+ */
+
+import {
+  emptyDiagnostics,
+  normalizeTimestamp,
+  noteUnknownKind,
+  type ParsedThread,
+  type ParsedTurn,
+  type ParseUnitResult,
+} from "../types";
+import {
+  missingHumanTurns,
+  isRecord,
+  joinTextBlocks,
+  pushTurn,
+  readJsonlRecords,
+  stringField,
+} from "./shared";
+
+export const CLAUDE_CODE_PARSER = "claude-code/1";
+
+const SKIPPED_TYPES = new Set([
+  "attachment",
+  "system",
+  "summary",
+  "file-history-snapshot",
+  "file-history-delta",
+  "queue-operation",
+  "last-prompt",
+  "ai-title",
+  "custom-title",
+  "permission-mode",
+  "mode",
+  "bridge-session",
+  "atis-latch",
+  "frame-link",
+  "pr-link",
+  "cost-state",
+  "tag",
+  "agent-name",
+  "continued-in",
+  "artifact-autoreact-ledger",
+  "artifact-comment-monitor",
+  "progress",
+  "fork-context-ref",
+  "history-suppression",
+]);
+
+/** Wrappers the CLI writes around non-speech input. */
+const WRAPPER_PREFIXES = [
+  "<command-name>",
+  "<command-message>",
+  "<command-args>",
+  "<local-command-",
+  "<task-notification>",
+  "<system-reminder>",
+  "<bash-input>",
+  "<bash-stdout>",
+  "<bash-stderr>",
+  "<user-memory-input>",
+];
+
+const COMMAND_NAME = /<command-name>([^<]{1,256})<\/command-name>/;
+const COMMAND_ARGS = /<command-args>([\s\S]{0,65536}?)<\/command-args>/;
+
+/** A human-typed slash command becomes `/name args`; other wrappers stay out. */
+function slashCommandText(text: string): string | undefined {
+  const name = COMMAND_NAME.exec(text)?.[1]?.trim();
+  if (!name) return undefined;
+  const args = COMMAND_ARGS.exec(text)?.[1]?.trim() ?? "";
+  const command = name.startsWith("/") ? name : `/${name}`;
+  return args ? `${command} ${args}` : command;
+}
+
+interface UserCandidate {
+  turn: ParsedTurn;
+  originKind?: string;
+  hasOrigin: boolean;
+  plainShape: boolean;
+}
+
+const SUBAGENT_FILE = /(?:^|\/)agent-([A-Za-z0-9_-]{1,128})\.jsonl$/;
+
+function userText(message: Record<string, unknown>): {
+  text?: string;
+  hasToolResult: boolean;
+} {
+  const content = message.content;
+  if (typeof content === "string")
+    return { text: content, hasToolResult: false };
+  if (!Array.isArray(content)) return { hasToolResult: false };
+  const hasToolResult = content.some(
+    (block) => isRecord(block) && block.type === "tool_result"
+  );
+  return { text: joinTextBlocks(content, ["text"]), hasToolResult };
+}
+
+export async function parseClaudeCodeSession(
+  path: string
+): Promise<ParseUnitResult> {
+  const diagnostics = emptyDiagnostics();
+  const subagentMatch = SUBAGENT_FILE.exec(path.replaceAll("\\", "/"));
+  const isSubagentFile = Boolean(subagentMatch);
+  const ordered: Array<ParsedTurn | UserCandidate> = [];
+  let sessionId: string | undefined;
+  let agentId: string | undefined = subagentMatch?.[1];
+  let firstCwd: string | undefined;
+  let fileHasOrigin = false;
+  let programmaticEntry = false;
+
+  for await (const { lineNumber, record } of readJsonlRecords(
+    path,
+    diagnostics
+  )) {
+    const type = record.type;
+    sessionId ??= stringField(record.sessionId);
+    agentId ??= isSubagentFile ? stringField(record.agentId) : undefined;
+    const cwd = stringField(record.cwd);
+    firstCwd ??= cwd;
+    if (diagnostics.formatVersion === undefined) {
+      diagnostics.formatVersion = stringField(record.version);
+    }
+    if (type === "user" && "origin" in record) fileHasOrigin = true;
+    // SDK / `claude -p` sessions receive prompts from a program, which may be
+    // another agent; they are not attributed to a person.
+    const entrypoint = stringField(record.entrypoint);
+    if (entrypoint?.startsWith("sdk")) programmaticEntry = true;
+
+    if (type !== "user" && type !== "assistant") {
+      if (typeof type !== "string" || !SKIPPED_TYPES.has(type)) {
+        noteUnknownKind(diagnostics, type);
+      }
+      continue;
+    }
+    const message = isRecord(record.message) ? record.message : {};
+    const base = {
+      turnId: stringField(record.uuid) ?? `line:${lineNumber}`,
+      timestamp: normalizeTimestamp(record.timestamp),
+      locator: `line:${lineNumber}`,
+      cwd,
+    };
+
+    // Sidechain records inside a main file are agent-to-agent traffic.
+    if (!isSubagentFile && record.isSidechain === true) {
+      diagnostics.injectedSkipped += 1;
+      continue;
+    }
+
+    if (type === "assistant") {
+      const text = joinTextBlocks(message.content, ["text"]);
+      if (text !== undefined) {
+        ordered.push({ ...base, role: "assistant", text });
+      }
+      continue;
+    }
+
+    const { text, hasToolResult } = userText(message);
+    if (hasToolResult || text === undefined) continue;
+    const trimmed = text.trimStart();
+    const wrapped = WRAPPER_PREFIXES.some((prefix) =>
+      trimmed.startsWith(prefix)
+    );
+    const plainShape =
+      record.isMeta !== true &&
+      record.isCompactSummary !== true &&
+      record.isVisibleInTranscriptOnly !== true &&
+      !wrapped;
+    const origin = isRecord(record.origin) ? record.origin : undefined;
+    const originKind = stringField(origin?.kind);
+    const command =
+      originKind === "human" && wrapped && record.isMeta !== true
+        ? slashCommandText(trimmed)
+        : undefined;
+    ordered.push({
+      turn: { ...base, role: "human", text: command ?? text },
+      originKind,
+      hasOrigin: "origin" in record,
+      plainShape: plainShape || command !== undefined,
+    });
+  }
+
+  const turns: ParsedTurn[] = [];
+  for (const entry of ordered) {
+    let turn: ParsedTurn;
+    if ("turn" in entry) {
+      // In a subagent file the "user" message is the parent agent's task.
+      const human =
+        !isSubagentFile &&
+        !programmaticEntry &&
+        entry.plainShape &&
+        (fileHasOrigin ? entry.originKind === "human" : true);
+      if (!human) {
+        diagnostics.injectedSkipped += 1;
+        continue;
+      }
+      turn = entry.turn;
+    } else {
+      turn = entry;
+    }
+    if (!pushTurn(turns, turn, diagnostics)) break;
+  }
+
+  if (!sessionId) {
+    return {
+      threads: [],
+      diagnostics,
+      complete: !diagnostics.truncatedTail,
+      parser: CLAUDE_CODE_PARSER,
+    };
+  }
+  if (!(isSubagentFile || programmaticEntry)) {
+    diagnostics.humanTurnsMissing = missingHumanTurns(turns);
+  }
+  const thread: ParsedThread = isSubagentFile
+    ? {
+        harness: "claude-code",
+        threadId: `${sessionId}/agent-${agentId ?? "unknown"}`,
+        sessionId,
+        parentThreadId: sessionId,
+        kind: "subagent",
+        cwd: firstCwd,
+        turns,
+      }
+    : {
+        harness: "claude-code",
+        threadId: sessionId,
+        sessionId,
+        kind: "main",
+        cwd: firstCwd,
+        turns,
+      };
+  return {
+    threads: [thread],
+    diagnostics,
+    complete: !diagnostics.truncatedTail && !diagnostics.humanTurnsMissing,
+    parser: CLAUDE_CODE_PARSER,
+  };
+}