@crossworks/client-types 0.230.43

package/src/search-query.ts

@@ -0,0 +1,103 @@
+/**
+ * Query-param parsing for `GET /api/search` — the owner-facing HTTP twin of
+ * the `search_nodes` / `search_chunks` MCP tools (mobile companion's search).
+ * Pure so it can be unit-tested without the route runtime.
+ */
+
+/** Mirrors the `search_nodes` tool's `type` enum — the API's contract. */
+export const SEARCH_NODE_TYPES = [
+  'branch',
+  'email',
+  'email_thread',
+  'file',
+  'note',
+  'page',
+  'sermon',
+  'contact',
+  'task',
+  'event',
+  'printer_project',
+  'telegram_message',
+  'documentation',
+  'journal',
+  'formula',
+  'draw',
+] as const;
+
+export type SearchNodeType = (typeof SEARCH_NODE_TYPES)[number];
+
+export type SearchApiQuery = {
+  q: string;
+  mode: 'nodes' | 'chunks';
+  type?: SearchNodeType;
+  branch?: string;
+  tags?: string[];
+  limit: number;
+};
+
+const MAX_Q = 500;
+const MAX_TAGS = 10;
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 50;
+// `branch` is cast to ::ltree server-side; reject anything that would make
+// the cast throw instead of surfacing a 500 — including over-long labels
+// (Postgres caps ltree labels at 255 chars).
+const LTREE_RE = /^[a-z0-9_]+(\.[a-z0-9_]+)*$/i;
+const MAX_BRANCH = 500;
+const MAX_LTREE_LABEL = 255;
+
+export function parseSearchQuery(sp: URLSearchParams): SearchApiQuery | { error: string } {
+  const q = (sp.get('q') ?? '').trim();
+  if (!q) return { error: 'q required' };
+  if (q.length > MAX_Q) return { error: `q too long (max ${MAX_Q})` };
+
+  const modeRaw = sp.get('mode') ?? 'nodes';
+  if (modeRaw !== 'nodes' && modeRaw !== 'chunks') {
+    return { error: "mode must be 'nodes' or 'chunks'" };
+  }
+
+  let type: SearchNodeType | undefined;
+  const typeRaw = sp.get('type')?.trim();
+  if (typeRaw) {
+    if (!(SEARCH_NODE_TYPES as readonly string[]).includes(typeRaw)) {
+      return { error: `unknown type '${typeRaw}'` };
+    }
+    type = typeRaw as SearchNodeType;
+  }
+
+  let branch: string | undefined;
+  const branchRaw = sp.get('branch')?.trim();
+  if (branchRaw) {
+    if (
+      branchRaw.length > MAX_BRANCH ||
+      !LTREE_RE.test(branchRaw) ||
+      branchRaw.split('.').some((label) => label.length > MAX_LTREE_LABEL)
+    ) {
+      return { error: 'invalid branch' };
+    }
+    branch = branchRaw;
+  }
+
+  let tags: string[] | undefined;
+  const tagsRaw = sp.get('tags')?.trim();
+  if (tagsRaw) {
+    tags = tagsRaw
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean)
+      .slice(0, MAX_TAGS);
+    if (tags.length === 0) tags = undefined;
+  }
+
+  let limit = DEFAULT_LIMIT;
+  const limitRaw = sp.get('limit');
+  if (limitRaw != null && limitRaw !== '') {
+    // Number(), not parseInt: '1e3' must clamp to 50, not truncate to 1;
+    // fractional/garbage input is a 400, not a silent guess.
+    const n = Number(limitRaw);
+    if (!Number.isInteger(n) || n < 1) return { error: 'invalid limit' };
+    limit = Math.min(n, MAX_LIMIT);
+  }
+
+  return { q, mode: modeRaw, type, branch, tags, limit };
+}

package/src/slugify.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import { slugify } from './slugify';
+
+// ── Legacy implementations, verbatim from the pre-centralisation call sites ──
+// The centralised `slugify(input, opts)` must reproduce each of these byte-for-
+// byte for every representative input, because their outputs are (or seed)
+// stored identity slugs. If one of these ever needs to change, that is a
+// migration, not a refactor — this file is the tripwire.
+
+// agents-client.tsx / (docs seeds this without the cap)
+const legacyNoUnderscore64 = (s: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+
+// docs/new-collection-dialog.tsx (no cap, has a redundant .trim())
+const legacyDocs = (s: string) =>
+  s
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+// skills / heartbeats / tool-groups / tools
+const legacyAllowUnderscore64 = (s: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+
+// dev-tools/save-tool-dialog.tsx (underscore separator)
+const legacySaveTool = (s: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 64);
+
+// api/export/[id]/route.ts (cap 80, 'export' fallback)
+const legacyExport = (title: string) => {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+  return slug || 'export';
+};
+
+// lib/ai-workers.ts (cap 60)
+const legacyAiWorker = (name: string) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-+|-+$)/g, '')
+    .slice(0, 60);
+
+const INPUTS = [
+  '',
+  '   ',
+  'Hello World',
+  'Hello   World',
+  '  leading and trailing  ',
+  'already-a-slug',
+  'snake_case_name',
+  'mixed_-_separators',
+  'UPPER.case/Punct!uation?',
+  'Q1/Q2 2026 report',
+  'dots.and-dashes_and spaces',
+  '---leading-dashes---',
+  '___leading_underscores___',
+  'web_search',
+  'a'.repeat(200),
+  'x_'.repeat(50),
+  'café résumé',
+  '你好 world',
+  '!!!',
+  '- _ - _',
+  'tab\tand\nnewline',
+  '123 numbers 456',
+];
+
+describe('slugify — byte-identical to every legacy call-site behaviour', () => {
+  it('matches the no-underscore / cap-64 profile (agents)', () => {
+    for (const s of INPUTS) {
+      expect(slugify(s, { maxLength: 64 })).toBe(legacyNoUnderscore64(s));
+    }
+  });
+
+  it('matches the docs profile (no cap, canonical default)', () => {
+    for (const s of INPUTS) {
+      expect(slugify(s)).toBe(legacyDocs(s));
+    }
+  });
+
+  it('matches the allow-underscore / cap-64 profile (skills, heartbeats, tool-groups, tools)', () => {
+    for (const s of INPUTS) {
+      expect(slugify(s, { allowUnderscore: true, maxLength: 64 })).toBe(legacyAllowUnderscore64(s));
+    }
+  });
+
+  it('matches the underscore-separator profile (save-tool)', () => {
+    for (const s of INPUTS) {
+      expect(slugify(s, { allowUnderscore: true, separator: '_', maxLength: 64 })).toBe(
+        legacySaveTool(s),
+      );
+    }
+  });
+
+  it('matches the export profile (cap 80, "export" fallback)', () => {
+    for (const s of INPUTS) {
+      expect(slugify(s, { maxLength: 80, fallback: 'export' })).toBe(legacyExport(s));
+    }
+  });
+
+  it('matches the ai-worker profile (cap 60)', () => {
+    for (const s of INPUTS) {
+      expect(slugify(s, { maxLength: 60 })).toBe(legacyAiWorker(s));
+    }
+  });
+});
+
+describe('slugify — canonical behaviour and edge cases', () => {
+  it('lower-cases and hyphenates runs of illegal characters', () => {
+    expect(slugify('Hello   World!!')).toBe('hello-world');
+  });
+
+  it('trims leading/trailing separators', () => {
+    expect(slugify('--Hello--')).toBe('hello');
+  });
+
+  it('drops underscores by default but keeps them with allowUnderscore', () => {
+    expect(slugify('a_b')).toBe('a-b');
+    expect(slugify('a_b', { allowUnderscore: true })).toBe('a_b');
+  });
+
+  it('collapses to the empty string (or fallback) for all-unicode / all-punctuation input', () => {
+    expect(slugify('你好')).toBe('');
+    expect(slugify('!!!')).toBe('');
+    expect(slugify('!!!', { fallback: 'export' })).toBe('export');
+  });
+
+  it('applies the length cap after trimming (a cut can leave a trailing separator)', () => {
+    // 'ab cd' -> 'ab-cd'; cap at 3 -> 'ab-' (mirrors the originals' slice-last order).
+    expect(slugify('ab cd', { maxLength: 3 })).toBe('ab-');
+  });
+
+  it('has no cap by default', () => {
+    const long = 'x'.repeat(500);
+    expect(slugify(long)).toHaveLength(500);
+  });
+
+  it('uses the given separator for both joining and end-trimming', () => {
+    expect(slugify('a b c', { allowUnderscore: true, separator: '_' })).toBe('a_b_c');
+    expect(slugify('__a b__', { allowUnderscore: true, separator: '_' })).toBe('a_b');
+  });
+});

package/src/slugify.ts

@@ -0,0 +1,71 @@
+/**
+ * Canonical slug normaliser for the web app.
+ *
+ * ── Divergence history (audit item #5a) ──────────────────────────────────────
+ * Roughly ten screens each grew their own private `slugify` by copy-paste, and
+ * they drifted apart into subtly incompatible rules:
+ *   - agents / ai-workers / docs / export: strip `_` (alnum + `-` only)
+ *   - skills / heartbeats / tool-groups / tools: KEEP `_` (it's a legal char in
+ *     those slug namespaces)
+ *   - save-tool: KEEP `_` AND join with `_` instead of `-` (tool slugs like
+ *     `web_search` read as underscore-cased)
+ *   - length caps ranged over {none, 60, 64, 80}
+ *   - the export route adds a `'export'` fallback for empty titles
+ * So the "same" typed name produced different slugs on different screens.
+ *
+ * These differences are NOT all accidental: an agent slug and a skill slug obey
+ * different server-side validation, so unifying them to one fixed behaviour
+ * would seed values the API then rejects. The options below exist precisely to
+ * preserve each call site's *legal* slug shape while sharing one implementation.
+ * DO NOT "simplify" them away — a stored slug that no longer round-trips orphans
+ * existing rows (agents, skills, tool groups, workers, folders keyed by slug).
+ *
+ * NOTE: the folder-slug helper in `files-client.tsx` intentionally does NOT use
+ * this — it *deletes* punctuation instead of turning it into a separator (a
+ * genuinely different normalisation for on-disk folder paths), so it stays
+ * separate and documented at its call site.
+ */
+
+export interface SlugifyOptions {
+  /** Keep `_` as a legal slug character instead of treating it as a separator.
+   *  Default `false` (underscores collapse into the separator). */
+  allowUnderscore?: boolean;
+  /** Hard cap on length, applied AFTER trimming separators (so, like the
+   *  originals, a cut can land mid-word and leave a trailing separator). Omit
+   *  for no cap. */
+  maxLength?: number;
+  /** Character that runs of illegal chars collapse into, and that is trimmed
+   *  from the ends. Default `'-'`; `save-tool` uses `'_'`. */
+  separator?: string;
+  /** Returned when normalisation yields an empty string (e.g. an all-unicode
+   *  title). Default `''`. */
+  fallback?: string;
+}
+
+function escapeForCharClassOrEnd(ch: string): string {
+  // Only `-` and `_` are ever passed as separators today; escape defensively so
+  // a future caller can't smuggle a regex metacharacter into the built pattern.
+  return ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Normalise free-form text into a URL/identifier-safe slug: lower-cased, with
+ * runs of illegal characters collapsed to a single separator and separators
+ * trimmed from both ends.
+ */
+export function slugify(input: string, opts: SlugifyOptions = {}): string {
+  const { allowUnderscore = false, maxLength, separator = '-', fallback = '' } = opts;
+
+  // Illegal chars = anything outside the keep-set. With underscores allowed we
+  // also keep `-`, mirroring the legacy `[^a-z0-9_-]` class; without, just alnum.
+  const keepClass = allowUnderscore ? 'a-z0-9_-' : 'a-z0-9';
+  const sep = escapeForCharClassOrEnd(separator);
+
+  let out = input
+    .toLowerCase()
+    .replace(new RegExp(`[^${keepClass}]+`, 'g'), separator)
+    .replace(new RegExp(`^${sep}+|${sep}+$`, 'g'), '');
+
+  if (maxLength != null) out = out.slice(0, maxLength);
+  return out || fallback;
+}

package/src/text-colors.ts

@@ -0,0 +1,18 @@
+/**
+ * Themed text (font) colour palette — twin of highlight-colors. Stores a TOKEN
+ * KEY (e.g. `chart-2`), never a raw colour, so coloured text tracks the active
+ * theme + light/dark. Unlike highlights (translucent tints) text uses the full
+ * token colour for legibility. Pure (no React) → safe in the server renderer.
+ */
+export const TEXT_COLOR_TOKENS = ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5'] as const;
+export type TextColorToken = (typeof TEXT_COLOR_TOKENS)[number];
+
+export function isTextColorToken(v: unknown): v is TextColorToken {
+  return typeof v === 'string' && (TEXT_COLOR_TOKENS as readonly string[]).includes(v);
+}
+
+/** CSS `color` for a text-colour token, or null if unknown. */
+export function textColor(token: unknown): string | null {
+  if (!isTextColorToken(token)) return null;
+  return `var(--${token})`;
+}

package/src/traces-format.ts

@@ -0,0 +1,77 @@
+/**
+ * Pure types + format helpers for traces. No DB imports. Safe to pull
+ * into a client component without dragging postgres-js / pg-boss /
+ * other Node-only modules into the browser bundle.
+ *
+ * Server-only data fetching lives in `./traces.ts`, which re-exports
+ * everything from this file so existing server callers don't need to
+ * update their import sites.
+ */
+
+export type TraceSummary = {
+  id: string;
+  kind: string;
+  status: string;
+  startedAt: string;
+  finishedAt: string | null;
+  durationMs: number | null;
+  costMicroUsd: number;
+  tokensIn: number;
+  tokensOut: number;
+  tokensCacheRead: number;
+  stepCount: number;
+  subjectKind: string | null;
+  subjectId: string | null;
+  agentName: string | null;
+  agentSlug: string | null;
+  error: string | null;
+};
+
+export type TraceSort = 'started' | 'cost' | 'duration';
+export type TraceSortDir = 'asc' | 'desc';
+
+export type TraceFilter = {
+  kinds?: string[];
+  statuses?: string[];
+  sinceHours?: number;
+  limit?: number;
+  offset?: number;
+  sort?: TraceSort;
+  dir?: TraceSortDir;
+};
+
+export type TraceStepSummary = {
+  id: string;
+  parentStepId: string | null;
+  ordinal: number;
+  name: string;
+  kind: string;
+  status: string;
+  startedAt: string;
+  finishedAt: string | null;
+  durationMs: number | null;
+  input: Record<string, unknown>;
+  output: Record<string, unknown>;
+  meta: Record<string, unknown>;
+  error: string | null;
+};
+
+export type TraceDetail = TraceSummary & {
+  data: Record<string, unknown>;
+  steps: TraceStepSummary[];
+};
+
+export function formatMicroUsd(microUsd: number): string {
+  if (microUsd === 0) return '$0';
+  const usd = microUsd / 1_000_000;
+  if (usd >= 1) return `$${usd.toFixed(2)}`;
+  if (usd >= 0.01) return `$${usd.toFixed(3)}`;
+  return `$${usd.toFixed(4)}`;
+}
+
+export function formatDuration(ms: number | null): string {
+  if (ms == null) return '—';
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60_000).toFixed(1)}m`;
+}

package/src/turn-streaming.ts

@@ -0,0 +1,37 @@
+/**
+ * Live turn streaming feature flags.
+ *
+ * The feature (SSE status trail + token streaming, see
+ * `docs/live-turn-streaming.md`) is **on by default**. It used to be dark-by-
+ * default behind `MANTLE_TURN_STREAMING=1`, but that put the on-switch in an
+ * env var that has to be set at BUILD time on the client (a `NEXT_PUBLIC_*`
+ * inline) — easy to forget, invisible once wrong, and the reason a deployed box
+ * could silently show only the static thinking bubble. So the default flipped:
+ * the env vars are now an *off* switch (a backup), and a server that wants the
+ * feature dark sets `MANTLE_TURN_STREAMING=0`. The stream route 404s when off;
+ * the client treats that 404 as a clean fallback (no reconnect loop), so the
+ * server stays the single source of truth even though the client flag is baked
+ * at build.
+ */
+
+/** A flag is ON unless explicitly disabled with 0/false/off/no (case-insensitive).
+ *  Unset → on. */
+function flagOn(raw: string | undefined): boolean {
+  const v = raw?.trim().toLowerCase();
+  return v !== '0' && v !== 'false' && v !== 'off' && v !== 'no';
+}
+
+/** Server-side master gate: the SSE/cancel routes exist and the POST turn route
+ *  goes non-blocking. Off only when `MANTLE_TURN_STREAMING` is explicitly falsy. */
+export function isTurnStreamingEnabled(): boolean {
+  return flagOn(process.env.MANTLE_TURN_STREAMING);
+}
+
+/** Client-side twin, compiled into the browser bundle. Defaults on (an unset
+ *  `NEXT_PUBLIC_MANTLE_TURN_STREAMING` → on), so the browser opens the stream;
+ *  if the server has it off the GET route 404s and the client falls back
+ *  cleanly. Set `NEXT_PUBLIC_MANTLE_TURN_STREAMING=0` at build to compile it
+ *  out entirely. */
+export function isTurnStreamingEnabledClient(): boolean {
+  return flagOn(process.env.NEXT_PUBLIC_MANTLE_TURN_STREAMING);
+}

package/src/types/integrity.ts

@@ -0,0 +1,164 @@
+/**
+ * Integrity surface — shared types.
+ *
+ * Two read-only views, no synthetic fixtures:
+ *   • Live (`landed.ts`) — observes the *real* content you add (notes, pages,
+ *     tasks, events, contacts, secrets, files, email) as it lands in the brain,
+ *     and reports its per-type footprint (L6 node · L5 summary/embedding/tsv ·
+ *     L4 facts · graph edges · the extractor_run trace). Honest by design: a
+ *     secret keeps its sealed body out of the LLM, a scanned image with no
+ *     vision worker *correctly* skips — those read neutral, not red.
+ *   • Corpus audit (`audit.ts`) — scans the *existing* corpus for invariant
+ *     violations (no writes, no cost).
+ *
+ * See docs/data-flow-tracing.md (the signature table) and docs/journey.md
+ * (the action→layer map) for the behaviour these footprints encode.
+ */
+
+export type CheckStatus = 'pass' | 'fail' | 'info';
+
+export type CheckResult = {
+  /** Short column-ish label: "Trace", "L5 summary", "Emb 768", … */
+  label: string;
+  status: CheckStatus;
+  /** Actual-vs-expected detail, shown on hover / in the expanded row. */
+  detail?: string;
+};
+
+/** The structural footprint of one node, read straight from the brain tables. */
+export type ProbeFootprint = {
+  nodeId: string;
+  exists: boolean;
+  nodeType: string | null;
+  summary: string | null;
+  embDims: number | null;
+  hasTsv: boolean;
+  nFacts: number;
+  factKinds: string[];
+  /** mentioned_in edges (entity → node). */
+  nEntities: number;
+  /** Duplicate mentioned_in edges (same entity → node twice) — must be 0 if the
+   *  extractor rebuilds idempotently rather than appending on re-extract. */
+  dupMentionEdges: number;
+  /** content_chunks rows for this node. */
+  nChunks: number;
+  run: {
+    traceId: string;
+    startedAt: string;
+    status: string;
+    disposition: string | null;
+    stepNames: string[];
+    costMicroUsd: number;
+  } | null;
+};
+
+/** One optional service/worker's readiness. */
+export type Capability = { available: boolean; detail: string };
+
+/** Brain-readiness snapshot. */
+export type Capabilities = {
+  tika: Capability;
+  vision: Capability;
+  extractor: Capability;
+  embedding: Capability;
+  summarizer: Capability;
+  reflector: Capability;
+  stt: Capability;
+};
+
+// ─── live landed view ───────────────────────────────────────────────────────
+
+export type LandedState =
+  /** Inserted, extractor hasn't terminated yet — transient; flips on node_indexed. */
+  | 'indexing'
+  /** Success + the expected layers landed (summary · 768-dim embedding · tsv). */
+  | 'ok'
+  /** Correctly skipped (e.g. a scanned image with no vision worker) — shows why. */
+  | 'skipped'
+  /** Success but a layer is missing (silent-miss / dim drift / duplicate edges). */
+  | 'fail'
+  /** No extractor_run after the stall window — is apps/agent + an extractor up? */
+  | 'stalled';
+
+export type LandedItem = {
+  nodeId: string;
+  nodeType: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  footprint: ProbeFootprint;
+  state: LandedState;
+  checks: CheckResult[];
+};
+
+export type LandedReport = {
+  generatedAt: string;
+  items: LandedItem[];
+  capabilities: Capabilities;
+  /** Total nodes matching the current type filter (ignores limit/offset) — the
+   *  denominator the pager needs, since `items` is one page. */
+  total: number;
+};
+
+// ─── passive corpus audit ───────────────────────────────────────────────────
+//
+// The read-only health scan of the *existing* brain for invariant violations
+// (no writes, no fixtures, no cost): "is what's already stored consistent?".
+
+export type AuditSeverity = 'high' | 'medium' | 'low';
+
+/** One offending row, with enough to drill in. */
+export type AuditSample = { id: string; kind: string; detail: string };
+
+export type AuditCheck = {
+  key: string;
+  label: string;
+  severity: AuditSeverity;
+  /** One-line explanation of the invariant + why a violation matters. */
+  note: string;
+  count: number;
+  /** True if the violation count hit the query cap (so `count` is a floor). */
+  capped: boolean;
+  ok: boolean;
+  samples: AuditSample[];
+  /** Age span (oldest/newest, `YYYY-MM-DD`) of the offending rows — uncapped,
+   *  so it reflects the true range even when `count` is floored. Lets the UI
+   *  tell pre-fix *sediment* (all old) apart from a *live* regression (recent).
+   *  null when the check has no natural timestamp or zero violations. */
+  oldestAt: string | null;
+  newestAt: string | null;
+};
+
+export type AuditReport = {
+  generatedAt: string;
+  checks: AuditCheck[];
+  totalViolations: number;
+};
+
+// ─── system config integrity ────────────────────────────────────────────────
+//
+// Read-only check of the agent/skill/tool/worker CONFIG graph against the
+// declarative manifest (apps/web/lib/system-manifest). Catches the silent-drop
+// cases the runtime resolvers hide: an agent referencing a skill/tool that has
+// no row, a specialist not wired into the persona's delegate_to, a default
+// worker missing for a kind. Same severity vocabulary as the corpus audit.
+
+export type SystemSample = { id: string; detail: string };
+
+export type SystemCheck = {
+  key: string;
+  label: string;
+  severity: AuditSeverity;
+  ok: boolean;
+  /** Human-readable state — what's right, or what's broken + why it matters. */
+  detail: string;
+  /** Offending specifics (dangling slugs, unlinked skills, missing agents). */
+  samples?: SystemSample[];
+};
+
+export type SystemReport = {
+  generatedAt: string;
+  checks: SystemCheck[];
+  /** Number of checks that are not ok. */
+  problems: number;
+};