@asaidimu/utils-workspace 3.1.0 → 4.0.0

package/index.d.mts

@@ -165,12 +165,12 @@ interface DocumentBlock {
 }
 /** Represents a structured proposal to create or modify a task. */
 interface TaskProposalBlock {
-    id: UUID;
-    taskId?: UUID;
+    id?: UUID;
+    ref?: string;
     type: 'task:proposal';
     title: string;
     steps: {
-        id?: UUID;
+        ref?: string;
         text: string;
         status: 'todo' | 'done';
     }[];
@@ -362,13 +362,14 @@ interface SessionMeta {
 type TaskStatus = 'todo' | 'active' | 'done' | 'blocked' | 'defered';
 /** A single item within a Task's checklist. */
 interface TaskStep {
-    id: UUID;
+    ref: string;
     text: string;
     completed?: Timestamp;
 }
 /** A high-level objective with nested steps, used for tracking AI progress. */
 interface Task {
     id: UUID;
+    ref?: string;
     title: string;
     description?: string;
     status: TaskStatus;
@@ -402,6 +403,8 @@ interface ContextSummary {
 }
 interface TaskSummary {
     id: UUID;
+    ref?: string;
+    description: string;
     title: string;
     status: TaskStatus;
     steps: {
@@ -540,15 +543,18 @@ interface DeleteContext extends BaseCommand {
         key: string;
     };
 }
+type TaskRef = UUID | string;
 interface AddTask extends BaseCommand {
     type: 'task:add';
     payload: Task;
 }
 interface UpdateTask extends BaseCommand {
     type: 'task:update';
-    payload: Partial<Task> & {
+    payload: Partial<Task> & ({
         id: UUID;
-    };
+    } | {
+        ref: string;
+    });
 }
 interface DeleteTask extends BaseCommand {
     type: 'task:delete';
@@ -851,11 +857,11 @@ interface LLMAdapter<TRequest, TRequestParams, TResponse> {
     /**
      * 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.
+     * @returns A Result containing standardized Turn object or an error.
      */
     parse(params: {
         response: TResponse;
-    }): Turn;
+    }): Result<Turn, WorkspaceError>;
 }
 
 /**
@@ -1296,8 +1302,8 @@ type CollectionName = typeof COLLECTIONS[keyof typeof COLLECTIONS];
 
 declare function del<T>(): T;
 declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
-declare function ok<T>(value: T): Result<T, never>;
-declare function err<E = WorkspaceError>(error: E): Result<never, E>;
+declare function success<T>(value: T): Result<T, never>;
+declare function error<E = WorkspaceError>(error: E): Result<never, E>;
 declare function omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
 declare function createProjectWorkspace<ProjectMetadata extends Record<string, any> = Record<string, any>>({ project, language }: {
     language: string;
@@ -1320,6 +1326,27 @@ declare const createEmptyRole: (name: string, label: string) => Role;
  */
 declare function bufferToBase64(data: ArrayBuffer | Uint8Array | number[]): string;
 
+/**
+ * Short, deterministic hash of a string (4 chars in base36).
+ * Suitable for AI-friendly reference tokens.
+ */
+declare function shortHash(s: string, length?: number): string;
+/**
+ * Generates a short, memorable reference for a task.
+ * - Returns the proposal's own `ref` if provided.
+ * - Otherwise returns a 4‑character hash of the proposal's `id` or `title`.
+ */
+declare function generateTaskRef(proposal: TaskProposalBlock): string;
+/**
+ * Generates a short step reference.
+ * - Returns the step's own `ref` if provided.
+ * - Otherwise returns `${taskRef}_${index+1}` (e.g., "a3f9_2").
+ *
+ * The underscore separator avoids confusion with colons, slashes, or
+ * numeric suffixes that could be misinterpreted by LLMs.
+ */
+declare function generateTaskStepRef(index: number, proposal: TaskProposalBlock): string;
+
 /**
  * Persistence contract for binary blob content and blob registry records.
  *
@@ -1644,8 +1671,8 @@ declare class TurnBuilder {
     addTaskProposal(title: string, steps: {
         text: string;
         status?: 'todo' | 'done';
-        id?: UUID;
-    }[], action?: 'create' | 'update' | 'complete', taskId?: UUID): TurnBuilder;
+        ref?: string;
+    }[], action?: 'create' | 'update' | 'complete', id?: string): TurnBuilder;
     addBlock(block: ContentBlock): TurnBuilder;
     deleteBlock(blockId: UUID): TurnBuilder;
     editTextBlock(blockId: UUID, newText: string): TurnBuilder;
@@ -1760,9 +1787,6 @@ declare class Session {
      * @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.
@@ -2030,7 +2054,7 @@ declare class GoogleGenAIAdapter implements LLMAdapter<{
      */
     parse({ response }: {
         response: GenerateContentResponse;
-    }): Turn;
+    }): Result<Turn, WorkspaceError>;
 }
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTask, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CallTool, type CollectionName, type Command, type ContentBlock, ContentStore, type Context, type ContextContent, type ContextSummary, type CreateSession, type CreateWorkspace, DefaultTurnProcessor, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTask, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type EffectiveSession, type ForkSession, GoogleGenAIAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InvalidCommandError, type LLMAdapter, MemoryBlobStorage, type NotFoundError, type OpenResult, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, type SaveTurn, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type Summarizer, type SummaryBlock, type SwitchRole, type Task, type TaskProposalBlock, type 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 };
+export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTask, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CallTool, type CollectionName, type Command, type ContentBlock, ContentStore, type Context, type ContextContent, type ContextSummary, type CreateSession, type CreateWorkspace, DefaultTurnProcessor, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTask, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type EffectiveSession, type ForkSession, GoogleGenAIAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InvalidCommandError, type LLMAdapter, MemoryBlobStorage, type NotFoundError, type OpenResult, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, type SaveTurn, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type Summarizer, type SummaryBlock, type SwitchRole, type Task, type TaskProposalBlock, type TaskRef, type TaskStatus, type TaskStep, type TaskSummary, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolCall, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type TopicIndex, type Turn, type TurnActor, TurnBuilder, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTask, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, WorkspaceManager, bufferToBase64, computeSHA256, createEmptyRole, createProjectWorkspace, createSimpleWorkspace, createWorkspaceDatabase, del, error, extractBlobRecord, extractBlobRef, generateTaskRef, generateTaskStepRef, merge, omitNullUndefined, shortHash, success };

package/index.d.ts

@@ -165,12 +165,12 @@ interface DocumentBlock {
 }
 /** Represents a structured proposal to create or modify a task. */
 interface TaskProposalBlock {
-    id: UUID;
-    taskId?: UUID;
+    id?: UUID;
+    ref?: string;
     type: 'task:proposal';
     title: string;
     steps: {
-        id?: UUID;
+        ref?: string;
         text: string;
         status: 'todo' | 'done';
     }[];
@@ -362,13 +362,14 @@ interface SessionMeta {
 type TaskStatus = 'todo' | 'active' | 'done' | 'blocked' | 'defered';
 /** A single item within a Task's checklist. */
 interface TaskStep {
-    id: UUID;
+    ref: string;
     text: string;
     completed?: Timestamp;
 }
 /** A high-level objective with nested steps, used for tracking AI progress. */
 interface Task {
     id: UUID;
+    ref?: string;
     title: string;
     description?: string;
     status: TaskStatus;
@@ -402,6 +403,8 @@ interface ContextSummary {
 }
 interface TaskSummary {
     id: UUID;
+    ref?: string;
+    description: string;
     title: string;
     status: TaskStatus;
     steps: {
@@ -540,15 +543,18 @@ interface DeleteContext extends BaseCommand {
         key: string;
     };
 }
+type TaskRef = UUID | string;
 interface AddTask extends BaseCommand {
     type: 'task:add';
     payload: Task;
 }
 interface UpdateTask extends BaseCommand {
     type: 'task:update';
-    payload: Partial<Task> & {
+    payload: Partial<Task> & ({
         id: UUID;
-    };
+    } | {
+        ref: string;
+    });
 }
 interface DeleteTask extends BaseCommand {
     type: 'task:delete';
@@ -851,11 +857,11 @@ interface LLMAdapter<TRequest, TRequestParams, TResponse> {
     /**
      * 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.
+     * @returns A Result containing standardized Turn object or an error.
      */
     parse(params: {
         response: TResponse;
-    }): Turn;
+    }): Result<Turn, WorkspaceError>;
 }
 
 /**
@@ -1296,8 +1302,8 @@ type CollectionName = typeof COLLECTIONS[keyof typeof COLLECTIONS];
 
 declare function del<T>(): T;
 declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
-declare function ok<T>(value: T): Result<T, never>;
-declare function err<E = WorkspaceError>(error: E): Result<never, E>;
+declare function success<T>(value: T): Result<T, never>;
+declare function error<E = WorkspaceError>(error: E): Result<never, E>;
 declare function omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
 declare function createProjectWorkspace<ProjectMetadata extends Record<string, any> = Record<string, any>>({ project, language }: {
     language: string;
@@ -1320,6 +1326,27 @@ declare const createEmptyRole: (name: string, label: string) => Role;
  */
 declare function bufferToBase64(data: ArrayBuffer | Uint8Array | number[]): string;
 
+/**
+ * Short, deterministic hash of a string (4 chars in base36).
+ * Suitable for AI-friendly reference tokens.
+ */
+declare function shortHash(s: string, length?: number): string;
+/**
+ * Generates a short, memorable reference for a task.
+ * - Returns the proposal's own `ref` if provided.
+ * - Otherwise returns a 4‑character hash of the proposal's `id` or `title`.
+ */
+declare function generateTaskRef(proposal: TaskProposalBlock): string;
+/**
+ * Generates a short step reference.
+ * - Returns the step's own `ref` if provided.
+ * - Otherwise returns `${taskRef}_${index+1}` (e.g., "a3f9_2").
+ *
+ * The underscore separator avoids confusion with colons, slashes, or
+ * numeric suffixes that could be misinterpreted by LLMs.
+ */
+declare function generateTaskStepRef(index: number, proposal: TaskProposalBlock): string;
+
 /**
  * Persistence contract for binary blob content and blob registry records.
  *
@@ -1644,8 +1671,8 @@ declare class TurnBuilder {
     addTaskProposal(title: string, steps: {
         text: string;
         status?: 'todo' | 'done';
-        id?: UUID;
-    }[], action?: 'create' | 'update' | 'complete', taskId?: UUID): TurnBuilder;
+        ref?: string;
+    }[], action?: 'create' | 'update' | 'complete', id?: string): TurnBuilder;
     addBlock(block: ContentBlock): TurnBuilder;
     deleteBlock(blockId: UUID): TurnBuilder;
     editTextBlock(blockId: UUID, newText: string): TurnBuilder;
@@ -1760,9 +1787,6 @@ declare class Session {
      * @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.
@@ -2030,7 +2054,7 @@ declare class GoogleGenAIAdapter implements LLMAdapter<{
      */
     parse({ response }: {
         response: GenerateContentResponse;
-    }): Turn;
+    }): Result<Turn, WorkspaceError>;
 }
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTask, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CallTool, type CollectionName, type Command, type ContentBlock, ContentStore, type Context, type ContextContent, type ContextSummary, type CreateSession, type CreateWorkspace, DefaultTurnProcessor, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTask, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type EffectiveSession, type ForkSession, GoogleGenAIAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InvalidCommandError, type LLMAdapter, MemoryBlobStorage, type NotFoundError, type OpenResult, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, type SaveTurn, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type Summarizer, type SummaryBlock, type SwitchRole, type Task, type TaskProposalBlock, type 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 };
+export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTask, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CallTool, type CollectionName, type Command, type ContentBlock, ContentStore, type Context, type ContextContent, type ContextSummary, type CreateSession, type CreateWorkspace, DefaultTurnProcessor, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTask, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type EffectiveSession, type ForkSession, GoogleGenAIAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InvalidCommandError, type LLMAdapter, MemoryBlobStorage, type NotFoundError, type OpenResult, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, type SaveTurn, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type Summarizer, type SummaryBlock, type SwitchRole, type Task, type TaskProposalBlock, type TaskRef, type TaskStatus, type TaskStep, type TaskSummary, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolCall, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type TopicIndex, type Turn, type TurnActor, TurnBuilder, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTask, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, WorkspaceManager, bufferToBase64, computeSHA256, createEmptyRole, createProjectWorkspace, createSimpleWorkspace, createWorkspaceDatabase, del, error, extractBlobRecord, extractBlobRef, generateTaskRef, generateTaskStepRef, merge, omitNullUndefined, shortHash, success };