@asaidimu/utils-workspace 5.0.0 → 6.1.0

package/index.d.mts

@@ -42,7 +42,7 @@ declare class TransactionContext {
      * Stages a single write operation against a store.
      * Does NOT touch the store — no I/O happens until commit().
      */
-    addOp<T extends Record<string, any>>(store: Store<T>, type: "put" | "delete" | "add", data: any): Promise<void>;
+    addOp<T extends Record<string, any>>(store: Store$1<T>, type: "put" | "delete" | "add", data: any): Promise<void>;
     /**
      * Commits all staged operations atomically.
      *
@@ -122,7 +122,7 @@ type BufferedOperation<T> = {
  *
  * @template T - The type of objects stored. Must include the key path property.
  */
-interface Store<T extends Record<string, any> = Record<string, any>> {
+interface Store$1<T extends Record<string, any> = Record<string, any>> {
     /**
      * Returns the name of this store (the IDB object store / collection name).
      * Used by TransactionContext to group operations and open a correctly-scoped
@@ -944,6 +944,9 @@ interface SessionMetadata {
         created?: Timestamp;
         /** UTC timestamp of the last activity within the session. */
         updated?: Timestamp;
+        /** The current model being use by the session */
+        model?: string;
+        [key: string]: any;
     };
     /** The current chronological leaf-node of the conversation DAG. */
     head?: {
@@ -1018,8 +1021,9 @@ interface TopicIndex {
         entries?: number;
     };
 }
-/** The complete in-memory read-model of the Workspace state. */
-interface Index {
+type IndexExtensions = Record<string, Record<string, any>>;
+interface Index<T extends IndexExtensions = IndexExtensions> {
+    /** The complete in-memory read-model of the Workspace state. */
     /** Lookup dictionary of Roles by their string name. */
     roles: Record<string, RoleSummary>;
     /** Lookup dictionary of Preferences by their UUID. */
@@ -1034,9 +1038,10 @@ interface Index {
     blobs: Record<SHA256, BlobRecord>;
     /** Lookup dictionary of registered Tool capabilities by their string name. */
     tools: Record<string, ToolSummary>;
+    extensions: T;
 }
 /** The root container for a user's workspace. */
-interface Workspace<ProjectMetadata extends Record<string, any> = Record<string, any>> {
+interface Workspace<ProjectMetadata extends Record<string, any> = Record<string, any>, Extentions extends Record<string, Record<string, any>> = IndexExtensions> {
     /** Unique identifier for the entire workspace environment. */
     id: UUID;
     /** Global user and systemic settings. */
@@ -1044,7 +1049,7 @@ interface Workspace<ProjectMetadata extends Record<string, any> = Record<string,
     /** High-level project metadata. */
     project: Project<ProjectMetadata>;
     /** The in-memory read-projection of all underlying stores. */
-    index: Index;
+    index: Index<Extentions>;
 }
 /**
  * Format used for exporting/importing a complete workspace state,
@@ -1092,6 +1097,15 @@ interface CreateWorkspace extends BaseCommand {
         project: Project;
     };
 }
+interface SyncWorkspace extends BaseCommand {
+    type: "workspace:sync";
+    /** If provided, updates these root properties during sync. */
+    payload: {
+        id?: UUID;
+        settings?: Settings;
+        project?: Project;
+    } | undefined;
+}
 interface AddRole extends BaseCommand {
     type: "role:add";
     /** The complete role object to inject into the workspace. */
@@ -1373,7 +1387,7 @@ interface ToolCallCommand extends BaseCommand {
     payload: ToolCall;
 }
 /** Union of all possible commands that can be dispatched to the Workspace Manager. */
-type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | UpdateSession | ForkSession | DeleteSession | SwitchSessionRole | AddSessionTopics | OverrideSessionPreferences | AddContext | UpdateContext | DeleteContext | UpdateTurn | AddTurn | EditTurn | BranchTurn | DeleteTurn | RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId | AddTopic | UpdateTopic | DeleteTopic | MergeTopics | ToolCallCommand;
+type Command = CreateWorkspace | SyncWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | UpdateSession | ForkSession | DeleteSession | SwitchSessionRole | AddSessionTopics | OverrideSessionPreferences | AddContext | UpdateContext | DeleteContext | UpdateTurn | AddTurn | EditTurn | BranchTurn | DeleteTurn | RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId | AddTopic | UpdateTopic | DeleteTopic | MergeTopics | ToolCallCommand;
 /**
  * Standard reducer pattern for updating workspace state.
  * @template T - Custom contextual additions for the reducer parameters.
@@ -1419,6 +1433,8 @@ interface ResolvedSession {
 interface WorkspaceEvents {
     /** Emitted when the index or core settings change. */
     "workspace:changed": DeepPartial<Workspace>;
+    /** Emitted when a full sync has completed. */
+    "workspace:synced": void;
     /** Emitted when a blob is registered, updated, or removed. */
     "blobs:changed": {
         /** Hash of the affected blob. */
@@ -1433,6 +1449,8 @@ interface SessionSnapshot {
     id: UUID;
     /** Top-level session definition fields. */
     meta: SessionMetadata;
+    /** Model identifier (e.g., "claude-sonnet-4-6", "gemini-2.0-flash"). */
+    model?: string;
     /** The active role — persona, instructions, role-level constraints. */
     role: Role;
     /** Unfiltered, unranked preferences attached strictly to the role or session. */
@@ -1467,6 +1485,8 @@ interface SessionSnapshot {
  *   - Uploading inline blobs to the provider where required.
  */
 interface Prompt {
+    /** Model identifier (e.g., "claude-sonnet-4-6", "gemini-2.0-flash"). */
+    model?: string;
     /** Correlates this prompt to its session for logging and evaluation. */
     session: UUID;
     /** System-level instructions, context, and preferences. */
@@ -1540,7 +1560,7 @@ interface AdapterStatus {
     };
     /** Pricing tiers for this model. */
     pricing: Array<{
-        unit: 'token' | 'call';
+        unit: 'token' | 'call' | "image";
         /** Exponent: price is per 10^scale units. */
         scale: number;
         /** Price per unit in USD. */
@@ -1561,7 +1581,7 @@ interface AdapterStatus {
         timeout?: number;
         /** The hard limits enforced by the provider. */
         capacity: Array<{
-            unit: 'token' | 'call';
+            unit: 'token' | 'call' | string;
             /** Maximum units allowed per period. */
             max: number;
             /** Period length in seconds. */
@@ -1580,20 +1600,33 @@ interface ExecuteResult {
     /** Side-effect commands to dispatch against the workspace. */
     effects: BaseCommand[];
 }
+/**
+ * A single labelled section of the system prompt.
+ * Mirrors PreparedPrompt.system exactly — the assembler's output is stored
+ * there directly, giving callers full inspection without re-parsing the string.
+ */
+interface PromptSection {
+    /**
+     * Origin label for this section.
+     * Core sections use fixed labels: 'operating-system' | 'persona' |
+     * 'preferences' | 'context' | 'instructions'.
+     * Extensions carry whatever label the injector provides.
+     */
+    label: string;
+    /** Text content exactly as it will be sent to the model. */
+    content: string;
+    /** Optional structured metadata for richer UI display or tooling. */
+    metadata?: Record<string, any>;
+}
 /**
  * The complete, final prompt exactly as the model will receive it.
  * Generic, provider-agnostic, fully inspectable, and executable.
  */
 interface PreparedPrompt {
+    /** Model identifier (e.g., "claude-sonnet-4-6", "gemini-2.0-flash"). */
+    model: string;
     /** The complete system instruction broken into labelled sections for inspection. */
-    system: Array<{
-        /** Origin label for this section (e.g., "persona", "context:project-brief"). */
-        label: string;
-        /** Text content exactly as it will be sent to the model. */
-        content: string;
-        /** Optional structured metadata for richer UI display. */
-        metadata?: Record<string, any>;
-    }>;
+    instructions: Array<PromptSection>;
     /** Final transcript turns that will be sent after adapter-level truncation. */
     transcript: Turn[];
     /** Final context entries included after adapter-level truncation. */
@@ -1627,6 +1660,238 @@ interface PreparedPrompt {
     executeStream?(): AsyncIterable<Partial<Turn> | ExecuteResult>;
 }
 
+/**
+ * Optional filter passed to schema(), description(), and rules() to control
+ * which block definitions are included in the output.
+ *
+ * Resolution order:
+ *   1. `emittable` gate is always applied first — non-emittable blocks never
+ *      appear in schema/description/rules regardless of other filters.
+ *   2. If `only` is provided, only those types are included. `exclude` is ignored.
+ *   3. If `exclude` is provided (and `only` is not), those types are removed.
+ */
+interface BlockFilter {
+    /**
+     * Whitelist of block type strings to include.
+     * When present, `exclude` is ignored entirely.
+     */
+    only?: string[];
+    /**
+     * Blacklist of block type strings to remove.
+     * Ignored when `only` is present.
+     */
+    exclude?: string[];
+}
+
+declare class ContentBlockRegistry {
+    private readonly store;
+    constructor();
+    /** Register a new block type. Throws if type already exists. */
+    register(definition: ContentBlockDefinition): void;
+    /** Remove a block type and its mappings. */
+    unregister(type: string): void;
+    /** Replace an existing block definition entirely, or upsert. */
+    update(type: string, partial: Partial<ContentBlockDefinition>): void;
+    /** Get a single definition by type string. */
+    get(type: string): ContentBlockDefinition | undefined;
+    /** Return all registered definitions. */
+    list(): ContentBlockDefinition[];
+    isType<T extends BaseContentBlock<any> = BaseContentBlock<any>>(block: BaseContentBlock<any>, type: string): block is T;
+    guard<T extends BaseContentBlock<any> = BaseContentBlock<any>>(type: string): (block: BaseContentBlock<any>) => block is T;
+    /**
+     * Returns a plain JSON Schema object scoped to emittable block definitions.
+     * The adapter converts this to a provider-specific format (e.g. Gemini Type enum).
+     */
+    schema(filter?: BlockFilter): Record<string, unknown>;
+    /**
+     * Returns the system-prompt section describing all emittable block types.
+     * Per-block rules are rendered as bullet points beneath each block's description.
+     */
+    description(filter?: BlockFilter): string;
+    /**
+     * Returns all rules across the filtered set of emittable block definitions,
+     * keyed by block type. Blocks with no rules are included with an empty array.
+     *
+     * The prompt assembler uses this to build a consolidated constraints section
+     * or to reason about per-block policies before dispatching to the model.
+     */
+    rules(filter?: BlockFilter): Record<string, string[]>;
+    /**
+     * Replace the rules for a specific block type.
+     * Convenience over update(type, { rules }) — more explicit at call sites.
+     * Throws if the type is not registered.
+     */
+    setRules(type: string, rules: string[]): void;
+    /**
+     * Converts a raw JSON object from a model response into a workspace block.
+     *
+     * Resolution order:
+     *   1. If a provider mapping exists for providerId, delegate to mapping.from(raw).
+     *   2. Otherwise, naive field-copy with a fresh UUID.
+     *
+     * Returns null if the type is unregistered or the mapping explicitly rejects the input.
+     */
+    parse(raw: {
+        type: string;
+        [key: string]: any;
+    }, providerId?: string): BaseContentBlock<any> | null;
+    /**
+     * Constructs a new block instance of the given type with a fresh UUID.
+     * Throws if the type is not registered.
+     */
+    create<T extends BaseContentBlock<any> = BaseContentBlock<any>>(type: string, defaults?: Partial<T>): T;
+    /**
+     * Deep clones an existing block, assigning a new UUID and applying any overrides.
+     */
+    clone<T extends BaseContentBlock<any> = BaseContentBlock<any>>(block: T, overrides?: Partial<T>): T;
+}
+
+/**
+ * An additional section injected by the adapter or application layer.
+ * Slots relative to a named core section anchor.
+ *
+ * Core section labels (fixed order):
+ *   'operating-system' → 'persona' → 'preferences' → 'context' → 'instructions'
+ *
+ * Anchor format:
+ *   'before:<label>' — inserted immediately before the named core section
+ *   'after:<label>'  — inserted immediately after the named core section
+ *   'prepend'        — inserted before all core sections
+ *   'append'         — inserted after all core sections (default when omitted)
+ */
+interface AssemblerExtension extends PromptSection {
+    /**
+     * Where to slot this section relative to the core sections.
+     * Defaults to 'append' when omitted.
+     *
+     * @example 'after:instructions'   // place registry description after instructions
+     * @example 'before:context'       // place tool list before context
+     * @example 'prepend'              // place before everything
+     * @example 'append'               // place after everything (default)
+     */
+    position?: `before:${string}` | `after:${string}` | "prepend" | "append";
+}
+/**
+ * Provider-agnostic system prompt assembler.
+ *
+ * Builds an ordered array of labelled sections from a Prompt plus any
+ * adapter-injected extensions. The adapter calls join() to produce the
+ * final string it wraps in its provider envelope.
+ *
+ * Responsibilities:
+ *   - Render core sections from Prompt fields in canonical order.
+ *   - Slot extensions at their declared anchor positions.
+ *   - Produce a consistent, inspectable section array.
+ *   - Join sections into a single string on demand.
+ *
+ * Not responsible for:
+ *   - Provider-specific wrapping (Content, system message, etc.).
+ *   - Block architecture text — the adapter injects that as an extension.
+ *   - Truncation — that is the adapter's concern.
+ */
+interface SystemPromptAssembler {
+    /**
+     * Builds the ordered array of prompt sections.
+     *
+     * Core sections are always rendered in this order:
+     *   1. operating-system — static workspace operating constraints
+     *   2. persona          — role.persona string
+     *   3. preferences      — active user preferences
+     *   4. context          — injected context entries
+     *   5. instructions     — global or session-level instructions (if present)
+     *
+     * Extensions are slotted relative to their declared `position` anchor.
+     * Multiple extensions targeting the same anchor are inserted in the order
+     * they appear in the extensions array.
+     *
+     * Core sections with no content (e.g. empty preferences, absent instructions)
+     * are omitted from the output entirely.
+     *
+     * @param prompt     - The fully built Prompt from PromptBuilder.
+     * @param extensions - Additional sections injected by the adapter or app layer.
+     */
+    build(prompt: Prompt, extensions?: AssemblerExtension[]): PromptSection[];
+    /**
+     * Joins an array of PromptSections into a single string suitable for
+     * passing to the model. Uses a consistent separator that works across providers.
+     *
+     * @param sections - The output of build().
+     */
+    join(sections: PromptSection[]): string;
+}
+/**
+ * A registered content block — self-contained and provider-agnostic.
+ */
+interface ContentBlockDefinition {
+    /** Discriminator used in the "type" field of the block. */
+    type: string;
+    /** JSON Schema fragment for this block's shape (used in responseSchema). */
+    schema: Record<string, unknown>;
+    /** Human/LLM-readable description of the block, injected into the system prompt. */
+    description: string;
+    /**
+     * Whether the model can produce this block type via structured JSON output.
+     *
+     * - `true`  → included in schema(), description(), and rules()
+     * - `false` → workspace-internal only; invisible to the model
+     */
+    emittable: boolean;
+    /**
+     * Ordered list of behavioural rules for this block type.
+     * Rendered as bullet points beneath the block's description in the system prompt,
+     * and also available separately via registry.rules().
+     *
+     * Examples:
+     *   - 'Never emit more than one summary block per turn.'
+     *   - 'Only emit when explicitly instructed by the system.'
+     */
+    rules: string[];
+    /**
+     * 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;
+    }>;
+}
+/**
+ * Application-layer services injected into every LLMAdapter.
+ * All services operate on workspace domain types only — no provider SDKs.
+ */
+interface WorkspaceServices {
+    /**
+     * Assembles the system prompt from a Prompt and adapter-injected extensions.
+     * The adapter calls assembler.build() to get the inspectable section array,
+     * then assembler.join() to get the string it wraps in its provider envelope.
+     */
+    assembler: SystemPromptAssembler;
+    /**
+     * Scans an assistant turn for actionable blocks and emits workspace commands.
+     */
+    processor: TurnProcessor;
+    /**
+     * Resolves BlobRefs to inline data or remote file mappings.
+     */
+    blobResolver: BlobResolver;
+    /**
+     * Self-describing catalogue of all known content block types.
+     */
+    blockRegistry: ContentBlockRegistry;
+    /**
+     * Model registry
+     */
+    models: ModelRegistry;
+}
+
 /**
  * A simple LRU (Least Recently Used) cache implementation.
  * Used for caching frequently accessed entities in memory.
@@ -1728,7 +1993,64 @@ declare class BlobStore {
     resolveMany(refs: BlobRef[], adapter?: string): Promise<Result<Map<SHA256, ResolvedBlob>, WorkspaceError>>;
 }
 
-declare class ContextStore {
+interface WorkspaceDatabase {
+    /**
+     * Open the database. Registers core schemas followed by any extension
+     * schemas supplied by the caller (domain plugins).
+     *
+     * Idempotent — safe to call multiple times; subsequent calls are no-ops
+     * if the database is already open.
+     */
+    open(extensionSchemas?: SchemaDefinition[]): Promise<void>;
+    /**
+     * Access a collection by schema name.
+     * Throws if the schema has not been registered.
+     */
+    collection<T>(schemaName: string): Promise<Collection<T>>;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+    /** get the underlying database connection. */
+    database(): Database;
+}
+/**
+ * Standard interface for all workspace entity stores.
+ * @template T - The full entity type.
+ * @template S - The summary type used for indexing.
+ * @template K - The primary key type.
+ */
+interface Store<T, S = T, K = string> {
+    get(key: K): Promise<T | null>;
+    add(entity: T): Promise<void>;
+    update(key: K, updates: Partial<T>): Promise<T | null>;
+    delete(key: K): Promise<boolean>;
+    list(): Promise<T[]>;
+    /**
+     * Distills a full entity into a lightweight summary for the index.
+     */
+    summarize(entity: T): S;
+}
+declare function createWorkspaceDatabase(db: Database): WorkspaceDatabase;
+/**
+ * Collection name constants
+ * Defines the names of the collections used in the Workspace database.
+ * Use these instead of raw strings throughout the codebase so a typo is a
+ * compile-time error rather than a silent runtime miss.
+ */
+declare const COLLECTIONS: {
+    readonly WORKSPACE: "workspace";
+    readonly ROLE: "role";
+    readonly PREFERENCE: "preference";
+    readonly CONTEXT: "context";
+    readonly SESSION: "session";
+    readonly TURN: "turn";
+    readonly BLOB: "blob";
+    readonly TOPIC: "topic";
+};
+type Collections = typeof COLLECTIONS[keyof typeof COLLECTIONS];
+
+declare class ContextStore implements Store<Context, ContextSummary, string> {
     private readonly collection;
     private readonly cache;
     constructor(collection: Collection<Context>, cache: LRUCache<string, Context>);
@@ -1741,9 +2063,10 @@ declare class ContextStore {
      * Retrieves all context items referenced by the given topics using the in-memory index.
      */
     getByTopics(index: Index, topics: string[]): Promise<Context[]>;
+    summarize(context: Context): ContextSummary;
 }
 
-declare class PreferenceStore {
+declare class PreferenceStore implements Store<Preference, PreferenceSummary, UUID> {
     private readonly collection;
     private readonly cache;
     constructor(collection: Collection<Preference>, cache: LRUCache<UUID, Preference>);
@@ -1753,13 +2076,14 @@ declare class PreferenceStore {
     delete(id: UUID): Promise<boolean>;
     load(ids: UUID[]): Promise<Preference[]>;
     list(): Promise<Preference[]>;
+    summarize(preference: Preference): PreferenceSummary;
 }
 
 /**
  * Atomic store for Role entities.
  * Receives a pre-resolved Collection and manages its own LRU cache.
  */
-declare class RoleStore {
+declare class RoleStore implements Store<Role, RoleSummary> {
     private readonly collection;
     private readonly cache;
     constructor(collection: Collection<Role>, cache: LRUCache<string, Role>);
@@ -1783,9 +2107,13 @@ declare class RoleStore {
      * Lists all roles.
      */
     list(): Promise<Role[]>;
+    /**
+     * Distills a full role into a lightweight summary for the index.
+     */
+    summarize(role: Role): RoleSummary;
 }
 
-declare class SessionStore {
+declare class SessionStore implements Store<SessionMetadata, SessionMetadata, UUID> {
     private readonly collection;
     private readonly cache;
     constructor(collection: Collection<SessionMetadata>, cache: LRUCache<UUID, SessionMetadata>);
@@ -1793,9 +2121,14 @@ declare class SessionStore {
     add(session: SessionMetadata): Promise<void>;
     update(id: UUID, updates: Partial<SessionMetadata>): Promise<SessionMetadata | null>;
     delete(id: UUID): Promise<boolean>;
+    /**
+     * Lists all sessions.
+     */
+    list(): Promise<SessionMetadata[]>;
+    summarize(session: SessionMetadata): SessionMetadata;
 }
 
-declare class TopicStore {
+declare class TopicStore implements Store<Topic, TopicIndex, string> {
     private readonly collection;
     private readonly cache;
     constructor(collection: Collection<Topic>, cache: LRUCache<string, Topic>);
@@ -1804,10 +2137,12 @@ declare class TopicStore {
     update(name: string, updates: Partial<Topic>): Promise<Topic | null>;
     delete(name: string): Promise<boolean>;
     getMany(names: string[]): Promise<Topic[]>;
+    list(): Promise<Topic[]>;
     /**
      * Checks if a topic is referenced by any entity in the workspace index.
      */
     referencedBy(name: string, index: Index): boolean;
+    summarize(topic: Topic): TopicIndex;
 }
 
 declare class TurnStore {
@@ -1827,50 +2162,52 @@ declare class TurnStore {
     delete(key: TurnKey): Promise<boolean>;
 }
 
-interface WorkspaceDatabase {
-    /**
-     * Open the database. Registers core schemas followed by any extension
-     * schemas supplied by the caller (domain plugins).
-     *
-     * Idempotent — safe to call multiple times; subsequent calls are no-ops
-     * if the database is already open.
-     */
-    open(extensionSchemas?: SchemaDefinition[]): Promise<void>;
-    /**
-     * Access a collection by schema name.
-     * Throws if the schema has not been registered.
-     */
-    collection<T>(schemaName: string): Promise<Collection<T>>;
-    /**
-     * Close the database connection.
-     */
-    close(): void;
-    /** get the underlying database connection. */
-    database(): Database;
+interface WorkspaceMetadata {
+    id: UUID;
+    settings: Settings;
+    project: Project;
 }
-declare function createWorkspaceDatabase(db: Database): WorkspaceDatabase;
+declare class WorkspaceStore implements Store<WorkspaceMetadata, WorkspaceMetadata> {
+    private readonly collection;
+    private readonly cache;
+    constructor(collection: Collection<WorkspaceMetadata>, cache: LRUCache<UUID, WorkspaceMetadata>);
+    get(id: UUID): Promise<WorkspaceMetadata | null>;
+    add(meta: WorkspaceMetadata): Promise<void>;
+    update(id: UUID, updates: Partial<WorkspaceMetadata>): Promise<WorkspaceMetadata | null>;
+    delete(id: UUID): Promise<boolean>;
+    list(): Promise<WorkspaceMetadata[]>;
+    summarize(meta: WorkspaceMetadata): WorkspaceMetadata;
+}
+
 /**
- * Collection name constants
- * Defines the names of the collections used in the Workspace database.
- * Use these instead of raw strings throughout the codebase so a typo is a
- * compile-time error rather than a silent runtime miss.
+ * A function that rebuilds a portion of the workspace index from persistent storage.
  */
-declare const COLLECTIONS: {
-    readonly ROLE: "role";
-    readonly PREFERENCE: "preference";
-    readonly CONTEXT: "context";
-    readonly SESSION: "session";
-    readonly TURN: "turn";
-    readonly BLOB: "blob";
-    readonly TOPIC: "topic";
-};
-type Collections = typeof COLLECTIONS[keyof typeof COLLECTIONS];
-
+type Indexer = (ctx: WorkspaceContext) => Promise<DeepPartial<Workspace>>;
+/**
+ * A bundle of domain-specific logic that can be plugged into the workspace.
+ * Allows app builders to group related schemas, reducers, stores, and blocks.
+ */
+interface WorkspaceExtension {
+    /** Schema definitions for new database collections. */
+    schemas?: SchemaDefinition[];
+    /** Reducers for handling custom commands. */
+    reducers?: Record<string, WorkspaceReducer<any>>;
+    /** Middleware for intercepting or observing workspace changes. */
+    middleware?: WorkspaceMiddleware[];
+    /** Indexers for rebuilding custom portions of the workspace index. */
+    indexers?: Indexer[];
+    /** Factory for custom entity stores. */
+    stores?: (ctx: Omit<WorkspaceContext, "workspace">) => Record<string, Store<any>> | Promise<Record<string, Store<any>>>;
+    /** Content block definitions for the LLM adapter. */
+    blocks?: ContentBlockDefinition[];
+}
 /**
  * The full set of stores passed to every reducer and middleware call.
  * Applications extend this with their own stores (e.g., `interface AppContext extends WorkspaceContext`).
  */
-interface WorkspaceContext {
+type WorkspaceContext<ProjectMetadata extends Record<string, any> = Record<string, any>, IndexExtentions extends Record<string, Record<string, any>> = Record<string, Record<string, any>>, StoreExtensions = any> = {
+    /** Store for managing workspace metadata (settings, project). */
+    workspaceStore: WorkspaceStore;
     /** Store for managing system personas and roles. */
     roles: RoleStore;
     /** Store for managing global and session-level user preferences. */
@@ -1888,10 +2225,12 @@ interface WorkspaceContext {
     /** Optional registry for managing available tools. */
     tools?: ToolRegistry;
     /** The current state of the workspace. */
-    workspace: Workspace;
+    workspace: Workspace<ProjectMetadata, IndexExtentions>;
     /** The underlying database used by the workspace */
     db: WorkspaceDatabase;
-}
+    /** Registry of functions to rebuild the workspace index. */
+    indexers: Indexer[];
+} & StoreExtensions;
 /**
  * Ranks and filters context entries by relevance to the current conversation.
  * The default implementation uses token overlap and recency weighting, but
@@ -1954,9 +2293,10 @@ interface LLMAdapter<TRequestParams extends Record<string, any> = {}> {
     /**
      * Returns the current state of the adapter. Callable at any time without a prompt.
      *
+     * @param model - The model whose params we want to query.
      * @returns The adapter's status, including context windows and rate limits.
      */
-    status(): Promise<AdapterStatus>;
+    status(model?: string): Promise<AdapterStatus>;
     /**
      * Processes a Prompt into a PreparedPrompt — the complete, final representation of what the model will receive.
      *
@@ -1967,6 +2307,42 @@ interface LLMAdapter<TRequestParams extends Record<string, any> = {}> {
         prompt: Prompt;
     } & TRequestParams): Promise<PreparedPrompt>;
 }
+interface LLMAdapterStatic<TRequestParams extends Record<string, any> = {}> {
+    /** Lists all model profiles that can be used with this adapter. */
+    models(): ModelProfile[];
+    new (...args: any[]): LLMAdapter<TRequestParams>;
+}
+interface ModelProfile {
+    /** Provider identifier, e.g. "google". */
+    provider: string;
+    /** Canonical model string as accepted by the API, e.g. "gemini-2.0-flash". */
+    name: string;
+    /** Context window and output limits. */
+    window: AdapterStatus["window"];
+    /** Capability flags. */
+    feature: AdapterStatus["feature"];
+    /** Pricing tiers. */
+    pricing: AdapterStatus["pricing"];
+    /**
+     * Hard rate limit capacity as enforced by the provider.
+     * Does not include runtime state (load, timeout).
+     */
+    capacity: AdapterStatus["rate"]["capacity"];
+}
+interface ModelRegistry {
+    /**
+     * Returns the profile for a model, or undefined if the model is unknown.
+     * Callers should treat an undefined return as a configuration error.
+     */
+    get(model: string): ModelProfile | undefined;
+    /** Lists all registered profiles, optionally filtered by provider. */
+    list(provider?: string): ModelProfile[];
+    /**
+     * Registers or replaces a model profile. Useful for preview models,
+     * fine-tunes, or updated specs that postdate the bundled defaults.
+     */
+    register(profile: ModelProfile): void;
+}
 /**
  * Analyzes assistant turn output for workspace side effects.
  * Implementations scan blocks and emit Commands that the Session dispatches.
@@ -1976,12 +2352,12 @@ interface TurnProcessor {
      * Scans an assistant turn for actionable blocks.
      *
      * @param turn - The turn containing blocks to process.
-     * @param sessionId - The UUID of the session the turn belongs to.
+     * @param session - The UUID of the session the turn belongs to.
      * @returns Commands to dispatch against the workspace.
      */
     process(turn: {
         blocks: BaseContentBlock<string>[];
-    }, sessionId?: UUID): BaseCommand[];
+    }, session: UUID): BaseCommand[];
 }
 /**
  * Compresses old transcript turns to reclaim token budget.
@@ -2080,18 +2456,7 @@ declare class WorkspaceManager {
      * @returns unsubscribe
      */
     subscribe<K extends keyof WorkspaceEvents>(event: K, listener: (payload: WorkspaceEvents[K]) => void): () => void;
-    ctx(): {
-        context: ContextStore;
-        roles: RoleStore;
-        preferences: PreferenceStore;
-        sessions: SessionStore;
-        topics: TopicStore;
-        blobs: BlobStore;
-        turns: TurnStore;
-        tools?: ToolRegistry | undefined;
-        db: WorkspaceDatabase;
-        workspace: Workspace<Record<string, any>>;
-    };
+    ctx(): WorkspaceContext;
 }
 
 declare class WorkspaceApi {
@@ -2123,8 +2488,18 @@ declare class Session {
     private _role;
     private _preferences;
     private tree;
+    private unsubscribe?;
     private constructor();
     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.
+     */
+    sync(): Promise<void>;
+    /**
+     * Closes the session and cleans up subscriptions.
+     */
+    close(): void;
     private _setRole;
     private _setPreference;
     id(): UUID;
@@ -2251,6 +2626,12 @@ declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
  * implementation for Browsers and Edge environments to avoid stack overflows.
  */
 declare function bufferToBase64(buffer: Uint8Array): 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;
+declare function getExtension<K extends string, V>(index: Index, key: K): Record<string, V>;
 
 interface CreateWorkspaceParams {
     db: Database;
@@ -2261,9 +2642,18 @@ interface CreateWorkspaceParams {
     processor: TurnProcessor;
     guard?: PermissionGuard;
     toolRegistry?: ToolRegistry;
+    models?: ModelProfile[];
+    extensions?: WorkspaceExtension[];
+    /** @deprecated use extensions instead */
     extensionSchemas?: SchemaDefinition[];
+    /** @deprecated use extensions instead */
     extensionReducers?: Record<string, WorkspaceReducer<any>>;
+    /** @deprecated use extensions instead */
     extensionMiddleware?: WorkspaceMiddleware[];
+    /** @deprecated use extensions instead */
+    extensionIndexers?: Indexer[];
+    /** @deprecated use extensions instead */
+    extensionStores?: (ctx: Omit<WorkspaceContext, "workspace">) => Record<string, any>;
 }
 /**
  * Boot factory for the Workspace library.
@@ -2272,7 +2662,8 @@ interface CreateWorkspaceParams {
 declare function createWorkspace(params: CreateWorkspaceParams): Promise<{
     manager: WorkspaceManager;
     sessions: SessionManager;
-    ctx: Omit<WorkspaceContext, "workspace">;
+    ctx: Omit<any, "workspace">;
+    services: WorkspaceServices;
 }>;
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTopic, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BaseContentBlock, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobResolver, type BranchInfo, type BranchTurn, COLLECTIONS, type Collections, type Command, type ContentBlock, type Context, type ContextContent, type ContextRetriever, type ContextSummary, type CreateSession, type CreateWorkspace, type CreateWorkspaceParams, type DeepPartial, 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, type ImageBlock, type ImageMediaType, type Index, type InvalidCommandError, type LLMAdapter, LRUCache, type MergeTopics, type ModelConstraint, type ModelConstraintMap, type ModelName, type NotFoundError, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceSummary, type Project, type PromptBuilder, type PromptBuilderOptions, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, 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 Summarizer, type SummaryBlock, type SwitchSessionRole, type SystemActor, type TextBlock, 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 UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTopic, type UpdateTurn, type Workspace, type WorkspaceBundle, type WorkspaceContext, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, WorkspaceManager, type WorkspaceMiddleware, type WorkspaceReducer, bufferToBase64, computeSHA256, createWorkspace, createWorkspaceDatabase, del, error, merge, ok, omitNullUndefined, success };
+export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTopic, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BaseContentBlock, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobResolver, type BranchInfo, type BranchTurn, COLLECTIONS, type Collections, type Command, type ContentBlock, type Context, type ContextContent, type ContextRetriever, type ContextSummary, type CreateSession, type CreateWorkspace, type CreateWorkspaceParams, type DeepPartial, 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, type ImageBlock, type ImageMediaType, type Index, type IndexExtensions, type Indexer, type InvalidCommandError, type LLMAdapter, type LLMAdapterStatic, LRUCache, 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 Project, type PromptBuilder, type PromptBuilderOptions, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, 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 TextBlock, 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 UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTopic, type UpdateTurn, type Workspace, type WorkspaceBundle, type WorkspaceContext, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, type WorkspaceExtension, WorkspaceManager, type WorkspaceMiddleware, type WorkspaceReducer, bufferToBase64, computeSHA256, createWorkspace, createWorkspaceDatabase, del, error, getExtension, merge, ok, omitNullUndefined, shortHash, success };