@asaidimu/utils-workspace 6.6.1 → 6.6.3

package/index.d.mts

@@ -818,9 +818,11 @@ interface BaseContentBlock<BlockType extends string> {
     /** Extensible key-value store for block-specific properties. */
     [key: string]: any;
 }
-/** Standard text content within a turn. */
+/**
+ * Represents a standard text-based content block within a conversational turn.
+ * This block is used for general communication, explanations, or any textual output.\n
+ */
 interface TextBlock extends BaseContentBlock<"text"> {
-    /** The raw markdown or plain text content. */
     text: string;
 }
 /** An image asset within a turn, optionally containing the resolved binary data. */
@@ -1057,6 +1059,8 @@ interface BaseContextContent<Kind extends string> {
 interface TextContextContent extends BaseContextContent<"text"> {
     /** The raw text content. */
     value: string;
+    format?: string;
+    extension?: string;
 }
 /**
  * Supported payload for structured JSON context.
@@ -1848,6 +1852,7 @@ interface AssemblerExtension extends PromptSection {
  * Provider-agnostic system prompt assembler.
  */
 interface SystemPromptAssembler {
+    readonly registry: ContentBlockRegistry;
     build<P, C>(provider: string, prompt: Prompt, mapTurn: (args: {
         turn: Turn;
         parts: P[];
@@ -1867,7 +1872,10 @@ type BlockMapper = {
      * Convert a workspace block into a provider-specific part.
      * The return type is `unknown` — the adapter casts it internally.
      */
-    to(block: BaseContentBlock<string>): unknown | Promise<unknown>;
+    to(params: {
+        block: BaseContentBlock<string>;
+        resolve: (ref: BlobRef) => Promise<Result<ResolvedBlob | null, WorkspaceError>>;
+    }): unknown | Promise<unknown>;
     /**
      * Convert a provider-extracted raw JSON object into a workspace block.
      * Return `null` if parsing fails.
@@ -1907,18 +1915,7 @@ interface ContentBlockDefinition {
      * Provider-specific mapping functions, keyed by provider ID (e.g. "google", "openai").
      * Each entry tells the adapter how to serialise/deserialise this block.
      */
-    mappings?: Record<string, {
-        /**
-         * Convert a workspace block into a provider-specific part.
-         * The return type is `unknown` — the adapter casts it internally.
-         */
-        to(block: BaseContentBlock<string>): unknown;
-        /**
-         * Convert a provider-extracted raw JSON object into a workspace block.
-         * Return `null` if parsing fails.
-         */
-        from(raw: any): BaseContentBlock<any> | null;
-    }>;
+    mappings?: Record<string, BlockMapper>;
 }
 /**
  * Application-layer services injected into every LLMAdapter.
@@ -3052,6 +3049,18 @@ declare class SessionManager {
     metadata(sessionId: UUID): SessionMetadata | undefined;
 }
 
+/**
+ * Standard TurnProcessor that handles core workspace blocks like artifacts.
+ * Applications can wrap this or delegate to it.
+ */
+declare class CoreTurnProcessor implements TurnProcessor {
+    process(turn: {
+        blocks: any[];
+    }, session: UUID): BaseCommand[];
+    private handleAddArtifact;
+    private handleUpdateArtifact;
+}
+
 /**
  * A fluent builder for creating Turn objects.
  * This class helps construct a Turn object by adding various content blocks.
@@ -3097,8 +3106,9 @@ declare class DefaultPromptBuilder implements PromptBuilder {
 }
 
 declare class PromptAssembler implements SystemPromptAssembler {
-    private readonly registry;
-    constructor(registry: ContentBlockRegistry);
+    private resolver;
+    readonly registry: ContentBlockRegistry;
+    constructor(_registry: ContentBlockRegistry, resolver: BlobResolver);
     build<P, C>(provider: string, prompt: Prompt, mapTurn: (args: {
         turn: Turn;
         parts: P[];
@@ -3128,7 +3138,7 @@ declare class PromptAssembler implements SystemPromptAssembler {
      */
     join(sections: PromptSection[]): string;
 }
-declare function createDefaultAssembler(registry: ContentBlockRegistry): PromptAssembler;
+declare function createDefaultAssembler(registry: ContentBlockRegistry, resolver: BlobResolver): PromptAssembler;
 
 declare class JaccardContextRetriever implements ContextRetriever {
     private readonly contextRegistry;
@@ -3181,8 +3191,8 @@ declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
  */
 declare function bufferToBase64(buffer: Uint8Array): string;
 /**
- * Short, deterministic hash of a string (4 chars in base36).
- * Suitable for AI-friendly reference tokens.
+ * Short, deterministic hash of a string (length chars in base36).
+ * Returns a uniformly distributed, fixed-length base36 string.
  */
 declare function shortHash(s: string, length?: number): string;
 declare function getExtension<K extends string, V>(index: Index, key: K): Record<string, V>;
@@ -3399,4 +3409,4 @@ declare function createWorkspace(params: CreateWorkspaceParams): Promise<{
     bootstrap: (config: BootstrapConfig) => Promise<BootstrapResult>;
 }>;
 
-export { type AdapterStatus, type AddArtifact, type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTopic, type AddTurn, type Artifact, type ArtifactSummary, type AssemblerExtension, type AuthRequest, type BackendError, type BaseCommand, type BaseContentBlock, type BaseContextContent, type BlobCommand, type BlobContextContent, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobResolver, type BlockMapper, type BootstrapConfig, type BootstrapResult, type BranchInfo, type BranchTurn, COLLECTIONS, type CheckpointBlock, type CheckpointSessionState, type Collections, type Command, type ContentBlock, type ContentBlockDefinition, type Context, type ContextContent, type ContextDefinition, type ContextRetriever, type ContextSummary, type CreateSession, type CreateWorkspace, type CreateWorkspaceParams, type DeepPartial, type DefaultContextContent, DefaultPromptBuilder, type DeleteArtifact, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTopic, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type ForkSession, index as GoogleAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexExtensions, type IndexedDBBlobConfig, IndexedDBBlobStorage, type Indexer, type InvalidCommandError, JaccardContextRetriever, type JsonContextContent, type LLMAdapter, type LLMAdapterStatic, LRUCache, MemoryBlobStorage, type MergeTopics, type ModelConstraint, type ModelConstraintMap, type ModelName, type ModelProfile, type ModelRegistry, type NotFoundError, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceSummary, type PreparedPrompt, type Project, type Prompt, PromptAssembler, type PromptBuilder, type PromptBuilderOptions, type PromptResult, type PromptSection, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type RemoteContextContent, type ResolvedBlob, type ResolvedSession, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionMetadata, type SessionSnapshot, type Settings, type Store, type Summarizer, type SummaryBlock, type SwitchSessionRole, type SyncWorkspace, type SystemActor, type SystemPromptAssembler, type TextBlock, type TextContextContent, type ThinkingBlock, type Timestamp, type ToolCall, type ToolCallCommand, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type Topic, type TopicIndex, type Turn, TurnBuilder, type TurnKey, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateArtifact, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTopic, type UpdateTurn, type Workspace, WorkspaceApi, type WorkspaceBundle, type WorkspaceContext, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, type WorkspaceExtension, WorkspaceManager, type WorkspaceMiddleware, type WorkspaceReducer, WorkspaceRegistry, type WorkspaceServices, bufferToBase64, computeSHA256, createDefaultAssembler, createEmptySession, createEmptyTurn, createEmptyWorkspace, createWorkspace, createWorkspaceDatabase, del, error, getExtension, merge, omitNullUndefined, sessionStateToMarkdown, shortHash, success };
+export { type AdapterStatus, type AddArtifact, type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTopic, type AddTurn, type Artifact, type ArtifactSummary, type AssemblerExtension, type AuthRequest, type BackendError, type BaseCommand, type BaseContentBlock, type BaseContextContent, type BlobCommand, type BlobContextContent, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobResolver, type BlockMapper, type BootstrapConfig, type BootstrapResult, type BranchInfo, type BranchTurn, COLLECTIONS, type CheckpointBlock, type CheckpointSessionState, type Collections, type Command, type ContentBlock, type ContentBlockDefinition, type Context, type ContextContent, type ContextDefinition, type ContextRetriever, type ContextSummary, CoreTurnProcessor, type CreateSession, type CreateWorkspace, type CreateWorkspaceParams, type DeepPartial, type DefaultContextContent, DefaultPromptBuilder, type DeleteArtifact, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTopic, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type ForkSession, index as GoogleAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexExtensions, type IndexedDBBlobConfig, IndexedDBBlobStorage, type Indexer, type InvalidCommandError, JaccardContextRetriever, type JsonContextContent, type LLMAdapter, type LLMAdapterStatic, LRUCache, MemoryBlobStorage, type MergeTopics, type ModelConstraint, type ModelConstraintMap, type ModelName, type ModelProfile, type ModelRegistry, type NotFoundError, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceSummary, type PreparedPrompt, type Project, type Prompt, PromptAssembler, type PromptBuilder, type PromptBuilderOptions, type PromptResult, type PromptSection, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type RemoteContextContent, type ResolvedBlob, type ResolvedSession, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionMetadata, type SessionSnapshot, type Settings, type Store, type Summarizer, type SummaryBlock, type SwitchSessionRole, type SyncWorkspace, type SystemActor, type SystemPromptAssembler, type TextBlock, type TextContextContent, type ThinkingBlock, type Timestamp, type ToolCall, type ToolCallCommand, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type Topic, type TopicIndex, type Turn, TurnBuilder, type TurnKey, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateArtifact, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTopic, type UpdateTurn, type Workspace, WorkspaceApi, type WorkspaceBundle, type WorkspaceContext, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, type WorkspaceExtension, WorkspaceManager, type WorkspaceMiddleware, type WorkspaceReducer, WorkspaceRegistry, type WorkspaceServices, bufferToBase64, computeSHA256, createDefaultAssembler, createEmptySession, createEmptyTurn, createEmptyWorkspace, createWorkspace, createWorkspaceDatabase, del, error, getExtension, merge, omitNullUndefined, sessionStateToMarkdown, shortHash, success };

package/index.d.ts

@@ -818,9 +818,11 @@ interface BaseContentBlock<BlockType extends string> {
     /** Extensible key-value store for block-specific properties. */
     [key: string]: any;
 }
-/** Standard text content within a turn. */
+/**
+ * Represents a standard text-based content block within a conversational turn.
+ * This block is used for general communication, explanations, or any textual output.\n
+ */
 interface TextBlock extends BaseContentBlock<"text"> {
-    /** The raw markdown or plain text content. */
     text: string;
 }
 /** An image asset within a turn, optionally containing the resolved binary data. */
@@ -1057,6 +1059,8 @@ interface BaseContextContent<Kind extends string> {
 interface TextContextContent extends BaseContextContent<"text"> {
     /** The raw text content. */
     value: string;
+    format?: string;
+    extension?: string;
 }
 /**
  * Supported payload for structured JSON context.
@@ -1848,6 +1852,7 @@ interface AssemblerExtension extends PromptSection {
  * Provider-agnostic system prompt assembler.
  */
 interface SystemPromptAssembler {
+    readonly registry: ContentBlockRegistry;
     build<P, C>(provider: string, prompt: Prompt, mapTurn: (args: {
         turn: Turn;
         parts: P[];
@@ -1867,7 +1872,10 @@ type BlockMapper = {
      * Convert a workspace block into a provider-specific part.
      * The return type is `unknown` — the adapter casts it internally.
      */
-    to(block: BaseContentBlock<string>): unknown | Promise<unknown>;
+    to(params: {
+        block: BaseContentBlock<string>;
+        resolve: (ref: BlobRef) => Promise<Result<ResolvedBlob | null, WorkspaceError>>;
+    }): unknown | Promise<unknown>;
     /**
      * Convert a provider-extracted raw JSON object into a workspace block.
      * Return `null` if parsing fails.
@@ -1907,18 +1915,7 @@ interface ContentBlockDefinition {
      * Provider-specific mapping functions, keyed by provider ID (e.g. "google", "openai").
      * Each entry tells the adapter how to serialise/deserialise this block.
      */
-    mappings?: Record<string, {
-        /**
-         * Convert a workspace block into a provider-specific part.
-         * The return type is `unknown` — the adapter casts it internally.
-         */
-        to(block: BaseContentBlock<string>): unknown;
-        /**
-         * Convert a provider-extracted raw JSON object into a workspace block.
-         * Return `null` if parsing fails.
-         */
-        from(raw: any): BaseContentBlock<any> | null;
-    }>;
+    mappings?: Record<string, BlockMapper>;
 }
 /**
  * Application-layer services injected into every LLMAdapter.
@@ -3052,6 +3049,18 @@ declare class SessionManager {
     metadata(sessionId: UUID): SessionMetadata | undefined;
 }
 
+/**
+ * Standard TurnProcessor that handles core workspace blocks like artifacts.
+ * Applications can wrap this or delegate to it.
+ */
+declare class CoreTurnProcessor implements TurnProcessor {
+    process(turn: {
+        blocks: any[];
+    }, session: UUID): BaseCommand[];
+    private handleAddArtifact;
+    private handleUpdateArtifact;
+}
+
 /**
  * A fluent builder for creating Turn objects.
  * This class helps construct a Turn object by adding various content blocks.
@@ -3097,8 +3106,9 @@ declare class DefaultPromptBuilder implements PromptBuilder {
 }
 
 declare class PromptAssembler implements SystemPromptAssembler {
-    private readonly registry;
-    constructor(registry: ContentBlockRegistry);
+    private resolver;
+    readonly registry: ContentBlockRegistry;
+    constructor(_registry: ContentBlockRegistry, resolver: BlobResolver);
     build<P, C>(provider: string, prompt: Prompt, mapTurn: (args: {
         turn: Turn;
         parts: P[];
@@ -3128,7 +3138,7 @@ declare class PromptAssembler implements SystemPromptAssembler {
      */
     join(sections: PromptSection[]): string;
 }
-declare function createDefaultAssembler(registry: ContentBlockRegistry): PromptAssembler;
+declare function createDefaultAssembler(registry: ContentBlockRegistry, resolver: BlobResolver): PromptAssembler;
 
 declare class JaccardContextRetriever implements ContextRetriever {
     private readonly contextRegistry;
@@ -3181,8 +3191,8 @@ declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
  */
 declare function bufferToBase64(buffer: Uint8Array): string;
 /**
- * Short, deterministic hash of a string (4 chars in base36).
- * Suitable for AI-friendly reference tokens.
+ * Short, deterministic hash of a string (length chars in base36).
+ * Returns a uniformly distributed, fixed-length base36 string.
  */
 declare function shortHash(s: string, length?: number): string;
 declare function getExtension<K extends string, V>(index: Index, key: K): Record<string, V>;
@@ -3399,4 +3409,4 @@ declare function createWorkspace(params: CreateWorkspaceParams): Promise<{
     bootstrap: (config: BootstrapConfig) => Promise<BootstrapResult>;
 }>;
 
-export { type AdapterStatus, type AddArtifact, type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTopic, type AddTurn, type Artifact, type ArtifactSummary, type AssemblerExtension, type AuthRequest, type BackendError, type BaseCommand, type BaseContentBlock, type BaseContextContent, type BlobCommand, type BlobContextContent, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobResolver, type BlockMapper, type BootstrapConfig, type BootstrapResult, type BranchInfo, type BranchTurn, COLLECTIONS, type CheckpointBlock, type CheckpointSessionState, type Collections, type Command, type ContentBlock, type ContentBlockDefinition, type Context, type ContextContent, type ContextDefinition, type ContextRetriever, type ContextSummary, type CreateSession, type CreateWorkspace, type CreateWorkspaceParams, type DeepPartial, type DefaultContextContent, DefaultPromptBuilder, type DeleteArtifact, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTopic, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type ForkSession, index as GoogleAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexExtensions, type IndexedDBBlobConfig, IndexedDBBlobStorage, type Indexer, type InvalidCommandError, JaccardContextRetriever, type JsonContextContent, type LLMAdapter, type LLMAdapterStatic, LRUCache, MemoryBlobStorage, type MergeTopics, type ModelConstraint, type ModelConstraintMap, type ModelName, type ModelProfile, type ModelRegistry, type NotFoundError, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceSummary, type PreparedPrompt, type Project, type Prompt, PromptAssembler, type PromptBuilder, type PromptBuilderOptions, type PromptResult, type PromptSection, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type RemoteContextContent, type ResolvedBlob, type ResolvedSession, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionMetadata, type SessionSnapshot, type Settings, type Store, type Summarizer, type SummaryBlock, type SwitchSessionRole, type SyncWorkspace, type SystemActor, type SystemPromptAssembler, type TextBlock, type TextContextContent, type ThinkingBlock, type Timestamp, type ToolCall, type ToolCallCommand, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type Topic, type TopicIndex, type Turn, TurnBuilder, type TurnKey, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateArtifact, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTopic, type UpdateTurn, type Workspace, WorkspaceApi, type WorkspaceBundle, type WorkspaceContext, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, type WorkspaceExtension, WorkspaceManager, type WorkspaceMiddleware, type WorkspaceReducer, WorkspaceRegistry, type WorkspaceServices, bufferToBase64, computeSHA256, createDefaultAssembler, createEmptySession, createEmptyTurn, createEmptyWorkspace, createWorkspace, createWorkspaceDatabase, del, error, getExtension, merge, omitNullUndefined, sessionStateToMarkdown, shortHash, success };
+export { type AdapterStatus, type AddArtifact, type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTopic, type AddTurn, type Artifact, type ArtifactSummary, type AssemblerExtension, type AuthRequest, type BackendError, type BaseCommand, type BaseContentBlock, type BaseContextContent, type BlobCommand, type BlobContextContent, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobResolver, type BlockMapper, type BootstrapConfig, type BootstrapResult, type BranchInfo, type BranchTurn, COLLECTIONS, type CheckpointBlock, type CheckpointSessionState, type Collections, type Command, type ContentBlock, type ContentBlockDefinition, type Context, type ContextContent, type ContextDefinition, type ContextRetriever, type ContextSummary, CoreTurnProcessor, type CreateSession, type CreateWorkspace, type CreateWorkspaceParams, type DeepPartial, type DefaultContextContent, DefaultPromptBuilder, type DeleteArtifact, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTopic, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type ForkSession, index as GoogleAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexExtensions, type IndexedDBBlobConfig, IndexedDBBlobStorage, type Indexer, type InvalidCommandError, JaccardContextRetriever, type JsonContextContent, type LLMAdapter, type LLMAdapterStatic, LRUCache, MemoryBlobStorage, type MergeTopics, type ModelConstraint, type ModelConstraintMap, type ModelName, type ModelProfile, type ModelRegistry, type NotFoundError, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceSummary, type PreparedPrompt, type Project, type Prompt, PromptAssembler, type PromptBuilder, type PromptBuilderOptions, type PromptResult, type PromptSection, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type RemoteContextContent, type ResolvedBlob, type ResolvedSession, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionMetadata, type SessionSnapshot, type Settings, type Store, type Summarizer, type SummaryBlock, type SwitchSessionRole, type SyncWorkspace, type SystemActor, type SystemPromptAssembler, type TextBlock, type TextContextContent, type ThinkingBlock, type Timestamp, type ToolCall, type ToolCallCommand, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type Topic, type TopicIndex, type Turn, TurnBuilder, type TurnKey, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateArtifact, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTopic, type UpdateTurn, type Workspace, WorkspaceApi, type WorkspaceBundle, type WorkspaceContext, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, type WorkspaceExtension, WorkspaceManager, type WorkspaceMiddleware, type WorkspaceReducer, WorkspaceRegistry, type WorkspaceServices, bufferToBase64, computeSHA256, createDefaultAssembler, createEmptySession, createEmptyTurn, createEmptyWorkspace, createWorkspace, createWorkspaceDatabase, del, error, getExtension, merge, omitNullUndefined, sessionStateToMarkdown, shortHash, success };