@asaidimu/utils-workspace 2.1.1 → 3.1.0

package/index.d.ts

@@ -1,10 +1,40 @@
 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.
+ * It makes all properties optional and applies the same transformation recursively
+ * to nested objects and array elements, allowing for selective updates while
+ * preserving the original structure. It also includes the original type T and
+ * undefined as possibilities for the top level and nested values.
+ */
+type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
+    [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;
@@ -12,44 +42,72 @@ type Result<T, E = WorkspaceError> = {
     ok: false;
     error: E;
 };
-type WorkspaceError = {
+/** 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;
 };
+/** 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;
 }
-interface Project {
+/** * 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;
-    owner: string;
-    repository?: string;
-    metadata?: Record<string, any>;
-}
+};
+/** 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;
@@ -61,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;
@@ -72,86 +131,147 @@ 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';
     ref?: BlobRef;
     blob?: ResolvedBlob;
     altText?: string;
 }
+/** A document asset within a turn. */
 interface DocumentBlock {
+    id: UUID;
     type: 'document';
     ref?: BlobRef;
     blob?: ResolvedBlob;
     title?: string;
 }
+/** Represents a structured proposal to create or modify a task. */
+interface TaskProposalBlock {
+    id: UUID;
+    taskId?: UUID;
+    type: 'task:proposal';
+    title: string;
+    steps: {
+        id?: UUID;
+        text: string;
+        status: 'todo' | 'done';
+    }[];
+    action: 'create' | 'update' | 'complete';
+}
+/** Captured request from the AI to execute a specific tool. */
 interface ToolUseBlock {
-    type: 'tool_use';
-    toolUseId: string;
+    id: UUID;
+    type: 'tool:use';
     name: string;
     input: Record<string, unknown>;
 }
+/** The resulting output (or error) from a tool execution. */
 interface ToolResultBlock {
-    type: 'tool_result';
-    toolUseId: string;
+    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 {
-    type: 'role_transition';
+    id: UUID;
+    type: 'role:transition';
     previousRole: string | null;
     newRole: string;
 }
-type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | SummaryBlock | RoleTransitionBlock | ThinkingBlock;
-type TurnRole = 'user' | 'assistant' | 'tool';
+/** 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[];
+    };
+    /** 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;
+} | {
+    type: 'tool';
+    payload: ToolCall;
+};
+/** 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;
-    role: 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.
-     */
-    roleSnapshot?: 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.
-     */
+    /** Name of the role active at the time of this turn. */
+    role?: string;
+    /** 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;
@@ -159,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;
@@ -168,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;
@@ -198,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[];
@@ -219,17 +349,39 @@ 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;
+    text: string;
+    completed?: Timestamp;
+}
+/** A high-level objective with nested steps, used for tracking AI progress. */
+interface Task {
+    id: UUID;
+    title: string;
+    description?: string;
+    status: TaskStatus;
+    steps: TaskStep[];
+    topics: string[];
+    metadata?: Record<string, any>;
+    created: Timestamp;
+    updated: Timestamp;
 }
 interface RoleSummary {
     name: string;
     label: string;
     description?: string;
-    /** Number of preference IDs listed on the role. */
     preferences: number;
 }
 interface PreferenceSummary {
@@ -248,30 +400,49 @@ interface ContextSummary {
     source?: string;
     metadata?: Record<string, any>;
 }
+interface TaskSummary {
+    id: UUID;
+    title: string;
+    status: TaskStatus;
+    steps: {
+        completed: number;
+        total: number;
+    };
+    topics: string[];
+}
+/** Maps topics to the various entities that reference them. */
 interface TopicIndex {
     topic: string;
     contextKeys: string[];
     preferences: UUID[];
+    tasks: UUID[];
     metadata?: {
         created?: Timestamp;
         updated?: Timestamp;
         entries?: number;
     };
 }
+/** The complete in-memory read-model of the Workspace state. */
 interface Index {
     roles: Record<string, RoleSummary>;
     preferences: Record<UUID, PreferenceSummary>;
     context: Record<string, ContextSummary>;
     sessions: Record<UUID, SessionMeta>;
+    tasks: Record<UUID, TaskSummary>;
     topics: Record<string, TopicIndex>;
     blobs: Record<SHA256, BlobRecord>;
+    tools: Record<string, ToolSummary>;
 }
-interface Workspace {
+/** The root container for a user's workspace. */
+interface Workspace<ProjectMetadata extends Record<string, any> = Record<string, any>> {
     id: UUID;
     settings: Settings;
-    project: Project;
+    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;
@@ -281,33 +452,27 @@ interface WorkspaceBundle {
     sessions: Record<UUID, SessionMeta & {
         turns: Turn[];
     }>;
+    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;
     preferences: Preference[];
     context: Context[];
     transcript: Turn[];
+    task: Task | null;
     instructions?: string;
 }
-interface CacheConfig {
-    roles?: number;
-    preferences?: number;
-    context?: 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';
@@ -375,6 +540,31 @@ interface DeleteContext extends BaseCommand {
         key: string;
     };
 }
+interface AddTask extends BaseCommand {
+    type: 'task:add';
+    payload: Task;
+}
+interface UpdateTask extends BaseCommand {
+    type: 'task:update';
+    payload: Partial<Task> & {
+        id: UUID;
+    };
+}
+interface DeleteTask extends BaseCommand {
+    type: 'task:delete';
+    payload: {
+        id: UUID;
+    };
+}
+/** Updates an existing turn record in storage. */
+interface SaveTurn extends BaseCommand {
+    type: 'turn:save';
+    payload: {
+        sessionId: UUID;
+        turn: Turn;
+    };
+}
+/** Appends a new turn to a session. */
 interface AddTurn extends BaseCommand {
     type: 'turn:add';
     payload: {
@@ -382,6 +572,7 @@ interface AddTurn extends BaseCommand {
         turn: Turn;
     };
 }
+/** Creates a new version of an existing turn. */
 interface EditTurn extends BaseCommand {
     type: 'turn:edit';
     payload: {
@@ -392,25 +583,26 @@ 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: {
         sessionId: UUID;
-        parentTurnId: UUID;
-        parentVersion: number;
-        newTurn: Turn;
+        turn: Turn;
     };
 }
+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: {
         sessionId: UUID;
         turnId: UUID;
         version: number;
-        newHead: {
-            id: UUID;
-            version: number;
-        } | null;
+        newHead: TurnRef | null;
     };
 }
 interface SwitchRole extends BaseCommand {
@@ -434,6 +626,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: {
@@ -444,6 +637,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: {
@@ -458,64 +662,73 @@ 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;
-type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | AddContext | UpdateContext | DeleteContext | AddTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | BlobCommand;
+interface CallTool extends BaseCommand {
+    type: 'tool:call';
+    payload: ToolCall;
+}
+/** 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;
         preferences: Preference[];
         context: Context[];
+        task: Task | null;
     };
+    /** Additional context items injected separately. */
     context: Context[];
+    /** The conversation history. */
     transcript: {
         turns: Turn[];
     };
@@ -524,6 +737,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;
@@ -532,11 +746,116 @@ 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 standardized Turn object for the workspace transcript.
+     */
+    parse(params: {
+        response: TResponse;
+    }): Turn;
 }
 
 /**
@@ -971,32 +1290,35 @@ declare const COLLECTIONS: {
     readonly CONTEXT: "context";
     readonly SESSION: "session";
     readonly TURN: "turn";
+    readonly TASK: "task";
 };
 type CollectionName = typeof COLLECTIONS[keyof typeof COLLECTIONS];
 
-/**
- * Utility type for representing partial updates to the state, allowing deep nesting.
- * It makes all properties optional and applies the same transformation recursively
- * to nested objects and array elements, allowing for selective updates while
- * preserving the original structure. It also includes the original type T and
- * undefined as possibilities for the top level and nested values.
- */
-type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
-    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
-} | undefined | T : T | undefined;
-
 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 omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
-declare function createSimpleWorkspace({ name, owner, language }: {
+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, 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;
 
 /**
  * Persistence contract for binary blob content and blob registry records.
@@ -1045,10 +1367,6 @@ interface BlobStorage {
     registerBlob?(record: BlobRecord, data: Uint8Array): Promise<void>;
 }
 
-interface TurnRef {
-    id: UUID;
-    version: number;
-}
 declare class TurnTree {
     private readonly db;
     constructor(db: WorkspaceDatabase);
@@ -1059,20 +1377,26 @@ declare class TurnTree {
      * Uses only declared schema fields — never $id.
      */
     private turnFilter;
+    private loadRaw;
     getHead(sessionId: UUID): Promise<TurnRef | null>;
     setHead(sessionId: UUID, head: TurnRef | null): Promise<void>;
+    save(sessionId: UUID, turn: Turn, head?: TurnRef | null): Promise<Turn>;
     append(sessionId: UUID, turn: Turn): Promise<Turn>;
     appendBatch(sessionId: UUID, turns: Turn[], finalHead: TurnRef | null): Promise<void>;
     replaceVersion(sessionId: UUID, newTurn: Turn): Promise<void>;
     branch(sessionId: UUID, newTurn: Turn): Promise<void>;
     loadAllTurns(sessionId: UUID): Promise<Turn[]>;
-    getActiveChain(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Turn[]>;
+    loadTurnVersions(sessionId: UUID, turnId: UUID): Promise<Turn[]>;
+    buildNodes(turns: Turn[], head: TurnRef | null, dirtyBuffer?: readonly Turn[]): Record<UUID, TurnNode>;
     buildNodeGraph(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Record<UUID, TurnNode>>;
+    getActiveChain(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Turn[]>;
+    buildActiveChain(sessionId: UUID): Promise<TurnNode[]>;
+    getTurnSiblings(turnId: UUID, sessionId: UUID): Promise<TurnNode[]>;
+    branchInfo(turnId: UUID, sessionId: UUID): Promise<BranchInfo>;
     deleteSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<void>;
     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
@@ -1084,11 +1408,13 @@ interface BlobStoreConfig {
 declare class BlobStore {
     private readonly storage;
     private readonly config;
+    private bus;
     /**
      * In-memory cache of BlobRecords. Kept consistent with the backend on
      * every write. Records are small (no bytes), so we cache all of them.
      */
     private readonly recordCache;
+    constructor(backend: BlobStorage, bus: EventBus<WorkspaceEvents>, config?: BlobStoreConfig);
     /**
      * Called after any operation that changes the blob registry.
      * Passes the full BlobRecord (or null on deletion). The integration
@@ -1098,14 +1424,17 @@ declare class BlobStore {
      * that only need summary fields (sha256, mediaType, sizeBytes, etc.)
      * can read them directly from BlobRecord without a separate type.
      */
-    onRegistryChanged?: (sha256: SHA256, record: BlobRecord | null) => void;
-    constructor(backend: BlobStorage, config?: BlobStoreConfig);
+    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => void;
     init(): Promise<void>;
     register(data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<BlobRef, WorkspaceError>>;
     retain(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
     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>;
@@ -1115,7 +1444,6 @@ declare class BlobStore {
         }>;
     }>;
     gc(): Promise<number>;
-    gcFull(): Promise<number>;
     purge(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
     getRecord(sha256: SHA256): BlobRecord | null;
     /**
@@ -1125,6 +1453,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;
@@ -1132,17 +1469,11 @@ declare class ContentStore {
     private readonly roleCache;
     private readonly preferenceCache;
     private readonly contextCache;
-    /**
-     * Called after any blob registry change with the sha256 and updated
-     * BlobRecord (null on deletion). Wire this to your state manager to
-     * keep Index.blobs current.
-     *
-     * ContentStore sets this on BlobStore.onRegistryChanged internally.
-     * Consumers set this property to receive the forwarded notifications.
-     */
-    onBlobRegistryChanged?: (sha256: SHA256, record: BlobRecord | null) => void;
+    private readonly taskCache;
+    private bus;
+    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => void;
     private constructor();
-    static create(db: WorkspaceDatabase, blobStorage: BlobStorage, config?: ContentStoreConfig): Promise<ContentStore>;
+    static create(db: WorkspaceDatabase, blobStorage: BlobStorage, eventBus: EventBus<WorkspaceEvents>, config?: ContentStoreConfig): Promise<ContentStore>;
     private init;
     getTurnTree(): TurnTree;
     getRole(name: string): Promise<Result<Role, WorkspaceError>>;
@@ -1155,6 +1486,10 @@ declare class ContentStore {
     saveContext(context: Context): Promise<void>;
     deleteContext(key: string): Promise<void>;
     getContextByTopics(indexState: Index, topics: string[]): Promise<Context[]>;
+    getTask(id: UUID): Promise<Result<Task, WorkspaceError>>;
+    saveTask(task: Task): Promise<void>;
+    deleteTask(id: UUID): Promise<void>;
+    getTasksByTopics(indexState: Index, topics: string[]): Promise<Task[]>;
     saveSession(meta: SessionMeta): Promise<void>;
     updateSessionMeta(sessionId: UUID, patch: DeepPartial<SessionMeta>): Promise<void>;
     deleteSession(sessionId: UUID): Promise<void>;
@@ -1165,43 +1500,52 @@ declare class ContentStore {
     recordBlobRemoteId(sha256: SHA256, providerId: string, fileId: string): Promise<Result<void, WorkspaceError>>;
     getBlobRecord(sha256: SHA256): BlobRecord | null;
     getAllBlobRecords(): Record<SHA256, BlobRecord>;
-    /**
-     * Returns the blob resolver function expected by PromptBuilder.
-     * Closes over the internal BlobStore — no BlobStore reference leaks out.
-     */
     getBlobResolver(): BlobStore['resolveRefs'];
-    recordTurn(sessionId: UUID, turn: Turn): Promise<Result<void, WorkspaceError>>;
+    appendTurn(sessionId: UUID, turn: Turn): Promise<Result<Turn, WorkspaceError>>;
+    saveTurn(sessionId: UUID, turn: Turn): Promise<Result<Turn, WorkspaceError>>;
     editTurn(sessionId: UUID, turnId: UUID, newBlocks: ContentBlock[], newVersion: number, roleSnapshot?: string): Promise<Result<void, WorkspaceError>>;
     branchTurn(sessionId: UUID, newTurn: Turn): Promise<Result<void, WorkspaceError>>;
     deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<void, WorkspaceError>>;
     copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
     resolveSession(workspace: Workspace, sessionId: UUID, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
+    gc(): Promise<number>;
 }
 
-declare function workspaceReducer({ index: state }: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
-
 declare class WorkspaceManager {
     private readonly contentStore;
+    private readonly permissionGuard?;
+    private readonly toolRegistry?;
+    private readonly processor;
+    private bus;
+    constructor(options: {
+        contentStore: ContentStore;
+        permissionGuard?: PermissionGuard;
+        toolRegistry?: ToolRegistry;
+        eventBus: EventBus<WorkspaceEvents>;
+        turnProcessor?: TurnProcessor;
+    });
+    store(): ContentStore;
+    turnProcessor(): TurnProcessor;
     /**
-     * Called when BlobStore triggers a registry change outside of a dispatch()
-     * call — e.g. eagerEviction deleting a blob on release. The caller should
-     * merge this patch into their Workspace.
+     * Initializes a Workspace's in-memory Index from environment-static
+     * sources (like ToolRegistry). Call this when opening a Workspace.
      */
-    onWorkspacePatch?: (patch: DeepPartial<Workspace>) => void;
-    constructor(contentStore: ContentStore);
+    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): Promise<Result<EffectiveSession, WorkspaceError>>;
+    resolveSession(workspace: Workspace, sessionId: UUID, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
     private handleContentSideEffects;
 }
 
-interface Summarizer {
-    summarize(transcript: Turn[], tokenBudget: number): Promise<{
-        summary: string;
-        remaining: Turn[];
-    }>;
+interface ContextRelevanceConfig {
+    recentMessageWindow?: number;
+    minScore?: number;
+    freshnessHalfLifeDays?: number;
 }
-
 interface ContextRankingInput {
     entries: Context[];
     recentMessages: string[];
@@ -1215,12 +1559,14 @@ interface PlanningInput {
     persona: string;
     preferences: Preference[];
     context: Context[];
+    task: Task | null;
     transcript: Turn[];
     budget?: TokenBudget;
 }
 interface PlanningOutput {
     preferences: Preference[];
     context: Context[];
+    task: Task | null;
     transcript: Turn[];
     truncated: {
         preferences: number;
@@ -1272,52 +1618,287 @@ declare class PromptBuilder {
     private resolvePreferenceConflicts;
 }
 
+/**
+ * A fluent builder for creating Turn objects.
+ * This class helps construct a Turn object by adding various content blocks.
+ */
+declare class TurnBuilder {
+    private readonly _actor;
+    private _turn;
+    constructor(_actor: TurnActor, initialTurn?: Turn);
+    addText(text: string): TurnBuilder;
+    addImage(ref?: BlobRef, altText?: string): TurnBuilder;
+    addDocument(ref?: BlobRef, title?: string): TurnBuilder;
+    addToolUse(name: string, input: Record<string, unknown>): TurnBuilder;
+    addToolResult(useId: UUID, content: string | Record<string, unknown>, isError?: boolean): TurnBuilder;
+    addSummary(text: string): TurnBuilder;
+    addRoleTransition(previousRole: string | null, newRole: string): TurnBuilder;
+    addThinking(thinking: string): TurnBuilder;
+    /**
+     * Adds a task proposal block.
+     * @param title The task title.
+     * @param steps Array of step objects (each with text and optional id/status). Status defaults to 'todo'.
+     * @param action The action type ('create', 'update', 'complete'). Defaults to 'create'.
+     * @param taskId Optional existing task ID (for update/complete).
+     */
+    addTaskProposal(title: string, steps: {
+        text: string;
+        status?: 'todo' | 'done';
+        id?: UUID;
+    }[], action?: 'create' | 'update' | 'complete', taskId?: UUID): TurnBuilder;
+    addBlock(block: ContentBlock): TurnBuilder;
+    deleteBlock(blockId: UUID): TurnBuilder;
+    editTextBlock(blockId: UUID, newText: string): TurnBuilder;
+    withId(id: UUID): TurnBuilder;
+    withVersion(version: number): TurnBuilder;
+    withTimestamp(timestamp: Timestamp): TurnBuilder;
+    withParent(parent: TurnRef): TurnBuilder;
+    withRoleSnapshot(roleSnapshot: string): TurnBuilder;
+    build(): Turn;
+}
+
+declare class DefaultTurnProcessor implements TurnProcessor {
+    private readonly handlers;
+    process(turn: Turn, sessionId?: UUID): Command[];
+}
+
 declare class Session {
-    /** The session ID this object manages. */
-    readonly sessionId: UUID;
+    private readonly sessionId;
+    private readonly tree;
+    private readonly manager;
+    constructor(sessionId: UUID, tree: TurnTree, manager: WorkspaceManager);
+    /** Returns the UUID of this session. */
+    id(): UUID;
     /**
-     * The turn DAG. Keys are turn IDs. Mutated in-place on every write.
-     * Callers read this directly for rendering — no copy is made.
+     * Retrieves the full metadata record for this session from the workspace index.
      */
-    readonly nodes: Record<UUID, TurnNode>;
+    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;
     /**
-     * Current head of the active branch. Mirrors what is in
-     * workspace.index.sessions[sessionId].head after each patch is applied.
-     * Session keeps its own copy so reads don't require workspace.
+     * 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>;
+    /**
+     * Retrieves a single turn node by its ID from the session graph.
+     */
+    getTurn(turnId: UUID): Promise<TurnNode | undefined>;
+    /**
+     * 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.
+     */
+    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>>;
+    createTask(workspace: Workspace, title: string, description: string | undefined, steps: {
+        text: string;
+    }[], topics: string[]): 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;
+    /**
+     * 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.
      */
-    private head;
-    /** Turns not yet flushed to storage. */
-    private readonly dirtyBuffer;
-    private flushTimer;
-    private flushChain;
-    private readonly flushConfig;
-    private readonly tree;
-    private readonly contentStore;
-    constructor(sessionId: UUID, nodes: Record<UUID, TurnNode>, head: TurnRef | null, tree: TurnTree, contentStore: ContentStore, flushConfig?: FlushConfig);
-    activeChain(): TurnNode[];
-    siblings(turnId: UUID): TurnNode[];
-    branchInfo(turnId: UUID): BranchInfo;
     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>>;
-    branchFrom(workspace: Workspace, newTurn: Turn): 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>>;
-    switchVersionLeft(_: Workspace, turnId: UUID): Result<DeepPartial<Workspace>, WorkspaceError>;
-    switchVersionRight(_: Workspace, turnId: UUID): 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>>;
-    flush(): Promise<void>;
-    dispose(): Promise<void>;
-    private findSubtreeTipForVersion;
-    private collectSubtreeIds;
-    private upsertNode;
-    private scheduleFlush;
-    private cancelFlushTimer;
-    private doFlush;
-}
-declare function buildTurnNode(turn: Turn, children?: UUID[]): TurnNode;
+    private findSubtreeTip;
+}
 
 interface SessionManagerConfig {
-    flush?: Partial<FlushConfig>;
 }
 interface OpenResult {
     session: Session;
@@ -1326,11 +1907,30 @@ interface OpenResult {
 declare class SessionManager {
     private readonly workspaceManager;
     private readonly contentStore;
-    private readonly flushConfig;
-    constructor(workspaceManager: WorkspaceManager, contentStore: ContentStore, config?: SessionManagerConfig);
+    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>>;
-    close(session: Session): Promise<void>;
     get workspace(): WorkspaceManager;
+    close(_: Session): Promise<void>;
 }
 
 /**
@@ -1400,4 +2000,37 @@ declare class IndexedDBBlobStorage implements BlobStorage {
     registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
 }
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type BlobCommand, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CacheConfig, 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 DeleteTurn, type DocumentBlock, type DocumentMediaType, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, MemoryBlobStorage, 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, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type SummaryBlock, type SwitchRole, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolResultBlock, 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 Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, WorkspaceManager, buildTurnNode, computeSHA256, 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;
+    }): Turn;
+}
+
+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 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, err, extractBlobRecord, extractBlobRef, merge, ok, omitNullUndefined };