@asaidimu/utils-workspace 6.5.5 → 6.5.7

package/index.d.mts

@@ -1769,9 +1769,7 @@ interface ContentBlockDefinition {
      * - `false` → workspace-internal only; invisible to the model
      */
     emittable: boolean;
-    /**
-     * Whether this block should be included in input to models
-     */
+    /** Whether this block should be included in input to models */
     consumable?: boolean;
     /**
      * Ordered list of behavioural rules for this block type.
@@ -2690,10 +2688,17 @@ declare class Session {
     private tree;
     private unsubscribe?;
     private constructor();
+    /**
+     * Factory method to create a new Session instance.
+     * @param sessionId - Unique identifier for the session.
+     * @param manager - Workspace manager for dispatching commands.
+     * @param processor - Turn processor for handling tool calls.
+     * @returns A fully initialised Session.
+     */
     static create(sessionId: UUID, manager: WorkspaceManager, processor: TurnProcessor): Promise<Session>;
     /**
-     * Synchronizes the session's in-memory state with the persistent stores.
-     * Useful after a workspace-wide sync or if state becomes stale.
+     * Synchronises the session's in‑memory state with the persistent stores.
+     * Useful after a workspace‑wide sync or if state becomes stale.
      */
     sync(): Promise<void>;
     /**
@@ -2702,57 +2707,163 @@ declare class Session {
     close(): void;
     private _setRole;
     private _setPreference;
+    /** Returns the session’s unique identifier. */
     id(): UUID;
     private ws;
+    /** Returns the session metadata from the workspace index. */
     meta(): SessionMetadata | undefined;
+    /** Returns the session’s label (display name). */
     label(): string | undefined;
+    /** Returns the session’s current Role object. */
     role(): Role | undefined;
+    /** Returns the list of topic strings associated with the session. */
     topics(): string[];
+    /** Returns the list of preferences active for this session. */
     preferences(): Preference[];
+    /** Returns the current head (last turn) of the session, or null if empty. */
     head(): TurnRef | null;
+    /** Returns the active chain of turns as an array of TurnNode. */
     turns(): TurnNode[];
+    /**
+     * Returns all sibling turns of a given turn (other children of the same parent).
+     * @param turnId - ID of the turn.
+     */
     siblings(turnId: UUID): Promise<TurnNode[]>;
+    /**
+     * Returns branching information for a turn (versions, navigation).
+     * @param turnId - ID of the turn.
+     */
     branchInfo(turnId: UUID): Promise<BranchInfo>;
+    /**
+     * Retrieves a TurnNode by its ID.
+     * @param turnId - ID of the turn.
+     */
     getTurn(turnId: UUID): Promise<TurnNode | undefined>;
+    /**
+     * Changes the session’s display label.
+     * @param newLabel - New label for the session.
+     */
     rename(newLabel: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Replaces the session’s topic list.
+     * @param topics - New array of topic strings.
+     */
     setTopics(topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     /**
-     * Updates the session's model identifier.
+     * Updates the session’s model identifier (e.g., "gpt-4").
+     * @param model - New model string.
      */
     setModel(model: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     /**
-     * Merges the provided metadata into the session's current metadata.
+     * Merges arbitrary metadata into the session’s metadata object.
+     * @param metadata - Key‑value pairs to merge.
      */
     updateMetadata(metadata: Record<string, any>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Adds topics to the session (does not replace existing ones).
+     * @param topics - Topics to add.
+     */
     addTopics(topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Replaces the session’s preference list with the given IDs.
+     * @param preferenceIds - Array of preference UUIDs.
+     */
     setPreferences(preferenceIds: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Creates a new session as a fork of this one.
+     * @param newSessionId - ID for the new session.
+     * @param label - Label for the new session.
+     * @param role - Optional role ID (defaults to current role).
+     * @param topics - Optional topics (defaults to current topics).
+     */
     fork(newSessionId: UUID, label: string, role?: string, topics?: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Dispatches a raw command to the workspace manager.
+     * @param command - BaseCommand to dispatch.
+     */
     dispatch(command: BaseCommand): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switches the session to a different role.
+     * @param newRole - ID of the new role (or EMPTY_SYSTEM_ROLE).
+     */
     switchRole(newRole: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Adds a turn to the session. The turn’s parent, version, role, and model
+     * are automatically filled if missing.
+     * @param turn - The turn to add (may be incomplete).
+     * @returns Result with the workspace patch and updates the in‑memory tree.
+     */
     addTurn(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Records a user turn (alias for addTurn).
+     * @param turn - The user turn.
+     */
     recordUserTurn(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Records an assistant turn, processes any tool calls, and optionally records denial turns.
+     * @param turn - The assistant turn (may contain tool calls).
+     * @param recordDenial - If true, adds a user turn explaining denied tool calls.
+     * @returns Result with the merged workspace patches.
+     */
     recordAssistantTurn(turn: Turn, recordDenial?: boolean): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     private buildDenialTurn;
     private describeCommand;
+    /**
+     * Edits an existing turn, creating a new version. The session head is moved to this new version.
+     * @param turnId - ID of the turn to edit.
+     * @param newBlocks - New content blocks for the turn.
+     * @param roleSnapshot - Optional role to associate (defaults to current active version's role).
+     * @param modelSnapshot - Optional model to associate (defaults to current active version's model).
+     */
     editTurn(turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string, modelSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Adds a branch turn (a turn that shares a parent with an existing turn).
+     * @param turn - The turn to branch (must have parent set).
+     */
     branch(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Deletes a specific version of a turn and optionally updates the session head.
+     * @param turnId - ID of the turn.
+     * @param version - Version number to delete.
+     * @param newHead - New head reference after deletion (or null to keep current head if still valid).
+     */
     deleteTurn(turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     /**
-     * Updates the status of a specific turn using the Result pattern.
+     * Updates the status (success/unsuccessful) of a specific turn version.
+     * @param turnId - ID of the turn.
+     * @param version - Version number of the turn to update.
+     * @param status - Result indicating success or failure.
+     */
+    updateTurnStatus(turnId: UUID, version: number, status: Result<undefined, WorkspaceError>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switches to the previous version of a turn (if available).
+     * @param turnId - ID of the turn.
      */
-    updateTurnStatus(turnId: UUID, status: Result<undefined, WorkspaceError>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     switchVersionLeft(turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switches to the next version of a turn (if available).
+     * @param turnId - ID of the turn.
+     */
     switchVersionRight(turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     private switchVersion;
     /**
-     * Assembles a SessionSnapshot for PromptBuilder.
-     * * @param target - Optional target for the snapshot.
-     * If a UUID is provided, it snapshots the history ending at that turn.
-     * If a Turn object is provided, it snapshots a "potential" state where
-     * this turn is appended to its parent (or current head) without committing it.
+     * Assembles a SessionSnapshot for the PromptBuilder.
+     * @param target - Optional target:
+     *   - If a UUID is provided, snapshots history ending at that turn.
+     *   - If a Turn object is provided, snapshots a "potential" state where
+     *     this turn is appended to its parent (or current head) without committing it.
      */
     snapshot(target?: UUID | Turn): Promise<SessionSnapshot | undefined>;
+    /**
+     * Rebuilds the in‑memory TurnTree.
+     * @param headOverride - If provided, use this as the session head instead of reading from the store.
+     *                       This avoids stale reads after mutations that change the head.
+     */
     private refreshTurnTree;
+    /**
+     * Finds the deepest descendant (tip) of a given turn version.
+     * Used when switching versions to determine the new session head.
+     */
     private findSubtreeTip;
 }
 
@@ -2865,7 +2976,7 @@ declare class TurnTree {
     private readonly nodes;
     private readonly _head;
     private constructor();
-    static build(sessionId: UUID, repository: TurnRepository): Promise<TurnTree>;
+    static build(sessionId: UUID, repository: TurnRepository, headOverride?: TurnRef | null): Promise<TurnTree>;
     head(): TurnRef | null;
     chain(): TurnNode[];
     /**

package/index.d.ts

@@ -1769,9 +1769,7 @@ interface ContentBlockDefinition {
      * - `false` → workspace-internal only; invisible to the model
      */
     emittable: boolean;
-    /**
-     * Whether this block should be included in input to models
-     */
+    /** Whether this block should be included in input to models */
     consumable?: boolean;
     /**
      * Ordered list of behavioural rules for this block type.
@@ -2690,10 +2688,17 @@ declare class Session {
     private tree;
     private unsubscribe?;
     private constructor();
+    /**
+     * Factory method to create a new Session instance.
+     * @param sessionId - Unique identifier for the session.
+     * @param manager - Workspace manager for dispatching commands.
+     * @param processor - Turn processor for handling tool calls.
+     * @returns A fully initialised Session.
+     */
     static create(sessionId: UUID, manager: WorkspaceManager, processor: TurnProcessor): Promise<Session>;
     /**
-     * Synchronizes the session's in-memory state with the persistent stores.
-     * Useful after a workspace-wide sync or if state becomes stale.
+     * Synchronises the session's in‑memory state with the persistent stores.
+     * Useful after a workspace‑wide sync or if state becomes stale.
      */
     sync(): Promise<void>;
     /**
@@ -2702,57 +2707,163 @@ declare class Session {
     close(): void;
     private _setRole;
     private _setPreference;
+    /** Returns the session’s unique identifier. */
     id(): UUID;
     private ws;
+    /** Returns the session metadata from the workspace index. */
     meta(): SessionMetadata | undefined;
+    /** Returns the session’s label (display name). */
     label(): string | undefined;
+    /** Returns the session’s current Role object. */
     role(): Role | undefined;
+    /** Returns the list of topic strings associated with the session. */
     topics(): string[];
+    /** Returns the list of preferences active for this session. */
     preferences(): Preference[];
+    /** Returns the current head (last turn) of the session, or null if empty. */
     head(): TurnRef | null;
+    /** Returns the active chain of turns as an array of TurnNode. */
     turns(): TurnNode[];
+    /**
+     * Returns all sibling turns of a given turn (other children of the same parent).
+     * @param turnId - ID of the turn.
+     */
     siblings(turnId: UUID): Promise<TurnNode[]>;
+    /**
+     * Returns branching information for a turn (versions, navigation).
+     * @param turnId - ID of the turn.
+     */
     branchInfo(turnId: UUID): Promise<BranchInfo>;
+    /**
+     * Retrieves a TurnNode by its ID.
+     * @param turnId - ID of the turn.
+     */
     getTurn(turnId: UUID): Promise<TurnNode | undefined>;
+    /**
+     * Changes the session’s display label.
+     * @param newLabel - New label for the session.
+     */
     rename(newLabel: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Replaces the session’s topic list.
+     * @param topics - New array of topic strings.
+     */
     setTopics(topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     /**
-     * Updates the session's model identifier.
+     * Updates the session’s model identifier (e.g., "gpt-4").
+     * @param model - New model string.
      */
     setModel(model: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     /**
-     * Merges the provided metadata into the session's current metadata.
+     * Merges arbitrary metadata into the session’s metadata object.
+     * @param metadata - Key‑value pairs to merge.
      */
     updateMetadata(metadata: Record<string, any>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Adds topics to the session (does not replace existing ones).
+     * @param topics - Topics to add.
+     */
     addTopics(topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Replaces the session’s preference list with the given IDs.
+     * @param preferenceIds - Array of preference UUIDs.
+     */
     setPreferences(preferenceIds: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Creates a new session as a fork of this one.
+     * @param newSessionId - ID for the new session.
+     * @param label - Label for the new session.
+     * @param role - Optional role ID (defaults to current role).
+     * @param topics - Optional topics (defaults to current topics).
+     */
     fork(newSessionId: UUID, label: string, role?: string, topics?: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Dispatches a raw command to the workspace manager.
+     * @param command - BaseCommand to dispatch.
+     */
     dispatch(command: BaseCommand): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switches the session to a different role.
+     * @param newRole - ID of the new role (or EMPTY_SYSTEM_ROLE).
+     */
     switchRole(newRole: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Adds a turn to the session. The turn’s parent, version, role, and model
+     * are automatically filled if missing.
+     * @param turn - The turn to add (may be incomplete).
+     * @returns Result with the workspace patch and updates the in‑memory tree.
+     */
     addTurn(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Records a user turn (alias for addTurn).
+     * @param turn - The user turn.
+     */
     recordUserTurn(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Records an assistant turn, processes any tool calls, and optionally records denial turns.
+     * @param turn - The assistant turn (may contain tool calls).
+     * @param recordDenial - If true, adds a user turn explaining denied tool calls.
+     * @returns Result with the merged workspace patches.
+     */
     recordAssistantTurn(turn: Turn, recordDenial?: boolean): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     private buildDenialTurn;
     private describeCommand;
+    /**
+     * Edits an existing turn, creating a new version. The session head is moved to this new version.
+     * @param turnId - ID of the turn to edit.
+     * @param newBlocks - New content blocks for the turn.
+     * @param roleSnapshot - Optional role to associate (defaults to current active version's role).
+     * @param modelSnapshot - Optional model to associate (defaults to current active version's model).
+     */
     editTurn(turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string, modelSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Adds a branch turn (a turn that shares a parent with an existing turn).
+     * @param turn - The turn to branch (must have parent set).
+     */
     branch(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Deletes a specific version of a turn and optionally updates the session head.
+     * @param turnId - ID of the turn.
+     * @param version - Version number to delete.
+     * @param newHead - New head reference after deletion (or null to keep current head if still valid).
+     */
     deleteTurn(turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     /**
-     * Updates the status of a specific turn using the Result pattern.
+     * Updates the status (success/unsuccessful) of a specific turn version.
+     * @param turnId - ID of the turn.
+     * @param version - Version number of the turn to update.
+     * @param status - Result indicating success or failure.
+     */
+    updateTurnStatus(turnId: UUID, version: number, status: Result<undefined, WorkspaceError>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switches to the previous version of a turn (if available).
+     * @param turnId - ID of the turn.
      */
-    updateTurnStatus(turnId: UUID, status: Result<undefined, WorkspaceError>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     switchVersionLeft(turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Switches to the next version of a turn (if available).
+     * @param turnId - ID of the turn.
+     */
     switchVersionRight(turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     private switchVersion;
     /**
-     * Assembles a SessionSnapshot for PromptBuilder.
-     * * @param target - Optional target for the snapshot.
-     * If a UUID is provided, it snapshots the history ending at that turn.
-     * If a Turn object is provided, it snapshots a "potential" state where
-     * this turn is appended to its parent (or current head) without committing it.
+     * Assembles a SessionSnapshot for the PromptBuilder.
+     * @param target - Optional target:
+     *   - If a UUID is provided, snapshots history ending at that turn.
+     *   - If a Turn object is provided, snapshots a "potential" state where
+     *     this turn is appended to its parent (or current head) without committing it.
      */
     snapshot(target?: UUID | Turn): Promise<SessionSnapshot | undefined>;
+    /**
+     * Rebuilds the in‑memory TurnTree.
+     * @param headOverride - If provided, use this as the session head instead of reading from the store.
+     *                       This avoids stale reads after mutations that change the head.
+     */
     private refreshTurnTree;
+    /**
+     * Finds the deepest descendant (tip) of a given turn version.
+     * Used when switching versions to determine the new session head.
+     */
     private findSubtreeTip;
 }
 
@@ -2865,7 +2976,7 @@ declare class TurnTree {
     private readonly nodes;
     private readonly _head;
     private constructor();
-    static build(sessionId: UUID, repository: TurnRepository): Promise<TurnTree>;
+    static build(sessionId: UUID, repository: TurnRepository, headOverride?: TurnRef | null): Promise<TurnTree>;
     head(): TurnRef | null;
     chain(): TurnNode[];
     /**