@blokkli/editor 2.0.0-alpha.5 → 2.0.0-alpha.51

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,100 @@
+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: {
+        name: string;
+        description: string;
+    }[];
+};
+/**
+ * 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[];
+    lazyToolNames: string[];
+    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;
+    /** Whether any non-server tools were called since the current plan step started. */
+    planStepHasWork: boolean;
+    /** Mark that real work was performed for the current plan step. */
+    markPlanStepWork: () => void;
+    /** Reset the work flag (called after advancing to the next plan step). */
+    resetPlanStepWork: () => 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>;
+/**
+ * Recursively strip $schema and additionalProperties from a JSON Schema object.
+ * These are unnecessary for the LLM and waste context window tokens.
+ */
+export declare function stripSchemaOverhead(obj: unknown): unknown;
+/**
+ * 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;
+}
+export 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_skills/index.d.ts

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

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

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { defineServerSideTool } from "../index.js";
+export default defineServerSideTool({
+  name: "load_skills",
+  description: "Load detailed guidelines for one or more skills (up to 3 at once). Call this before writing or editing content that should follow specific rules or guidelines.",
+  inputSchema(ctx) {
+    return z.object({
+      names: z.array(
+        z.enum(
+          ctx.resolvedSkills.map((s) => s.name)
+        )
+      ).min(1).max(3).describe("The skills to load")
+    });
+  },
+  isAvailable(ctx) {
+    return ctx.resolvedSkills.length > 0;
+  },
+  handle(ctx, input) {
+    const loaded = [];
+    const autoLoaded = [];
+    const errors = [];
+    const extraBlocks = [];
+    for (const name of input.names) {
+      const skill = ctx.resolvedSkills.find((s) => s.name === name);
+      if (!skill) {
+        errors.push(name);
+        continue;
+      }
+      ctx.loadedSkills.add(skill.name);
+      loaded.push(skill.name);
+      for (const toolName of skill.tools) {
+        if (ctx.lazyToolNames.includes(toolName) && !ctx.activatedLazyTools.has(toolName)) {
+          ctx.activatedLazyTools.add(toolName);
+          autoLoaded.push(toolName);
+        }
+      }
+      ctx.send({
+        type: "server_tool_result",
+        tool: "load_skills",
+        label: skill.label
+      });
+      extraBlocks.push({
+        type: "skill",
+        name: skill.name,
+        text: `# Skill: ${skill.name}
+
+${skill.content}`
+      });
+    }
+    if (loaded.length > 0) {
+      ctx.markPlanStepWork();
+      return {
+        toolResults: [
+          {
+            type: "tool_result",
+            tool_use_id: ctx.toolUseId,
+            content: JSON.stringify({
+              loaded,
+              ...autoLoaded.length ? { tools_loaded: autoLoaded } : {},
+              ...errors.length ? { not_found: errors } : {}
+            })
+          }
+        ],
+        extraBlocks
+      };
+    }
+    return {
+      toolResults: [
+        {
+          type: "tool_result",
+          tool_use_id: ctx.toolUseId,
+          content: JSON.stringify({
+            error: `Skills not found: ${errors.join(", ")}`
+          }),
+          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,44 @@
+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.lazyToolNames.includes(name)) {
+        ctx.activatedLazyTools.add(name);
+        loaded.push(name);
+      }
+    }
+    if (loaded.length) {
+      ctx.markPlanStepWork();
+      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,59 @@
+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;
+};
+export type StreamTemplateName = 'fix_readability' | 'translate' | 'rewrite' | 'generate_content';
+/**
+ * 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;
+    /** Tool names that should be auto-loaded when this skill is activated. */
+    tools?: string[];
+    /**
+     * Stream templates for which this skill's content (from getContents)
+     * should be injected into the sub-agent's system prompt.
+     *
+     * Use this for project-specific writing guidelines, terminology,
+     * tone-of-voice rules, or language constraints that the sub-agent should
+     * follow when rewriting text.
+     */
+    streamTemplates?: StreamTemplateName[];
+};
+/**
+ * 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;
+    /** Tool names to auto-load when this skill is activated. */
+    tools: string[];
+};

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

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/modules/agent/runtime/server/stream.js

@@ -0,0 +1,190 @@
+import {
+  createError,
+  defineEventHandler,
+  readBody,
+  useRuntimeConfig
+} from "#imports";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { provider, models, skills } from "#blokkli-build/agent-server";
+import { FieldStreamParser } from "./streamParser.js";
+import { resolveTemplate } from "./templates/index.js";
+const TOKEN_EXPIRY_SECONDS = 300;
+const config = useRuntimeConfig();
+const authSecret = config.blokkli?.agent?.authSecret || "";
+const apiKey = config.blokkli?.agent?.apiKey || "";
+function validateToken(token, authSecret2) {
+  const colonIndex = token.indexOf(":");
+  if (colonIndex === -1) return false;
+  const timestampStr = token.substring(0, colonIndex);
+  const providedHmac = token.substring(colonIndex + 1);
+  const timestamp = parseInt(timestampStr, 10);
+  if (isNaN(timestamp)) return false;
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - timestamp) > TOKEN_EXPIRY_SECONDS) return false;
+  const expectedHmac = createHmac("sha256", authSecret2).update(timestampStr).digest("hex");
+  if (providedHmac.length !== expectedHmac.length) return false;
+  return timingSafeEqual(
+    Buffer.from(providedHmac, "hex"),
+    Buffer.from(expectedHmac, "hex")
+  );
+}
+function writeSSE(res, event, data) {
+  res.write(`event: ${event}
+data: ${JSON.stringify(data)}
+
+`);
+}
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event);
+  const { authToken, template, templateParams, model, fields, pageContext } = body;
+  if (!authToken || !template || !fields?.length) {
+    throw createError({
+      statusCode: 400,
+      message: "Missing required fields: authToken, template, fields"
+    });
+  }
+  if (!authSecret || !validateToken(authToken, authSecret)) {
+    throw createError({
+      statusCode: 401,
+      message: "Unauthorized"
+    });
+  }
+  if (!apiKey) {
+    throw createError({
+      statusCode: 500,
+      message: "API key not configured"
+    });
+  }
+  const resolvedModel = model || models[0]?.name;
+  if (!resolvedModel) {
+    throw createError({
+      statusCode: 500,
+      message: "No model configured"
+    });
+  }
+  const res = event.node.res;
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive"
+  });
+  const abortController = new AbortController();
+  event.node.req.on("close", () => {
+    abortController.abort();
+  });
+  const parser = new FieldStreamParser();
+  let skillContext;
+  if (pageContext) {
+    const skillContextParts = [];
+    for (const skill of skills) {
+      if (skill.streamTemplates?.includes(template)) {
+        const content = skill.getContents(pageContext);
+        if (content) {
+          skillContextParts.push(content);
+        }
+      }
+    }
+    if (skillContextParts.length > 0) {
+      skillContext = skillContextParts.join("\n\n");
+    }
+  }
+  const templateCall = {
+    template,
+    templateParams: templateParams || {}
+  };
+  const { systemPrompt, userMessage } = resolveTemplate(
+    templateCall,
+    fields,
+    skillContext
+  );
+  try {
+    const stream = provider.createStream(
+      { apiKey, model: resolvedModel },
+      {
+        systemPrompt: [{ text: systemPrompt }],
+        messages: [{ role: "user", content: userMessage }],
+        tools: [],
+        maxTokens: 16384,
+        signal: abortController.signal
+      }
+    );
+    const emitParserEvents = (parserEvents) => {
+      for (const pe of parserEvents) {
+        const field = fields[pe.index];
+        if (!field) continue;
+        switch (pe.type) {
+          case "field_start":
+            writeSSE(res, "field_start", {
+              uuid: field.uuid,
+              fieldName: field.fieldName,
+              mode: pe.mode
+            });
+            break;
+          case "full_delta":
+            writeSSE(res, "field_delta", {
+              uuid: field.uuid,
+              fieldName: field.fieldName,
+              value: pe.value
+            });
+            break;
+          case "replace_delta":
+            writeSSE(res, "replace_delta", {
+              uuid: field.uuid,
+              fieldName: field.fieldName,
+              search: pe.search,
+              value: pe.value
+            });
+            break;
+          case "operation_end":
+            writeSSE(res, "operation_end", {
+              uuid: field.uuid,
+              fieldName: field.fieldName,
+              search: pe.search,
+              replace: pe.replace
+            });
+            break;
+          case "field_end":
+            writeSSE(res, "field_end", {
+              uuid: field.uuid,
+              fieldName: field.fieldName
+            });
+            break;
+        }
+      }
+    };
+    let usage;
+    for await (const streamEvent of stream) {
+      if (abortController.signal.aborted) break;
+      if (streamEvent.type === "text_delta") {
+        emitParserEvents(parser.feed(streamEvent.text));
+      }
+      if (streamEvent.type === "message_end") {
+        if (streamEvent.inputTokens !== void 0 && streamEvent.outputTokens !== void 0) {
+          const defaultModel = models.find((m) => m.isDefault) || models[0];
+          usage = {
+            inputTokens: streamEvent.inputTokens,
+            outputTokens: streamEvent.outputTokens,
+            cacheCreationInputTokens: streamEvent.cacheCreationInputTokens ?? 0,
+            cacheReadInputTokens: streamEvent.cacheReadInputTokens ?? 0,
+            pricing: defaultModel?.pricing ?? null
+          };
+        }
+      }
+      if (streamEvent.type === "error") {
+        writeSSE(res, "error", {
+          message: streamEvent.error.message
+        });
+        break;
+      }
+    }
+    emitParserEvents(parser.flush());
+    writeSSE(res, "done", { usage });
+  } catch (error) {
+    if (!abortController.signal.aborted) {
+      writeSSE(res, "error", {
+        message: error instanceof Error ? error.message : "Unknown error"
+      });
+    }
+  }
+  res.end();
+});