@asaidimu/utils-workspace 2.1.1 → 3.0.0

package/index.d.ts

@@ -1,5 +1,17 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
+import { EventBus } from '@asaidimu/events';
+
+/**
+ * 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;
 
 type UUID = string;
 type Timestamp = string;
@@ -12,35 +24,38 @@ type Result<T, E = WorkspaceError> = {
     ok: false;
     error: E;
 };
-type WorkspaceError = {
+type DuplicateKeyError = {
     code: 'DUPLICATE_KEY';
     resource: string;
     key: string;
-} | {
+};
+type NotFoundError = {
     code: 'NOT_FOUND';
     resource: string;
     id: string;
-} | {
+};
+type InvalidCommandError = {
     code: 'INVALID_COMMAND';
     reason: string;
-} | {
+};
+type BackendError = {
     code: 'BACKEND_ERROR';
     reason: string;
-} | {
+};
+type BlobError = {
     code: 'BLOB_ERROR';
     reason: string;
 };
+type WorkspaceError = DuplicateKeyError | NotFoundError | InvalidCommandError | BackendError | BlobError;
 interface Settings {
     language: string;
     defaultRole?: string;
     prompt?: string;
 }
-interface Project {
+type Project<Metadata extends Record<string, any> = Record<string, any>> = Metadata & {
+    id: UUID;
     name: string;
-    owner: string;
-    repository?: string;
-    metadata?: Record<string, any>;
-}
+};
 type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
 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';
 type BlobMediaType = ImageMediaType | DocumentMediaType;
@@ -78,59 +93,104 @@ interface BlobRecord {
     lastUsedAt: Timestamp;
 }
 interface TextBlock {
+    id: UUID;
     type: 'text';
     text: string;
 }
 interface ImageBlock {
+    id: UUID;
     type: 'image';
     ref?: BlobRef;
     blob?: ResolvedBlob;
     altText?: string;
 }
 interface DocumentBlock {
+    id: UUID;
     type: 'document';
     ref?: BlobRef;
     blob?: ResolvedBlob;
     title?: string;
 }
+interface TaskProposalBlock {
+    id: UUID;
+    taskId?: UUID;
+    type: 'task:proposal';
+    title: string;
+    steps: {
+        id?: UUID;
+        text: string;
+        status: 'todo' | 'done';
+    }[];
+    action: 'create' | 'update' | 'complete';
+}
 interface ToolUseBlock {
-    type: 'tool_use';
-    toolUseId: string;
+    id: UUID;
+    type: 'tool:use';
     name: string;
     input: Record<string, unknown>;
 }
 interface ToolResultBlock {
-    type: 'tool_result';
-    toolUseId: string;
+    id: UUID;
+    type: 'tool:result';
+    useId: UUID;
     content: string | Record<string, unknown>;
     isError?: boolean;
 }
 interface ThinkingBlock {
+    id: UUID;
     type: 'thinking';
     thinking: string;
 }
 interface SummaryBlock {
+    id: UUID;
     type: 'summary';
     text: string;
 }
 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 ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | SummaryBlock | RoleTransitionBlock | ThinkingBlock | TaskProposalBlock;
+interface ToolSummary {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, any>;
+        required: string[];
+    };
+    /**
+     * The semantic tags for this tool.
+     * Used by the ContextRetriever to filter relevance.
+     */
+    topics: string[];
+}
+interface ToolCall {
+    id: UUID;
+    tool: UUID;
+    arguments: Record<string, any>;
+}
+type AuthRequest = {
+    type: 'command';
+    payload: Command;
+} | {
+    type: 'tool';
+    payload: ToolCall;
+};
 type TurnRole = 'user' | 'assistant' | 'tool';
 interface Turn {
     id: UUID;
     version: number;
-    role: TurnRole;
+    owner: TurnRole;
     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;
+    role?: string;
     /**
      * Parent pointer. Null for root turns.
      * This is plain data stored on the document — the DAG is reconstructed
@@ -224,6 +284,24 @@ interface SessionMeta {
         id: UUID;
         version: number;
     } | null;
+    task: UUID | null;
+}
+type TaskStatus = 'todo' | 'active' | 'done' | 'blocked' | 'defered';
+interface TaskStep {
+    id: UUID;
+    text: string;
+    completed?: Timestamp;
+}
+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;
@@ -248,10 +326,21 @@ interface ContextSummary {
     source?: string;
     metadata?: Record<string, any>;
 }
+interface TaskSummary {
+    id: UUID;
+    title: string;
+    status: TaskStatus;
+    steps: {
+        completed: number;
+        total: number;
+    };
+    topics: string[];
+}
 interface TopicIndex {
     topic: string;
     contextKeys: string[];
     preferences: UUID[];
+    tasks: UUID[];
     metadata?: {
         created?: Timestamp;
         updated?: Timestamp;
@@ -263,13 +352,15 @@ interface Index {
     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 {
+interface Workspace<ProjectMetadata extends Record<string, any> = Record<string, any>> {
     id: UUID;
     settings: Settings;
-    project: Project;
+    project: Project<ProjectMetadata>;
     index: Index;
 }
 interface WorkspaceBundle {
@@ -281,6 +372,7 @@ interface WorkspaceBundle {
     sessions: Record<UUID, SessionMeta & {
         turns: Turn[];
     }>;
+    tasks: Record<UUID, Task>;
     blobs: Record<SHA256, BlobRecord>;
 }
 interface EffectiveSession {
@@ -289,12 +381,14 @@ interface EffectiveSession {
     preferences: Preference[];
     context: Context[];
     transcript: Turn[];
+    task: Task | null;
     instructions?: string;
 }
 interface CacheConfig {
     roles?: number;
     preferences?: number;
     context?: number;
+    tasks?: number;
 }
 interface FlushConfig {
     maxBufferSize: number;
@@ -375,6 +469,29 @@ 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;
+    };
+}
+interface SaveTurn extends BaseCommand {
+    type: 'turn:save';
+    payload: {
+        sessionId: UUID;
+        turn: Turn;
+    };
+}
 interface AddTurn extends BaseCommand {
     type: 'turn:add';
     payload: {
@@ -396,21 +513,20 @@ interface BranchTurn extends BaseCommand {
     type: 'turn:branch';
     payload: {
         sessionId: UUID;
-        parentTurnId: UUID;
-        parentVersion: number;
-        newTurn: Turn;
+        turn: Turn;
     };
 }
+interface TurnRef {
+    id: UUID;
+    version: number;
+}
 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 {
@@ -485,7 +601,11 @@ interface RecordBlobRemoteId extends BaseCommand {
     };
 }
 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;
+}
+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;
 interface TokenBudget {
     total: number;
     estimator?: (text: string) => number;
@@ -514,6 +634,7 @@ interface Prompt {
         persona: string;
         preferences: Preference[];
         context: Context[];
+        task: Task | null;
     };
     context: Context[];
     transcript: {
@@ -538,6 +659,13 @@ interface TranscriptWindow {
     flushedCount: number;
     hasMore: boolean;
 }
+interface WorkspaceEvents {
+    'workspace:changed': DeepPartial<Workspace>;
+    'blobs:changed': {
+        sha256: SHA256;
+        record: BlobRecord | null;
+    };
+}
 
 /**
  * Buffers write operations across one or more stores and commits them atomically.
@@ -971,25 +1099,19 @@ 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 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 }: {
     name: string;
     language: string;
@@ -1045,10 +1167,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,15 +1177,22 @@ 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>;
 }
@@ -1084,11 +1209,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,8 +1225,7 @@ 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>>;
@@ -1115,7 +1241,6 @@ declare class BlobStore {
         }>;
     }>;
     gc(): Promise<number>;
-    gcFull(): Promise<number>;
     purge(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
     getRecord(sha256: SHA256): BlobRecord | null;
     /**
@@ -1132,17 +1257,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 +1274,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 +1288,75 @@ 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>;
 
+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 bus;
     /**
-     * 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.
+     * Called after any workspace change
      */
-    onWorkspacePatch?: (patch: DeepPartial<Workspace>) => void;
-    constructor(contentStore: ContentStore);
+    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => void;
+    constructor(options: {
+        contentStore: ContentStore;
+        permissionGuard?: PermissionGuard;
+        toolRegistry?: ToolRegistry;
+        eventBus: EventBus<WorkspaceEvents>;
+    });
+    /**
+     * Initializes a Workspace's in-memory Index from environment-static
+     * sources (like ToolRegistry). Call this when opening a Workspace.
+     */
+    init(_: Workspace): DeepPartial<Workspace>;
     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 ContextRankingInput {
     entries: Context[];
     recentMessages: string[];
@@ -1215,12 +1370,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,49 +1429,87 @@ 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 _owner;
+    private _turn;
+    constructor(_owner: TurnRole, 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 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);
+    turns(): Promise<TurnNode[]>;
+    siblings(turnId: UUID): Promise<TurnNode[]>;
+    branchInfo(turnId: UUID): Promise<BranchInfo>;
+    id(): string;
     /**
-     * The turn DAG. Keys are turn IDs. Mutated in-place on every write.
-     * Callers read this directly for rendering — no copy is made.
+     * 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.
      */
-    readonly nodes: Record<UUID, TurnNode>;
+    startTurn(owner: TurnRole): TurnBuilder;
     /**
-     * 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.
+     * 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.
      */
-    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>>;
+    /**
+     * 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.
+     */
     editTurn(workspace: Workspace, turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    branchFrom(workspace: Workspace, newTurn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    branch(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     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>;
+    switchVersionLeft(workspace: Workspace, turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    switchVersionRight(workspace: Workspace, turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     private switchVersion;
     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;
+}
 
 interface SessionManagerConfig {
     flush?: Partial<FlushConfig>;
@@ -1326,11 +1521,10 @@ 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);
     open(workspace: Workspace, sessionId: UUID): Promise<Result<OpenResult, WorkspaceError>>;
-    close(session: Session): Promise<void>;
     get workspace(): WorkspaceManager;
+    close(_: Session): Promise<void>;
 }
 
 /**
@@ -1400,4 +1594,4 @@ 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 };
+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 };