@blokkli/editor 2.0.0-alpha.31 → 2.0.0-alpha.33

package/dist/modules/agent/runtime/server/providers/types.d.ts

@@ -0,0 +1,74 @@
+import type { ClientToolDefinition, GenericMessage } from '../../shared/types.js';
+import type { SystemPromptBlock } from '../system-prompts/types.js';
+export type { GenericTextBlock, GenericToolUseBlock, GenericToolResultBlock, GenericContentBlock, GenericMessage, } from '../../shared/types.js';
+/**
+ * Normalized stream events that all providers emit.
+ * The agent handler processes these uniformly regardless of provider.
+ */
+export type StreamEvent = {
+    type: 'text_start';
+} | {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'text_end';
+} | {
+    type: 'tool_use_start';
+    id: string;
+    name: string;
+} | {
+    type: 'tool_use_delta';
+    partial_json: string;
+} | {
+    type: 'tool_use_end';
+} | {
+    type: 'message_end';
+    stop_reason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop';
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+} | {
+    type: 'error';
+    error: Error;
+} | {
+    type: 'debug_request';
+    tools: unknown;
+};
+/**
+ * Configuration passed to provider when creating a stream.
+ */
+export type ProviderConfig = {
+    /** API key for the provider */
+    apiKey: string;
+    /** Model to use (provider-specific) */
+    model: string;
+};
+/**
+ * Options for creating a stream.
+ */
+export type StreamOptions = {
+    /** System prompt blocks with optional cache hints */
+    systemPrompt: SystemPromptBlock[];
+    /** Conversation messages */
+    messages: GenericMessage[];
+    /** Available tools */
+    tools: ClientToolDefinition[];
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+};
+/**
+ * Interface that all AI providers must implement.
+ */
+export interface AIProvider {
+    /** Provider name for identification */
+    readonly name: string;
+    /**
+     * Create a stream of events for the given messages.
+     * The provider converts generic messages to its native format,
+     * calls the API, and yields normalized StreamEvents.
+     */
+    createStream(config: ProviderConfig, options: StreamOptions): AsyncIterable<StreamEvent>;
+}

package/dist/modules/agent/runtime/server/server-tools/complete_plan_step/index.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+declare const _default: import("..").ServerSideTool<z.ZodObject<{}, z.core.$strip>>;
+export default _default;

package/dist/modules/agent/runtime/server/server-tools/complete_plan_step/index.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { defineServerSideTool } from "../index.js";
+const schema = z.object({});
+export default defineServerSideTool({
+  name: "complete_plan_step",
+  description: "Mark the current plan step as completed and get the next step. Call this when you have finished all work for the current step.",
+  inputSchema() {
+    return schema;
+  },
+  isAvailable(ctx) {
+    return !!ctx.plan && ctx.plan.steps.some(
+      (s) => s.status === "in_progress" || s.status === "pending"
+    );
+  },
+  handle(ctx) {
+    const currentStep = ctx.plan?.steps.find((s) => s.status === "in_progress");
+    if (!ctx.plan || !currentStep) {
+      return {
+        toolResults: [
+          {
+            type: "tool_result",
+            tool_use_id: ctx.toolUseId,
+            content: JSON.stringify({ error: "No active plan step" }),
+            is_error: true
+          }
+        ]
+      };
+    }
+    currentStep.status = "completed";
+    const nextStep = ctx.plan.steps.find((s) => s.status === "pending");
+    if (nextStep) {
+      nextStep.status = "in_progress";
+    }
+    ctx.send({
+      type: "server_tool_result",
+      tool: "complete_plan_step",
+      label: currentStep.label
+    });
+    ctx.send({
+      type: "plan_update",
+      plan: ctx.toClientPlan()
+    });
+    if (nextStep) {
+      return {
+        toolResults: [
+          {
+            type: "tool_result",
+            tool_use_id: ctx.toolUseId,
+            content: JSON.stringify({
+              completed: currentStep.label,
+              next_step: {
+                label: nextStep.label,
+                description: nextStep.description
+              }
+            })
+          }
+        ]
+      };
+    }
+    ctx.setPlan(null);
+    ctx.send({
+      type: "plan_update",
+      plan: null
+    });
+    return {
+      toolResults: [
+        {
+          type: "tool_result",
+          tool_use_id: ctx.toolUseId,
+          content: JSON.stringify({
+            completed: currentStep.label,
+            all_steps_completed: true,
+            message: "All plan steps are completed. Summarize what was done."
+          })
+        }
+      ]
+    };
+  }
+});

package/dist/modules/agent/runtime/server/server-tools/create_plan/index.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+declare const _default: import("..").ServerSideTool<z.ZodObject<{
+    title: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export default _default;

package/dist/modules/agent/runtime/server/server-tools/create_plan/index.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { defineServerSideTool } from "../index.js";
+const schema = z.object({
+  title: z.string().describe("Short title for the plan"),
+  steps: z.array(
+    z.object({
+      label: z.string().describe('Short label shown to the user (e.g. "Add hero section")'),
+      description: z.string().describe(
+        "Detailed instructions for yourself on what to do in this step"
+      )
+    })
+  ).min(2).describe("The steps of the plan")
+});
+export default defineServerSideTool({
+  name: "create_plan",
+  description: "Create a step-by-step plan for a complex task. The user will review and approve the plan before you proceed. Each step needs a short label (shown to the user) and a detailed description (your notes on what to do). Do NOT create plans for simple tasks.",
+  inputSchema() {
+    return schema;
+  },
+  isAvailable(ctx) {
+    return !ctx.plan;
+  },
+  async handle(ctx, input) {
+    const title = input.title || "Plan";
+    const steps = input.steps.map((s) => ({
+      label: s.label,
+      description: s.description,
+      status: "pending"
+    }));
+    ctx.setPlan({ title, steps });
+    ctx.send({
+      type: "plan_update",
+      plan: ctx.toClientPlan()
+    });
+    ctx.send({
+      type: "server_tool_result",
+      tool: "create_plan",
+      label: title
+    });
+    ctx.commitMessagesEarly({
+      type: "tool_result",
+      tool_use_id: ctx.toolUseId,
+      content: JSON.stringify({
+        status: "awaiting_approval",
+        title,
+        steps: steps.map((s) => s.label)
+      })
+    });
+    const approved = await ctx.waitForPlanApproval();
+    if (approved) {
+      steps[0].status = "in_progress";
+      ctx.send({
+        type: "plan_update",
+        plan: ctx.toClientPlan()
+      });
+      ctx.updateLastToolResult(
+        ctx.toolUseId,
+        JSON.stringify({
+          approved: true,
+          message: "Plan approved. Start executing now.",
+          current_step: {
+            label: steps[0].label,
+            description: steps[0].description
+          }
+        })
+      );
+    } else {
+      ctx.updateLastToolResult(
+        ctx.toolUseId,
+        JSON.stringify({
+          approved: false,
+          message: "The user rejected the plan. Ask what they would like to change."
+        })
+      );
+      ctx.setPlan(null);
+      ctx.send({
+        type: "plan_update",
+        plan: null
+      });
+    }
+    return {
+      toolResults: [],
+      messagesCommitted: true
+    };
+  }
+});

package/dist/modules/agent/runtime/server/server-tools/index.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import type { ClientToolDefinition, ClientPlanState, GenericContentBlock, GenericTextBlock, GenericSkillBlock, ServerMessage } from '../../shared/types.js';
+import type { ResolvedSkill } from '../skills/types.js';
+export type ServerPlanStep = {
+    label: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'completed';
+};
+export type ServerPlan = {
+    title: string;
+    steps: ServerPlanStep[];
+};
+export type ToolResultEntry = {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+/**
+ * Context available when building tool definitions and schemas.
+ * Lets each tool decide visibility and shape its input schema dynamically.
+ */
+export type ToolDefinitionContext = {
+    resolvedSkills: ResolvedSkill[];
+    plan: ServerPlan | null;
+    unloadedLazyTools: ClientToolDefinition[];
+};
+/**
+ * Context passed to `handle()` — provides access to session state
+ * and communication helpers each handler needs.
+ */
+export type ServerToolContext = {
+    toolUseId: string;
+    send: (message: ServerMessage) => void;
+    resolvedSkills: ResolvedSkill[];
+    lazyTools: ClientToolDefinition[];
+    activatedLazyTools: Set<string>;
+    loadedSkills: Set<string>;
+    plan: ServerPlan | null;
+    setPlan: (plan: ServerPlan | null) => void;
+    toClientPlan: () => ClientPlanState | null;
+    waitForPlanApproval: () => Promise<boolean>;
+    assistantContent: GenericContentBlock[];
+    commitMessagesEarly: (toolResult: ToolResultEntry) => void;
+    updateLastToolResult: (toolUseId: string, content: string) => void;
+};
+/**
+ * Return type of a server-side tool handler.
+ */
+export type ServerToolResult = {
+    toolResults: ToolResultEntry[];
+    extraBlocks?: (GenericTextBlock | GenericSkillBlock)[];
+    /** When true, messages were already committed (e.g. create_plan). */
+    messagesCommitted?: boolean;
+};
+/**
+ * A server-side tool.
+ *
+ * `inputSchema` is a callback that receives the current turn's context and
+ * returns a zod schema. The schema serves double duty:
+ *  - converted to JSON Schema via `z.toJSONSchema()` for the LLM, and
+ *  - used for runtime validation of the LLM's response via `.parse()`.
+ *
+ * Static tools can ignore the context parameter; dynamic tools (e.g. those
+ * with runtime enum values) use it to build the right constraints.
+ *
+ * `isAvailable` controls whether the tool is offered on a given turn.
+ * When omitted the tool is always included.
+ */
+export type ServerSideTool<T extends z.ZodType = z.ZodType> = {
+    name: string;
+    description: string;
+    inputSchema: (ctx: ToolDefinitionContext) => T;
+    /** Return false to hide this tool for the current turn. */
+    isAvailable?: (ctx: ToolDefinitionContext) => boolean;
+    handle: (ctx: ServerToolContext, input: z.infer<T>) => Promise<ServerToolResult> | ServerToolResult;
+};
+/**
+ * Identity function for type inference when defining a server-side tool.
+ */
+export declare function defineServerSideTool<T extends z.ZodType>(tool: ServerSideTool<T>): ServerSideTool<T>;
+/**
+ * Build a ClientToolDefinition from a ServerSideTool for a given context.
+ * Returns null when the tool should not be offered this turn.
+ */
+export declare function buildDefinition(tool: ServerSideTool, ctx: ToolDefinitionContext): ClientToolDefinition | null;

package/dist/modules/agent/runtime/server/server-tools/index.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export function defineServerSideTool(tool) {
+  return tool;
+}
+function stripSchemaOverhead(obj) {
+  if (Array.isArray(obj)) {
+    return obj.map(stripSchemaOverhead);
+  }
+  if (typeof obj === "object" && obj !== null) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (key === "$schema" || key === "additionalProperties") continue;
+      if (key === "propertyNames") continue;
+      result[key] = stripSchemaOverhead(value);
+    }
+    return result;
+  }
+  return obj;
+}
+export function buildDefinition(tool, ctx) {
+  if (tool.isAvailable && !tool.isAvailable(ctx)) {
+    return null;
+  }
+  const schema = tool.inputSchema(ctx);
+  return {
+    name: tool.name,
+    description: tool.description,
+    input_schema: stripSchemaOverhead(z.toJSONSchema(schema))
+  };
+}

package/dist/modules/agent/runtime/server/server-tools/load_skill/index.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+declare const _default: import("..").ServerSideTool<z.ZodObject<{
+    name: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+}, z.core.$strip>>;
+export default _default;

package/dist/modules/agent/runtime/server/server-tools/load_skill/index.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { defineServerSideTool } from "../index.js";
+export default defineServerSideTool({
+  name: "load_skill",
+  description: "Load detailed guidelines for a specific skill. Call this before writing or editing content that should follow specific rules or guidelines.",
+  inputSchema(ctx) {
+    return z.object({
+      name: z.enum(ctx.resolvedSkills.map((s) => s.name)).describe("The skill to load")
+    });
+  },
+  isAvailable(ctx) {
+    return ctx.resolvedSkills.length > 0;
+  },
+  handle(ctx, input) {
+    const skill = ctx.resolvedSkills.find((s) => s.name === input.name);
+    if (skill) {
+      ctx.loadedSkills.add(skill.name);
+      ctx.send({
+        type: "server_tool_result",
+        tool: "load_skill",
+        label: skill.label
+      });
+      return {
+        toolResults: [
+          {
+            type: "tool_result",
+            tool_use_id: ctx.toolUseId,
+            content: JSON.stringify({
+              loaded: true,
+              name: skill.name
+            })
+          }
+        ],
+        extraBlocks: [
+          {
+            type: "skill",
+            name: skill.name,
+            text: `# Skill: ${skill.name}
+
+${skill.content}`
+          }
+        ]
+      };
+    }
+    return {
+      toolResults: [
+        {
+          type: "tool_result",
+          tool_use_id: ctx.toolUseId,
+          content: JSON.stringify({
+            error: `Skill '${input.name}' not found`
+          }),
+          is_error: true
+        }
+      ]
+    };
+  }
+});

package/dist/modules/agent/runtime/server/server-tools/load_tools/index.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+declare const _default: import("..").ServerSideTool<z.ZodObject<{
+    tools: z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+}, z.core.$strip>>;
+export default _default;

package/dist/modules/agent/runtime/server/server-tools/load_tools/index.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { defineServerSideTool } from "../index.js";
+export default defineServerSideTool({
+  name: "load_tools",
+  description: 'Load additional tools by name before using them. You must call this before using any tool listed under "Additional Tools" in the system prompt.',
+  inputSchema(ctx) {
+    return z.object({
+      tools: z.array(
+        z.enum(
+          ctx.unloadedLazyTools.map((t) => t.name)
+        )
+      ).describe("Tool names to activate")
+    });
+  },
+  isAvailable(ctx) {
+    return ctx.unloadedLazyTools.length > 0;
+  },
+  handle(ctx, input) {
+    const loaded = [];
+    for (const name of input.tools) {
+      if (ctx.lazyTools.some((t) => t.name === name)) {
+        ctx.activatedLazyTools.add(name);
+        loaded.push(name);
+      }
+    }
+    if (loaded.length) {
+      ctx.send({
+        type: "server_tool_result",
+        tool: "load_tools",
+        label: String(loaded.length)
+      });
+    }
+    return {
+      toolResults: [
+        {
+          type: "tool_result",
+          tool_use_id: ctx.toolUseId,
+          content: JSON.stringify({ loaded })
+        }
+      ]
+    };
+  }
+});

package/dist/modules/agent/runtime/server/skills/defineBlokkliAgentSkill.d.ts

@@ -0,0 +1,23 @@
+import type { SkillDefinition } from './types.js';
+/**
+ * Define a blökkli agent skill.
+ *
+ * Skills are domain-specific guidelines that the AI agent can load on-demand.
+ * The getContents function receives the current page context and can return
+ * null if the skill is not applicable for that context.
+ *
+ * @example
+ * ```ts
+ * export default defineBlokkliAgentSkill({
+ *   name: 'my-skill',
+ *   description: 'Guidelines for writing content.',
+ *   getContents: (context) => {
+ *     if (context.entityLanguage !== 'de') {
+ *       return null
+ *     }
+ *     return `# Guidelines\n...`
+ *   },
+ * })
+ * ```
+ */
+export declare function defineBlokkliAgentSkill(definition: SkillDefinition): SkillDefinition;

package/dist/modules/agent/runtime/server/skills/defineBlokkliAgentSkill.js

@@ -0,0 +1,3 @@
+export function defineBlokkliAgentSkill(definition) {
+  return definition;
+}

package/dist/modules/agent/runtime/server/skills/index.d.ts

@@ -0,0 +1,2 @@
+export { defineBlokkliAgentSkill } from './defineBlokkliAgentSkill.js';
+export type { SkillDefinition, SkillLabel, ResolvedSkill } from './types.js';

package/dist/modules/agent/runtime/server/skills/index.js

@@ -0,0 +1 @@
+export { defineBlokkliAgentSkill } from "./defineBlokkliAgentSkill.js";

package/dist/modules/agent/runtime/server/skills/types.d.ts

@@ -0,0 +1,45 @@
+import type { PageContext } from '../../shared/types.js';
+/**
+ * Translatable label: either a plain string or an object keyed by language code.
+ * When an object, 'en' is required as fallback, other languages are optional.
+ */
+export type SkillLabel = string | {
+    en: string;
+    de?: string;
+    fr?: string;
+    it?: string;
+    gsw_CH?: string;
+};
+/**
+ * Skill definition with context-aware content getter.
+ * Used by defineBlokkliAgentSkill() to define skills as TypeScript modules.
+ */
+export type SkillDefinition = {
+    /** Unique identifier (kebab-case) */
+    name: string;
+    /** Human-readable label shown in the conversation UI */
+    label: SkillLabel;
+    /** When to use this skill */
+    description: string;
+    /**
+     * Get the skill content for the given page context.
+     * Return null if the skill is not applicable for this context.
+     */
+    getContents: (context: PageContext) => string | null;
+};
+/**
+ * Resolved skill after getContents has been called.
+ * Contains the actual content for display/use.
+ */
+export type ResolvedSkill = {
+    /** Unique identifier (kebab-case) */
+    name: string;
+    /** Human-readable label shown in the conversation UI (localized) */
+    label: string;
+    /** English label for use in the system prompt */
+    englishLabel: string;
+    /** When to use this skill */
+    description: string;
+    /** The resolved content for this context */
+    content: string;
+};

package/dist/modules/agent/runtime/server/system-prompts/defineBlokkliAgentSystemPrompt.d.ts

@@ -0,0 +1,21 @@
+import type { SystemPromptDefinition } from './types.js';
+/**
+ * Define a blökkli agent system prompt section.
+ *
+ * System prompt sections are collected at build time and assembled into the
+ * full system prompt at runtime. Each section has a weight that determines
+ * its position, and optional mode filtering.
+ *
+ * @example
+ * ```ts
+ * export default defineBlokkliAgentSystemPrompt({
+ *   id: 'my-section',
+ *   title: 'My Section',
+ *   weight: 550,
+ *   getPrompt: (context) => {
+ *     return `Custom prompt content based on ${context.pageContext.title}`
+ *   },
+ * })
+ * ```
+ */
+export declare function defineBlokkliAgentSystemPrompt(definition: SystemPromptDefinition): SystemPromptDefinition;

package/dist/modules/agent/runtime/server/system-prompts/defineBlokkliAgentSystemPrompt.js

@@ -0,0 +1,3 @@
+export function defineBlokkliAgentSystemPrompt(definition) {
+  return definition;
+}

package/dist/modules/agent/runtime/server/system-prompts/helpers.d.ts

@@ -0,0 +1,20 @@
+import type { BlockBundleContentField } from '../../shared/types.js';
+/**
+ * Get a human-readable description of the edit mode.
+ */
+export declare function getEditModeDescription(editMode: string): string;
+/**
+ * Format a list of items as `### \`id\` - label` with optional descriptions.
+ * Optionally includes intro/outro text.
+ *
+ * Returns null when the items array is empty.
+ */
+export declare function formatItems(items: {
+    id: string;
+    label: string;
+    description?: string;
+}[], intro?: string, outro?: string): string | null;
+/**
+ * Format a content field as a prompt line.
+ */
+export declare function formatContentField(field: BlockBundleContentField): string;

package/dist/modules/agent/runtime/server/system-prompts/helpers.js

@@ -0,0 +1,41 @@
+export function getEditModeDescription(editMode) {
+  switch (editMode) {
+    case "editing":
+      return "The user has full editing access and can make any changes to the page structure and content.";
+    case "translating":
+      return "The user is translating the page content. They can only edit content text fields to provide translations. Structural changes (adding, deleting, moving paragraphs) are not allowed.";
+    case "readonly":
+      return "The user has read-only access. No changes can be made to the page. You can only answer questions about the content.";
+    case "review":
+      return "The user is reviewing the page. No changes can be made. You can only answer questions about the content.";
+    default:
+      return "";
+  }
+}
+export function formatItems(items, intro, outro) {
+  if (items.length === 0) {
+    return null;
+  }
+  const lines = [];
+  if (intro) {
+    lines.push(intro, "");
+  }
+  for (const item of items) {
+    const heading = item.label && item.label !== item.id ? `### \`${item.id}\` - ${item.label}` : `### \`${item.id}\``;
+    lines.push(heading);
+    if (item.description) {
+      lines.push(item.description);
+    }
+    lines.push("");
+  }
+  if (outro) {
+    lines.push(outro);
+  }
+  return lines.join("\n");
+}
+export function formatContentField(field) {
+  if (field.type === "reference" || field.type === "link") {
+    return `- ${field.name} (${field.type}): ${field.allowed.map((a) => `${a.type} [${a.bundles.join(", ")}]`).join(", ")}`;
+  }
+  return `- ${field.name} (${field.type})`;
+}

package/dist/modules/agent/runtime/server/system-prompts/index.d.ts

@@ -0,0 +1,2 @@
+export { defineBlokkliAgentSystemPrompt } from './defineBlokkliAgentSystemPrompt.js';
+export type { SystemPromptDefinition, SystemPromptContext } from './types.js';

package/dist/modules/agent/runtime/server/system-prompts/index.js

@@ -0,0 +1 @@
+export { defineBlokkliAgentSystemPrompt } from "./defineBlokkliAgentSystemPrompt.js";