@asaidimu/utils-workspace 6.0.0 → 6.2.0

package/index.d.ts

@@ -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
@@ -883,44 +883,45 @@ interface Preference {
     /** UTC timestamp of when this preference was established or last updated. */
     timestamp: Timestamp;
 }
-/** Discriminated union of types that can be injected into the AI context. */
-type ContextContent = {
-    /** Denotes raw, unstructured text. */
+/** Supported payload for text-based context. */
+type TextContextContent = {
     kind: "text";
-    /** The text payload to inject. */
     value: string;
-} | {
-    /** Denotes structured JSON data. */
+};
+/** Supported payload for structured JSON context. */
+type JsonContextContent = {
     kind: "json";
-    /** The JSON payload. */
     value: unknown;
-} | {
-    /** Denotes a reference to a registered blob in the workspace store. */
+};
+/** Supported payload for blob-based context. */
+type BlobContextContent = {
     kind: "blob";
-    /** The hash linking to the full blob record. */
     sha256: SHA256;
-    /** The mime-type of the blob. */
     mediaType: BlobMediaType;
-    /** File size in bytes. */
     sizeBytes: number;
-    /** Human-readable filename. */
     filename?: string;
-} | {
-    /** Denotes data living at an external HTTP URI. */
+};
+/** Supported payload for remote URI context. */
+type RemoteContextContent = {
     kind: "remote";
-    /** The fully qualified URI to the external resource. */
     uri: URI;
-    /** Optional hint for the expected mime-type at the remote destination. */
     mediaType?: BlobMediaType;
 };
+/** Union of built-in context types. */
+type DefaultContextContent = TextContextContent | JsonContextContent | BlobContextContent | RemoteContextContent;
+/**
+ * Discriminated union of types that can be injected into the AI context.
+ * Extensions provide their own T which MUST include a unique 'kind' discriminator.
+ */
+type ContextContent<T = any> = DefaultContextContent | T;
 /** A contextual item (file, snippet, or data) attached to a session or prompt. */
-interface Context {
+interface Context<T = any> {
     /** Unique lookup key for this context entry. */
     key: string;
     /** Topics linking this context to relevant sessions or roles. */
     topics: string[];
     /** The actual payload of the context block. */
-    content: ContextContent;
+    content: ContextContent<T>;
     /** UTC timestamp of when the context was added. */
     timestamp: Timestamp;
     /** Extensible key-value store for application-specific contextual metadata. */
@@ -988,6 +989,8 @@ interface PreferenceSummary {
 interface ContextSummary {
     /** The unique key for the context item. */
     key: string;
+    /** The kind of context (e.g. 'text', 'blob', 'task'). Used for routing. */
+    kind: string;
     /** Associated semantic topics. */
     topics: string[];
     /** UTC timestamp of addition. */
@@ -1097,6 +1100,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. */
@@ -1378,7 +1390,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.
@@ -1424,6 +1436,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. */
@@ -1463,6 +1477,265 @@ interface SessionSnapshot {
     };
 }
 
+/**
+ * Registry for managing context kind definitions and their behaviors.
+ */
+declare class ContextRegistry {
+    private readonly store;
+    constructor();
+    private registerDefaults;
+    /**
+     * Registers a new context definition.
+     * @param definition The context definition to register.
+     */
+    register(definition: ContextDefinition): void;
+    /**
+     * Retrieves a context definition by kind.
+     * @param kind The context kind to retrieve.
+     */
+    get(kind: string): ContextDefinition | undefined;
+    /**
+     * Lists all registered context definitions.
+     */
+    list(): ContextDefinition[];
+}
+
+/**
+ * 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;
+    /**
+     * Registry for managing custom context kinds.
+     */
+    contextRegistry: ContextRegistry;
+    /**
+     * Model registry
+     */
+    models: ModelRegistry;
+}
+
 /**
  * Output of PromptBuilder.build(). Input to LLMAdapter.resolve().
  *
@@ -1489,6 +1762,8 @@ interface Prompt {
         /** Ranked context entries (text and json kinds only). Blob context is
          *  represented as referential blocks in the transcript instead. */
         context: Context[];
+        /** Additional sections injected by the adapter or application layer. */
+        extensions?: AssemblerExtension[];
     };
     /** Active conversation chain, oldest to newest. May include synthetic turns.
      *  Image and document blocks carry a BlobRef only; the adapter resolves them. */
@@ -1549,7 +1824,7 @@ interface AdapterStatus {
     };
     /** Pricing tiers for this model. */
     pricing: Array<{
-        unit: 'token' | 'call' | "image";
+        unit: "token" | "call" | "image";
         /** Exponent: price is per 10^scale units. */
         scale: number;
         /** Price per unit in USD. */
@@ -1570,7 +1845,7 @@ interface AdapterStatus {
         timeout?: number;
         /** The hard limits enforced by the provider. */
         capacity: Array<{
-            unit: 'token' | 'call' | string;
+            unit: "token" | "call" | string;
             /** Maximum units allowed per period. */
             max: number;
             /** Period length in seconds. */
@@ -1631,7 +1906,7 @@ interface PreparedPrompt {
         /** Total input tokens — estimated or exact. */
         total: number;
         /** Whether total is an estimate or exact (provider-supplied). */
-        source: 'estimated' | 'exact';
+        source: "estimated" | "exact";
         /** Maximum output tokens configured for this request. */
         output?: number;
         /** Tokens remaining in the context window after this prompt. */
@@ -1750,22 +2025,86 @@ 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>);
-    get(key: string): Promise<Context | null>;
+    private readonly registry?;
+    private readonly delegates;
+    constructor(collection: Collection<Context>, cache: LRUCache<string, Context>, registry?: ContextRegistry | undefined);
+    /**
+     * Registers a specialized store for a specific context kind.
+     */
+    registerDelegate(kind: string, store: Store<Context, ContextSummary, string>): void;
+    get(key: string, kind?: string): Promise<Context | null>;
     add(context: Context): Promise<void>;
     list(): Promise<Context[]>;
-    update(key: string, updates: Partial<Context>): Promise<Context | null>;
-    delete(key: string): Promise<boolean>;
+    update(key: string, updates: Partial<Context>, kind?: string): Promise<Context | null>;
+    delete(key: string, kind?: string): Promise<boolean>;
     /**
      * 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>);
@@ -1775,13 +2114,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>);
@@ -1805,9 +2145,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>);
@@ -1815,9 +2159,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>);
@@ -1826,10 +2175,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 {
@@ -1849,50 +2200,86 @@ declare class TurnStore {
     delete(key: TurnKey): Promise<boolean>;
 }
 
-interface WorkspaceDatabase {
+interface WorkspaceMetadata {
+    id: UUID;
+    settings: Settings;
+    project: Project;
+}
+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;
+}
+
+/**
+ * A function that rebuilds a portion of the workspace index from persistent storage.
+ */
+type Indexer = (ctx: WorkspaceContext) => Promise<DeepPartial<Workspace>>;
+/**
+ * Definition of a specific kind of context and how the system interacts with it.
+ */
+interface ContextDefinition<T = any> {
+    /** Unique discriminator for this context kind (e.g., 'text', 'blob', 'task'). */
+    kind: string;
     /**
-     * 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.
+     * Where this context prefers to live in the prompt.
+     * 'system' -> Rendered into the system instructions.
+     * 'transcript' -> Rendered as a synthetic turn prefixing the transcript.
      */
-    open(extensionSchemas?: SchemaDefinition[]): Promise<void>;
+    target: "system" | "transcript";
     /**
-     * Access a collection by schema name.
-     * Throws if the schema has not been registered.
+     * Transforms the context item into one or more content blocks.
+     * If these blocks contain BlobRefs, the PromptBuilder will automatically
+     * catalogue them for the adapter.
      */
-    collection<T>(schemaName: string): Promise<Collection<T>>;
+    render(context: Context<T>): ContentBlock | ContentBlock[];
     /**
-     * Close the database connection.
+     * Returns a plain text representation for the RAG/retriever system.
      */
-    close(): void;
-    /** get the underlying database connection. */
-    database(): Database;
+    toString(context: Context<T>): string;
+    /**
+     * Produces a condensed summary for the workspace index projection.
+     */
+    summarize(context: Context<T>): ContextSummary;
+    /**
+     * Optional factory for a custom store for this context kind.
+     * If omitted, the default 'context' collection is used.
+     */
+    store?: (ctx: WorkspaceContext) => Store<Context<T>, ContextSummary, string>;
 }
-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.
+ * A bundle of domain-specific logic that can be plugged into the workspace.
+ * Allows app builders to group related schemas, reducers, stores, and blocks.
  */
-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];
-
+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[];
+    /** Custom context kind definitions. */
+    contexts?: ContextDefinition[];
+}
 /**
  * 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`).
  */
 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. */
@@ -1913,6 +2300,8 @@ type WorkspaceContext<ProjectMetadata extends Record<string, any> = Record<strin
     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.
@@ -2171,8 +2560,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;
@@ -2300,9 +2699,9 @@ 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 (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>;
 
@@ -2315,9 +2714,17 @@ 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>;
 }
 /**
@@ -2328,6 +2735,7 @@ declare function createWorkspace(params: CreateWorkspaceParams): Promise<{
     manager: WorkspaceManager;
     sessions: SessionManager;
     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 IndexExtensions, 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 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, getExtension, merge, ok, omitNullUndefined, shortHash, 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 BlobContextContent, 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 ContextDefinition, type ContextRetriever, type ContextSummary, type CreateSession, type CreateWorkspace, type CreateWorkspaceParams, type DeepPartial, type DefaultContextContent, 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 JsonContextContent, 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 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 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 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 };