@blokkli/editor 2.0.0-alpha.32 → 2.0.0-alpha.34

package/dist/modules/agent/runtime/app/types/index.d.ts

@@ -0,0 +1,440 @@
+import type { BlokkliApp } from '#blokkli/editor/types/app';
+import type { FullBlokkliAdapter, MutationResponseLike, AdapterMethods } from '#blokkli/editor/adapter';
+import type { EditMode } from '#blokkli/editor/types/state';
+import { z } from 'zod';
+import type { Component } from 'vue';
+/**
+ * Translation function type (matches $t from BlokkliApp).
+ */
+export type TranslationFunction = (key: string, defaultValue: string) => string;
+/**
+ * A host entity (parent of a block).
+ * Used consistently across tools for specifying block locations.
+ */
+export type Host = {
+    type: string;
+    uuid: string;
+    field: string;
+};
+export type McpToolCategory = 'query' | 'mutation';
+/**
+ * Result shape for mutation tools after the framework applies the mutation.
+ * This is the type passed to `prunedSummary` for non-component mutation tools.
+ */
+export type MutationToolResult = {
+    success: true;
+    historyIndex: number;
+    newParagraphs?: Array<{
+        uuid: string;
+        bundle: string;
+        paragraphFields?: string[];
+    }>;
+} | {
+    success: false;
+    rejected?: true;
+};
+/**
+ * Result from a query tool - includes a label for UI display
+ * and the actual result data sent to the LLM.
+ */
+export type QueryResult<T = unknown> = {
+    /** Human-readable label for display in conversation UI */
+    label: string;
+    /** The actual result data sent to the LLM */
+    result: T;
+    /**
+     * UUIDs of blocks related to this query.
+     * The framework will select these blocks and scroll them into view.
+     */
+    affectedUuids?: string[];
+};
+/**
+ * Error result that can be returned by any tool.
+ */
+export type ToolError = {
+    error: string;
+};
+/**
+ * Makes specified adapter methods required (non-optional).
+ */
+export type RequireAdapterMethods<T extends FullBlokkliAdapter<any>, Methods extends readonly AdapterMethods[]> = Omit<T, Methods[number]> & Required<Pick<T, Methods[number] & keyof T>>;
+/**
+ * A mutation action returned by mutation tools.
+ * The framework handles user approval and executes apply() when approved.
+ *
+ * @typeParam Methods - Adapter methods that are guaranteed to exist on the adapter.
+ */
+export type MutationAction<Methods extends readonly AdapterMethods[] = readonly []> = {
+    /** Type of mutation (for UI display) */
+    type: 'add' | 'delete' | 'move' | 'rewrite' | 'options';
+    /** Human-readable description for UI */
+    label: string;
+    /** The apply function - called when user accepts */
+    apply: (adapter: RequireAdapterMethods<FullBlokkliAdapter<any>, Methods>) => Promise<MutationResponseLike<any>> | undefined;
+    /** Optional revert function - called when user rejects (for rewrite preview) */
+    revert?: () => void;
+    /** Data to include in the success result sent to AI */
+    result?: Record<string, unknown>;
+    /**
+     * UUIDs of blocks affected by this mutation.
+     * The framework will select these blocks and scroll them into view after apply.
+     */
+    affectedUuids?: string[];
+};
+/**
+ * Context provided to tool execute functions.
+ * The adapter type has required methods marked as non-optional.
+ */
+export type McpToolContext<Methods extends readonly AdapterMethods[] = readonly []> = {
+    /** The blokkli app instance */
+    app: BlokkliApp;
+    /** Item entity type from module config */
+    itemEntityType: string;
+    /** The adapter with required methods guaranteed to exist */
+    adapter: Methods extends readonly AdapterMethods[] ? RequireAdapterMethods<FullBlokkliAdapter<any>, Methods> : FullBlokkliAdapter<any>;
+};
+/**
+ * Base definition for an MCP tool using Zod schemas.
+ *
+ * For query tools (category: 'query'):
+ *   execute() returns QueryResult<T> or ToolError.
+ *   QueryResult includes a label for UI display and the result data.
+ *
+ * For mutation tools (category: 'mutation'):
+ *   execute() returns a MutationAction or ToolError.
+ *   The framework handles user approval and formats the response.
+ *
+ * For tools with a component:
+ *   execute() returns data to pass to the component
+ *   The component emits the final result matching resultSchema
+ */
+export type McpToolDefinition<TParamsSchema extends z.ZodType = z.ZodType, TResultSchema extends z.ZodType = z.ZodType, TMethods extends readonly AdapterMethods[] = readonly [], TComponent extends Component | undefined = undefined, TCategory extends McpToolCategory = McpToolCategory> = {
+    /** Unique tool name (snake_case) */
+    name: string;
+    /** Description shown to the AI model */
+    description: string;
+    /** Optional icon name */
+    icon?: string;
+    /** Tool category: 'query' for immediate execution, 'mutation' for user approval */
+    category: TCategory;
+    /**
+     * Returns the label to display while the tool is executing.
+     * This is shown before the tool completes and provides its final label.
+     */
+    label: ($t: TranslationFunction) => string;
+    /** Zod schema for input parameters */
+    paramsSchema: TParamsSchema;
+    /** Zod schema for the result */
+    resultSchema: TResultSchema;
+    /** Optional: adapter methods required for this tool to be available */
+    requiredAdapterMethods?: TMethods;
+    /**
+     * Edit modes in which this tool is available.
+     * - 'editing': Full access, all tools available
+     * - 'translating': Only text-changing tools + query tools
+     * - 'readonly': Only query tools (read-only operations)
+     * - 'review': Only query tools (read-only operations)
+     */
+    modes: EditMode[];
+    /**
+     * Optional Vue component for interactive tools.
+     *
+     * When provided, the component receives { context, params } props and must
+     * emit a 'done' event with the result. The component is responsible for:
+     * - Rendering the UI for user interaction
+     * - Applying changes via the adapter
+     * - Emitting the final result back to the AI
+     *
+     * Use this for tools that need user interaction beyond simple approve/reject,
+     * such as batch operations with selective approval.
+     */
+    component?: TComponent;
+    /**
+     * Function to execute the tool.
+     *
+     * Query tools: Return QueryResult<T> with label for UI display.
+     * Mutation tools: Return a MutationAction or ToolError.
+     *
+     * For tools with a component:
+     * - The execute function is called first, and its result is passed to the component as params
+     * - The component handles all user interaction and emits the final result
+     */
+    execute: (context: McpToolContext<TMethods>, params: z.infer<TParamsSchema>) => TComponent extends Component ? unknown | Promise<unknown> : TCategory extends 'mutation' ? MutationAction<TMethods> | ToolError | Promise<MutationAction<TMethods> | ToolError> : QueryResult<z.infer<TResultSchema>> | ToolError | Promise<QueryResult<z.infer<TResultSchema>> | ToolError>;
+    /**
+     * If true, mutation tools require explicit user approval before applying.
+     * When false or omitted, mutations are applied immediately.
+     * Only relevant for tools with category 'mutation'.
+     */
+    requiresApproval?: boolean;
+    /**
+     * If true, this tool is not sent to the LLM until activated via load_tools.
+     * Lazy tools are listed by name + description in the system prompt so the
+     * LLM knows they exist and can load them on demand.
+     */
+    lazy?: boolean;
+    /**
+     * Whether results become stale after any mutation.
+     * When true, old results from this tool are marked as stale during pruning.
+     * Typical for query tools that return page structure (e.g. get_child_blocks).
+     */
+    volatile?: boolean;
+    /**
+     * Callback to compute a pruning summary from the tool result.
+     * Called client-side after tool execution. The returned string is included
+     * as `_summary` in the result sent to the server, and used during pruning
+     * instead of the generic fallback.
+     *
+     * The result type depends on the tool category:
+     * - Query tools / component tools: `z.infer<TResultSchema>`
+     * - Mutation tools (no component): `MutationToolResult`
+     */
+    prunedSummary?: (result: TComponent extends Component ? z.infer<TResultSchema> : TCategory extends 'query' ? z.infer<TResultSchema> : MutationToolResult) => string;
+    /**
+     * Optional function returning mock params for styling/debugging.
+     * When provided, the debug view will render the component with these params.
+     */
+    mockParams?: () => z.infer<TParamsSchema>;
+    /**
+     * Optional additional mock param variants for the debug gallery.
+     * Each entry renders an extra instance of the component.
+     */
+    mockParamsVariants?: () => z.infer<TParamsSchema>[];
+};
+/**
+ * A tool definition with a relaxed execute signature.
+ *
+ * Used as the return type for factory resolve callbacks. Preserves structural
+ * checking on all other properties (catches typos and excess properties) while
+ * allowing each tool to have its own specific execute signature via
+ * defineBlokkliAgentTool().
+ */
+export type FactoryResolvedTool = {
+    name: string;
+    description: string;
+    icon?: string;
+    category: McpToolCategory;
+    label: ($t: TranslationFunction) => string;
+    paramsSchema: z.ZodType;
+    resultSchema: z.ZodType;
+    requiredAdapterMethods?: readonly AdapterMethods[];
+    modes: EditMode[];
+    component?: Component;
+    requiresApproval?: boolean;
+    lazy?: boolean;
+    volatile?: boolean;
+    prunedSummary?: (result: any) => string;
+    execute: (...args: any[]) => any;
+    mockParams?: () => any;
+    mockParamsVariants?: () => any[];
+};
+/**
+ * Input for a tool factory that dynamically creates tools at runtime.
+ *
+ * Instead of defining a single static tool, a factory uses a `resolve` callback
+ * that is called when the agent connects. The callback returns an array of
+ * McpToolDefinition objects, allowing tools to be created based on runtime state
+ * (e.g., available content search tabs from the adapter).
+ */
+export type McpToolFactoryInput = {
+    /**
+     * Called once when the agent connects. Returns an array of tool definitions
+     * that are registered as if they were statically defined.
+     *
+     * Each returned tool is a full McpToolDefinition with its own
+     * requiredAdapterMethods, execute function, and schemas. Use
+     * defineBlokkliAgentTool() for each tool to get full type inference.
+     *
+     * The context provides access to the app and adapter so the factory can
+     * query runtime state (e.g., available content search tabs) to decide
+     * which tools to create. If adapter methods are optional, check for their
+     * existence before calling them (or return an empty array).
+     */
+    resolve: (context: McpToolContext) => Promise<FactoryResolvedTool[]> | FactoryResolvedTool[];
+};
+/**
+ * A tool factory with the __factory marker for runtime identification.
+ */
+export type McpToolFactory = McpToolFactoryInput & {
+    __factory: true;
+};
+/**
+ * A tool item is either a static tool definition or a factory that produces tools.
+ */
+export type McpToolItem = McpToolDefinition | McpToolFactory;
+/**
+ * A pre-defined agent prompt that users can select.
+ */
+export type AgentPromptDefinition = {
+    /** Unique prompt ID */
+    id: string;
+    /** Returns the label shown in the UI */
+    getLabel: (app: BlokkliApp) => string;
+    /** Returns the prompt text sent to the agent */
+    getPrompt: (app: BlokkliApp) => string;
+    /** Optional: returns the prompt text shown in the conversation UI. Defaults to getPrompt. */
+    getUserPrompt?: (app: BlokkliApp) => string;
+};
+/**
+ * Input for a prompt factory that dynamically creates prompts at runtime.
+ */
+export type AgentPromptFactoryInput = {
+    /**
+     * Called to resolve prompts dynamically based on runtime state.
+     */
+    resolve: (app: BlokkliApp) => AgentPromptDefinition[] | AgentPromptDefinition;
+};
+/**
+ * A prompt factory with the __factory marker for runtime identification.
+ */
+export type AgentPromptFactory = AgentPromptFactoryInput & {
+    __factory: true;
+};
+/**
+ * A prompt item is either a static prompt definition or a factory that produces prompts.
+ */
+export type AgentPromptItem = AgentPromptDefinition | AgentPromptFactory;
+/**
+ * A user message in the conversation history.
+ */
+declare const userConversationItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"user">;
+    content: z.ZodString;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        id: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * An assistant text message in the conversation history.
+ */
+declare const assistantConversationItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"assistant">;
+    content: z.ZodString;
+}, z.core.$strip>;
+/**
+ * A tool call in the conversation history.
+ * Status is 'active' while executing, then 'success' or 'error' when complete.
+ */
+declare const toolConversationItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"tool">;
+    callId: z.ZodString;
+    tool: z.ZodString;
+    label: z.ZodString;
+    status: z.ZodEnum<{
+        success: "success";
+        error: "error";
+        active: "active";
+    }>;
+}, z.core.$strip>;
+/**
+ * A server-side tool call result in the conversation history.
+ */
+declare const serverToolConversationItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"server_tool">;
+    tool: z.ZodEnum<{
+        load_skill: "load_skill";
+        load_tools: "load_tools";
+        create_plan: "create_plan";
+        complete_plan_step: "complete_plan_step";
+        plan_completed: "plan_completed";
+    }>;
+    label: z.ZodString;
+}, z.core.$strip>;
+/**
+ * An error message in the conversation history.
+ */
+declare const errorConversationItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"error">;
+    errorType: any;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Discriminated union of all conversation item schemas.
+ */
+export declare const conversationItemSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"user">;
+    content: z.ZodString;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        id: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"assistant">;
+    content: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"tool">;
+    callId: z.ZodString;
+    tool: z.ZodString;
+    label: z.ZodString;
+    status: z.ZodEnum<{
+        success: "success";
+        error: "error";
+        active: "active";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"server_tool">;
+    tool: z.ZodEnum<{
+        load_skill: "load_skill";
+        load_tools: "load_tools";
+        create_plan: "create_plan";
+        complete_plan_step: "complete_plan_step";
+        plan_completed: "plan_completed";
+    }>;
+    label: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"error">;
+    errorType: any;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>], "type">;
+export type UserConversationItem = z.infer<typeof userConversationItemSchema>;
+export type AssistantConversationItem = z.infer<typeof assistantConversationItemSchema>;
+export type ToolConversationItem = z.infer<typeof toolConversationItemSchema>;
+export type ServerToolConversationItem = z.infer<typeof serverToolConversationItemSchema>;
+export type ErrorConversationItem = z.infer<typeof errorConversationItemSchema>;
+/**
+ * A conversation item that failed validation when restoring from persistence.
+ * Displayed as a placeholder so the user sees something went wrong.
+ */
+export type UnknownConversationItem = {
+    type: 'unknown';
+    id: string;
+    timestamp: number;
+};
+/**
+ * Finalized items in conversation history (never modified after being pushed).
+ */
+export type ConversationItem = z.infer<typeof conversationItemSchema> | UnknownConversationItem;
+/**
+ * The single item currently being built (streaming text or pending tool).
+ * Only one active item can exist at a time. When complete, it's pushed to conversation history.
+ */
+export type ActiveItem = AssistantConversationItem | ToolConversationItem;
+export type TextAttachment = {
+    type: 'text';
+    id: string;
+    content: string;
+};
+export type Attachment = TextAttachment;
+export {};

package/dist/modules/agent/runtime/app/types/index.js

@@ -0,0 +1,51 @@
+import { agentErrorTypeSchema } from "#blokkli/agent/shared/types";
+import { z } from "zod";
+const conversationItemBase = z.object({
+  id: z.string(),
+  timestamp: z.number()
+});
+const userConversationItemSchema = conversationItemBase.extend({
+  type: z.literal("user"),
+  content: z.string(),
+  attachments: z.array(
+    z.object({
+      type: z.literal("text"),
+      id: z.string(),
+      content: z.string()
+    })
+  ).optional()
+});
+const assistantConversationItemSchema = conversationItemBase.extend({
+  type: z.literal("assistant"),
+  content: z.string()
+});
+const toolConversationItemSchema = conversationItemBase.extend({
+  type: z.literal("tool"),
+  callId: z.string(),
+  tool: z.string(),
+  label: z.string(),
+  status: z.enum(["active", "success", "error"])
+});
+const serverToolConversationItemSchema = conversationItemBase.extend({
+  type: z.literal("server_tool"),
+  tool: z.enum([
+    "load_skill",
+    "load_tools",
+    "create_plan",
+    "complete_plan_step",
+    "plan_completed"
+  ]),
+  label: z.string()
+});
+const errorConversationItemSchema = conversationItemBase.extend({
+  type: z.literal("error"),
+  errorType: agentErrorTypeSchema,
+  retryable: z.boolean().optional()
+});
+export const conversationItemSchema = z.discriminatedUnion("type", [
+  userConversationItemSchema,
+  assistantConversationItemSchema,
+  toolConversationItemSchema,
+  serverToolConversationItemSchema,
+  errorConversationItemSchema
+]);

package/dist/modules/agent/runtime/server/Session.d.ts

@@ -0,0 +1,94 @@
+import type { Peer } from 'crossws';
+import type { PageContext, ClientToolDefinition, ConversationStateSnapshot, GenericMessage } from '../shared/types.js';
+import type { ServerPlan } from './server-tools/index.js';
+export declare class Session {
+    messages: GenericMessage[];
+    pendingToolCalls: Map<string, {
+        resolve: (result: {
+            result: unknown;
+            error?: string;
+        }) => void;
+        reject: (error: Error) => void;
+    }>;
+    abortController: AbortController | null;
+    isProcessing: boolean;
+    /** Eager tools sent to the LLM on every turn */
+    tools: ClientToolDefinition[];
+    /** Lazy tools held back until activated via load_tools */
+    lazyTools: ClientToolDefinition[];
+    /** Names of lazy tools that have been activated via load_tools */
+    activatedLazyTools: Set<string>;
+    /** Names of skills that have been loaded via load_skill */
+    loadedSkills: Set<string>;
+    /** Page context received from client on init */
+    pageContext?: PageContext;
+    /** Current plan (null when no plan is active) */
+    plan: ServerPlan | null;
+    /** Pending plan approval promise resolver */
+    pendingPlanApproval: {
+        resolve: (approved: boolean) => void;
+    } | null;
+    /** Last tools payload sent to the provider (for transcript debugging) */
+    private lastProviderTools;
+    init(tools: ClientToolDefinition[], pageContext: PageContext): void;
+    start(peer: Peer, prompt: string, apiKey: string, authSecret: string, selectedUuids?: string[]): void;
+    resolveToolResult(callId: string, result: {
+        result: unknown;
+        error?: string;
+    }): void;
+    cancel(peer: Peer): void;
+    acceptChanges(peer: Peer, authSecret: string): void;
+    rejectChanges(peer: Peer, authSecret: string): void;
+    approvePlan(): void;
+    rejectPlan(): void;
+    getTranscript(peer: Peer): void;
+    newConversation(peer: Peer, authSecret: string): void;
+    cleanup(): void;
+    /**
+     * Build a persistence snapshot and send it to the client.
+     */
+    sendConversationState(peer: Peer, authSecret: string): void;
+    /**
+     * Create an aggressively pruned snapshot of the current conversation
+     * for client-side persistence.
+     */
+    getConversationStateForPersistence(authSecret: string): ConversationStateSnapshot;
+    /**
+     * Restore conversation state from a client-provided snapshot.
+     * Verifies HMAC integrity before loading.
+     */
+    restoreConversation(state: ConversationStateSnapshot, authSecret: string): {
+        success: boolean;
+        reason?: string;
+    };
+    /**
+     * Convert the server plan to a client-facing plan (strips descriptions).
+     */
+    private toClientPlan;
+    /**
+     * Build an ActivePlanContext from the current plan state,
+     * or undefined if no plan step is in progress.
+     */
+    private getActivePlanContext;
+    /**
+     * Wait for the user to approve or reject the plan.
+     */
+    private waitForPlanApproval;
+    private runAgentLoop;
+    private waitForToolResult;
+    /**
+     * Bug 3 fix: safely push a user message, merging with the last message
+     * if it's also a user message to avoid consecutive same-role messages.
+     */
+    private safePushUserMessage;
+    /**
+     * Remove skills from loadedSkills whose text content has been pruned
+     * from the conversation messages.
+     */
+    private reconcileLoadedSkills;
+    /**
+     * Build a map of tool name to pruning metadata from all known tools.
+     */
+    private buildToolMetadataMap;
+    private buildTranscript;
+}