@asaidimu/utils-workspace 3.0.0 → 4.0.0

package/index.d.mts

@@ -1,6 +1,8 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
 import { EventBus } from '@asaidimu/events';
+import * as _google_genai from '@google/genai';
+import { GenerateContentParameters, GenerateContentResponse, GoogleGenAI } from '@google/genai';
 
 /**
  * Utility type for representing partial updates to the state, allowing deep nesting.
@@ -13,10 +15,26 @@ type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readon
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
 } | undefined | T : T | undefined;
 
+/**
+ * core/types.ts
+ * * This file contains the primary domain models, data structures, and command types
+ * for the AI Workspace. It acts as the "Source of Truth" for all modules.
+ */
+
+/** RFC 4122 compliant Universally Unique Identifier. */
 type UUID = string;
+/** ISO-8601 formatted UTC timestamp string. */
 type Timestamp = string;
+/** Uniform Resource Identifier string. */
 type URI = string;
+/** Hexadecimal representation of a SHA-256 hash. */
 type SHA256 = string;
+/** Special marker used to denote a role with no specific instructions or identity. */
+declare const EMPTY_SYSTEM_ROLE = "__system__";
+/**
+ * A functional wrapper for operations that can fail.
+ * Encourages explicit error handling over try/catch blocks.
+ */
 type Result<T, E = WorkspaceError> = {
     ok: true;
     value: T;
@@ -24,47 +42,72 @@ type Result<T, E = WorkspaceError> = {
     ok: false;
     error: E;
 };
+/** Occurs when attempting to create a resource with a key that already exists. */
 type DuplicateKeyError = {
     code: 'DUPLICATE_KEY';
     resource: string;
     key: string;
 };
+/** Occurs when a requested resource cannot be found by its unique identifier. */
 type NotFoundError = {
     code: 'NOT_FOUND';
     resource: string;
     id: string;
 };
+/** Triggered when a command payload fails validation or is logically inconsistent. */
 type InvalidCommandError = {
     code: 'INVALID_COMMAND';
     reason: string;
 };
+/** Generic wrapper for unexpected infrastructure or downstream service failures. */
 type BackendError = {
     code: 'BACKEND_ERROR';
     reason: string;
 };
+/** Specific errors related to blob storage, retrieval, or corruption. */
 type BlobError = {
     code: 'BLOB_ERROR';
     reason: string;
 };
-type WorkspaceError = DuplicateKeyError | NotFoundError | InvalidCommandError | BackendError | BlobError;
+/** Triggered when the current actor lacks sufficient privileges for a command. */
+type PermissionDeniedError = {
+    code: 'PERMISSION_DENIED';
+    command: Command;
+    reason: string;
+};
+/** Union of all possible error types within the Workspace domain. */
+type WorkspaceError = DuplicateKeyError | NotFoundError | InvalidCommandError | BackendError | PermissionDeniedError | BlobError;
+/** Global user preferences and defaults for the workspace. */
 interface Settings {
+    /** Default language code (e.g., 'en-US'). */
     language: string;
+    /** The name of the role used when starting a new session. */
     defaultRole?: string;
+    /** Global instructions appended to all system prompts. */
     prompt?: string;
 }
+/** * Represents the project-level metadata.
+ * Allows for extensible metadata fields via the generic Metadata type.
+ */
 type Project<Metadata extends Record<string, any> = Record<string, any>> = Metadata & {
     id: UUID;
     name: string;
 };
+/** Supported mime-types for image assets. */
 type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+/** Supported mime-types for text-based or structured documents. */
 type DocumentMediaType = 'application/pdf' | 'application/json' | 'text/plain' | 'text/html' | 'text/markdown' | 'text/csv' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+/** Union of all media types handled by the blob system. */
 type BlobMediaType = ImageMediaType | DocumentMediaType;
 /**
- * Lightweight pointer to a blob — the subset of BlobRecord that content
- * blocks and context entries carry. Use this at call sites that only need
- * to reference a blob, not inspect its registry metadata.
+ * A lightweight reference to a blob.
+ * Used in content blocks to avoid passing heavy metadata or binary data.
  */
 type BlobRef = Pick<BlobRecord, 'sha256' | 'mediaType' | 'sizeBytes' | 'filename' | 'previewUrl'>;
+/**
+ * Represents a blob that has been fetched into memory.
+ * Can be 'inline' (binary data present) or 'remote' (stored in an external provider).
+ */
 type ResolvedBlob = {
     kind: 'inline';
     sha256: SHA256;
@@ -76,10 +119,11 @@ type ResolvedBlob = {
     mediaType: BlobMediaType;
     fileId: string;
     providerId: string;
+    timestamp: Timestamp;
 };
 /**
- * Full registry entry for a blob. BlobRef is a Pick of this type, so
- * a BlobRecord is always assignable to BlobRef.
+ * The authoritative registry entry for a file in the system.
+ * Includes reference counting for garbage collection and remote mappings.
  */
 interface BlobRecord {
     sha256: SHA256;
@@ -87,16 +131,23 @@ interface BlobRecord {
     sizeBytes: number;
     filename?: string;
     previewUrl?: string;
+    /** Number of content blocks currently referencing this blob. */
     refCount: number;
-    remoteIds: Record<string, string>;
+    /** Map of provider IDs to their specific external file identifiers. */
+    remoteIds: Record<string, {
+        id: string;
+        timestamp: Timestamp;
+    }>;
     createdAt: Timestamp;
     lastUsedAt: Timestamp;
 }
+/** Standard text content within a turn. */
 interface TextBlock {
     id: UUID;
     type: 'text';
     text: string;
 }
+/** An image asset within a turn, optionally containing the resolved binary data. */
 interface ImageBlock {
     id: UUID;
     type: 'image';
@@ -104,6 +155,7 @@ interface ImageBlock {
     blob?: ResolvedBlob;
     altText?: string;
 }
+/** A document asset within a turn. */
 interface DocumentBlock {
     id: UUID;
     type: 'document';
@@ -111,67 +163,76 @@ interface DocumentBlock {
     blob?: ResolvedBlob;
     title?: string;
 }
+/** Represents a structured proposal to create or modify a task. */
 interface TaskProposalBlock {
-    id: UUID;
-    taskId?: UUID;
+    id?: UUID;
+    ref?: string;
     type: 'task:proposal';
     title: string;
     steps: {
-        id?: UUID;
+        ref?: string;
         text: string;
         status: 'todo' | 'done';
     }[];
     action: 'create' | 'update' | 'complete';
 }
+/** Captured request from the AI to execute a specific tool. */
 interface ToolUseBlock {
     id: UUID;
     type: 'tool:use';
     name: string;
     input: Record<string, unknown>;
 }
+/** The resulting output (or error) from a tool execution. */
 interface ToolResultBlock {
     id: UUID;
     type: 'tool:result';
+    /** References the ToolUseBlock ID that generated this result. */
     useId: UUID;
     content: string | Record<string, unknown>;
     isError?: boolean;
 }
+/** Internal "Chain of Thought" or reasoning generated by the model. */
 interface ThinkingBlock {
     id: UUID;
     type: 'thinking';
     thinking: string;
 }
+/** A condensed summary of previous conversation history. */
 interface SummaryBlock {
     id: UUID;
     type: 'summary';
     text: string;
 }
+/** Notates that the session has switched from one Role persona to another. */
 interface RoleTransitionBlock {
     id: UUID;
     type: 'role:transition';
     previousRole: string | null;
     newRole: string;
 }
+/** Union of all possible content types that can exist within a conversation Turn. */
 type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | SummaryBlock | RoleTransitionBlock | ThinkingBlock | TaskProposalBlock;
+/** Definition of a tool available to the AI. */
 interface ToolSummary {
     name: string;
     description: string;
+    /** JSON Schema defining the required input arguments. */
     parameters: {
         type: 'object';
         properties: Record<string, any>;
         required: string[];
     };
-    /**
-     * The semantic tags for this tool.
-     * Used by the ContextRetriever to filter relevance.
-     */
+    /** Semantic tags used to help the model find relevant tools. */
     topics: string[];
 }
+/** An instance of a tool being called with specific arguments. */
 interface ToolCall {
     id: UUID;
     tool: UUID;
     arguments: Record<string, any>;
 }
+/** A request for authorization before executing a command or tool. */
 type AuthRequest = {
     type: 'command';
     payload: Command;
@@ -179,39 +240,38 @@ type AuthRequest = {
     type: 'tool';
     payload: ToolCall;
 };
-type TurnRole = 'user' | 'assistant' | 'tool';
+/** Identifies whether a turn originated from the user, the AI, a tool, or the system. */
+type TurnActor = 'user' | 'assistant' | 'tool' | 'system';
+/** * The flat storage format for a conversation turn.
+ * Supports versioning and parent-pointers for branching conversation trees (DAG).
+ */
 interface Turn {
     id: UUID;
+    /** Incrementing number for edits to the same turn ID. */
     version: number;
-    owner: TurnRole;
+    actor: TurnActor;
     blocks: ContentBlock[];
     timestamp: Timestamp;
-    /**
-     * The name of the role active when this turn was recorded.
-     * Snapshot so history is stable even if the role is later renamed.
-     */
+    /** Name of the role active at the time of this turn. */
     role?: string;
-    /**
-     * Parent pointer. Null for root turns.
-     * This is plain data stored on the document — the DAG is reconstructed
-     * in memory by TurnTree.buildNodeGraph() at session open time.
-     */
+    /** Link to the preceding turn in the conversation tree. */
     parent: {
         id: UUID;
         version: number;
     } | null;
-    /**
-     * Partition key. Stored on the Turn document so Collection.filter
-     * can retrieve all turns for a session in a single query.
-     * Not present on Turn objects used purely in memory (e.g. dirty buffer).
-     */
+    /** Used for fast filtering within a specific chat session. */
     sessionId?: UUID;
 }
+/**
+ * An in-memory representation of a turn, including all its versions and children.
+ * This is used for rendering threaded/branching conversations.
+ */
 interface TurnNode {
     id: UUID;
+    /** Map of version numbers to the Turn data. */
     versions: Record<number, Turn>;
     activeVersion: number;
-    role: TurnRole;
+    role: TurnActor;
     blocks: ContentBlock[];
     timestamp: Timestamp;
     roleSnapshot?: string;
@@ -219,8 +279,10 @@ interface TurnNode {
         id: UUID;
         version: number;
     } | null;
+    /** Map of version numbers to an array of child turn IDs. */
     children: Record<number, UUID[]>;
 }
+/** UI helper for navigating between different versions of a turn (e.g. "2 of 5"). */
 interface BranchInfo {
     versions: number[];
     currentIndex: number;
@@ -228,19 +290,27 @@ interface BranchInfo {
     hasPrev: boolean;
     hasNext: boolean;
 }
+/** A system persona containing specific instructions and associated preferences. */
 interface Role {
+    /** Unique identifier name (e.g. "software-architect"). */
     name: string;
+    /** Human-readable display label. */
     label: string;
     description?: string;
+    /** The core instructions (system prompt) for this persona. */
     persona: string;
+    /** Array of Preference IDs associated with this role. */
     preferences: UUID[];
 }
+/** A specific user preference or "memory" that informs model behavior. */
 interface Preference {
     id: UUID;
     content: string;
+    /** Topics used for retrieval-augmented generation (RAG). */
     topics: string[];
     timestamp: Timestamp;
 }
+/** Discriminated union of types that can be injected into the AI context. */
 type ContextContent = {
     kind: 'text';
     value: string;
@@ -258,20 +328,20 @@ type ContextContent = {
     uri: URI;
     mediaType?: BlobMediaType;
 };
+/** A contextual item (file, snippet, or data) attached to a session or prompt. */
 interface Context {
+    /** Unique lookup key. */
     key: string;
     topics: string[];
     content: ContextContent;
     timestamp: Timestamp;
     metadata?: Record<string, any>;
 }
-/**
- * SessionMeta is stored as a document in the 'session' collection.
- * The head pointer lives here — no separate session_heads store needed.
- */
+/** Metadata for a conversation session, stored in the persistent collection. */
 interface SessionMeta {
     id: UUID;
     label: string;
+    /** The active Role name for this session. */
     role: string;
     topics: string[];
     preferences: UUID[];
@@ -279,21 +349,27 @@ interface SessionMeta {
         created?: Timestamp;
         updated?: Timestamp;
     };
+    /** Tracks how many turns have been persisted to the database. */
     flushedTurnCount: number;
+    /** The current leaf-node of the conversation. */
     head: {
         id: UUID;
         version: number;
     } | null;
+    /** Optional link to a specific Task being worked on. */
     task: UUID | null;
 }
 type TaskStatus = 'todo' | 'active' | 'done' | 'blocked' | 'defered';
+/** A single item within a Task's checklist. */
 interface TaskStep {
-    id: UUID;
+    ref: string;
     text: string;
     completed?: Timestamp;
 }
+/** A high-level objective with nested steps, used for tracking AI progress. */
 interface Task {
     id: UUID;
+    ref?: string;
     title: string;
     description?: string;
     status: TaskStatus;
@@ -307,7 +383,6 @@ interface RoleSummary {
     name: string;
     label: string;
     description?: string;
-    /** Number of preference IDs listed on the role. */
     preferences: number;
 }
 interface PreferenceSummary {
@@ -328,6 +403,8 @@ interface ContextSummary {
 }
 interface TaskSummary {
     id: UUID;
+    ref?: string;
+    description: string;
     title: string;
     status: TaskStatus;
     steps: {
@@ -336,6 +413,7 @@ interface TaskSummary {
     };
     topics: string[];
 }
+/** Maps topics to the various entities that reference them. */
 interface TopicIndex {
     topic: string;
     contextKeys: string[];
@@ -347,6 +425,7 @@ interface TopicIndex {
         entries?: number;
     };
 }
+/** The complete in-memory read-model of the Workspace state. */
 interface Index {
     roles: Record<string, RoleSummary>;
     preferences: Record<UUID, PreferenceSummary>;
@@ -357,12 +436,16 @@ interface Index {
     blobs: Record<SHA256, BlobRecord>;
     tools: Record<string, ToolSummary>;
 }
+/** The root container for a user's workspace. */
 interface Workspace<ProjectMetadata extends Record<string, any> = Record<string, any>> {
     id: UUID;
     settings: Settings;
     project: Project<ProjectMetadata>;
     index: Index;
 }
+/** * Format used for exporting/importing a complete workspace state,
+ * including all historical turns and binary records.
+ */
 interface WorkspaceBundle {
     format: 'aiworkspace/4.0';
     workspace: Workspace;
@@ -375,6 +458,7 @@ interface WorkspaceBundle {
     tasks: Record<UUID, Task>;
     blobs: Record<SHA256, BlobRecord>;
 }
+/** A fully hydrated view of a session, including resolved objects for the prompt builder. */
 interface EffectiveSession {
     session: SessionMeta;
     role: Role;
@@ -384,24 +468,14 @@ interface EffectiveSession {
     task: Task | null;
     instructions?: string;
 }
-interface CacheConfig {
-    roles?: number;
-    preferences?: number;
-    context?: number;
-    tasks?: number;
-}
-interface FlushConfig {
-    maxBufferSize: number;
-    flushIntervalMs: number;
-}
-interface ContentStoreConfig {
-    cache?: CacheConfig;
-    flush?: FlushConfig;
-}
 interface BaseCommand {
+    /** Discriminator for the command type. */
     type: string;
     timestamp: Timestamp;
+    /** The ID of the user or system component that initiated the command. */
     actor?: string;
+    description?: string;
+    synthetic?: boolean;
 }
 interface CreateWorkspace extends BaseCommand {
     type: 'workspace:create';
@@ -469,15 +543,18 @@ interface DeleteContext extends BaseCommand {
         key: string;
     };
 }
+type TaskRef = UUID | string;
 interface AddTask extends BaseCommand {
     type: 'task:add';
     payload: Task;
 }
 interface UpdateTask extends BaseCommand {
     type: 'task:update';
-    payload: Partial<Task> & {
+    payload: Partial<Task> & ({
         id: UUID;
-    };
+    } | {
+        ref: string;
+    });
 }
 interface DeleteTask extends BaseCommand {
     type: 'task:delete';
@@ -485,6 +562,7 @@ interface DeleteTask extends BaseCommand {
         id: UUID;
     };
 }
+/** Updates an existing turn record in storage. */
 interface SaveTurn extends BaseCommand {
     type: 'turn:save';
     payload: {
@@ -492,6 +570,7 @@ interface SaveTurn extends BaseCommand {
         turn: Turn;
     };
 }
+/** Appends a new turn to a session. */
 interface AddTurn extends BaseCommand {
     type: 'turn:add';
     payload: {
@@ -499,6 +578,7 @@ interface AddTurn extends BaseCommand {
         turn: Turn;
     };
 }
+/** Creates a new version of an existing turn. */
 interface EditTurn extends BaseCommand {
     type: 'turn:edit';
     payload: {
@@ -509,6 +589,7 @@ interface EditTurn extends BaseCommand {
         roleSnapshot?: string;
     };
 }
+/** Creates a new branch in the conversation history from a specific turn. */
 interface BranchTurn extends BaseCommand {
     type: 'turn:branch';
     payload: {
@@ -520,6 +601,7 @@ interface TurnRef {
     id: UUID;
     version: number;
 }
+/** Removes a specific version of a turn and updates the session head if necessary. */
 interface DeleteTurn extends BaseCommand {
     type: 'turn:delete';
     payload: {
@@ -550,6 +632,7 @@ interface OverrideSessionPreferences extends BaseCommand {
         preferences: UUID[];
     };
 }
+/** Creates a new session starting from the state of an existing one. */
 interface ForkSession extends BaseCommand {
     type: 'session:fork';
     payload: {
@@ -560,6 +643,17 @@ interface ForkSession extends BaseCommand {
         topics?: string[];
     };
 }
+interface UpdateSession extends BaseCommand {
+    type: 'session:update';
+    payload: {
+        sessionId: UUID;
+        label?: string;
+        role?: string;
+        topics?: string[];
+        preferences?: UUID[];
+        task?: UUID | null;
+    };
+}
 interface DeleteSession extends BaseCommand {
     type: 'session:delete';
     payload: {
@@ -574,30 +668,35 @@ interface RegisterBlob extends BaseCommand {
         filename?: string;
     };
 }
+/** Increases reference count to prevent garbage collection. */
 interface RetainBlob extends BaseCommand {
     type: 'blob:retain';
     payload: {
         sha256: SHA256;
     };
 }
+/** Decreases reference count. */
 interface ReleaseBlob extends BaseCommand {
     type: 'blob:release';
     payload: {
         sha256: SHA256;
     };
 }
+/** Immediately removes a blob regardless of reference count. */
 interface PurgeBlob extends BaseCommand {
     type: 'blob:purge';
     payload: {
         sha256: SHA256;
     };
 }
+/** Maps a local blob to an external provider's file ID. */
 interface RecordBlobRemoteId extends BaseCommand {
     type: 'blob:record_remote_id';
     payload: {
         sha256: SHA256;
         providerId: string;
         fileId: string;
+        timestamp?: Timestamp;
     };
 }
 type BlobCommand = RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId;
@@ -605,30 +704,27 @@ interface CallTool extends BaseCommand {
     type: 'tool:call';
     payload: ToolCall;
 }
-type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | AddContext | UpdateContext | DeleteContext | AddTask | UpdateTask | DeleteTask | AddTurn | SaveTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | BlobCommand | CallTool;
+/** Union of all possible commands that can be dispatched to the Workspace Manager. */
+type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | UpdateSession | AddContext | UpdateContext | DeleteContext | AddTask | UpdateTask | DeleteTask | AddTurn | SaveTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | BlobCommand | CallTool;
+/** Configuration for token counting and management during prompt generation. */
 interface TokenBudget {
     total: number;
     estimator?: (text: string) => number;
     blobTokensPerKB?: number;
 }
+/** Details regarding why a specific preference was excluded from a prompt. */
 interface PreferenceConflict {
     topic: string;
     kept: UUID;
     dropped: UUID;
     reason: 'superseded_by_newer';
 }
-interface ContextRelevanceConfig {
-    recentMessageWindow?: number;
-    minScore?: number;
-    freshnessHalfLifeDays?: number;
-}
 /**
- * Prompt.transcript.turns is Turn[].
- * Synthetic turns produced by PromptAssembler (summary blocks, truncation
- * notices, referential attachments) carry generated UUIDs and version 0,
- * with parent: null. They are ephemeral — never stored, never patched.
+ * The final structure sent to an LLM provider.
+ * Assembled by the PromptAssembler by resolving roles, context, and history.
  */
 interface Prompt {
+    /** Information destined for the System Message. */
     system: {
         instructions?: string;
         persona: string;
@@ -636,7 +732,9 @@ interface Prompt {
         context: Context[];
         task: Task | null;
     };
+    /** Additional context items injected separately. */
     context: Context[];
+    /** The conversation history. */
     transcript: {
         turns: Turn[];
     };
@@ -645,6 +743,7 @@ interface Prompt {
         used: number;
         breakdown: Record<string, number>;
     };
+    /** Statistics on what was removed to fit within the token limit. */
     truncated: {
         preferences: number;
         interactions: number;
@@ -653,20 +752,118 @@ interface Prompt {
     warnings: string[];
     conflicts: PreferenceConflict[];
 }
-interface TranscriptWindow {
-    sessionId: UUID;
-    turns: Turn[];
-    flushedCount: number;
-    hasMore: boolean;
-}
+/** Typed events emitted by the Workspace when data changes. */
 interface WorkspaceEvents {
+    /** Emitted when the index or core settings change. */
     'workspace:changed': DeepPartial<Workspace>;
+    /** Emitted when a blob is registered, updated, or removed. */
     'blobs:changed': {
         sha256: SHA256;
         record: BlobRecord | null;
     };
 }
 
+/**
+ * Handles transcript compression and history management.
+ * When a conversation exceeds the model's context window, the Summarizer
+ * condenses older turns into a single summary string to reclaim tokens.
+ */
+interface Summarizer {
+    /**
+     * Compresses the provided transcript.
+     * * @param transcript - The current list of conversation turns.
+     * @param tokenBudget - The maximum allowed tokens for the history.
+     * @returns A promise resolving to the summary and the remaining uncompressed turns.
+     */
+    summarize(transcript: Turn[], tokenBudget: number): Promise<{
+        summary: string;
+        remaining: Turn[];
+    }>;
+}
+/**
+ * Analyzes model outputs for side effects and workspace actions.
+ * The TurnProcessor scans the assistant's response (Turn) for specific
+ * triggers, such as file edits, UI updates, or state changes.
+ */
+interface TurnProcessor {
+    /**
+     * Scans a turn for actionable blocks and returns workspace commands.
+     * @param turn - The assistant turn to be processed.
+     * @param sessionId - The session in which the turn was generated.
+     * @returns An array of Commands to synchronize the Workspace state.
+     */
+    process(turn: Turn, sessionId?: UUID): Command[];
+}
+/**
+ * Manages the lifecycle and execution of external tools.
+ * Acts as a central hub for discovering available capabilities and
+ * routing tool calls to their respective executors.
+ */
+interface ToolRegistry {
+    /**
+     * Subscribes to changes in the tool ecosystem.
+     * @param callback - Invoked whenever tools are added, removed, or updated.
+     */
+    onRegistryChanged(callback: (tools: ToolSummary[]) => void): void;
+    /**
+     * Retrieves a list of all currently registered and available tools.
+     * @returns An array of summaries describing tool capabilities and schemas.
+     */
+    list(): ToolSummary[];
+    /**
+     * Executes a tool call in a stateless manner.
+     * * @template T - The expected return type of the tool execution.
+     * @param call - The specific tool call requested by the model.
+     * @returns A promise resolving to a Result wrapper containing the tool output.
+     */
+    execute<T = any>(call: ToolCall): Promise<Result<T>>;
+}
+/**
+ * Enforces security and authorization policies.
+ * * The PermissionGuard ensures that the current execution context (User/Session)
+ * has the necessary privileges to perform a requested action or tool call.
+ */
+interface PermissionGuard {
+    /**
+     * Validates if the current context has the right to execute the request.
+     * * @param request - The authentication payload and target action.
+     * @returns A Result containing the authorized payload or an error.
+     */
+    authenticate(request: AuthRequest): Promise<Result<AuthRequest["payload"] | null>>;
+}
+/**
+ * Bridge between the internal Workspace types and external LLM APIs.
+ * This generic adapter allows the system to remain vendor-agnostic by
+ * centralizing the translation logic for different providers (Google, OpenAI, etc.).
+ * @template TRequest - The specific request shape expected by the provider SDK.
+ * @template TRequestParams - Extra parameters for the request (e.g., model name, temperature).
+ * @template TResponse - The raw response shape returned by the provider SDK.
+ */
+interface LLMAdapter<TRequest, TRequestParams, TResponse> {
+    /**
+     * Maps the internal `Prompt` to the vendor-specific request format.
+     * * @param params - The prompt and provider-specific configuration.
+     * @returns The formatted request object ready for the SDK.
+     */
+    /**
+     * Prepares the request and identifies necessary side-effects (like uploads).
+     */
+    prepare(params: {
+        prompt: Prompt;
+    } & TRequestParams): Promise<{
+        request: TRequest;
+        effects?: Command[];
+    }>;
+    /**
+     * Maps the vendor-specific response back to an internal `Turn`.
+     * * @param params - The raw response received from the model API.
+     * @returns A Result containing standardized Turn object or an error.
+     */
+    parse(params: {
+        response: TResponse;
+    }): Result<Turn, WorkspaceError>;
+}
+
 /**
  * Buffers write operations across one or more stores and commits them atomically.
  *
@@ -1105,20 +1302,50 @@ type CollectionName = typeof COLLECTIONS[keyof typeof COLLECTIONS];
 
 declare function del<T>(): T;
 declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
-declare function ok<T>(value: T): Result<T, never>;
-declare function err<E = WorkspaceError>(error: E): Result<never, E>;
+declare function success<T>(value: T): Result<T, never>;
+declare function error<E = WorkspaceError>(error: E): Result<never, E>;
 declare function omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
 declare function createProjectWorkspace<ProjectMetadata extends Record<string, any> = Record<string, any>>({ project, language }: {
     language: string;
     project: Omit<Project<ProjectMetadata>, "id">;
 }): Workspace<ProjectMetadata>;
-declare function createSimpleWorkspace({ name, owner, language }: {
+declare function createSimpleWorkspace({ name, actor, language }: {
     name: string;
     language: string;
-    owner: string;
+    actor: string;
 }): Workspace;
 declare function extractBlobRecord(patch: DeepPartial<Workspace>): BlobRecord | null;
 declare function extractBlobRef(record: BlobRecord): BlobRef;
+declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
+/**
+ * Creates a skeleton Role object with empty defaults.
+ */
+declare const createEmptyRole: (name: string, label: string) => Role;
+/**
+ * Isomorphic Base64 converter (Node.js / browser).
+ */
+declare function bufferToBase64(data: ArrayBuffer | Uint8Array | number[]): string;
+
+/**
+ * Short, deterministic hash of a string (4 chars in base36).
+ * Suitable for AI-friendly reference tokens.
+ */
+declare function shortHash(s: string, length?: number): string;
+/**
+ * Generates a short, memorable reference for a task.
+ * - Returns the proposal's own `ref` if provided.
+ * - Otherwise returns a 4‑character hash of the proposal's `id` or `title`.
+ */
+declare function generateTaskRef(proposal: TaskProposalBlock): string;
+/**
+ * Generates a short step reference.
+ * - Returns the step's own `ref` if provided.
+ * - Otherwise returns `${taskRef}_${index+1}` (e.g., "a3f9_2").
+ *
+ * The underscore separator avoids confusion with colons, slashes, or
+ * numeric suffixes that could be misinterpreted by LLMs.
+ */
+declare function generateTaskStepRef(index: number, proposal: TaskProposalBlock): string;
 
 /**
  * Persistence contract for binary blob content and blob registry records.
@@ -1197,7 +1424,6 @@ declare class TurnTree {
     copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
 }
 
-declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
 interface BlobStoreConfig {
     /**
      * When true, blobs with refCount === 0 are deleted from the backend
@@ -1232,6 +1458,10 @@ declare class BlobStore {
     release(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
     recordRemoteId(sha256: SHA256, providerId: string, fileId: string): Promise<Result<void, WorkspaceError>>;
     getRemoteId(sha256: SHA256, providerId: string): string | null;
+    getRemoteRecord(sha256: SHA256, providerId: string): {
+        id: string;
+        timestamp: Timestamp;
+    } | null;
     resolveRef(ref: BlobRef, providerId: string | null): Promise<Result<ResolvedBlob, WorkspaceError>>;
     resolveRefs(refs: BlobRef[], providerId: string | null): Promise<{
         resolved: Map<SHA256, ResolvedBlob>;
@@ -1250,6 +1480,15 @@ declare class BlobStore {
     getAllRecords(): Record<SHA256, BlobRecord>;
 }
 
+interface CacheConfig {
+    roles?: number;
+    preferences?: number;
+    context?: number;
+    tasks?: number;
+}
+interface ContentStoreConfig {
+    cache?: CacheConfig;
+}
 declare class ContentStore {
     private readonly db;
     readonly tree: TurnTree;
@@ -1299,64 +1538,41 @@ declare class ContentStore {
     gc(): Promise<number>;
 }
 
-declare function workspaceReducer({ index: state }: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
-
-interface Summarizer {
-    summarize(transcript: Turn[], tokenBudget: number): Promise<{
-        summary: string;
-        remaining: Turn[];
-    }>;
-}
-interface ToolRegistry {
-    /**
-     * Subscribe to tool registry changes.
-     * The callback is executed whenever the set of available tools changes.
-     */
-    onRegistryChanged(callback: (tools: ToolSummary[]) => void): void;
-    /**
-     * Returns all tools currently available in the environment.
-     */
-    list(): ToolSummary[];
-    /**
-     * The stateless executor.
-     * Takes the call, returns the raw result.
-     */
-    execute<T = any>(call: ToolCall): Promise<Result<T>>;
-}
-interface PermissionGuard {
-    /**
-     * An async predicate that determines if the current context
-     * (user, session, project) has the right to execute the request.
-     */
-    authenticate(request: AuthRequest): Promise<Result<null>>;
-}
-
 declare class WorkspaceManager {
     private readonly contentStore;
     private readonly permissionGuard?;
     private readonly toolRegistry?;
+    private readonly processor;
     private bus;
-    /**
-     * Called after any workspace change
-     */
-    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => void;
     constructor(options: {
         contentStore: ContentStore;
         permissionGuard?: PermissionGuard;
         toolRegistry?: ToolRegistry;
         eventBus: EventBus<WorkspaceEvents>;
+        turnProcessor?: TurnProcessor;
     });
+    store(): ContentStore;
+    turnProcessor(): TurnProcessor;
     /**
      * Initializes a Workspace's in-memory Index from environment-static
      * sources (like ToolRegistry). Call this when opening a Workspace.
      */
-    init(_: Workspace): DeepPartial<Workspace>;
+    initTools(_: Workspace): DeepPartial<Workspace>;
+    /**
+     * Called after any workspace change
+     */
+    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => void;
     reduce(workspace: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
     dispatch(workspace: Workspace, command: Command): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     resolveSession(workspace: Workspace, sessionId: UUID, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
     private handleContentSideEffects;
 }
 
+interface ContextRelevanceConfig {
+    recentMessageWindow?: number;
+    minScore?: number;
+    freshnessHalfLifeDays?: number;
+}
 interface ContextRankingInput {
     entries: Context[];
     recentMessages: string[];
@@ -1434,9 +1650,9 @@ declare class PromptBuilder {
  * This class helps construct a Turn object by adding various content blocks.
  */
 declare class TurnBuilder {
-    private readonly _owner;
+    private readonly _actor;
     private _turn;
-    constructor(_owner: TurnRole, initialTurn?: Turn);
+    constructor(_actor: TurnActor, initialTurn?: Turn);
     addText(text: string): TurnBuilder;
     addImage(ref?: BlobRef, altText?: string): TurnBuilder;
     addDocument(ref?: BlobRef, title?: string): TurnBuilder;
@@ -1455,8 +1671,8 @@ declare class TurnBuilder {
     addTaskProposal(title: string, steps: {
         text: string;
         status?: 'todo' | 'done';
-        id?: UUID;
-    }[], action?: 'create' | 'update' | 'complete', taskId?: UUID): TurnBuilder;
+        ref?: string;
+    }[], action?: 'create' | 'update' | 'complete', id?: string): TurnBuilder;
     addBlock(block: ContentBlock): TurnBuilder;
     deleteBlock(blockId: UUID): TurnBuilder;
     editTextBlock(blockId: UUID, newText: string): TurnBuilder;
@@ -1468,51 +1684,245 @@ declare class TurnBuilder {
     build(): Turn;
 }
 
+declare class DefaultTurnProcessor implements TurnProcessor {
+    private readonly handlers;
+    process(turn: Turn, sessionId?: UUID): Command[];
+}
+
 declare class Session {
     private readonly sessionId;
     private readonly tree;
     private readonly manager;
     constructor(sessionId: UUID, tree: TurnTree, manager: WorkspaceManager);
+    /** Returns the UUID of this session. */
+    id(): UUID;
+    /**
+     * Retrieves the full metadata record for this session from the workspace index.
+     */
+    meta(workspace: Workspace): SessionMeta | undefined;
+    /** Returns the human-readable label for the session. */
+    label(workspace: Workspace): string | undefined;
+    /** Returns the name of the role currently assigned to this session. */
+    private roleName;
+    /**
+     * Returns the RoleSummary (label, description, etc.) for the session's active role.
+     */
+    role(workspace: Workspace): RoleSummary | undefined;
+    /** Returns the list of topics associated with this session. */
+    topics(workspace: Workspace): string[];
+    /** Returns the list of preference IDs overriding defaults for this session. */
+    preferences(workspace: Workspace): UUID[];
+    /**
+     * Returns the current "head" pointer (turnId and version) of the conversation DAG.
+     */
+    head(workspace: Workspace): TurnRef | null;
+    /**
+     * Returns the full Task object if the session is currently linked to a task.
+     */
+    task(workspace: Workspace): Promise<Task | undefined>;
+    /**
+     * Returns the TaskSummary if the session is currently linked to a task.
+     */
+    taskSummary(workspace: Workspace): TaskSummary | undefined;
+    /**
+     * Checks whether the session is linked to any task.
+     */
+    hasTask(workspace: Workspace): boolean;
+    /**
+     * Builds the active conversation chain (the current linear history) as an array
+     * of TurnNode objects, following the head pointer and parent links.
+     */
     turns(): Promise<TurnNode[]>;
+    /**
+     * Returns all sibling turns of the given turn (other turns that share the same parent).
+     */
     siblings(turnId: UUID): Promise<TurnNode[]>;
+    /**
+     * Returns version‑branching information for a given turn, including available versions,
+     * current index, and navigation capabilities.
+     */
     branchInfo(turnId: UUID): Promise<BranchInfo>;
-    id(): string;
     /**
-     * Creates a new fluent TurnBuilder for constructing a Turn object.
-     * @param owner The role of the owner of the turn (e.g., 'user', 'assistant', 'tool').
-     * @returns A new TurnBuilder instance.
+     * Retrieves a single turn node by its ID from the session graph.
      */
-    startTurn(owner: TurnRole): TurnBuilder;
+    getTurn(turnId: UUID): Promise<TurnNode | undefined>;
     /**
-     * Saves a constructed Turn object to the session. This method handles setting the session ID
-     * and automatically determines the parent turn if not explicitly provided in the Turn object.
-     * @param workspace The current workspace state.
-     * @param turn The Turn object to save. It can be constructed using the TurnBuilder.
-     * @param parentRef Optional TurnRef to explicitly set the parent of the turn. If not provided,
-     *                  the current head of the active chain will be used as the parent.
-     * @returns A promise resolving to a Result containing a DeepPartial<Workspace> on success,
-     *          or a WorkspaceError on failure.
+     * Changes the session's display label.
+     * @param workspace Current workspace state.
+     * @param newLabel New human‑readable label.
+     * @returns A patch to merge into the workspace state.
      */
-    addTurn(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    rename(workspace: Workspace, newLabel: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Replaces the session's topic list entirely.
+     * @param workspace Current workspace state.
+     * @param topics New array of topics (overwrites existing).
+     * @returns A patch to merge into the workspace state.
+     */
+    setTopics(workspace: Workspace, topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Adds topics to the session (union, no duplicates).
+     * @param workspace Current workspace state.
+     * @param topics Topics to add.
+     * @returns A patch to merge into the workspace state.
+     */
+    addTopics(workspace: Workspace, topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Replaces the session's preference override list entirely.
+     * @param workspace Current workspace state.
+     * @param preferenceIds New array of preference IDs.
+     * @returns A patch to merge into the workspace state.
+     */
+    setPreferences(workspace: Workspace, preferenceIds: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Links the session to a task, or removes the link if taskId is null.
+     * @param workspace Current workspace state.
+     * @param taskId ID of the task to link, or null to unlink.
+     * @returns A patch to merge into the workspace state.
+     */
+    setActiveTask(workspace: Workspace, taskId: UUID | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Removes the link between the session and its current task (if any).
+     * @param workspace Current workspace state.
+     * @returns A patch to merge into the workspace state.
+     */
+    unsetTask(workspace: Workspace): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Creates a new session as a fork (copy) of this one.
+     * @param workspace Current workspace state.
+     * @param newSessionId Unique ID for the new session.
+     * @param label Display label for the new session.
+     * @param role Optional role override (defaults to current role).
+     * @param topics Optional topic override (defaults to current topics).
+     * @returns A patch to merge into the workspace state.
+     */
+    fork(workspace: Workspace, newSessionId: UUID, label: string, role?: string, topics?: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Permanently deletes this session and all its turns from the workspace.
+     * @param workspace Current workspace state.
+     * @returns A patch to merge into the workspace state.
+     */
+    delete(workspace: Workspace): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    dispatch(workspace: Workspace, command: Command): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switches the session to a different role.
+     * @param workspace Current workspace state.
+     * @param newRole Name of the target role (must exist in the workspace).
+     * @returns A patch to merge into the workspace state.
+     */
+    switchRole(workspace: Workspace, newRole: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Returns all available roles in the workspace.
+     */
+    listRoles(workspace: Workspace): RoleSummary[];
+    /**
+     * Returns a specific role by name, or undefined if not found.
+     */
+    getRole(workspace: Workspace, name: string): RoleSummary | undefined;
     /**
-     * Updates an existing turn in the session using a fully constructed Turn object.
-     * This method will dispatch a 'turn:edit' command.
-     * @param workspace The current workspace state.
-     * @param updatedTurn The Turn object containing the updated blocks and other properties.
-     * @returns A promise resolving to a Result containing a DeepPartial<Workspace> on success,
-     *          or a WorkspaceError on failure.
+     * Creates a new role.
+     * @param workspace Current workspace state.
+     * @param name Unique identifier for the role (e.g., "software-architect").
+     * @param label Human-readable display label.
+     * @param persona The system prompt / instructions for this role.
+     * @param description Optional description.
+     * @param preferenceIds Optional array of preference IDs to associate.
+     * @returns A patch to merge into the workspace state.
+     */
+    createRole(workspace: Workspace, name: string, label: string, persona: string, description?: string, preferenceIds?: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Updates an existing role.
+     * @param workspace Current workspace state.
+     * @param name Name of the role to update (must exist).
+     * @param updates Partial updates (label, description, persona, preferences).
+     * @returns A patch to merge into the workspace state.
+     */
+    updateRole(workspace: Workspace, name: string, updates: Partial<Pick<Role, 'label' | 'description' | 'persona' | 'preferences'>>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Deletes a role. Fails if the role is still referenced by any session.
+     * @param workspace Current workspace state.
+     * @param name Name of the role to delete.
+     * @returns A patch to merge into the workspace state.
+     */
+    deleteRole(workspace: Workspace, name: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Saves a constructed Turn object to the session. The turn's parent is automatically
+     * set to the current head of the active chain unless overridden in the turn object.
+     * @param workspace Current workspace state.
+     * @param turn The Turn object (can be built with startTurn()).
+     * @returns A patch to merge into the workspace state.
+     */
+    addTurn(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    recordUserTurn(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    recordAssistantTurn(workspace: Workspace, turn: Turn, recordDenial?: boolean): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    private buildDenialTurn;
+    private describeCommand;
+    /**
+     * Creates a new version of an existing turn with updated content.
+     * @param workspace Current workspace state.
+     * @param turnId ID of the turn to edit.
+     * @param newBlocks New content blocks for the turn.
+     * @param roleSnapshot Optional role name to record with this version.
+     * @returns A patch to merge into the workspace state.
      */
     editTurn(workspace: Workspace, turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Creates a new branch from a specific turn (the parent must be set on the turn).
+     * @param workspace Current workspace state.
+     * @param turn The new turn that continues from an existing parent.
+     * @returns A patch to merge into the workspace state.
+     */
     branch(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Deletes a specific version of a turn and all its descendants.
+     * @param workspace Current workspace state.
+     * @param turnId ID of the turn to delete.
+     * @param version Version number of the turn to delete.
+     * @param newHead Optional new head pointer after deletion.
+     * @returns A patch to merge into the workspace state.
+     */
     deleteTurn(workspace: Workspace, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switch to the previous version of a turn (if available).
+     * This changes the active chain head but does not create new data.
+     * @param workspace Current workspace state.
+     * @param turnId ID of the turn whose version to switch.
+     * @returns A patch to merge into the workspace state.
+     */
     switchVersionLeft(workspace: Workspace, turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switch to the next version of a turn (if available).
+     * This changes the active chain head but does not create new data.
+     * @param workspace Current workspace state.
+     * @param turnId ID of the turn whose version to switch.
+     * @returns A patch to merge into the workspace state.
+     */
     switchVersionRight(workspace: Workspace, turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     private switchVersion;
+    addPreference(workspace: Workspace, content: string, topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    listPreferences(workspace: Workspace): Promise<PreferenceSummary[]>;
+    addContext(workspace: Workspace, key: string, content: ContextContent, topics: string[], metadata?: Record<string, any>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    listContextSummaries(workspace: Workspace): Promise<ContextSummary[]>;
+    /**
+ * Registers a new blob in the workspace and returns its SHA256 and BlobRef.
+ * This dispatches a blob:register command and extracts the resulting SHA256
+ * from the returned workspace patch.
+ */
+    registerBlob(workspace: Workspace, data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<{
+        sha256: SHA256;
+        ref: BlobRef;
+    }, WorkspaceError>>;
+    /**
+     * Resolves the session into an EffectiveSession object, which bundles the
+     * session metadata, role, preferences, context, transcript, and linked task.
+     * @param workspace Current workspace state.
+     * @returns The resolved effective session or an error.
+     */
     resolve(workspace: Workspace): Promise<Result<EffectiveSession, WorkspaceError>>;
+    private findSubtreeTip;
 }
 
 interface SessionManagerConfig {
-    flush?: Partial<FlushConfig>;
 }
 interface OpenResult {
     session: Session;
@@ -1522,6 +1932,26 @@ declare class SessionManager {
     private readonly workspaceManager;
     private readonly contentStore;
     constructor(workspaceManager: WorkspaceManager, contentStore: ContentStore);
+    /**
+     * Returns an array of all session metadata entries in the workspace.
+     */
+    list(workspace: Workspace): SessionMeta[];
+    /**
+     * Retrieves the metadata for a specific session without hydrating a Session object.
+     */
+    meta(workspace: Workspace, sessionId: UUID): SessionMeta | undefined;
+    /**
+     * Creates a new session and returns a hydrated Session instance.
+     * This method dispatches a 'session:create' command which is validated by the
+     * reducer (checking for unique IDs and valid roles) and persisted
+     * to the content store.
+     */
+    create(workspace: Workspace, params: {
+        label: string;
+        role?: string;
+        topics?: string[];
+        preferences?: UUID[];
+    }): Promise<Result<OpenResult, WorkspaceError>>;
     open(workspace: Workspace, sessionId: UUID): Promise<Result<OpenResult, WorkspaceError>>;
     get workspace(): WorkspaceManager;
     close(_: Session): Promise<void>;
@@ -1594,4 +2024,37 @@ declare class IndexedDBBlobStorage implements BlobStorage {
     registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
 }
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTask, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CacheConfig, type CallTool, type CollectionName, type Command, type ContentBlock, ContentStore, type ContentStoreConfig, type Context, type ContextContent, type ContextRelevanceConfig, type ContextSummary, type CreateSession, type CreateWorkspace, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTask, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InvalidCommandError, MemoryBlobStorage, type NotFoundError, type OpenResult, type OverrideSessionPreferences, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, type SaveTurn, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type SummaryBlock, type SwitchRole, type Task, type TaskProposalBlock, type TaskStatus, type TaskStep, type TaskSummary, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolCall, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnNode, type TurnRef, type TurnRole, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateTask, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, WorkspaceManager, computeSHA256, createProjectWorkspace, createSimpleWorkspace, createWorkspaceDatabase, del, err, extractBlobRecord, extractBlobRef, merge, ok, omitNullUndefined, workspaceReducer };
+declare class GoogleGenAIAdapter implements LLMAdapter<{
+    model: string;
+}, GenerateContentParameters, GenerateContentResponse> {
+    private _;
+    constructor(_: GoogleGenAI);
+    /**
+     * Converts a Prompt into a GenerateContentRequest for @google/genai.
+     */
+    prepare({ prompt, model }: {
+        prompt: Prompt;
+        model: string;
+    }): Promise<{
+        request: {
+            model: string;
+            contents: _google_genai.Content[];
+            config: {
+                systemInstruction: _google_genai.Content;
+                thinkingConfig: {
+                    includeThoughts: boolean;
+                };
+                responseMimeType: string;
+                responseSchema: _google_genai.Schema;
+            };
+        };
+    }>;
+    /**
+     * Parses the GenerateContentResponse into a Turn (assistant turn).
+     */
+    parse({ response }: {
+        response: GenerateContentResponse;
+    }): Result<Turn, WorkspaceError>;
+}
+
+export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTask, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CallTool, type CollectionName, type Command, type ContentBlock, ContentStore, type Context, type ContextContent, type ContextSummary, type CreateSession, type CreateWorkspace, DefaultTurnProcessor, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTask, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type EffectiveSession, type ForkSession, GoogleGenAIAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InvalidCommandError, type LLMAdapter, MemoryBlobStorage, type NotFoundError, type OpenResult, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, type SaveTurn, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type Summarizer, type SummaryBlock, type SwitchRole, type Task, type TaskProposalBlock, type TaskRef, type TaskStatus, type TaskStep, type TaskSummary, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolCall, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type TopicIndex, type Turn, type TurnActor, TurnBuilder, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTask, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, WorkspaceManager, bufferToBase64, computeSHA256, createEmptyRole, createProjectWorkspace, createSimpleWorkspace, createWorkspaceDatabase, del, error, extractBlobRecord, extractBlobRef, generateTaskRef, generateTaskStepRef, merge, omitNullUndefined, shortHash, success };