@free-intelligence/core 1.1.0

package/src/conversation/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @free-intelligence/core — conversation library contract (DD-002B1).
+ *
+ * Local-first transcript persistence primitives: the record/summary types, the
+ * storage contract (ConversationLibrary), and pure helpers (title/preview
+ * derivation + privacy-by-structure sanitization). Adapters (IndexedDB, backend)
+ * implement ConversationLibrary in later layers — they live in fi-glass and the
+ * apps, never here.
+ */
+
+export type { ConversationRecord, ConversationSummary } from './record';
+export type { ConversationLibrary } from './library';
+export {
+  CONVERSATION_SCHEMA_VERSION,
+  createConversationRecord,
+  summarizeConversation,
+  deriveConversationTitle,
+  deriveConversationPreview,
+  sanitizeConversationMessage,
+  type CreateConversationRecordArgs,
+} from './helpers';

package/src/conversation/library.ts

@@ -0,0 +1,25 @@
+/**
+ * ConversationLibrary — the storage contract for local-first conversations.
+ *
+ * A pure async interface: adapters implement it over IndexedDB (fi-glass), a
+ * backend, or filesystem (later layers) without core taking a dependency on any
+ * of them. `list` returns light summaries (cheap); `get` hydrates one full
+ * record; `put` upserts; `delete`/`clear` remove. Keeping the contract in core
+ * is what stops a reusable persistence primitive from being trapped in a
+ * consumer app (DD-002-LESSON / framework-first-canary).
+ */
+
+import type { ConversationRecord, ConversationSummary } from './record';
+
+export interface ConversationLibrary {
+  /** All conversations as light summaries, newest `updatedAt` first. */
+  list(): Promise<ConversationSummary[]>;
+  /** The full record for `id`, or `null` if none. */
+  get(id: string): Promise<ConversationRecord | null>;
+  /** Insert or replace a record by its `id`. */
+  put(record: ConversationRecord): Promise<void>;
+  /** Remove the record for `id` (no-op if absent). */
+  delete(id: string): Promise<void>;
+  /** Remove every stored conversation. */
+  clear(): Promise<void>;
+}

package/src/conversation/record.ts

@@ -0,0 +1,38 @@
+/**
+ * ConversationRecord — the persisted shape of one local-first conversation.
+ *
+ * DD-002B1: og118 (and every future fi-glass shell) needs the transcript to
+ * survive a refresh and a list of past chats for a sidebar. The record is the
+ * unit a ConversationLibrary stores; the summary is the light row a sidebar
+ * lists without paying for the full message array. Pure data — no React, no
+ * browser, no transport. The `id` doubles as the backend session_id so the
+ * local transcript and the server's conversation store key the same thread.
+ */
+
+import type { ChatMessage } from '../chat/message';
+
+export interface ConversationRecord {
+  /** Stable id. Doubles as the backend session_id for the same thread. */
+  id: string;
+  /** Human-readable title, derived from the first user message. */
+  title: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+  /** ISO 8601 timestamp of the last change. */
+  updatedAt: string;
+  /** The thread, sanitized for storage (role/content/timestamp only). */
+  messages: ChatMessage[];
+  /** Snippet of the last non-empty message, for the sidebar. */
+  preview: string;
+  /** Schema version of this record, for forward migrations. */
+  schemaVersion: number;
+}
+
+/** A light row for listing conversations in a sidebar (no messages). */
+export interface ConversationSummary {
+  id: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  preview: string;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+// @free-intelligence/core — public surface.
+// Phase 1 ships the theme-token contract. Berkelio (97) adds the agent event
+// contract (Plan/Steps/Sources/Guard) below, material-agnostic; the fi-runner
+// stream client lands in a later phase.
+export type { ThemeTokens } from './theme/contract';
+export type {
+  VoiceAdapter,
+  VoiceOption,
+  AudioSource,
+  TranscriptResult,
+  TranscribeContext,
+} from './voice/adapter';
+export type { ChatMessage, ChatStreamingState } from './chat/message';
+export type { ChatHook } from './chat/hook';
+
+// Agent-turn contract (Berkelio). Types describe the wire stream + reduced
+// state; the reducer + state factory are pure runtime values.
+export type {
+  AgentStreamEvent,
+  StepStatus,
+  GuardLevel,
+  ToolCall,
+  GuardRejection,
+  AgentMeta,
+} from './agent/events';
+export type {
+  PlanStep,
+  AgentPlan,
+  PlanOutcome,
+  AgentTurnStatus,
+  AgentTurnState,
+} from './agent/state';
+export { initialAgentTurnState, applyAgentEvent } from './agent/state';
+export { makeUserMessage, foldAssistantTurn } from './agent/transcript';
+export type { AgentHook } from './agent/hook';
+
+// Conversation library contract (DD-002B1). Local-first transcript persistence:
+// record/summary types, the ConversationLibrary storage contract, and pure
+// helpers (title/preview derivation + privacy-by-structure sanitization).
+// Storage adapters (IndexedDB, backend) implement the contract in later layers.
+export type {
+  ConversationRecord,
+  ConversationSummary,
+  ConversationLibrary,
+  CreateConversationRecordArgs,
+} from './conversation';
+export {
+  CONVERSATION_SCHEMA_VERSION,
+  createConversationRecord,
+  summarizeConversation,
+  deriveConversationTitle,
+  deriveConversationPreview,
+  sanitizeConversationMessage,
+} from './conversation';

package/src/theme/contract.ts

@@ -0,0 +1,30 @@
+/**
+ * ThemeTokens — the material-agnostic slot contract for a frosted-surface theme.
+ *
+ * Every `fi-<material>` skin (fi-glass today; future fi-slate, fi-paper, …) fills
+ * these same slots with its own values. Consumers — fi-glass's shell/agentic
+ * components and the apps themselves — depend only on this shape, never on a
+ * concrete material. That is precisely what makes "material = token swap" hold
+ * without any material having to depend on another.
+ *
+ * This is pure data: no React, no styling, no logic. It lives in core so a future
+ * material never has to reach into fi-glass just to learn the slot shape.
+ */
+export interface ThemeTokens {
+  /** Backdrop blur radius for frosted surfaces, e.g. `"12px"`. */
+  blur: string;
+  /** Reduced blur radius for small viewports (≤768px), e.g. `"8px"`. */
+  blurCompact: string;
+  /** Surface fill opacity, `0..1`. */
+  opacity: number;
+  /** Backdrop saturation boost, e.g. `"180%"`. */
+  saturation: string;
+  /** Light surface base fill as an `"r, g, b"` triple, e.g. `"255, 255, 255"`. */
+  surfaceLight: string;
+  /** Light surface border (full CSS color), e.g. `"rgba(255, 255, 255, 0.18)"`. */
+  borderLight: string;
+  /** Dark surface fill (full CSS color), e.g. `"rgba(15, 23, 42, 0.7)"`. */
+  surfaceDark: string;
+  /** Dark surface border (full CSS color), e.g. `"rgba(148, 163, 184, 0.2)"`. */
+  borderDark: string;
+}

package/src/voice/adapter.ts

@@ -0,0 +1,71 @@
+// @free-intelligence/core · voice engine contract
+//
+// Mirrors the StreamAdapter philosophy: the contract lives in core, the
+// implementations live in the apps. fi-glass consumes ONLY this interface and
+// stays backend-agnostic — it never knows about Azure, OpenAI, endpoints, auth,
+// or session ids. An app implements VoiceAdapter once against its own backend
+// and passes the instance to the voice UI.
+
+/**
+ * Audio produced by synthesize().
+ *
+ * - `Blob`        → a fully-rendered clip; fi-glass calls URL.createObjectURL.
+ * - `{ url }`     → a ready (possibly streaming) URL; fi-glass uses it directly.
+ *
+ * Supporting both keeps streaming TTS (hear-while-generating) open without
+ * forcing every backend to stream.
+ */
+export type AudioSource = Blob | { url: string };
+
+/** A selectable TTS voice offered by the adapter. */
+export interface VoiceOption {
+  /** Stable id passed back to synthesize() (e.g. "nova", "en-US-AvaNeural"). */
+  id: string;
+  /** Human label for the picker (e.g. "Nova"). */
+  label: string;
+  /** Optional group header for the picker (e.g. "OpenAI", "Azure Neural"). */
+  group?: string;
+}
+
+/** Result of transcribing one recorded audio chunk. */
+export interface TranscriptResult {
+  /** Recognized text for this chunk (may be empty). */
+  text: string;
+}
+
+/** Metadata fi-glass passes alongside each transcription chunk. */
+export interface TranscribeContext {
+  /**
+   * 0-based index of this chunk within the current recording. A streaming
+   * adapter uses it for session/ordering; a one-shot adapter (single chunk on
+   * stop) simply ignores it.
+   */
+  index: number;
+  /** Lets the app abort the in-flight request when recording stops. */
+  signal?: AbortSignal;
+}
+
+/**
+ * VoiceAdapter — the app's voice engine, injected whole into fi-glass.
+ *
+ * Capabilities are a la carte (all members optional):
+ *   - no adapter          -> no voice (UI hides mic + speak)
+ *   - synthesize present  -> TTS available (SpeakButton + AudioPlayer)
+ *   - transcribe present  -> STT available (VoiceMicButton dictation)
+ *
+ * Add a new capability by adding an optional member here — never by threading a
+ * new callback through the components.
+ */
+export interface VoiceAdapter {
+  // ---- TTS (output) ----
+  /** Synthesize speech for `text` in an optional voice id; resolves to audio. */
+  synthesize?(text: string, voice?: string): Promise<AudioSource>;
+  /** Voices offered in the player's picker. */
+  readonly availableVoices?: VoiceOption[];
+  /** Voice id used when the caller doesn't specify one. */
+  readonly defaultVoice?: string;
+
+  // ---- STT (input) ----
+  /** Transcribe one recorded audio chunk to text. */
+  transcribe?(chunk: Blob, ctx?: TranscribeContext): Promise<TranscriptResult>;
+}