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

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

@@ -0,0 +1,49 @@
+import type { PageContext, EditMode } from '../../shared/types.js';
+import type { ResolvedSkill } from '../skills/types.js';
+export type ActivePlanContext = {
+    title: string;
+    totalSteps: number;
+    completedSteps: number;
+    currentStep: {
+        label: string;
+        description: string;
+    };
+    remainingSteps: string[];
+};
+export type SystemPromptContext = {
+    pageContext: PageContext;
+    resolvedSkills: ResolvedSkill[];
+    lazyTools: {
+        name: string;
+        description: string;
+    }[];
+    isDebugMode: boolean;
+    activePlan?: ActivePlanContext;
+    loadedSkills: ReadonlySet<string>;
+};
+export type SystemPromptDefinition = {
+    id: string;
+    title: string;
+    weight: number;
+    modes?: EditMode[];
+    /**
+     * Cache group for prompt caching optimization.
+     * - 'static': Content never changes (cached indefinitely within TTL).
+     * - 'per-page': Content is stable across turns within a conversation (cached per page context).
+     * - Omit for per-turn content that changes every turn (e.g. plan progress).
+     *
+     * Prompts are sorted by cache group (static → per-page → per-turn), then by weight.
+     * This ensures stable prefixes for both Anthropic (explicit breakpoints) and OpenAI (automatic prefix caching).
+     */
+    cacheGroup?: 'static' | 'per-page';
+    getPrompt: (context: Readonly<SystemPromptContext>) => string | null;
+};
+/**
+ * A single block in the structured system prompt.
+ * Providers use cacheHint to apply provider-specific caching strategies.
+ */
+export type SystemPromptBlock = {
+    text: string;
+    /** When set, signals that everything up to and including this block can be cached. */
+    cacheHint?: 'ephemeral';
+};

package/dist/modules/agent/runtime/shared/placeholders.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Replaced with the name of the current user.
+ */
+export declare const PLACEHOLDER_USER_NAME = "@BKUSERNAME";

package/dist/modules/agent/runtime/shared/placeholders.js

@@ -0,0 +1 @@
+export const PLACEHOLDER_USER_NAME = "@BKUSERNAME";

package/dist/modules/agent/runtime/shared/types.d.ts

@@ -0,0 +1,426 @@
+import { z } from 'zod';
+/**
+ * Defines an AI model with optional pricing for cost calculation.
+ */
+export type AgentModelDefinition = {
+    /** Model identifier passed to the AI provider (e.g. 'claude-haiku-4-5'). */
+    name: string;
+    /** Human-readable label shown in the UI. */
+    label: string;
+    /** Whether this is the default model. The first model is used if none is marked. */
+    isDefault?: boolean;
+    /** Per-million-token pricing. When set, cost is computed and shown in the UI. */
+    pricing?: {
+        input: number;
+        cacheWrite: number;
+        cacheRead: number;
+        output: number;
+    };
+};
+/**
+ * Text content block in a message.
+ */
+export type GenericTextBlock = {
+    type: 'text';
+    text: string;
+};
+/**
+ * Skill content block - loaded skill guidelines injected into the conversation.
+ * Providers serialize this as a text block for the API.
+ */
+export type GenericSkillBlock = {
+    type: 'skill';
+    name: string;
+    text: string;
+};
+/**
+ * Tool use content block - assistant requesting tool execution.
+ */
+export type GenericToolUseBlock = {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+};
+/**
+ * Tool result content block - result of tool execution.
+ */
+export type GenericToolResultBlock = {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+/**
+ * Content block in a message.
+ */
+export type GenericContentBlock = GenericTextBlock | GenericSkillBlock | GenericToolUseBlock | GenericToolResultBlock;
+/**
+ * Generic message format used internally.
+ * Provider implementations convert to/from this format.
+ */
+export type GenericMessage = {
+    role: 'user' | 'assistant';
+    content: string | GenericContentBlock[];
+};
+/**
+ * Snapshot of conversation state for persistence.
+ * Sent from server to client after each completed turn.
+ * The hash prevents client-side tampering.
+ */
+export type ConversationStateSnapshot = {
+    messages: GenericMessage[];
+    activatedLazyTools: string[];
+    hash: string;
+};
+/**
+ * Content field metadata for a block bundle.
+ * Unifies editable text fields and droppable reference/link fields.
+ */
+export type BlockBundleContentField = {
+    name: string;
+    label: string;
+    type: 'plain' | 'markup';
+} | {
+    name: string;
+    label: string;
+    type: 'reference' | 'link';
+    allowed: {
+        type: string;
+        bundles: string[];
+    }[];
+};
+/**
+ * Block field (nested blocks) metadata for a block bundle.
+ */
+export type BlockBundleBlockField = {
+    name: string;
+    label: string;
+    allowedBundles: string[];
+    cardinality: number;
+};
+/**
+ * Block bundle definition with field metadata.
+ */
+export type BlockBundle = {
+    id: string;
+    label: string;
+    description?: string;
+    contentFields: BlockBundleContentField[];
+    paragraphFields: BlockBundleBlockField[];
+};
+/**
+ * Edit mode determines what actions the user is allowed to perform.
+ */
+export type EditMode = 'readonly' | 'editing' | 'translating' | 'review';
+/**
+ * Fragment definition for reusable content blocks.
+ */
+export type Fragment = {
+    name: string;
+    label: string;
+    description?: string;
+};
+/**
+ * Page context sent from client to server on init.
+ * Provides the AI agent with knowledge of the page and available block types.
+ */
+export type PageContext = {
+    /** The page title */
+    title: string;
+    /** The page entity type (use this as parent.type when adding root-level blocks) */
+    entityType: string;
+    /** The page entity UUID (use this as parent.uuid when adding root-level blocks) */
+    entityUuid: string;
+    /** The page bundle machine name (e.g., "page", "article") */
+    entityBundle: string;
+    /** The page bundle label (e.g., "Article", "Landing Page") */
+    bundleLabel: string;
+    /** The item entity type for blocks */
+    itemEntityType: string;
+    /** Available block bundles */
+    bundles: BlockBundle[];
+    /** The UI/interface language code (e.g., "en", "de") */
+    interfaceLanguage: string;
+    /** The content/entity language code (e.g., "en", "de") */
+    entityLanguage: string;
+    /** Whether the entity is published or null if entity is not publishable */
+    isPublished: boolean | null;
+    /** The current edit mode - determines what actions are available */
+    editMode: EditMode;
+    /** Available fragments (reusable content blocks) */
+    fragments: Fragment[];
+    /** Content fields on the page entity itself (e.g., lead text, hero image) */
+    entityContentFields: BlockBundleContentField[];
+};
+/**
+ * Classified error categories for AI provider errors.
+ * Both Anthropic and OpenAI SDKs map to these via HTTP status codes.
+ */
+export declare const agentErrorTypeSchema: z.ZodEnum<{
+    authentication: "authentication";
+    rate_limit: "rate_limit";
+    overloaded: "overloaded";
+    not_found: "not_found";
+    bad_request: "bad_request";
+    connection: "connection";
+    unauthorized: "unauthorized";
+    unknown: "unknown";
+}>;
+export type AgentErrorType = z.infer<typeof agentErrorTypeSchema>;
+/**
+ * A single step in a plan as seen by the client (no description — that stays server-side).
+ */
+export type ClientPlanStep = {
+    label: string;
+    status: 'pending' | 'in_progress' | 'completed';
+};
+/**
+ * Plan state sent to the client. Contains only labels and statuses,
+ * not the detailed descriptions that the LLM uses internally.
+ */
+export type ClientPlanState = {
+    title: string;
+    steps: ClientPlanStep[];
+};
+/**
+ * Token pricing rates per million tokens, captured at the time of the turn.
+ */
+export type UsagePricing = {
+    input: number;
+    cacheWrite: number;
+    cacheRead: number;
+    output: number;
+};
+/**
+ * A single usage turn as sent by the server and stored by the client.
+ * Contains raw token counts and the pricing that was active at the time,
+ * so cost can be computed correctly even after pricing changes.
+ */
+export type UsageTurn = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    pricing: UsagePricing | null;
+};
+/**
+ * Tool definition sent from client to server on init.
+ */
+export type ClientToolDefinition = {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    lazy?: boolean;
+    category?: 'query' | 'mutation';
+    volatile?: boolean;
+};
+export type PageStructureBlock = {
+    uuid: string;
+    bundle: string;
+    contentFields?: Record<string, string>;
+    fields?: Record<string, PageStructureBlock[]>;
+};
+export declare const pageStructureSchema: z.ZodObject<{
+    totalParagraphs: z.ZodNumber;
+    fields: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodType<PageStructureBlock, unknown, z.core.$ZodTypeInternals<PageStructureBlock, unknown>>>>;
+    entityContentFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type PageStructure = z.infer<typeof pageStructureSchema>;
+export declare const clientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"authenticate">;
+    authToken: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"init">;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        lazy: z.ZodOptional<z.ZodBoolean>;
+        category: z.ZodOptional<z.ZodEnum<{
+            query: "query";
+            mutation: "mutation";
+        }>>;
+        volatile: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    pageContext: z.ZodObject<{
+        title: z.ZodString;
+        entityType: z.ZodString;
+        entityUuid: z.ZodString;
+        entityBundle: z.ZodString;
+        bundleLabel: z.ZodString;
+        itemEntityType: z.ZodString;
+        bundles: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            contentFields: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                name: z.ZodString;
+                label: z.ZodString;
+                type: z.ZodEnum<{
+                    plain: "plain";
+                    markup: "markup";
+                }>;
+            }, z.core.$strip>, z.ZodObject<{
+                name: z.ZodString;
+                label: z.ZodString;
+                type: z.ZodEnum<{
+                    reference: "reference";
+                    link: "link";
+                }>;
+                allowed: z.ZodArray<z.ZodObject<{
+                    type: z.ZodString;
+                    bundles: z.ZodArray<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>;
+            paragraphFields: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                label: z.ZodString;
+                allowedBundles: z.ZodArray<z.ZodString>;
+                cardinality: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        interfaceLanguage: z.ZodString;
+        entityLanguage: z.ZodString;
+        isPublished: z.ZodNullable<z.ZodBoolean>;
+        editMode: z.ZodEnum<{
+            readonly: "readonly";
+            editing: "editing";
+            translating: "translating";
+            review: "review";
+        }>;
+        fragments: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        entityContentFields: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodEnum<{
+                plain: "plain";
+                markup: "markup";
+            }>;
+        }, z.core.$strip>, z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodEnum<{
+                reference: "reference";
+                link: "link";
+            }>;
+            allowed: z.ZodArray<z.ZodObject<{
+                type: z.ZodString;
+                bundles: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"start">;
+    prompt: z.ZodString;
+    selectedUuids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_result">;
+    callId: z.ZodString;
+    result: z.ZodUnknown;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cancel">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"accept">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"reject">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"get_transcript">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"new_conversation">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"restore_conversation">;
+    state: z.ZodObject<{
+        messages: z.ZodArray<z.ZodObject<{
+            role: z.ZodEnum<{
+                user: "user";
+                assistant: "assistant";
+            }>;
+            content: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"skill">;
+                name: z.ZodString;
+                text: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"tool_use">;
+                id: z.ZodString;
+                name: z.ZodString;
+                input: z.ZodUnknown;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"tool_result">;
+                tool_use_id: z.ZodString;
+                content: z.ZodString;
+                is_error: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>], "type">>]>;
+        }, z.core.$strip>>;
+        activatedLazyTools: z.ZodArray<z.ZodString>;
+        hash: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plan_approve">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plan_reject">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+}, z.core.$strip>], "type">;
+/**
+ * Messages sent from client to server over WebSocket.
+ */
+export type ClientMessage = z.infer<typeof clientMessageSchema>;
+/**
+ * Messages sent from server to client over WebSocket.
+ */
+export type ServerMessage = {
+    type: 'authenticated';
+} | {
+    type: 'tool_call';
+    callId: string;
+    tool: string;
+    params: Record<string, unknown>;
+} | {
+    type: 'thinking';
+    content?: string;
+} | {
+    type: 'text';
+    content: string;
+} | {
+    type: 'text_delta';
+    content: string;
+} | {
+    type: 'done';
+    message?: string;
+} | {
+    type: 'error';
+    errorType: AgentErrorType;
+    message: string;
+    detail?: string;
+    retryable?: boolean;
+} | {
+    type: 'transcript';
+    content: string;
+} | {
+    type: 'server_tool_result';
+    tool: 'load_skill' | 'load_tools' | 'create_plan' | 'complete_plan_step';
+    label: string;
+} | {
+    type: 'plan_update';
+    plan: ClientPlanState | null;
+} | {
+    type: 'conversation_state';
+    state: ConversationStateSnapshot;
+} | {
+    type: 'usage';
+    usage: UsageTurn;
+} | {
+    type: 'conversation_restored';
+} | {
+    type: 'conversation_restore_failed';
+    reason: string;
+};

package/dist/modules/agent/runtime/shared/types.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+export const agentErrorTypeSchema = z.enum([
+  "authentication",
+  // 401 — bad API key
+  "rate_limit",
+  // 429 — too many requests
+  "overloaded",
+  // 529 (Anthropic) / 503 — service overloaded
+  "not_found",
+  // 404 — invalid model or endpoint
+  "bad_request",
+  // 400 — malformed request
+  "connection",
+  // Network/connection failure
+  "unauthorized",
+  // WebSocket auth token invalid or missing
+  "unknown"
+  // Anything else
+]);
+const blockBundleContentFieldSchema = z.union([
+  z.object({
+    name: z.string(),
+    label: z.string(),
+    type: z.enum(["plain", "markup"])
+  }),
+  z.object({
+    name: z.string(),
+    label: z.string(),
+    type: z.enum(["reference", "link"]),
+    allowed: z.array(
+      z.object({
+        type: z.string(),
+        bundles: z.array(z.string())
+      })
+    )
+  })
+]);
+const blockBundleBlockFieldSchema = z.object({
+  name: z.string(),
+  label: z.string(),
+  allowedBundles: z.array(z.string()),
+  cardinality: z.number()
+});
+const blockBundleSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  contentFields: z.array(blockBundleContentFieldSchema),
+  paragraphFields: z.array(blockBundleBlockFieldSchema)
+});
+const fragmentSchema = z.object({
+  name: z.string(),
+  label: z.string(),
+  description: z.string().optional()
+});
+const pageContextSchema = z.object({
+  title: z.string(),
+  entityType: z.string(),
+  entityUuid: z.string(),
+  entityBundle: z.string(),
+  bundleLabel: z.string(),
+  itemEntityType: z.string(),
+  bundles: z.array(blockBundleSchema),
+  interfaceLanguage: z.string(),
+  entityLanguage: z.string(),
+  isPublished: z.boolean().nullable(),
+  editMode: z.enum(["readonly", "editing", "translating", "review"]),
+  fragments: z.array(fragmentSchema),
+  entityContentFields: z.array(blockBundleContentFieldSchema)
+});
+const pageStructureBlockSchema = z.lazy(
+  () => z.object({
+    uuid: z.string(),
+    bundle: z.string(),
+    contentFields: z.record(z.string(), z.string()).optional(),
+    fields: z.record(z.string(), z.array(pageStructureBlockSchema)).optional()
+  })
+);
+export const pageStructureSchema = z.object({
+  totalParagraphs: z.number(),
+  fields: z.record(z.string(), z.array(pageStructureBlockSchema)),
+  entityContentFields: z.record(z.string(), z.string()).optional()
+});
+const clientToolDefinitionSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  input_schema: z.record(z.string(), z.unknown()),
+  lazy: z.boolean().optional(),
+  category: z.enum(["query", "mutation"]).optional(),
+  volatile: z.boolean().optional()
+});
+const genericContentBlockSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), text: z.string() }),
+  z.object({ type: z.literal("skill"), name: z.string(), text: z.string() }),
+  z.object({
+    type: z.literal("tool_use"),
+    id: z.string(),
+    name: z.string(),
+    input: z.unknown()
+  }),
+  z.object({
+    type: z.literal("tool_result"),
+    tool_use_id: z.string(),
+    content: z.string(),
+    is_error: z.boolean().optional()
+  })
+]);
+const genericMessageSchema = z.object({
+  role: z.enum(["user", "assistant"]),
+  content: z.union([z.string(), z.array(genericContentBlockSchema)])
+});
+const conversationStateSnapshotSchema = z.object({
+  messages: z.array(genericMessageSchema),
+  activatedLazyTools: z.array(z.string()),
+  hash: z.string()
+});
+export const clientMessageSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("authenticate"), authToken: z.string() }),
+  z.object({
+    type: z.literal("init"),
+    tools: z.array(clientToolDefinitionSchema),
+    pageContext: pageContextSchema
+  }),
+  z.object({
+    type: z.literal("start"),
+    prompt: z.string(),
+    selectedUuids: z.array(z.string()).optional()
+  }),
+  z.object({
+    type: z.literal("tool_result"),
+    callId: z.string(),
+    result: z.unknown(),
+    error: z.string().optional()
+  }),
+  z.object({ type: z.literal("cancel") }),
+  z.object({ type: z.literal("accept") }),
+  z.object({ type: z.literal("reject") }),
+  z.object({ type: z.literal("get_transcript") }),
+  z.object({ type: z.literal("new_conversation") }),
+  z.object({
+    type: z.literal("restore_conversation"),
+    state: conversationStateSnapshotSchema
+  }),
+  z.object({ type: z.literal("plan_approve") }),
+  z.object({ type: z.literal("plan_reject") }),
+  z.object({ type: z.literal("ping") })
+]);

package/dist/modules/drupal/graphql/base/query.pbConfig.graphql

@@ -1,4 +1,26 @@
+fragment paragraphsBlokkliUserPermissions on ParagraphsBlokkliUser {
+  use_blokkli: hasPermission(permission: "view paragraphs blokkli edit state")
+  take_ownership: hasPermission(
+    permission: "take ownership of paragraphs blokkli edit state"
+  )
+  create_library_item: hasPermission(
+    permission: "create paragraph library item"
+  )
+
+  edit_library_item: hasPermission(permission: "edit paragraph library item")
+
+  manage_default_templates: hasPermission(
+    permission: "manage default paragraph templates"
+  )
+
+  create_comments: hasPermission(permission: "post comments")
+  view_comments: hasPermission(permission: "access comments")
+  use_agent: hasPermission(permission: "use paragraphs blokkli agent")
+}
 query pbConfig($entityType: String!, $entityBundle: String!) {
+  userPermissions: paragraphsBlokkliGetUser {
+    ...paragraphsBlokkliUserPermissions
+  }
   clipboards: pbGetSupportedClipboards {
     ...paragraphsBlokkliSupportedClipboard
   }
@@ -38,14 +60,17 @@ query pbConfig($entityType: String!, $entityBundle: String!) {
     entityType: $entityType
     entityBundle: $entityBundle
   ) {
+    type: fieldType
     name
     label
     entityType
     entityBundle
     cardinality
     canEdit
-    allowedEntityType
-    allowedBundles
+    allowed {
+      type: entityType
+      bundles
+    }
     required
   }