@crossworks/client-types 0.232.127 → 0.232.140

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/client-types",
-  "version": "0.232.127",
+  "version": "0.232.140",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/dto/agent-graph.ts

@@ -0,0 +1,229 @@
+/**
+ * @mantle/client-types · agent-graph
+ *
+ * Skills, tools, tool groups and AI workers — the pieces an agent is
+ * assembled from.
+ *
+ * Split out of the 2548-line index.ts on 2026-09-02 (audit, tier 3) with the
+ * contents unchanged. index.ts re-exports every one of these, so the package's
+ * public surface is byte-identical — only the file a symbol lives in moved.
+ */
+
+// ── Skills ────────────────────────────────────────────────────────────────────
+
+/** A skill as returned by `GET /api/skills`. */
+export interface SkillDTO {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  instructions: string;
+  /** Template state heartbeats inherit on create. */
+  defaultState: Record<string, unknown>;
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** A heartbeat that references a skill — drives the "used by N heartbeats" badge. */
+export interface HeartbeatRef {
+  slug: string;
+  name: string;
+  status: string;
+}
+
+/** `GET /api/skills/backrefs` — heartbeat refs keyed by skill slug. */
+export type SkillBackrefs = Record<string, HeartbeatRef[]>;
+
+// ── Tools ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Tool handler descriptor — the canonical wire shape. Mirrors @mantle/db's
+ * `ToolHandler` union; kept standalone here so this package stays zero-dep (no
+ * postgres type graph). Drift is caught where it matters: `@mantle/tools` aliases
+ * `ToolSummary = ToolDTO`, so if db's union ever diverges from this one, that
+ * package fails to compile.
+ */
+export interface RecipeStep {
+  tool: string;
+  input?: Record<string, unknown>;
+  as?: string;
+}
+
+export type ToolHandler =
+  | { kind: 'builtin'; ref: string }
+  | {
+      kind: 'http';
+      url: string;
+      method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+      headers?: Record<string, string>;
+      query?: Record<string, string>;
+      body?: string | null;
+      headersRef?: string | null;
+      authRef?: string | null;
+      timeoutMs?: number;
+      /** Provenance on rows materialised by an OpenAPI connector's sync. */
+      openapi?: { group: string; op: string; vanishedAt?: string; editedAt?: string };
+    }
+  | { kind: 'shell'; cmd: string }
+  | { kind: 'mcp'; group: string; toolName: string; vanishedAt?: string }
+  | { kind: 'recipe'; steps: RecipeStep[]; output?: unknown };
+
+/** A tool as returned by `GET /api/tools`. */
+export interface ToolDTO {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: ToolHandler;
+  requiresConfirm: boolean;
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** `GET/PUT /api/tools/settings` — the two owner-level tool policy toggles. */
+export interface ToolSettings {
+  /** Tools an agent authors (Toolsmith) start confirm-gated until cleared. */
+  requireApproval: boolean;
+  /** Unattended heartbeats park email/web calls for approval. */
+  egressGate: boolean;
+}
+
+// ── Tool groups ───────────────────────────────────────────────────────────────
+
+/**
+ * The service binding on a group that IS an API integration: where its calls go,
+ * which vault entry authenticates them, where that credential is placed, and
+ * pointers to the stored API docs + usage skill. Mirrors the `ToolGroupIntegration`
+ * type in @mantle/db. `secretRef` is a `service/label` pointer and auth-template
+ * values are `{{secret:…}}` refs — a plaintext key never crosses this wire.
+ */
+export interface ToolGroupIntegrationDTO {
+  service: string;
+  baseUrl?: string;
+  secretRef?: string;
+  authTemplate?: {
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+  };
+  docsNodeId?: string;
+  docsSourceUrl?: string;
+  docsUpdatedAt?: string;
+  /** Slug of the usage skill that travels with this group's grant. */
+  skillSlug?: string;
+  /** Set when the group is an MCP CONNECTOR — a mirror of an external MCP
+   *  server's tools. `secretRef` is a `service/label` vault pointer; the
+   *  sync-bookkeeping fields are written by the connector sync. */
+  mcp?: {
+    url: string;
+    secretRef?: string;
+    authHeader?: string;
+    authScheme?: string;
+    /** OAuth bookkeeping when the server uses the MCP auth flow. Tokens and
+     *  the client registration are vault-sealed and never cross this wire. */
+    oauth?: {
+      enabled: true;
+      status: 'pending' | 'connected' | 'needs_reconnect';
+      clientId?: string;
+      pending?: { state: string; redirectUri: string; startedAt: string };
+      redirectUri?: string;
+      tokenExpiresAt?: string;
+      connectedAt?: string;
+      lastError?: string;
+    };
+    lastSyncAt?: string;
+    toolCount?: number;
+    serverInfo?: { name?: string; version?: string };
+  };
+  /** Set when the group is an OPENAPI CONNECTOR — its operations are compiled
+   *  into ordinary http tools by the connector sync. Auth stays on the
+   *  surrounding integration fields (`baseUrl`/`secretRef`/`authTemplate`),
+   *  never in this block; the sync-bookkeeping fields are written by the sync. */
+  openapi?: {
+    specUrl: string;
+    specHash?: string;
+    selection?: { tags?: string[]; operations?: string[] };
+    apiTitle?: string;
+    apiVersion?: string;
+    lastSyncAt?: string;
+    toolCount?: number;
+  };
+}
+
+/** A tool group — a named bundle of tool slugs granted to agents wholesale. */
+export interface ToolGroupDTO {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  toolSlugs: string[];
+  /** Set when the group is an API integration; null for capability-only bundles. */
+  integration: ToolGroupIntegrationDTO | null;
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** `GET /api/tool-groups` — each group plus which agent slugs grant it. */
+export interface ToolGroupWithRefs extends ToolGroupDTO {
+  grantedTo: string[];
+}
+
+// ── AI workers ────────────────────────────────────────────────────────────────
+
+/** Worker kinds (mirrors the @mantle/db `ai_worker_kind` enum). Drift is caught
+ *  by `toAiWorkerDTO` in lib/ai-workers, whose mapping won't compile if the db
+ *  enum gains/renames a value. */
+export type AiWorkerKind =
+  | 'reflector'
+  | 'extractor'
+  | 'summarizer'
+  | 'tts'
+  | 'stt'
+  | 'vision'
+  | 'document'
+  | 'image_gen'
+  | 'embedding'
+  | 'search'
+  | 'search_advanced'
+  | 'narrator'
+  | 'suggester';
+
+/** An AI worker as returned by `GET /api/ai-workers`. `params` is jsonb (shape
+ *  varies by kind) — kept loose here; the form narrows per kind. */
+export interface AiWorkerDTO {
+  id: string;
+  slug: string;
+  name: string;
+  kind: AiWorkerKind;
+  provider: string;
+  model: string;
+  apiKeyId: string | null;
+  systemPrompt: string | null;
+  params: Record<string, unknown>;
+  enabled: boolean;
+  priority: number;
+  isDefault: boolean;
+  backupProvider: string | null;
+  backupModel: string | null;
+  backupApiKeyId: string | null;
+  backupEnabled: boolean;
+  baseUrl: string | null;
+  viaTailnet: boolean;
+  backupBaseUrl: string | null;
+  backupViaTailnet: boolean;
+  usageCount: number;
+  lastUsedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** `GET /api/ai-workers/config` — static-ish bits the worker form needs. */
+export interface AiWorkerConfig {
+  /** Providers with a native-PDF document adapter (vs. rasterize-at-ingest). */
+  nativeDocProviders: string[];
+  /** Online tailnet peer MagicDNS names (route base-URL datalist). */
+  tailnetPeers: string[];
+}

package/src/dto/agents.ts

@@ -0,0 +1,190 @@
+/**
+ * @mantle/client-types · agents
+ *
+ * Agents themselves: role, avatar, memory/params jsonb, persona notes and
+ * the experience readout.
+ *
+ * Split out of the 2548-line index.ts on 2026-09-02 (audit, tier 3) with the
+ * contents unchanged. index.ts re-exports every one of these, so the package's
+ * public surface is byte-identical — only the file a symbol lives in moved.
+ */
+
+// ── Agents ────────────────────────────────────────────────────────────────────
+
+/** Conversational + worker roles an agent row can carry. Mirrors the
+ *  `agent_role` enum (`packages/db/src/schema/agents.ts`); the `/settings/agents`
+ *  page only lists the conversational ones. */
+export type AgentRole =
+  | 'assistant'
+  | 'responder'
+  | 'extractor'
+  | 'summarizer'
+  | 'reflector'
+  | 'custom'
+  // Runner-queue worker template (docs/runs.md) — never conversational.
+  | 'worker';
+
+/** Per-agent generated avatar (style + seed → DiceBear). null = initials. */
+export interface AgentAvatarDTO {
+  style: string;
+  seed: string;
+  /** Avatar-builder component choices layered over the seed: component name →
+   *  pinned variant, or null to hide an optional component. Stale entries
+   *  (from another style) are ignored at render time.
+   *
+   *  READ: absent = seed only. WRITE protocol (agents create/patch): an
+   *  ABSENT parts key means "keep what's stored" — so a parts-unaware client
+   *  can never wipe pins — `{}` is the explicit clear, and a non-empty map
+   *  replaces. Every client that writes avatars must send `{}` to clear. */
+  parts?: Record<string, string | null>;
+}
+
+/** Memory/budget tuning (jsonb). All fields optional — empty = runtime defaults.
+ *  Replicated standalone (NOT re-exported from @mantle/db) to keep this package
+ *  zero-dep; the server aliases its `AgentMemoryConfig` against this so drift is
+ *  a compile error. */
+export interface AgentMemoryConfigDTO {
+  history_limit?: number;
+  history_window_hours?: number | null;
+  digest_limit?: number;
+  fact_limit?: number;
+  content_hit_limit?: number;
+  chunk_limit?: number;
+  inject_journal?: boolean;
+  inject_working_notes?: boolean;
+  summarize_threshold?: number;
+  summarize_batch?: number;
+  extract_types?: string[];
+  extract_facts?: boolean;
+  extract_cost_cap_micro_usd?: number | null;
+  delegate_to?: string[];
+  max_iterations?: number;
+  result_handling?: {
+    inline_max_kb?: number;
+    embed_min_kb?: number;
+    spill_max_kb?: number;
+  };
+}
+
+/** Sampling + voice-reply params (jsonb). */
+export interface AgentParamsDTO {
+  temperature?: number;
+  max_tokens?: number;
+  top_p?: number;
+  max_retries?: number;
+  voice?: {
+    enabled?: boolean;
+    name?: 'alloy' | 'echo' | 'fable' | 'nova' | 'onyx' | 'shimmer';
+    model?: 'tts-1' | 'tts-1-hd';
+    speed?: number;
+  };
+  /** Propose a follow-up question after each completed turn (the suggester
+   *  worker's chip above the chat composer). Absent/false = off. */
+  suggest_follow_up?: boolean;
+}
+
+/** One persona note (jsonb element). Soft-retired, never deleted — the read
+ *  path filters `retiredAt`. `at`/`retiredAt` are ISO strings. */
+export interface PersonaNoteDTO {
+  id?: string;
+  kind: 'style' | 'relationship' | 'correction';
+  content: string;
+  at: string;
+  source?: { type: 'turn' | 'digest'; id: string };
+  retiredAt?: string;
+  retiredReason?: 'superseded' | 'removed';
+  supersededBy?: string;
+}
+
+/** Raw counters behind an agent's experience level — always shipped next to
+ *  the level so the UI can show WHY it is level N. All are lifetime counts for
+ *  THIS brain (experience is per-brain, display-only — never a trust gate). */
+export interface AgentExperienceComponentsDTO {
+  /** Completed conversation turns this agent answered on the assistant
+   *  stream (web, Telegram, mobile). Team/forum turns live in a different
+   *  store and are not counted (yet). */
+  turns: number;
+  /** Tool calls that succeeded across those turns. */
+  toolSuccesses: number;
+  /** Delegated runs this agent completed for other agents. */
+  delegations: number;
+  /** Heartbeat fires this agent completed. */
+  heartbeats: number;
+}
+
+/** An agent's experience readout — a soft-capped level derived from real
+ *  accumulated usage (see `agent-experience.ts` server-side for the weights
+ *  and curve). Computed at read time; nothing is stored. */
+export interface AgentExperienceDTO {
+  level: number;
+  /** Total XP earned. */
+  xp: number;
+  /** Cumulative XP at which the current level began. */
+  levelXp: number;
+  /** Cumulative XP needed to reach the next level. */
+  nextLevelXp: number;
+  components: AgentExperienceComponentsDTO;
+}
+
+/** An agent as returned by `GET /api/agents` (and `…/[id]`). Dates are ISO
+ *  strings. The server aliases its `AgentSummary` to this so the wire shape and
+ *  the consuming client can't drift. */
+export interface AgentDTO {
+  id: string;
+  slug: string;
+  name: string;
+  description: string | null;
+  role: AgentRole;
+  provider: string;
+  model: string;
+  apiKeyId: string | null;
+  backupProvider: string | null;
+  backupModel: string | null;
+  backupApiKeyId: string | null;
+  backupEnabled: boolean;
+  baseUrl: string | null;
+  viaTailnet: boolean;
+  backupBaseUrl: string | null;
+  backupViaTailnet: boolean;
+  ttsWorkerId: string | null;
+  systemPrompt: string;
+  skillSlugs: string[];
+  toolGroupSlugs: string[];
+  memoryConfig: AgentMemoryConfigDTO;
+  params: AgentParamsDTO;
+  avatar: AgentAvatarDTO | null;
+  personaNotes: PersonaNoteDTO[];
+  /** The co-admin login this agent is the personal assistant for (migration
+   *  0143), or null for a shared agent. Set, it becomes that login's default
+   *  chat target — the mechanism that keeps two people typing at once out of
+   *  one interleaved thread. Not a privacy boundary: every login still sees
+   *  and can open every agent. */
+  assignedUserId: string | null;
+  /** ISO timestamp of the current assignment; null when unassigned. */
+  assignedAt: string | null;
+  priority: number;
+  enabled: boolean;
+  /** True when this agent ships from the system manifest (a def-synced
+   *  specialist). Since 2026-07-29 only its params/memoryConfig tuning
+   *  re-syncs on upgrade — prompt, model, provider and key are operator-owned
+   *  and survive. Drives the "system" badge on the agents screens. */
+  manifestManaged: boolean;
+  lastUsedAt: string | null;
+  usageCount: number;
+  /** Experience readout (level + raw counters). Optional: filled on the list
+   *  reads the agent screens use (`GET /api/agents`, the assistant thread
+   *  bundle); absent on single-row CRUD echoes where computing it would cost
+   *  extra queries for nothing. */
+  experience?: AgentExperienceDTO;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** A lightweight agent option (slug + name + role) for picker dropdowns —
+ *  `GET /api/agents/options`. Unlike `GET /api/agents` (conversational roles
+ *  only), this lists EVERY agent, so heartbeats can bind worker-role agents. */
+export interface AgentOptionDTO {
+  slug: string;
+  name: string;
+  role: AgentRole;
+}

package/src/dto/comms.ts

@@ -0,0 +1,114 @@
+/**
+ * @mantle/client-types · comms
+ *
+ * Calendar feeds, Microsoft drives and the email reading pane.
+ *
+ * Split out of the 2548-line index.ts on 2026-09-02 (audit, tier 3) with the
+ * contents unchanged. index.ts re-exports every one of these, so the package's
+ * public surface is byte-identical — only the file a symbol lives in moved.
+ */
+
+// ── Calendar ────────────────────────────────────────────────────────────────────
+
+/** A subscribed calendar feed as returned by `GET /api/calendar` — the wire
+ *  projection of @mantle/db's `CalendarAccount` row. The sealed `feedUrlEnc`
+ *  credential, `ownerId`, and `syncState` are server-only and intentionally
+ *  omitted; dates are ISO strings. The route maps its rows to this so the wire
+ *  shape and the consuming client can't drift. */
+export interface CalendarAccountDTO {
+  id: string;
+  /** 'ics' (future: 'google' | 'microsoft'). */
+  provider: string;
+  displayName: string;
+  /** Optional UI accent (hex) so multiple calendars are distinguishable. */
+  color: string | null;
+  enabled: boolean;
+  lastEventCount: number | null;
+  lastSyncAt: string | null;
+  lastSyncError: string | null;
+}
+
+// ── Microsoft (SharePoint / OneDrive) ───────────────────────────────────────────
+
+/** A discovered drive as returned by `GET/POST /api/microsoft/accounts/[id]/drives`
+ *  — the wire projection of @mantle/db's `MsDrive` row. The Graph `deltaLink`
+ *  cursor and `accountId` are server-only and omitted; `lastSyncAt` is an ISO
+ *  string. The route maps its rows to this so the shapes can't drift. */
+export interface MsDriveDTO {
+  id: string;
+  /** Graph drive id. */
+  driveId: string;
+  /** `personal` (OneDrive) | `documentLibrary` (SharePoint) | other. */
+  driveType: string;
+  name: string;
+  /** SharePoint site display name; null for OneDrive. */
+  siteName: string | null;
+  webUrl: string | null;
+  enabled: boolean;
+  lastSyncAt: string | null;
+  lastError: string | null;
+  /** How many scope selections the drive has; 0 = syncing everything. */
+  scopeCount: number;
+}
+
+/** One scope selection on a drive, as stored/returned by
+ *  `GET/PUT /api/microsoft/drives/[id]/scopes`. Folder scopes include the
+ *  whole subtree (path prefix); file scopes match that one item. */
+export interface MsDriveScopeDTO {
+  itemId: string;
+  /** After-`root:` path, always starting with `/` (e.g. `/Reports/2026`). */
+  path: string;
+  isFolder: boolean;
+  name: string | null;
+}
+
+/** One row of a drive-folder listing from
+ *  `GET /api/microsoft/drives/[id]/browse` — the scope picker's navigation
+ *  unit. Selection state is client-derived by matching against the scope set. */
+export interface MsDriveChildDTO {
+  itemId: string;
+  name: string;
+  isFolder: boolean;
+  childCount: number | null;
+  size: number | null;
+  path: string | null;
+  webUrl: string | null;
+}
+
+// ── Email (inbox reading pane) ──────────────────────────────────────────────────
+
+/** One message as returned by `GET /api/email/messages/[id]` — the wire
+ *  projection of @mantle/db's `Email` row, trimmed to what the reading pane
+ *  renders. Server-only/sensitive columns are dropped: the raw `bodyHtml` (it's
+ *  sanitized server-side into `MessageDetailDTO.bodyHtmlSafe` and must never
+ *  cross the wire untrusted), plus account/node/provider ids, labels, snippet,
+ *  etc. `internalDate` is an ISO string. */
+export interface EmailDTO {
+  id: string;
+  subject: string | null;
+  fromAddr: string;
+  fromName: string | null;
+  toAddrs: string[];
+  ccAddrs: string[];
+  internalDate: string;
+  folder: string | null;
+  isRead: boolean;
+  isStarred: boolean;
+  bodyText: string | null;
+}
+
+/** One attachment row returned with a message. */
+export interface EmailAttachmentDTO {
+  id: string;
+  filename: string;
+  mimeType: string | null;
+  sizeBytes: number | null;
+}
+
+/** `GET /api/email/messages/[id]` — a message, its attachments, and the
+ *  server-sanitized HTML body (the raw `bodyHtml` never crosses the wire). */
+export interface MessageDetailDTO {
+  email: EmailDTO;
+  attachments: EmailAttachmentDTO[];
+  bodyHtmlSafe: string | null;
+}

package/src/dto/heartbeats.ts

@@ -0,0 +1,60 @@
+/**
+ * @mantle/client-types · heartbeats
+ *
+ * Heartbeats — the brain on its own clock.
+ *
+ * Split out of the 2548-line index.ts on 2026-09-02 (audit, tier 3) with the
+ * contents unchanged. index.ts re-exports every one of these, so the package's
+ * public surface is byte-identical — only the file a symbol lives in moved.
+ */
+
+// ── Heartbeats ─────────────────────────────────────────────────────────────────
+
+/** A heartbeat's schedule (jsonb). `cron` is read-only in v1 (the form locks it);
+ *  create/update only accept once/interval/manual. `at` is an ISO string. */
+export type HeartbeatScheduleSpecDTO =
+  | { kind: 'once'; at: string }
+  | { kind: 'interval'; every_minutes: number; jitter_minutes?: number }
+  | { kind: 'cron'; expr: string }
+  | { kind: 'manual' };
+
+/** Where a heartbeat's reply is delivered (jsonb). */
+export type HeartbeatSurfaceDTO = { kind: 'telegram'; chat_id: string } | { kind: 'web' };
+
+/** Optional quiet-hours window (jsonb). null tz = use the profile timezone. */
+export interface HeartbeatQuietHoursDTO {
+  from: string;
+  to: string;
+  tz?: string | null;
+}
+
+/** A heartbeat as returned by `GET /api/heartbeats(/[id])`. Dates are ISO
+ *  strings. The server aliases its `HeartbeatSummary` to this so the wire shape
+ *  and the consuming client can't drift. */
+/** Alias kept for the heartbeats settings screens (formerly @server/lib/heartbeats). */
+export type HeartbeatSummary = HeartbeatDTO;
+
+export interface HeartbeatDTO {
+  id: string;
+  slug: string;
+  name: string;
+  description: string | null;
+  agentSlug: string;
+  skillSlug: string;
+  scheduleKind: 'once' | 'interval' | 'cron' | 'manual';
+  schedule: HeartbeatScheduleSpecDTO;
+  surface: HeartbeatSurfaceDTO;
+  nextFireAt: string | null;
+  lastFiredAt: string | null;
+  fireCount: number;
+  maxFires: number | null;
+  minIdleMinutes: number | null;
+  quietHours: HeartbeatQuietHoursDTO | null;
+  earliestAt: string | null;
+  cooldownMinutes: number | null;
+  state: Record<string, unknown>;
+  status: 'active' | 'paused' | 'completed' | 'cancelled';
+  completionReason: string | null;
+  createdAt: string;
+  updatedAt: string;
+}

package/src/dto/recall.ts

@@ -0,0 +1,21 @@
+/**
+ * @mantle/client-types · recall
+ *
+ * Recall — the owner's memory maps.
+ *
+ * Split out of the 2548-line index.ts on 2026-09-02 (audit, tier 3) with the
+ * contents unchanged. index.ts re-exports every one of these, so the package's
+ * public surface is byte-identical — only the file a symbol lives in moved.
+ */
+
+// ── Recall (memory maps) ─────────────────────────────────────────────────────
+
+export type {
+  RecallLintIssueDTO,
+  RecallLintSeverity,
+  RecallMapDetailDTO,
+  RecallMapSummaryDTO,
+  RecallNodeDTO,
+  RecallOptionDTO,
+  RecallPageStateDTO,
+} from '../types/recall';