@gmickel/gno 2.5.1 → 2.6.0

package/src/sessions/types.ts

@@ -0,0 +1,457 @@
+/**
+ * Shared contracts for native agent-session ingestion.
+ *
+ * Data flow: native source -> harness parser -> sanitizer -> one durable
+ * JSONL archive file per thread -> ordinary collection sync through the
+ * JSONL record adapter. Every surface (CLI, MCP, REST, SDK, Web UI) consumes
+ * the receipt and status shapes defined here.
+ *
+ * @module src/sessions/types
+ */
+
+export const SESSION_HARNESSES = [
+  "codex",
+  "claude-code",
+  "openclaw",
+  "hermes",
+] as const;
+export type SessionHarness = (typeof SESSION_HARNESSES)[number];
+
+export const SESSION_HARNESS_LABELS: Record<SessionHarness, string> = {
+  codex: "Codex",
+  "claude-code": "Claude Code",
+  openclaw: "OpenClaw",
+  hermes: "Hermes",
+};
+
+/** Speaker classes that reach the archive. Everything else is skipped. */
+export type SessionRole = "human" | "assistant";
+
+/** Largest `limit` accepted by one import call. */
+export const MAX_IMPORT_LIMIT = 100_000;
+
+/** Version of the archive line layout; bumps force a rewrite on import. */
+export const SESSION_ARCHIVE_FORMAT_VERSION = 2;
+
+/** Bounds applied while reading sources. */
+export const SESSION_LIMITS = {
+  /** Largest native file or database read in one unit. */
+  maxSourceBytes: 512 * 1024 * 1024,
+  /** Largest physical JSONL line parsed; larger lines are skipped and counted. */
+  maxLineBytes: 32 * 1024 * 1024,
+  /** Largest dialogue text kept for one turn; larger turns are skipped. */
+  maxTurnChars: 256 * 1024,
+  /** Largest number of archived turns for one thread. */
+  maxTurnsPerThread: 20_000,
+  /** Largest archive file written for one thread. */
+  maxArchiveBytesPerThread: 64 * 1024 * 1024,
+  /** Largest number of threads one database unit may yield. */
+  maxThreadsPerUnit: 50_000,
+  /** Units listed individually in a receipt. */
+  maxReceiptUnits: 200,
+  /** Distinct unknown record kinds reported per unit. */
+  maxDiagnosticKinds: 32,
+  /** Units enumerated below one source root. */
+  maxUnitsPerSource: 100_000,
+} as const;
+
+/** One archived dialogue turn after structural classification. */
+export interface ParsedTurn {
+  /** Native logical turn ID (message/item ID or a stable ordinal locator). */
+  turnId: string;
+  role: SessionRole;
+  text: string;
+  /** Normalized ISO-8601 UTC timestamp; absent when unknown or unparseable. */
+  timestamp?: string;
+  /** Safe native locator inside the unit, e.g. `line:42` or `messages/17`. */
+  locator: string;
+  /** Working directory recorded for this turn, when the format carries one. */
+  cwd?: string;
+}
+
+export type SessionThreadKind = "main" | "subagent" | "fork" | "continuation";
+
+/** One conversation thread as recovered from a native unit. */
+export interface ParsedThread {
+  harness: SessionHarness;
+  /** Native thread identity (distinct for forks and subagents). */
+  threadId: string;
+  /** Native root session identity shared by forks/subagents when known. */
+  sessionId: string;
+  parentThreadId?: string;
+  kind: SessionThreadKind;
+  /** Recorded working directory for the thread. */
+  cwd?: string;
+  turns: ParsedTurn[];
+}
+
+/** Bounded, content-free diagnostics for one unit. */
+export interface UnitDiagnostics {
+  /** Record kinds the parser does not recognise, with counts. */
+  unknownKinds: Record<string, number>;
+  malformedRecords: number;
+  overLimitRecords: number;
+  overLimitTurns: number;
+  /** Records skipped because they are injected context, not speech. */
+  injectedSkipped: number;
+  /** Records copied from a parent thread (fork/continuation history). */
+  copiedHistorySkipped: number;
+  /** Final line was cut mid-write (a growing file). */
+  truncatedTail: boolean;
+  /**
+   * Single-thread file units: assistant turns exist but no human turn was
+   * recognised (possible format drift); the unit stays incomplete.
+   */
+  humanTurnsMissing: boolean;
+  /**
+   * Database units: main threads with assistant turns but no human turn.
+   * Reported per thread, so one such thread cannot hold the unit back.
+   */
+  threadsWithoutHuman: number;
+  /**
+   * Database units: threads left unread because the unit reached
+   * `maxThreadsPerUnit`; the unit stays incomplete so its checkpoint does
+   * not advance past them.
+   */
+  threadsOverLimit: number;
+  /** Format revision reported by the source, when recorded. */
+  formatVersion?: string;
+}
+
+export const emptyDiagnostics = (): UnitDiagnostics => ({
+  unknownKinds: {},
+  malformedRecords: 0,
+  overLimitRecords: 0,
+  overLimitTurns: 0,
+  injectedSkipped: 0,
+  copiedHistorySkipped: 0,
+  truncatedTail: false,
+  humanTurnsMissing: false,
+  threadsWithoutHuman: 0,
+  threadsOverLimit: 0,
+});
+
+const SAFE_KIND = /[^A-Za-z0-9_.:/-]/g;
+
+/** Record an unknown kind without retaining source content. */
+export function noteUnknownKind(
+  diagnostics: UnitDiagnostics,
+  kind: unknown
+): void {
+  const label =
+    typeof kind === "string" && kind.length > 0
+      ? kind.slice(0, 64).replace(SAFE_KIND, "_")
+      : "(none)";
+  const known = diagnostics.unknownKinds[label];
+  if (
+    known === undefined &&
+    Object.keys(diagnostics.unknownKinds).length >=
+      SESSION_LIMITS.maxDiagnosticKinds
+  ) {
+    return;
+  }
+  diagnostics.unknownKinds[label] = (known ?? 0) + 1;
+}
+
+export interface ParseUnitResult {
+  threads: ParsedThread[];
+  diagnostics: UnitDiagnostics;
+  /** True when every byte of the unit was read and understood or skipped by policy. */
+  complete: boolean;
+  /** Parser identity recorded in archive provenance. */
+  parser: string;
+}
+
+/** Normalize a native timestamp to ISO-8601 UTC or drop it. */
+export function normalizeTimestamp(value: unknown): string | undefined {
+  let date: Date | undefined;
+  if (typeof value === "string" && value.trim()) {
+    const trimmed = value.trim();
+    // Numeric strings are epoch seconds or milliseconds.
+    if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+      return normalizeTimestamp(Number(trimmed));
+    }
+    date = new Date(trimmed);
+  } else if (typeof value === "number" && Number.isFinite(value)) {
+    // Heuristic boundary between epoch seconds and epoch milliseconds.
+    date = new Date(value < 1e11 ? value * 1000 : value);
+  }
+  if (!date || Number.isNaN(date.getTime())) return undefined;
+  const year = date.getUTCFullYear();
+  if (year < 1990 || year > 2200) return undefined;
+  return date.toISOString();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Receipts and status (shared across every surface)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const SESSION_UNIT_OUTCOMES = [
+  "imported",
+  "updated",
+  "unchanged",
+  "skipped_policy",
+  "unsupported",
+  "incomplete",
+  "failed",
+] as const;
+export type SessionUnitOutcome = (typeof SESSION_UNIT_OUTCOMES)[number];
+
+export interface SessionImportCounts {
+  /** Threads written to the archive for the first time. */
+  imported: number;
+  /** Threads whose archive file changed. */
+  updated: number;
+  /** Threads whose archive file was already current. */
+  unchanged: number;
+  /** Threads withheld by policy (mixed-domain, over-limit). */
+  skippedPolicy: number;
+  /** Units whose format was not recognised. */
+  unsupported: number;
+  /** Units read only partially; their checkpoint did not advance. */
+  incomplete: number;
+  /** Units that could not be read. */
+  failed: number;
+}
+
+export interface SessionTurnCounts {
+  human: number;
+  assistant: number;
+  redactions: number;
+  injectedSkipped: number;
+  copiedHistorySkipped: number;
+  overLimit: number;
+}
+
+export interface SessionUnitReceipt {
+  sourceId: string;
+  harness: SessionHarness | null;
+  /** Safe locator (basename or database table path); never a host path. */
+  locator: string;
+  outcome: SessionUnitOutcome;
+  reason?: string;
+  threads: number;
+  turns: number;
+  /** Destination collections for archived threads of this unit. */
+  collections: string[];
+  unknownKinds?: Record<string, number>;
+  warnings?: string[];
+}
+
+export interface SessionImportReceipt {
+  schemaVersion: "1";
+  dryRun: boolean;
+  index: string;
+  sourceIds: string[];
+  status: "complete" | "partial" | "failed" | "nothing_to_do";
+  counts: SessionImportCounts;
+  turns: SessionTurnCounts;
+  units: SessionUnitReceipt[];
+  unitsTruncated: boolean;
+  /** Pending units left for a later run because `limit` was reached. */
+  deferredUnits: number;
+  lexical: {
+    status: "ready" | "failed" | "skipped";
+    collections: string[];
+    error?: string;
+  };
+  embedding: { backlog: number | null };
+  warnings: string[];
+}
+
+export interface SessionSourceStatus {
+  id: string;
+  harness: SessionHarness;
+  collection: string;
+  available: boolean;
+  units: {
+    total: number;
+    complete: number;
+    incomplete: number;
+    failed: number;
+    pending: number;
+  };
+  archivedThreads: number;
+  staleParser: number;
+  sourceUnavailable: number;
+  lastImportAt: string | null;
+}
+
+export interface SessionsStatus {
+  schemaVersion: "1";
+  configured: boolean;
+  index: string;
+  collections: Array<{ name: string; threads: number }>;
+  sources: SessionSourceStatus[];
+  /** Opt-in automation; `profiles` is empty when nothing is configured. */
+  automation: SessionAutomationStatus;
+  warnings: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Automation (opt-in hooks and daemon schedules)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** What admitted a run: a host hook, a daemon schedule tick, or an explicit run. */
+export type SessionTriggerKind = "hook" | "schedule" | "manual";
+
+/** Outcome of one automation run. `up_to_date` is a verified no-op. */
+export type SessionRunOutcome =
+  | "complete"
+  | "up_to_date"
+  | "partial"
+  | "failed";
+
+/**
+ * Reader-facing profile state: `off` (no trigger enabled, nothing pending),
+ * `idle`, `pending`, `running`, `retrying` (a failed run waits for its
+ * backoff), `partial` or `failed` (the last run; see `recovery`).
+ */
+export type SessionProfileState =
+  | "off"
+  | "idle"
+  | "pending"
+  | "running"
+  | "retrying"
+  | "partial"
+  | "failed";
+
+export interface SessionRunRecord {
+  triggers: SessionTriggerKind[];
+  startedAt: string;
+  finishedAt: string;
+  outcome: SessionRunOutcome;
+  /** Stable reason code for partial/failed runs (no content, no paths). */
+  reason: string | null;
+  threads: { imported: number; updated: number; unchanged: number };
+  units: { incomplete: number; failed: number; deferred: number };
+}
+
+export interface SessionProfileStatus {
+  id: string;
+  sources: string[];
+  /** Destination archive collections of the selected sources. */
+  collections: string[];
+  state: SessionProfileState;
+  hook: {
+    harness: string;
+    enabled: boolean;
+    /** Owned entry present in the host settings; null when unreadable. */
+    installed: boolean | null;
+  } | null;
+  schedule: {
+    enabled: boolean;
+    cadence: string;
+    nextDueAt: string | null;
+  } | null;
+  limit: number;
+  retries: number;
+  pending: {
+    since: string;
+    triggers: SessionTriggerKind[];
+  } | null;
+  running: { startedAt: string; triggers: SessionTriggerKind[] } | null;
+  lastTrigger: { kind: SessionTriggerKind; at: string } | null;
+  lastRun: SessionRunRecord | null;
+  lastSuccessAt: string | null;
+  retryAt: string | null;
+  /** Next action for the owner when the profile needs attention. */
+  recovery: string | null;
+}
+
+export interface SessionAutomationStatus {
+  daemon: {
+    /** `running` only with a fresh heartbeat from a live daemon process. */
+    state: "running" | "not_running" | "stale";
+    heartbeatAt: string | null;
+  };
+  /** IANA timezone used for human-readable times; stored instants are UTC. */
+  timezone: string;
+  profiles: SessionProfileStatus[];
+}
+
+/** Result of one explicit or daemon-drained automation run. */
+export interface SessionAutomationRunResult {
+  schemaVersion: "1";
+  profileId: string;
+  /** False when the run could not start (busy, disabled, nothing pending). */
+  ran: boolean;
+  outcome: SessionRunOutcome | "not_started";
+  reason: string | null;
+  /** True when admitted work is still waiting (deferred units, failure, busy). */
+  pending: boolean;
+  receipts: SessionImportReceipt[];
+}
+
+export interface SessionDiscoveryCandidate {
+  harness: SessionHarness;
+  /** Absolute host path; only local owner surfaces receive it. */
+  path: string;
+  units: number;
+  bytes: number;
+  truncated: boolean;
+  formatVersions: string[];
+  registeredAs: string | null;
+}
+
+export interface SessionsDiscovery {
+  schemaVersion: "1";
+  candidates: SessionDiscoveryCandidate[];
+  warnings: string[];
+}
+
+export type SessionsErrorCode =
+  | "SESSIONS_NOT_CONFIGURED"
+  | "SESSIONS_BINDING_MISMATCH"
+  | "SESSIONS_SELECTION_REQUIRED"
+  | "SESSIONS_DESTINATION_REQUIRED"
+  | "SESSIONS_UNKNOWN_SOURCE"
+  | "SESSIONS_UNKNOWN_COLLECTION"
+  | "SESSIONS_UNSAFE_PATH"
+  | "SESSIONS_SOURCE_UNAVAILABLE"
+  | "SESSIONS_UNSUPPORTED_FORMAT"
+  | "SESSIONS_INVALID_INPUT"
+  | "SESSIONS_BUSY"
+  | "SESSIONS_RUNTIME_FAILURE"
+  | "SESSIONS_UNKNOWN_PROFILE"
+  | "SESSIONS_UNSUPPORTED_INTEGRATION";
+
+/** Typed error shared by every sessions surface. */
+export class SessionsError extends Error {
+  readonly code: SessionsErrorCode;
+
+  constructor(code: SessionsErrorCode, message: string) {
+    super(message);
+    this.name = "SessionsError";
+    this.code = code;
+  }
+}
+
+/** Errors that describe the caller's input rather than runtime state. */
+export const SESSIONS_VALIDATION_CODES: ReadonlySet<SessionsErrorCode> =
+  new Set([
+    "SESSIONS_NOT_CONFIGURED",
+    "SESSIONS_BINDING_MISMATCH",
+    "SESSIONS_SELECTION_REQUIRED",
+    "SESSIONS_DESTINATION_REQUIRED",
+    "SESSIONS_UNKNOWN_SOURCE",
+    "SESSIONS_UNKNOWN_COLLECTION",
+    "SESSIONS_UNSAFE_PATH",
+    "SESSIONS_UNSUPPORTED_FORMAT",
+    "SESSIONS_INVALID_INPUT",
+    "SESSIONS_UNKNOWN_PROFILE",
+    "SESSIONS_UNSUPPORTED_INTEGRATION",
+  ]);
+
+/**
+ * Typed, path-free error for remote surfaces (REST, MCP). Filesystem and
+ * store failures carry host paths in their messages; those stay in the
+ * server log.
+ */
+export function remoteSafeSessionsError(error: unknown): SessionsError {
+  if (error instanceof SessionsError) return error;
+  return new SessionsError(
+    "SESSIONS_RUNTIME_FAILURE",
+    "The session operation failed on the server (filesystem or index error); retry, or run the command locally for details."
+  );
+}

package/src/store/sqlite/adapter.ts

@@ -527,6 +527,30 @@ function isDatabaseLockedError(cause: unknown): boolean {
   );
 }
 
+/**
+ * Run a best-effort write without waiting for another writer: when the index
+ * is locked (SQLITE_BUSY) the write is skipped instead of blocking the event
+ * loop for the configured busy timeout.
+ */
+function withoutBusyWait(db: Database, write: () => void): void {
+  const current =
+    db.query<{ timeout: number }, []>("PRAGMA busy_timeout").get()?.timeout ??
+    0;
+  db.exec("PRAGMA busy_timeout = 0");
+  try {
+    write();
+  } catch (cause) {
+    const code = (cause as { code?: unknown } | null)?.code;
+    const busy =
+      code === "SQLITE_BUSY" ||
+      code === "SQLITE_LOCKED" ||
+      isDatabaseLockedError(cause);
+    if (!busy) throw cause;
+  } finally {
+    db.exec(`PRAGMA busy_timeout = ${current}`);
+  }
+}
+
 /** Resolve a caller-supplied busy_timeout, defaulting rather than using 0. */
 function resolveBusyTimeoutMs(busyTimeoutMs?: number): number {
   if (
@@ -811,6 +835,11 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     this.configPath = configPath;
   }
 
+  /** Path this adapter opened; names the index's request ledger. */
+  getDbPath(): string {
+    return this.dbPath;
+  }
+
   /**
    * Get raw SQLite database handle for vector operations.
    * Part of SqliteDbProvider interface - use with isSqliteDbProvider() type guard.
@@ -1202,9 +1231,12 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
         return ok(null);
       }
       if (row.fingerprint !== expectedFingerprint) {
-        db.run(
-          "DELETE FROM activation_receipts WHERE collection = ? AND connector_target = ?",
-          [collection, connectorTarget]
+        // Best-effort cleanup: a busy writer leaves the stale row for later.
+        withoutBusyWait(db, () =>
+          db.run(
+            "DELETE FROM activation_receipts WHERE collection = ? AND connector_target = ?",
+            [collection, connectorTarget]
+          )
         );
         return ok(null);
       }
@@ -1216,9 +1248,12 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
         receipt.collection !== row.collection ||
         (receipt.evidence.connectorTarget ?? "") !== row.connector_target
       ) {
-        db.run(
-          "DELETE FROM activation_receipts WHERE collection = ? AND connector_target = ?",
-          [collection, connectorTarget]
+        // Best-effort cleanup: a busy writer leaves the stale row for later.
+        withoutBusyWait(db, () =>
+          db.run(
+            "DELETE FROM activation_receipts WHERE collection = ? AND connector_target = ?",
+            [collection, connectorTarget]
+          )
         );
         return ok(null);
       }
@@ -1243,8 +1278,11 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
       if (!serialized.ok) {
         return err("INVALID_INPUT", serialized.error);
       }
-      db.run(
-        `INSERT INTO activation_receipts (
+      // A receipt is a cache: status paths on resident event loops must not
+      // busy-wait behind another writer (for example an import child).
+      withoutBusyWait(db, () =>
+        db.run(
+          `INSERT INTO activation_receipts (
            collection, connector_target, schema_version, fingerprint,
            receipt_json, updated_at
          ) VALUES (?, ?, ?, ?, ?, datetime('now'))
@@ -1253,13 +1291,14 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
            fingerprint = excluded.fingerprint,
            receipt_json = excluded.receipt_json,
            updated_at = datetime('now')`,
-        [
-          serialized.projected.collection,
-          serialized.connectorTarget,
-          serialized.projected.schemaVersion,
-          serialized.projected.fingerprint,
-          serialized.json,
-        ]
+          [
+            serialized.projected.collection,
+            serialized.connectorTarget,
+            serialized.projected.schemaVersion,
+            serialized.projected.fingerprint,
+            serialized.json,
+          ]
+        )
       );
       return ok(undefined);
     } catch (cause) {

package/src/store/sqlite/scoped-index.ts

@@ -2,6 +2,7 @@ import type { Config } from "../../config/types";
 
 import { getIndexDbPath } from "../../app/constants";
 import { indexesMatch } from "../../core/indexed-reference";
+import { assertSessionBinding } from "../../sessions/binding";
 import { SqliteAdapter } from "./adapter";
 
 export interface ScopedIndexStore {
@@ -36,6 +37,14 @@ export async function openScopedIndexStore(options: {
     );
   }
 
+  // A session archive index only opens with its own archive config.
+  await assertSessionBinding({
+    config: options.config,
+    configPath: options.configPath ?? "<inline-config>",
+    indexName: requestedIndexName ?? "default",
+    dbPath,
+  });
+
   const store = new SqliteAdapter();
   store.setConfigPath(options.configPath ?? "<inline-config>");
   const openResult = await store.open(

package/browser-extension/artifacts/gno-browser-clipper-v2.5.1.zip.sha256

@@ -1 +0,0 @@
-61f94e89a85a038072704ca3bc398c38c264cf6b9a09e2e891058d1d7795a453  gno-browser-clipper-v2.5.1.zip