@asaidimu/utils-workspace 6.5.11 → 6.6.0

package/index.d.ts

@@ -1,6 +1,6 @@
 import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
-import { GenerateContentParameters, GoogleGenAI, GenerateContentResponse, Content, Part } from '@google/genai';
+import { GenerateContentParameters, GoogleGenAI, GenerateContentResponse } from '@google/genai';
 
 /**
  * Buffers write operations across one or more stores and commits them atomically.
@@ -551,12 +551,85 @@ interface CheckpointSessionState {
      * TODO items, or incomplete reasoning paths.
      */
     unresolved: string[];
+    /**
+     * Derived realizations, synthesized understanding, reframings, or emergent patterns discovered during the conversation.
+     * These are not raw facts or decisions, but higher-level understanding gained by either party.
+     */
+    insights?: string[];
     /**
      * Additional continuity information that does not cleanly fit
      * other state categories but is required for faithful continuation.
      */
     notes?: string[];
+    /**
+     * External documents, URLs, or resources brought into the conversation
+     * by the user or referenced during reasoning.
+     *
+     * These are inputs — things that informed the conversation.
+     */
+    references?: ContextReference[];
+    /**
+     * Artifacts produced during the conversation.
+     *
+     * These are outputs — things created as a result of the conversation.
+     * The record is keyed by artifact key and description
+     */
+    artifacts?: ContextReference[];
 }
+interface ContextReference {
+    /**
+     * The Key of the injected context item this reference points to.
+     * Allows the runtime to re-inject the same context when resuming.
+     * Omitted for external references that were never part of the Context system.
+     */
+    key?: string;
+    label: string;
+    /** Why this reference matters for conversational continuity. */
+    description: string;
+}
+interface Artifact extends BaseContentBlock<"artifact"> {
+    /** Unique lookup key for this artifact entry. */
+    key: string;
+    /** Incrementing number representing edits to the same artifact ID. */
+    version: number;
+    /** Short human-readable label. */
+    label: string;
+    /**
+     * What was produced, its structure, and its role in the conversation.
+     * Enough detail to understand the artifact without re-reading it.
+     */
+    description: string;
+    /** The contents of the artifact. */
+    content: TextContextContent;
+    /**
+     * Current status of this artifact.
+     * - complete: finished and accepted
+     * - draft: produced but pending refinement
+     */
+    status: "complete" | "draft";
+    /**
+     * UTC timestamp of when this artifact was produced.
+     * Preserves ordering when multiple artifacts exist.
+     */
+    created?: Timestamp;
+    /**
+     * UTC timestamp of when this artifact was updated.
+     * Preserves ordering when multiple artifacts exist.
+     */
+    updated?: Timestamp;
+}
+type ArtifactPatchFormat = "unified-diff";
+interface ArtifactPatch {
+    format: ArtifactPatchFormat;
+    value: string;
+}
+type ArtifactUpdate = Pick<Artifact, "key" | "status"> & ({
+    content: TextContextContent;
+    patch?: never;
+} | {
+    patch: ArtifactPatch;
+    content?: never;
+});
 
 /**
  * This file contains the primary domain models, data structures, and command types
@@ -734,6 +807,12 @@ interface BlobRecord {
 interface BaseContentBlock<BlockType extends string> {
     /** Unique identifier for the specific content block instance. */
     id: UUID;
+    /**
+     * Stable unique identifier for this artifact across the conversation.
+     * Allows lineage references from other artifacts.
+     * Different from id in that it is designed for model consumption
+     */
+    key?: string;
     /** Discriminator used to determine the shape and rendering of the block. */
     type: BlockType;
     /** Extensible key-value store for block-specific properties. */
@@ -963,39 +1042,63 @@ interface Preference {
     /** UTC timestamp of when this preference was established or last updated. */
     timestamp: Timestamp;
 }
-/** Supported payload for text-based context. */
-type TextContextContent = {
-    kind: "text";
+/**
+ * Base interface for all context content variants.
+ * Uses a discriminated union pattern where the `kind` field determines the concrete type.
+ * @template Kind - A string literal type that identifies the specific content variant.
+ */
+interface BaseContextContent<Kind extends string> {
+    kind: Kind;
+}
+/**
+ * Supported payload for text-based context.
+ * Extends the base interface with a fixed `"text"` kind.
+ */
+interface TextContextContent extends BaseContextContent<"text"> {
+    /** The raw text content. */
     value: string;
-};
-/** Supported payload for structured JSON context. */
-type JsonContextContent = {
-    kind: "json";
+}
+/**
+ * Supported payload for structured JSON context.
+ * Extends the base interface with a fixed `"json"` kind.
+ */
+interface JsonContextContent extends BaseContextContent<"json"> {
+    /** The parsed JSON value (can be any valid JSON type). */
     value: unknown;
-};
-/** Supported payload for blob-based context. */
-type BlobContextContent = {
-    kind: "blob";
+}
+/**
+ * Supported payload for blob-based context (binary data identified by hash).
+ * Extends the base interface with a fixed `"blob"` kind.
+ */
+interface BlobContextContent extends BaseContextContent<"blob"> {
+    /** SHA-256 hash of the blob content. */
     sha256: SHA256;
+    /** MIME type of the blob. */
     mediaType: BlobMediaType;
+    /** Size of the blob in bytes. */
     sizeBytes: number;
+    /** Optional suggested filename. */
     filename?: string;
-};
-/** Supported payload for remote URI context. */
-type RemoteContextContent = {
-    kind: "remote";
+}
+/**
+ * Supported payload for remote URI context (content accessible via URL).
+ * Extends the base interface with a fixed `"remote"` kind.
+ */
+interface RemoteContextContent extends BaseContextContent<"remote"> {
+    /** The URI where the content can be retrieved. */
     uri: URI;
+    /** Optional MIME type hint for the remote content. */
     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;
+type ContextContent<T extends BaseContextContent<any> = any> = DefaultContextContent | T;
 /** A contextual item (file, snippet, or data) attached to a session or prompt. */
-interface Context<T = any> {
+interface Context<T extends BaseContextContent<any> = any> {
     /** Unique lookup key for this context entry. */
     key: string;
     /** Topics linking this context to relevant sessions or roles. */
@@ -1019,6 +1122,10 @@ interface SessionMetadata {
     topics: string[];
     /** Array of UUIDs pointing to explicitly active preferences for this session. */
     preferences: UUID[];
+    /** Array of keys pointing to explicitly active context for this session. */
+    context?: Array<string>;
+    /** Array of keys pointing to explicitly active context for this session. */
+    artifacts?: Array<string>;
     /** Timestamps detailing the session lifecycle. */
     metadata: {
         /** UTC timestamp of session creation. */
@@ -1065,6 +1172,21 @@ interface PreferenceSummary {
     /** A truncated preview string of the preference content. */
     snippet?: string;
 }
+/** In-memory summary of an Artifact. */
+interface ArtifactSummary {
+    /** The unique key for the artifact. */
+    key: string;
+    /** Incrementing number representing edits. */
+    version: number;
+    /** Associated semantic topics. */
+    topics: string[];
+    /** UTC timestamp of the last update. */
+    timestamp: Timestamp;
+    /** Human-readable label. */
+    label: string;
+    /** Status (complete or draft). */
+    status: "complete" | "draft";
+}
 /** In-memory summary of a Context entry. */
 interface ContextSummary {
     /** The unique key for the context item. */
@@ -1111,6 +1233,8 @@ interface Index<T extends IndexExtensions = IndexExtensions> {
     roles: Record<string, RoleSummary>;
     /** Lookup dictionary of Preferences by their UUID. */
     preferences: Record<UUID, PreferenceSummary>;
+    /** Lookup dictionary of Artifacts by their unique key. */
+    artifacts: Record<string, ArtifactSummary>;
     /** Lookup dictionary of Context entries by their specific key. */
     context: Record<string, ContextSummary>;
     /** Lookup dictionary of active Sessions by their UUID. */
@@ -1261,6 +1385,27 @@ interface DeleteContext extends BaseCommand {
         key: string;
     };
 }
+interface AddArtifact extends BaseCommand {
+    type: "artifact:add";
+    /** The complete artifact object to register. */
+    payload: Artifact & {
+        sessionId: UUID;
+    };
+}
+interface UpdateArtifact extends BaseCommand {
+    type: "artifact:update";
+    /** Delta properties to update an existing artifact record. */
+    payload: ArtifactUpdate & {
+        sessionId: UUID;
+    };
+}
+interface DeleteArtifact extends BaseCommand {
+    type: "artifact:delete";
+    /** Key of the artifact to destroy. */
+    payload: {
+        key: string;
+    };
+}
 /** Updates an existing turn record in storage. */
 interface UpdateTurn extends BaseCommand {
     type: "turn:update";
@@ -1365,7 +1510,11 @@ interface UpdateSession extends BaseCommand {
         role?: string;
         topics?: string[];
         preferences?: UUID[];
+        context?: string[];
+        artifacts?: string[];
         metadata?: SessionMetadata["metadata"];
+        head?: SessionMetadata["head"];
+        constraints?: SessionMetadata["constraints"];
     };
 }
 interface DeleteSession extends BaseCommand {
@@ -1471,7 +1620,7 @@ interface ToolCallCommand extends BaseCommand {
     payload: ToolCall;
 }
 /** Union of all possible commands that can be dispatched to the Workspace Manager. */
-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;
+type Command = CreateWorkspace | SyncWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | UpdateSession | ForkSession | DeleteSession | SwitchSessionRole | AddSessionTopics | OverrideSessionPreferences | AddContext | UpdateContext | DeleteContext | AddArtifact | UpdateArtifact | DeleteArtifact | 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.
@@ -1541,6 +1690,8 @@ interface SessionSnapshot {
     preferences: Preference[];
     /** All context entries whose topics overlap with the session's active topics. */
     context: Context[];
+    /** Array of keys pointing to explicitly active context for this session. */
+    artifacts: Array<Artifact>;
     /** Full active chain from TurnTree — oldest to newest. Untruncated. */
     transcript: Turn[];
     /** The session's active semantic topic set. */
@@ -1695,50 +1846,20 @@ interface AssemblerExtension extends PromptSection {
 }
 /**
  * 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().
-     */
+    build<P, C>(provider: string, prompt: Prompt, mapTurn: (args: {
+        turn: Turn;
+        parts: P[];
+    }) => C, extensions?: AssemblerExtension[]): Promise<{
+        system: string;
+        transcript: C[];
+        sections: PromptSection[];
+    }>;
+    parse(provider: string, raw: Array<{
+        type: string;
+        [key: string]: any;
+    }>): BaseContentBlock<any>[];
     join(sections: PromptSection[]): string;
 }
 type BlockMapper = {
@@ -1746,7 +1867,7 @@ 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;
+    to(block: BaseContentBlock<string>): unknown | Promise<unknown>;
     /**
      * Convert a provider-extracted raw JSON object into a workspace block.
      * Return `null` if parsing fails.
@@ -1836,7 +1957,7 @@ interface WorkspaceServices {
  * Output of PromptBuilder.build(). Input to LLMAdapter.resolve().
  *
  * Contains fully ranked and conflict-resolved preferences, context, and a
- * catalogue of blob references — but is NOT truncated and does NOT contain
+ * catalogue of blob references - but is NOT truncated and does NOT contain
  * resolved binary blob data. The adapter is responsible for:
  *   - Deciding what fits within the model's context window.
  *   - Resolving only the BlobRefs that survive truncation.
@@ -1858,6 +1979,8 @@ interface Prompt {
         /** Ranked context entries (text and json kinds only). Blob context is
          *  represented as referential blocks in the transcript instead. */
         context: Context[];
+        /** Ranked artifact entries included after adapter-level truncation. */
+        artifacts: Artifact[];
         /** Additional sections injected by the adapter or application layer. */
         extensions?: AssemblerExtension[];
     };
@@ -1868,12 +1991,12 @@ interface Prompt {
      * Lightweight catalogue of every blob referenced anywhere in this prompt
      * (system.context or transcript), keyed by SHA256.
      *
-     * Values are BlobRefs — metadata only, no binary data. The adapter uses
+     * Values are BlobRefs - metadata only, no binary data. The adapter uses
      * this catalogue to resolve or upload blobs for whichever turns and context
      * entries survive its truncation pass.
      */
     blobs: Map<SHA256, BlobRef>;
-    /** The role object — for inspection and adapter use. */
+    /** The role object - for inspection and adapter use. */
     role: Role;
     /** Model constraints to be merged by the adapter (turn > session > role). */
     constraints: ModelConstraintMap;
@@ -1900,7 +2023,7 @@ interface AdapterStatus {
         size: number;
         /** Maximum output tokens for this model. */
         out: number;
-        /** Tokens remaining — estimated or as reported by the provider. */
+        /** Tokens remaining - estimated or as reported by the provider. */
         free?: number;
     };
     /** Capability flags for this model. */
@@ -1954,7 +2077,7 @@ interface AdapterStatus {
 /**
  * The result of `PreparedPrompt.execute()`. Contains the turn and derived effects.
  */
-interface ExecuteResult {
+interface PromptResult {
     /** The newly generated assistant turn. */
     turn: Turn;
     /** Side-effect commands to dispatch against the workspace. */
@@ -1962,7 +2085,7 @@ interface ExecuteResult {
 }
 /**
  * A single labelled section of the system prompt.
- * Mirrors PreparedPrompt.system exactly — the assembler's output is stored
+ * Mirrors PreparedPrompt.system exactly - the assembler's output is stored
  * there directly, giving callers full inspection without re-parsing the string.
  */
 interface PromptSection {
@@ -1993,6 +2116,8 @@ interface PreparedPrompt {
     transcript: Turn[];
     /** Final context entries included after adapter-level truncation. */
     context: Context[];
+    /** Final artifact entries included after adapter-level truncation. */
+    artifacts: Artifact[];
     /** Final preferences included after adapter-level truncation. */
     preferences: Preference[];
     /** The resolved model constraints for this request. */
@@ -2001,7 +2126,7 @@ interface PreparedPrompt {
     tokens: {
         /** Breakdown by section. Keys are adapter-defined. */
         breakdown: Record<string, number>;
-        /** Total input tokens — estimated or exact. */
+        /** Total input tokens - estimated or exact. */
         total: number;
         /** Whether total is an estimate or exact (provider-supplied). */
         source: "estimated" | "exact";
@@ -2014,12 +2139,12 @@ interface PreparedPrompt {
      * Sends this prompt to the model.
      * @returns The parsed assistant Turn plus any execution side-effects.
      */
-    execute(): Promise<Result<ExecuteResult, WorkspaceError>>;
+    execute(): Promise<Result<PromptResult, WorkspaceError>>;
     /**
      * Streaming variant of execute(). Yields partial turns as tokens arrive.
      * Present only if the adapter and model support streaming.
      */
-    executeStream?(): AsyncIterable<Partial<Turn> | ExecuteResult>;
+    executeStream?(): AsyncIterable<Partial<Turn> | PromptResult>;
 }
 
 /**
@@ -2177,6 +2302,7 @@ declare const COLLECTIONS: {
     readonly TURN: "turn";
     readonly BLOB: "blob";
     readonly TOPIC: "topic";
+    readonly ARTIFACT: "artifact";
 };
 type Collections = (typeof COLLECTIONS)[keyof typeof COLLECTIONS];
 
@@ -2202,6 +2328,22 @@ declare class ContextStore implements Store<Context, ContextSummary, string> {
     summarize(context: Context): ContextSummary;
 }
 
+declare class ArtifactStore implements Store<Artifact, ArtifactSummary, string> {
+    private readonly collection;
+    private readonly cache;
+    constructor(collection: Collection<Artifact>, cache: LRUCache<string, Artifact>);
+    get(key: string): Promise<Artifact | null>;
+    add(artifact: Artifact): Promise<void>;
+    update(key: string, updates: Partial<Artifact>): Promise<Artifact | null>;
+    delete(key: string): Promise<boolean>;
+    list(): Promise<Artifact[]>;
+    /**
+     * Retrieves all artifacts referenced by the given topics using the in-memory index.
+     */
+    getByTopics(index: Index, topics: string[]): Promise<Artifact[]>;
+    summarize(artifact: Artifact): ArtifactSummary;
+}
+
 declare class PreferenceStore implements Store<Preference, PreferenceSummary, UUID> {
     private readonly collection;
     private readonly cache;
@@ -2322,7 +2464,7 @@ 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> {
+interface ContextDefinition<T extends BaseContextContent<any> = any> {
     /** Unique discriminator for this context kind (e.g., 'text', 'blob', 'task'). */
     kind: string;
     /**
@@ -2384,6 +2526,8 @@ type WorkspaceContext<ProjectMetadata extends Record<string, any> = Record<strin
     preferences: PreferenceStore;
     /** Store for managing RAG-retrievable context entries. */
     context: ContextStore;
+    /** Store for managing durable conversational artifacts. */
+    artifacts: ArtifactStore;
     /** Store for managing active and archived conversation sessions. */
     sessions: SessionStore;
     /** Store for managing topic metadata and indexing. */
@@ -2770,6 +2914,26 @@ declare class Session {
      * @param preferenceIds - Array of preference UUIDs.
      */
     setPreferences(preferenceIds: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Replaces the session’s context list.
+     * @param contextKeys - New array of context keys.
+     */
+    setContext(contextKeys: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Adds context keys to the session (does not replace existing ones).
+     * @param contextKeys - Context keys to add.
+     */
+    addContext(contextKeys: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Removes context keys from the session.
+     * @param contextKeys - Context keys to remove.
+     */
+    removeContext(contextKeys: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Replaces the session’s artifact list.
+     * @param artifactKeys - New array of artifact keys.
+     */
+    setArtifacts(artifactKeys: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     /**
      * Creates a new session as a fork of this one.
      * @param newSessionId - ID for the new session.
@@ -2882,6 +3046,7 @@ declare class SessionManager {
         role: string;
         topics: string[];
         preferences?: UUID[];
+        metadata?: Record<string, any>;
     }): Promise<Session>;
     list(): SessionMetadata[];
     metadata(sessionId: UUID): SessionMetadata | undefined;
@@ -2903,7 +3068,7 @@ declare class TurnBuilder {
     addSummary(text: string): TurnBuilder;
     addRoleTransition(previousRole: string | undefined, newRole: string): TurnBuilder;
     addThinking(thinking: string): TurnBuilder;
-    addBlock(block: ContentBlock): TurnBuilder;
+    addBlock(block: BaseContentBlock<any>): TurnBuilder;
     deleteBlock(blockId: UUID): TurnBuilder;
     editTextBlock(blockId: UUID, newText: string): TurnBuilder;
     withId(id: UUID): TurnBuilder;
@@ -2931,25 +3096,39 @@ declare class DefaultPromptBuilder implements PromptBuilder {
     build(snapshot: SessionSnapshot, _: WorkspaceContext, options?: PromptBuilderOptions): Promise<Result<Prompt, WorkspaceError>>;
 }
 
-declare class DefaultSystemPromptAssembler implements SystemPromptAssembler {
+declare class PromptAssembler implements SystemPromptAssembler {
+    private readonly registry;
+    constructor(registry: ContentBlockRegistry);
+    build<P, C>(provider: string, prompt: Prompt, mapTurn: (args: {
+        turn: Turn;
+        parts: P[];
+    }) => C, extensions?: AssemblerExtension[]): Promise<{
+        system: string;
+        sections: PromptSection[];
+        transcript: C[];
+    }>;
+    private buildSections;
     /**
-     * Builds the ordered array of PromptSections from a Prompt plus extensions.
+     * Parses an array of raw block objects from a model response into typed
+     * workspace ContentBlocks via the registry.
+     *
+     * The caller (adapter + response.ts) owns wire-format extraction — pulling
+     * the raw blocks array out of the provider envelope. This method owns only
+     * the registry dispatch: raw → registry.parse(raw, providerId) → ContentBlock.
      *
-     * Algorithm:
-     *   1. Build the five candidate core sections from the Prompt.
-     *   2. Drop any core section that has no meaningful content.
-     *   3. Walk the extensions array and splice each one into the result at
-     *      its declared anchor position.
-     *   4. Return the final ordered array.
+     * Unknown or unregistered block types are skipped (registry returns null
+     * and logs a warning). This method never throws on bad input.
      */
-    build(prompt: Prompt, extensions?: AssemblerExtension[]): PromptSection[];
+    parse(provider: string, rawBlocks: Array<{
+        type: string;
+        [key: string]: any;
+    }>): ContentBlock[];
     /**
      * Joins an ordered array of PromptSections into a single string.
-     * Uses a consistent separator that renders clearly across providers.
      */
     join(sections: PromptSection[]): string;
 }
-declare function createDefaultAssembler(): DefaultSystemPromptAssembler;
+declare function createDefaultAssembler(registry: ContentBlockRegistry): PromptAssembler;
 
 declare class JaccardContextRetriever implements ContextRetriever {
     private readonly contextRegistry;
@@ -3096,7 +3275,7 @@ declare class GoogleGenAIAdapter implements LLMAdapter<GenerateContentParameters
         model: string;
         models?: Array<ModelProfile>;
     });
-    private registerGeminiMappings;
+    private registerMappings;
     status(_?: string): Promise<AdapterStatus>;
     resolve(params: {
         prompt: Prompt;
@@ -3109,47 +3288,56 @@ declare const mappings: Record<string, BlockMapper>;
 
 declare const GOOGLE_MODELS: Array<ModelProfile>;
 
+type RawBlock = {
+    type: string;
+    [key: string]: any;
+};
 /**
- * Extracts workspace ContentBlocks from a Gemini GenerateContentResponse.
+ * What the wire-format extraction layer returns to the adapter.
  *
- * Responsibility split:
- *   - This function owns the Gemini wire format (candidates, parts, thought flag).
- *   - Block validation and construction is fully delegated to the registry.
- *     Unknown block types returned by the model are silently dropped (registry
- *     returns null for unregistered types) and logged by the registry itself.
- *   - If the model ignores the structured JSON schema and returns raw text,
- *     it automatically wraps the response in a TextBlock with markdown repair.
- */
-declare function parseModelResponse(response: GenerateContentResponse, registry: ContentBlockRegistry): Result<ContentBlock[], WorkspaceError>;
-
+ * - `thinking`  — zero or more thinking blocks, fully constructed (they carry
+ *                 no registry mapping; their shape is fixed by the protocol).
+ * - `rawBlocks` — the JSON blocks array from the model's structured output,
+ *                 unparsed. The adapter hands these to assembler.parse().
+ * - `fallback`  — set instead of rawBlocks when the model returned raw text
+ *                 rather than the requested JSON schema. The adapter wraps
+ *                 this in a TextBlock via wrapAsTextBlock.
+ */
+type ExtractionResult = {
+    ok: true;
+    thinking: ThinkingBlock[];
+    rawBlocks: RawBlock[];
+} | {
+    ok: true;
+    thinking: ThinkingBlock[];
+    fallback: string;
+} | {
+    ok: false;
+    thinking: ThinkingBlock[];
+    error: WorkspaceError;
+};
 /**
- * Maps a workspace Turn into a Gemini Content object.
+ * Extracts structured data from a Gemini GenerateContentResponse.
  *
- * Blob blocks (image, document) are resolved to inline or remote Parts via
- * mapBlobRefToPart. All other blocks are dispatched through the registry's
- * provider mapping for provider() — a missing mapping is a programming error
- * and throws immediately rather than silently degrading.
- */
-declare function mapTurnToContent(turn: Turn, resolveBlob: BlobResolver, registry: ContentBlockRegistry): Promise<Content>;
-/**
- * Maps a single workspace block to a Gemini Part via the registry's provider mapping.
+ * Responsibility:
+ *   - Owns the Gemini wire format: candidates, parts, thought flag.
+ *   - Separates thinking parts from the JSON payload.
+ *   - Returns raw blocks (unparsed) or a fallback string.
+ *   - Has no knowledge of the block registry or provider mappings.
  *
- * Throws if no mapping is registered for provider() — every block type that can
- * appear in a transcript must have a Gemini mapping registered by the adapter at
- * initialisation time. There is no silent fallback: an unmapped block is a gap in
- * the adapter's setup, not a recoverable runtime condition.
+ * Registry dispatch (raw → ContentBlock) is the assembler's job.
  */
-declare function mapBlockToPart(block: BaseContentBlock<string>, registry: ContentBlockRegistry): Part | null;
+declare function extractModelResponse(response: GenerateContentResponse): ExtractionResult;
 
+type index_ExtractionResult = ExtractionResult;
 declare const index_GOOGLE_MODELS: typeof GOOGLE_MODELS;
 type index_GoogleGenAIAdapter = GoogleGenAIAdapter;
 declare const index_GoogleGenAIAdapter: typeof GoogleGenAIAdapter;
-declare const index_mapBlockToPart: typeof mapBlockToPart;
-declare const index_mapTurnToContent: typeof mapTurnToContent;
+type index_RawBlock = RawBlock;
+declare const index_extractModelResponse: typeof extractModelResponse;
 declare const index_mappings: typeof mappings;
-declare const index_parseModelResponse: typeof parseModelResponse;
 declare namespace index {
-  export { index_GOOGLE_MODELS as GOOGLE_MODELS, index_GoogleGenAIAdapter as GoogleGenAIAdapter, index_mapBlockToPart as mapBlockToPart, index_mapTurnToContent as mapTurnToContent, index_mappings as mappings, index_parseModelResponse as parseModelResponse };
+  export { type index_ExtractionResult as ExtractionResult, index_GOOGLE_MODELS as GOOGLE_MODELS, index_GoogleGenAIAdapter as GoogleGenAIAdapter, type index_RawBlock as RawBlock, index_extractModelResponse as extractModelResponse, index_mappings as mappings };
 }
 
 interface CreateWorkspaceParams {
@@ -3211,4 +3399,4 @@ declare function createWorkspace(params: CreateWorkspaceParams): Promise<{
     bootstrap: (config: BootstrapConfig) => Promise<BootstrapResult>;
 }>;
 
-export { type AdapterStatus, type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTopic, type AddTurn, type AssemblerExtension, type AuthRequest, type BackendError, type BaseCommand, type BaseContentBlock, 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, DefaultSystemPromptAssembler, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTopic, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type ExecuteResult, 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, type PromptBuilder, type PromptBuilderOptions, 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 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, 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 };