@skaile/forge-editor 6.3.0 → 6.4.0

package/dist/server/chat-agent.d.ts

@@ -0,0 +1,85 @@
+import { AgentOp } from "../core/agent-op-types.js";
+import { AGENT_TOOL, AgentOpProblem } from "../features/ai/protocol/agent-ops.js";
+import { ChatBlockModel, ChatToolCall, DocumentChatMessage } from "../features/ai/protocol/chat.js";
+import "../features/ai/protocol/index.js";
+import { ToolContext, ToolRegistry } from "./tools.js";
+import { JSONSchema7 } from "ai";
+//#region src/server/chat-agent.d.ts
+/** The `edit_document` tool as an agent offers it to its model: name, description and JSON schema of the input. */
+export interface ChatAgentEditTool {
+  name: typeof AGENT_TOOL;
+  description: string;
+  inputSchema: JSONSchema7;
+}
+/** What `ChatAgentTurn.checkEdit` answers for one `edit_document` call. */
+export interface ChatAgentEdit {
+  /** The valid operations, numbered on from the request's `nextOp` across the calls of the turn. */
+  ops: AgentOp[];
+  /** The operations dropped from this call, with the reason. */
+  problems: AgentOpProblem[];
+  /** The tool result for the model: which operations are shown for review and, with problems, what to correct and send again. */
+  feedback: string;
+}
+/** One chat turn as the agent receives it: everything the built-in loop would give its model, prepared by the server. */
+export interface ChatAgentTurn {
+  /** The user `ports.identity` authenticated for the request. */
+  user: object;
+  /** The Document open in the chat (`documentId` of the request); absent for a chat without a Document. */
+  documentId?: string;
+  /** The conversation as the client sent it; the last message is the user's new message. */
+  messages: readonly DocumentChatMessage[];
+  /** The open Document as block lines (`[id] markdown`), the snapshot the client sent. */
+  document: string;
+  /** Block IDs edits are limited to (the selection, as far as the document has them); null: the whole document. */
+  scope: readonly string[] | null;
+  /** Block types, host blocks, `convert` targets and preferred structure, as the system prompt describes them. */
+  blockModel: ChatBlockModel;
+  /** The read-only tools of the chat (`EditorServerOptions.tools`); run a call with `tools.providers.get(name)!.handle(toolContext, input)`. */
+  tools: ToolRegistry;
+  /** The context the tools run with (ports, user, the request's abort signal, live content, open Document). */
+  toolContext: ToolContext;
+  /** The system prompt of the built-in loop (`documentChatSystem(blockModel, tools.infos)`): citations, editing through `edit_document`, the block model. */
+  system: string;
+  /** The `edit_document` tool to offer the model; with the host's change sets its operations may name other Documents. */
+  editTool: ChatAgentEditTool;
+  /**
+   * Checks the input of one `edit_document` call like the built-in loop does (`checkAgentOps`), together with the operations
+   * the turn's earlier calls accepted (the per-turn limit, a block edited twice, an operation inside a replaced block); an
+   * operation naming another Document is checked against it when the host keeps change sets. Hand `feedback` back to the
+   * model as the tool result (with problems it asks for corrected versions of only the dropped operations), and yield
+   * `{ type: 'edit', ops, dropped: problems }` so the client shows the operations for review.
+   */
+  checkEdit(input: unknown): Promise<ChatAgentEdit>;
+  /** Aborts when the client cancels the chat. */
+  signal: AbortSignal;
+}
+/** What an agent streams for one turn: answer text (deltas), a read-only tool call it ran, operations `checkEdit` accepted. */
+export type ChatAgentPart = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'tool';
+  call: ChatToolCall;
+} | {
+  type: 'edit';
+  ops: AgentOp[];
+  dropped: AgentOpProblem[];
+};
+/** A host-provided agent that answers document chat turns in place of the built-in model loop. A thrown error ends the turn as the stream's `error` event. */
+export interface ChatAgent {
+  turn(input: ChatAgentTurn): AsyncIterable<ChatAgentPart>;
+}
+/**
+ * JSON schema of the `edit_document` input: the list `ops`. Deliberately loose (only `type` is required), so a malformed
+ * call reaches `checkAgentOps` and gets a precise retry message. With `workspace` (the host keeps change sets and a mutator)
+ * an operation may name another Document by `documentId`.
+ */
+export declare function documentEditInputSchema({ workspace }?: {
+  workspace?: boolean;
+}): JSONSchema7;
+/** The `edit_document` tool of the document chat (name, description, `documentEditInputSchema`), as the built-in loop and `ChatAgentTurn.editTool` offer it. */
+export declare function documentEditTool({ workspace }?: {
+  workspace?: boolean;
+}): ChatAgentEditTool;
+//#endregion
+//# sourceMappingURL=chat-agent.d.ts.map

package/dist/server/chat-agent.js

@@ -0,0 +1,61 @@
+import { AGENT_OP_TYPES } from "../core/agent-op-types.js";
+import { AGENT_TOOL } from "../features/ai/protocol/agent-ops.js";
+//#region src/server/chat-agent.ts
+/**
+* JSON schema of the `edit_document` input: the list `ops`. Deliberately loose (only `type` is required), so a malformed
+* call reaches `checkAgentOps` and gets a precise retry message. With `workspace` (the host keeps change sets and a mutator)
+* an operation may name another Document by `documentId`.
+*/
+function documentEditInputSchema({ workspace = false } = {}) {
+	return {
+		type: "object",
+		properties: { ops: {
+			type: "array",
+			description: "Die Operationen in Dokumentreihenfolge.",
+			items: {
+				type: "object",
+				properties: {
+					type: {
+						type: "string",
+						enum: [...AGENT_OP_TYPES],
+						description: "update: Blockinhalt ersetzen; delete: Block löschen; add: Blöcke einfügen; convert: Blocktyp ändern."
+					},
+					...workspace && { documentId: {
+						type: "string",
+						description: "Nur für Blöcke eines anderen Dokuments: dessen ID (zusammen mit den Block-IDs aus find_blocks oder read_block). Es muss ein Dokument sein, das die Nutzerin bzw. der Nutzer bearbeiten darf. Ohne Angabe gilt das geöffnete Dokument."
+					} },
+					id: {
+						type: "string",
+						description: "update/delete/convert: ID des Blocks aus dem Dokument."
+					},
+					afterId: {
+						type: ["string", "null"],
+						description: "add (Pflicht): ID des Blocks, nach dem eingefügt wird; für den Dokumentanfang ausdrücklich null."
+					},
+					markdown: {
+						type: "string",
+						description: "update/add: der neue Inhalt als Markdown, ohne Block-ID."
+					},
+					to: {
+						type: "string",
+						description: "convert: der neue Blocktyp, einer der im Systemprompt erlaubten Werte (z. B. paragraph, heading2, composite:task)."
+					}
+				},
+				required: ["type"]
+			}
+		} },
+		required: ["ops"]
+	};
+}
+/** The `edit_document` tool of the document chat (name, description, `documentEditInputSchema`), as the built-in loop and `ChatAgentTurn.editTool` offer it. */
+function documentEditTool({ workspace = false } = {}) {
+	return {
+		name: AGENT_TOOL,
+		description: workspace ? "Schlägt Änderungen vor. Operationen am geöffneten Dokument zeigt die Nutzerin bzw. der Nutzer im Dokument zur Prüfung an; Operationen mit documentId (anderes Dokument des Arbeitsbereichs) landen in einem Änderungssatz, den die Nutzerin bzw. der Nutzer je Dokument prüft und übernimmt oder ablehnt." : "Schlägt Änderungen am Dokument vor. Jede Operation wird der Nutzerin bzw. dem Nutzer im Dokument zur Prüfung angezeigt.",
+		inputSchema: documentEditInputSchema({ workspace })
+	};
+}
+//#endregion
+export { documentEditInputSchema, documentEditTool };
+
+//# sourceMappingURL=chat-agent.js.map

package/dist/server/chat-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-agent.js","names":[],"sources":["../../src/server/chat-agent.ts"],"sourcesContent":["// i18n-ignore-file: model-facing tool description and input schema (German, like the chat's system prompt)\nimport type { JSONSchema7 } from 'ai'\nimport { AGENT_OP_TYPES, AGENT_TOOL, type AgentOp, type AgentOpProblem, type ChatBlockModel, type ChatToolCall, type DocumentChatMessage } from '../features/ai/protocol'\nimport type { ToolContext, ToolRegistry } from './tools'\n\n// The document chat with a host-provided agent instead of the built-in model loop (`EditorServerOptions.chatAgent`).\n// `POST /api/ai/chat` keeps everything around the loop: it parses and checks the request, builds the document snapshot,\n// checks the proposed operations and streams the same SSE events to the client. The agent only answers the turn: text,\n// the read-only tool calls it ran, and the operations it proposed through `checkEdit`.\n\n/** The `edit_document` tool as an agent offers it to its model: name, description and JSON schema of the input. */\nexport interface ChatAgentEditTool {\n  name: typeof AGENT_TOOL\n  description: string\n  inputSchema: JSONSchema7\n}\n\n/** What `ChatAgentTurn.checkEdit` answers for one `edit_document` call. */\nexport interface ChatAgentEdit {\n  /** The valid operations, numbered on from the request's `nextOp` across the calls of the turn. */\n  ops: AgentOp[]\n  /** The operations dropped from this call, with the reason. */\n  problems: AgentOpProblem[]\n  /** The tool result for the model: which operations are shown for review and, with problems, what to correct and send again. */\n  feedback: string\n}\n\n/** One chat turn as the agent receives it: everything the built-in loop would give its model, prepared by the server. */\nexport interface ChatAgentTurn {\n  /** The user `ports.identity` authenticated for the request. */\n  user: object\n  /** The Document open in the chat (`documentId` of the request); absent for a chat without a Document. */\n  documentId?: string\n  /** The conversation as the client sent it; the last message is the user's new message. */\n  messages: readonly DocumentChatMessage[]\n  /** The open Document as block lines (`[id] markdown`), the snapshot the client sent. */\n  document: string\n  /** Block IDs edits are limited to (the selection, as far as the document has them); null: the whole document. */\n  scope: readonly string[] | null\n  /** Block types, host blocks, `convert` targets and preferred structure, as the system prompt describes them. */\n  blockModel: ChatBlockModel\n  /** The read-only tools of the chat (`EditorServerOptions.tools`); run a call with `tools.providers.get(name)!.handle(toolContext, input)`. */\n  tools: ToolRegistry\n  /** The context the tools run with (ports, user, the request's abort signal, live content, open Document). */\n  toolContext: ToolContext\n  /** The system prompt of the built-in loop (`documentChatSystem(blockModel, tools.infos)`): citations, editing through `edit_document`, the block model. */\n  system: string\n  /** The `edit_document` tool to offer the model; with the host's change sets its operations may name other Documents. */\n  editTool: ChatAgentEditTool\n  /**\n   * Checks the input of one `edit_document` call like the built-in loop does (`checkAgentOps`), together with the operations\n   * the turn's earlier calls accepted (the per-turn limit, a block edited twice, an operation inside a replaced block); an\n   * operation naming another Document is checked against it when the host keeps change sets. Hand `feedback` back to the\n   * model as the tool result (with problems it asks for corrected versions of only the dropped operations), and yield\n   * `{ type: 'edit', ops, dropped: problems }` so the client shows the operations for review.\n   */\n  checkEdit(input: unknown): Promise<ChatAgentEdit>\n  /** Aborts when the client cancels the chat. */\n  signal: AbortSignal\n}\n\n/** What an agent streams for one turn: answer text (deltas), a read-only tool call it ran, operations `checkEdit` accepted. */\nexport type ChatAgentPart =\n  | { type: 'text', text: string }\n  | { type: 'tool', call: ChatToolCall }\n  | { type: 'edit', ops: AgentOp[], dropped: AgentOpProblem[] }\n\n/** A host-provided agent that answers document chat turns in place of the built-in model loop. A thrown error ends the turn as the stream's `error` event. */\nexport interface ChatAgent {\n  turn(input: ChatAgentTurn): AsyncIterable<ChatAgentPart>\n}\n\n/**\n * JSON schema of the `edit_document` input: the list `ops`. Deliberately loose (only `type` is required), so a malformed\n * call reaches `checkAgentOps` and gets a precise retry message. With `workspace` (the host keeps change sets and a mutator)\n * an operation may name another Document by `documentId`.\n */\nexport function documentEditInputSchema({ workspace = false }: { workspace?: boolean } = {}): JSONSchema7 {\n  return {\n    type: 'object',\n    properties: {\n      ops: {\n        type: 'array',\n        description: 'Die Operationen in Dokumentreihenfolge.',\n        items: {\n          type: 'object',\n          properties: {\n            type: { type: 'string', enum: [...AGENT_OP_TYPES], description: 'update: Blockinhalt ersetzen; delete: Block löschen; add: Blöcke einfügen; convert: Blocktyp ändern.' },\n            ...(workspace && { documentId: { type: 'string', description: 'Nur für Blöcke eines anderen Dokuments: dessen ID (zusammen mit den Block-IDs aus find_blocks oder read_block). Es muss ein Dokument sein, das die Nutzerin bzw. der Nutzer bearbeiten darf. Ohne Angabe gilt das geöffnete Dokument.' } }),\n            id: { type: 'string', description: 'update/delete/convert: ID des Blocks aus dem Dokument.' },\n            afterId: { type: ['string', 'null'], description: 'add (Pflicht): ID des Blocks, nach dem eingefügt wird; für den Dokumentanfang ausdrücklich null.' },\n            markdown: { type: 'string', description: 'update/add: der neue Inhalt als Markdown, ohne Block-ID.' },\n            to: { type: 'string', description: 'convert: der neue Blocktyp, einer der im Systemprompt erlaubten Werte (z. B. paragraph, heading2, composite:task).' },\n          },\n          required: ['type'],\n        },\n      },\n    },\n    required: ['ops'],\n  }\n}\n\n/** The `edit_document` tool of the document chat (name, description, `documentEditInputSchema`), as the built-in loop and `ChatAgentTurn.editTool` offer it. */\nexport function documentEditTool({ workspace = false }: { workspace?: boolean } = {}): ChatAgentEditTool {\n  return {\n    name: AGENT_TOOL,\n    description: workspace\n      ? 'Schlägt Änderungen vor. Operationen am geöffneten Dokument zeigt die Nutzerin bzw. der Nutzer im Dokument zur Prüfung an; Operationen mit documentId (anderes Dokument des Arbeitsbereichs) landen in einem Änderungssatz, den die Nutzerin bzw. der Nutzer je Dokument prüft und übernimmt oder ablehnt.'\n      : 'Schlägt Änderungen am Dokument vor. Jede Operation wird der Nutzerin bzw. dem Nutzer im Dokument zur Prüfung angezeigt.',\n    inputSchema: documentEditInputSchema({ workspace }),\n  }\n}\n"],"mappings":";;;;;;;;AA6EA,SAAgB,wBAAwB,EAAE,YAAY,UAAmC,CAAC,GAAgB;CACxG,OAAO;EACL,MAAM;EACN,YAAY,EACV,KAAK;GACH,MAAM;GACN,aAAa;GACb,OAAO;IACL,MAAM;IACN,YAAY;KACV,MAAM;MAAE,MAAM;MAAU,MAAM,CAAC,GAAG,cAAc;MAAG,aAAa;KAAuG;KACvK,GAAI,aAAa,EAAE,YAAY;MAAE,MAAM;MAAU,aAAa;KAAwO,EAAE;KACxS,IAAI;MAAE,MAAM;MAAU,aAAa;KAAyD;KAC5F,SAAS;MAAE,MAAM,CAAC,UAAU,MAAM;MAAG,aAAa;KAAmG;KACrJ,UAAU;MAAE,MAAM;MAAU,aAAa;KAA2D;KACpG,IAAI;MAAE,MAAM;MAAU,aAAa;KAAqH;IAC1J;IACA,UAAU,CAAC,MAAM;GACnB;EACF,EACF;EACA,UAAU,CAAC,KAAK;CAClB;AACF;;AAGA,SAAgB,iBAAiB,EAAE,YAAY,UAAmC,CAAC,GAAsB;CACvG,OAAO;EACL,MAAM;EACN,aAAa,YACT,8SACA;EACJ,aAAa,wBAAwB,EAAE,UAAU,CAAC;CACpD;AACF"}

package/dist/server/document-tools.d.ts

@@ -0,0 +1,22 @@
+import { ToolProvider } from "./tools.js";
+import { WorkspaceToolsOptions } from "./workspace-tools.js";
+//#region src/server/document-tools.d.ts
+/** The Markdown serializer `read_blocks` writes with: the options of `createWorkspaceTools`. */
+export type DocumentToolsOptions = WorkspaceToolsOptions;
+/**
+ * The read-only document tools of the document chat, for `EditorServerOptions.tools` / `provideEditorServer({ tools })`, next
+ * to `createWorkspaceTools`:
+ *
+ * - `document_outline(documentId?)`: the tree of all Blocks of the open Document (or of another one the user may read): per
+ *   Block its ID, node type, heading level or Block type and title, the IDs of the Blocks directly inside it and the length of
+ *   its text;
+ * - `read_blocks(documentId?, blockIds)`: up to 50 Blocks of one Document as Markdown, each cut like `read_block`
+ *   (`READ_BLOCK_LIMIT`), all together at most eight times that.
+ *
+ * Both read the current content (live content of an open Document first, else `loadCurrentContent`) and need no index. An
+ * unreadable Document and an unknown Block answer the same sentence as `read_block`, so the tools never confirm that a
+ * Document or Block exists where the user may not look.
+ */
+export declare function createDocumentTools(options?: DocumentToolsOptions): ToolProvider[];
+//#endregion
+//# sourceMappingURL=document-tools.d.ts.map

package/dist/server/document-tools.js

@@ -0,0 +1,190 @@
+import { TYPED_BLOCK_TITLE, isTypedBlock, typeIdOf } from "../core/typed-block.js";
+import { loadCurrentContent } from "./stored-content.js";
+import { createBlockMarkdown } from "./block-index.js";
+import { mayReadDocument } from "./readable-documents.js";
+import { INLINE_NODES, findBlock } from "./document-blocks.js";
+import { READ_BLOCK_LIMIT, parsed, unreadableBlock } from "./workspace-tools.js";
+import { z } from "zod";
+import { jsonSchema, tool } from "ai";
+//#region src/server/document-tools.ts
+/** Block IDs `read_blocks` reads in one call. */
+const READ_BLOCKS_MAX = 50;
+/** Characters of all Blocks one `read_blocks` call returns; the Blocks after the one that reaches it are left out with a note. */
+const READ_BLOCKS_TOTAL_LIMIT = 8 * READ_BLOCK_LIMIT;
+const outlineInput = z.object({ documentId: z.string().min(1).max(200).optional() });
+const readBlocksInput = z.object({
+	documentId: z.string().min(1).max(200).optional(),
+	blockIds: z.array(z.string().min(1).max(100)).min(1).max(READ_BLOCKS_MAX)
+});
+const NO_DOCUMENT = "Im Chat ist kein Dokument geöffnet: gib documentId an.";
+/** The current content of `documentId` (live first, else stored), `null` when the user may not read it or it does not exist. */
+async function readableContent(ctx, documentId) {
+	if (!await mayReadDocument(ctx.ports, ctx.user, documentId)) return null;
+	return ctx.liveContent(documentId) ?? await loadCurrentContent(ctx.ports.documents, documentId);
+}
+const attrString = (node, key) => typeof node.attrs?.[key] === "string" ? node.attrs[key] : "";
+/** The plain text of an inline node or a textblock's inline content, chips as their label. */
+function inlineText(node) {
+	switch (node.type) {
+		case "text": return node.text ?? "";
+		case "hardBreak": return " ";
+		case "mention": return `@${attrString(node, "label") || attrString(node, "id")}`;
+		case "tag": return `#${attrString(node, "name")}`;
+		case "reference": return attrString(node, "label");
+		default: return (node.content ?? []).map(inlineText).join("");
+	}
+}
+/** The title of a Block as the Block index has it: a Typed block's title row, a heading's text, `''` for any other Block. */
+function titleOf(node) {
+	if (isTypedBlock(node)) return (node.content ?? []).filter((child) => child.type === TYPED_BLOCK_TITLE).map(inlineText).join("").trim();
+	return node.type === "heading" ? inlineText(node).trim() : "";
+}
+/**
+* Every Block of `content` (every non-inline node with an `id`, the rule of `blockLinesOfContent`), in document order, a Block
+* before the Blocks nested in it. A Block's `children` are the Blocks directly inside it, through nodes without an ID (a list
+* without one, say).
+*/
+function outlineOf(content) {
+	const entries = [];
+	const walk = (node) => {
+		let chars = 0;
+		const blocks = [];
+		for (const child of node.content ?? []) {
+			if (child.type !== void 0 && INLINE_NODES.has(child.type)) {
+				chars += inlineText(child).length;
+				continue;
+			}
+			const id = child.attrs?.id;
+			if (typeof id !== "string" || !id) {
+				const inner = walk(child);
+				chars += inner.chars;
+				blocks.push(...inner.blocks);
+				continue;
+			}
+			const entry = {
+				id,
+				type: child.type ?? "",
+				chars: 0
+			};
+			if (child.type === "heading" && typeof child.attrs?.level === "number") entry.level = child.attrs.level;
+			if (isTypedBlock(child)) entry.blockType = typeIdOf(child);
+			const title = titleOf(child);
+			if (title) entry.title = title;
+			entries.push(entry);
+			const inner = walk(child);
+			entry.chars = inner.chars;
+			if (inner.blocks.length) entry.children = inner.blocks;
+			chars += inner.chars;
+			blocks.push(id);
+		}
+		return {
+			chars,
+			blocks
+		};
+	};
+	walk(content);
+	return entries;
+}
+/**
+* The read-only document tools of the document chat, for `EditorServerOptions.tools` / `provideEditorServer({ tools })`, next
+* to `createWorkspaceTools`:
+*
+* - `document_outline(documentId?)`: the tree of all Blocks of the open Document (or of another one the user may read): per
+*   Block its ID, node type, heading level or Block type and title, the IDs of the Blocks directly inside it and the length of
+*   its text;
+* - `read_blocks(documentId?, blockIds)`: up to 50 Blocks of one Document as Markdown, each cut like `read_block`
+*   (`READ_BLOCK_LIMIT`), all together at most eight times that.
+*
+* Both read the current content (live content of an open Document first, else `loadCurrentContent`) and need no index. An
+* unreadable Document and an unknown Block answer the same sentence as `read_block`, so the tools never confirm that a
+* Document or Block exists where the user may not look.
+*/
+function createDocumentTools(options = {}) {
+	let markdown = options.markdown;
+	const markdownOf = () => markdown ??= createBlockMarkdown({
+		...options.schema && { schema: options.schema },
+		...options.blockTypes && { blockTypes: options.blockTypes }
+	});
+	return [{
+		name: "document_outline",
+		tool: tool({
+			description: "Liefert die Gliederung eines Dokuments als JSON: alle Blöcke in Dokumentreihenfolge, je mit id, type (Knotentyp), level (bei Überschriften), blockType (bei typisierten Blöcken), title (Überschriftentext bzw. Titel des typisierten Blocks), children (IDs der direkt enthaltenen Blöcke) und chars (Textlänge in Zeichen, enthaltene Blöcke eingeschlossen). Ohne documentId das im Chat geöffnete Dokument in seinem aktuellen Stand; mit documentId ein anderes lesbares Dokument. Den Inhalt einzelner Blöcke liest du mit read_blocks.",
+			inputSchema: jsonSchema({
+				type: "object",
+				properties: { documentId: {
+					type: "string",
+					description: "ID des Dokuments; ohne Angabe das geöffnete Dokument."
+				} }
+			})
+		}),
+		async handle(ctx, input) {
+			const checked = parsed(outlineInput, input);
+			if ("problem" in checked) return checked.problem;
+			const documentId = checked.value.documentId ?? ctx.documentId;
+			if (!documentId) return NO_DOCUMENT;
+			const content = await readableContent(ctx, documentId);
+			if (!content) return `Das Dokument „${documentId}“ ist nicht lesbar oder existiert nicht.`;
+			const blocks = outlineOf(content);
+			if (!blocks.length) return `Das Dokument „${documentId}“ hat keine Blöcke.`;
+			return JSON.stringify({
+				documentId,
+				blocks
+			});
+		}
+	}, {
+		name: "read_blocks",
+		tool: tool({
+			description: `Liest Blöcke eines Dokuments als Markdown, bis zu ${READ_BLOCKS_MAX} auf einmal, in der angegebenen Reihenfolge. Ohne documentId aus dem im Chat geöffneten Dokument in seinem aktuellen Stand, mit documentId aus einem anderen lesbaren Dokument. Ein Block enthält die in ihm verschachtelten Blöcke. Block-IDs stammen aus document_outline oder find_blocks. Ein Block über ${READ_BLOCK_LIMIT} Zeichen wird gekürzt; ab ${READ_BLOCKS_TOTAL_LIMIT} Zeichen insgesamt werden die übrigen Blöcke ausgelassen und sind mit einem weiteren Aufruf zu lesen.`,
+			inputSchema: jsonSchema({
+				type: "object",
+				properties: {
+					documentId: {
+						type: "string",
+						description: "ID des Dokuments; ohne Angabe das geöffnete Dokument."
+					},
+					blockIds: {
+						type: "array",
+						items: { type: "string" },
+						minItems: 1,
+						maxItems: READ_BLOCKS_MAX,
+						description: "IDs der Blöcke im Dokument."
+					}
+				},
+				required: ["blockIds"]
+			})
+		}),
+		async handle(ctx, input) {
+			const checked = parsed(readBlocksInput, input);
+			if ("problem" in checked) return checked.problem;
+			const documentId = checked.value.documentId ?? ctx.documentId;
+			if (!documentId) return NO_DOCUMENT;
+			const blockIds = [...new Set(checked.value.blockIds)];
+			const content = await readableContent(ctx, documentId);
+			const parts = [];
+			let total = 0;
+			for (const [i, blockId] of blockIds.entries()) {
+				if (total >= READ_BLOCKS_TOTAL_LIMIT) {
+					const rest = blockIds.slice(i);
+					parts.push(`[… ${rest.length} weitere Blöcke ausgelassen, die Grenze von ${READ_BLOCKS_TOTAL_LIMIT} Zeichen ist erreicht: ${rest.join(", ")}]`);
+					break;
+				}
+				const node = content && findBlock(content, blockId);
+				if (!node) {
+					parts.push(unreadableBlock(documentId, blockId));
+					continue;
+				}
+				const title = titleOf(node);
+				const head = `Dokument „${documentId}“, Block „${blockId}“ (${isTypedBlock(node) ? typeIdOf(node) : node.type ?? ""}${title ? `, ${title}` : ""}):`;
+				const body = markdownOf()([node]).trim();
+				const shown = body.length > 6e3 ? `${body.slice(0, READ_BLOCK_LIMIT)}\n\n[… gekürzt, ${body.length - READ_BLOCK_LIMIT} Zeichen fehlen]` : body;
+				total += Math.min(body.length, READ_BLOCK_LIMIT);
+				parts.push(`${head}\n\n${shown}`);
+			}
+			return parts.join("\n\n---\n\n");
+		}
+	}];
+}
+//#endregion
+export { createDocumentTools };
+
+//# sourceMappingURL=document-tools.js.map

package/dist/server/document-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-tools.js","names":[],"sources":["../../src/server/document-tools.ts"],"sourcesContent":["// i18n-ignore-file: model-facing tool descriptions and results (German, like the chat's system prompt)\nimport type { JSONContent } from '@tiptap/core'\nimport { jsonSchema, tool } from 'ai'\nimport { z } from 'zod'\nimport type { BlockMarkdown } from '../core/block-index'\nimport { isTypedBlock, TYPED_BLOCK_TITLE, typeIdOf } from '../core/typed-block'\nimport { createBlockMarkdown } from './block-index'\nimport { findBlock, INLINE_NODES } from './document-blocks'\nimport { mayReadDocument } from './readable-documents'\nimport { loadCurrentContent } from './stored-content'\nimport type { ToolContext, ToolProvider } from './tools'\nimport { parsed, READ_BLOCK_LIMIT, unreadableBlock, type WorkspaceToolsOptions } from './workspace-tools'\n\n// Read-only tools of the document chat that look into one Document as a whole: its tree of Blocks and several Blocks at once.\n// Unlike `createWorkspaceTools` they read the Document's content directly (no Block index): the live content of a Document\n// open in the collaboration server first, else the stored content in the current shape.\n\n/** Block IDs `read_blocks` reads in one call. */\nconst READ_BLOCKS_MAX = 50\n/** Characters of all Blocks one `read_blocks` call returns; the Blocks after the one that reaches it are left out with a note. */\nconst READ_BLOCKS_TOTAL_LIMIT = 8 * READ_BLOCK_LIMIT\n\n/** The Markdown serializer `read_blocks` writes with: the options of `createWorkspaceTools`. */\nexport type DocumentToolsOptions = WorkspaceToolsOptions\n\nconst outlineInput = z.object({\n  documentId: z.string().min(1).max(200).optional(),\n})\nconst readBlocksInput = z.object({\n  documentId: z.string().min(1).max(200).optional(),\n  blockIds: z.array(z.string().min(1).max(100)).min(1).max(READ_BLOCKS_MAX),\n})\n\nconst NO_DOCUMENT = 'Im Chat ist kein Dokument geöffnet: gib documentId an.'\n\n/** The current content of `documentId` (live first, else stored), `null` when the user may not read it or it does not exist. */\nasync function readableContent(ctx: ToolContext, documentId: string): Promise<JSONContent | null> {\n  if (!await mayReadDocument(ctx.ports, ctx.user, documentId)) return null\n  return ctx.liveContent(documentId) ?? await loadCurrentContent(ctx.ports.documents, documentId)\n}\n\nconst attrString = (node: JSONContent, key: string): string => typeof node.attrs?.[key] === 'string' ? node.attrs[key] as string : ''\n\n/** The plain text of an inline node or a textblock's inline content, chips as their label. */\nfunction inlineText(node: JSONContent): string {\n  switch (node.type) {\n    case 'text': return node.text ?? ''\n    case 'hardBreak': return ' '\n    case 'mention': return `@${attrString(node, 'label') || attrString(node, 'id')}`\n    case 'tag': return `#${attrString(node, 'name')}`\n    case 'reference': return attrString(node, 'label')\n    default: return (node.content ?? []).map(inlineText).join('')\n  }\n}\n\n/** The title of a Block as the Block index has it: a Typed block's title row, a heading's text, `''` for any other Block. */\nfunction titleOf(node: JSONContent): string {\n  if (isTypedBlock(node)) return (node.content ?? []).filter(child => child.type === TYPED_BLOCK_TITLE).map(inlineText).join('').trim()\n  return node.type === 'heading' ? inlineText(node).trim() : ''\n}\n\n/** One Block of `document_outline`. */\ninterface OutlineEntry {\n  id: string\n  /** Node type (`paragraph`, `heading`, `typedBlock`, …). */\n  type: string\n  /** Level of a heading. */\n  level?: number\n  /** Block type id of a Typed block. */\n  blockType?: string\n  /** Title of a Typed block, text of a heading. */\n  title?: string\n  /** IDs of the Blocks directly inside this one, in document order. */\n  children?: string[]\n  /** Characters of the Block's text, nested Blocks included. */\n  chars: number\n}\n\n/**\n * Every Block of `content` (every non-inline node with an `id`, the rule of `blockLinesOfContent`), in document order, a Block\n * before the Blocks nested in it. A Block's `children` are the Blocks directly inside it, through nodes without an ID (a list\n * without one, say).\n */\nfunction outlineOf(content: JSONContent): OutlineEntry[] {\n  const entries: OutlineEntry[] = []\n  const walk = (node: JSONContent): { chars: number, blocks: string[] } => {\n    let chars = 0\n    const blocks: string[] = []\n    for (const child of node.content ?? []) {\n      if (child.type !== undefined && INLINE_NODES.has(child.type)) {\n        chars += inlineText(child).length\n        continue\n      }\n      const id = child.attrs?.id\n      if (typeof id !== 'string' || !id) {\n        const inner = walk(child)\n        chars += inner.chars\n        blocks.push(...inner.blocks)\n        continue\n      }\n      const entry: OutlineEntry = { id, type: child.type ?? '', chars: 0 }\n      if (child.type === 'heading' && typeof child.attrs?.level === 'number') entry.level = child.attrs.level\n      if (isTypedBlock(child)) entry.blockType = typeIdOf(child)\n      const title = titleOf(child)\n      if (title) entry.title = title\n      entries.push(entry)\n      const inner = walk(child)\n      entry.chars = inner.chars\n      if (inner.blocks.length) entry.children = inner.blocks\n      chars += inner.chars\n      blocks.push(id)\n    }\n    return { chars, blocks }\n  }\n  walk(content)\n  return entries\n}\n\n/**\n * The read-only document tools of the document chat, for `EditorServerOptions.tools` / `provideEditorServer({ tools })`, next\n * to `createWorkspaceTools`:\n *\n * - `document_outline(documentId?)`: the tree of all Blocks of the open Document (or of another one the user may read): per\n *   Block its ID, node type, heading level or Block type and title, the IDs of the Blocks directly inside it and the length of\n *   its text;\n * - `read_blocks(documentId?, blockIds)`: up to 50 Blocks of one Document as Markdown, each cut like `read_block`\n *   (`READ_BLOCK_LIMIT`), all together at most eight times that.\n *\n * Both read the current content (live content of an open Document first, else `loadCurrentContent`) and need no index. An\n * unreadable Document and an unknown Block answer the same sentence as `read_block`, so the tools never confirm that a\n * Document or Block exists where the user may not look.\n */\nexport function createDocumentTools(options: DocumentToolsOptions = {}): ToolProvider[] {\n  let markdown = options.markdown\n  const markdownOf = (): BlockMarkdown => markdown ??= createBlockMarkdown({\n    ...(options.schema && { schema: options.schema }),\n    ...(options.blockTypes && { blockTypes: options.blockTypes }),\n  })\n\n  const documentOutline: ToolProvider = {\n    name: 'document_outline',\n    tool: tool({\n      description: 'Liefert die Gliederung eines Dokuments als JSON: alle Blöcke in Dokumentreihenfolge, je mit id, type (Knotentyp), level (bei Überschriften), blockType (bei typisierten Blöcken), title (Überschriftentext bzw. Titel des typisierten Blocks), children (IDs der direkt enthaltenen Blöcke) und chars (Textlänge in Zeichen, enthaltene Blöcke eingeschlossen). Ohne documentId das im Chat geöffnete Dokument in seinem aktuellen Stand; mit documentId ein anderes lesbares Dokument. Den Inhalt einzelner Blöcke liest du mit read_blocks.',\n      inputSchema: jsonSchema<{ documentId?: string }>({\n        type: 'object',\n        properties: {\n          documentId: { type: 'string', description: 'ID des Dokuments; ohne Angabe das geöffnete Dokument.' },\n        },\n      }),\n    }),\n    async handle(ctx, input) {\n      const checked = parsed(outlineInput, input)\n      if ('problem' in checked) return checked.problem\n      const documentId = checked.value.documentId ?? ctx.documentId\n      if (!documentId) return NO_DOCUMENT\n      const content = await readableContent(ctx, documentId)\n      // The same sentence for an unreadable and a missing Document: the tool never confirms that a Document exists the user may not read.\n      if (!content) return `Das Dokument „${documentId}“ ist nicht lesbar oder existiert nicht.`\n      const blocks = outlineOf(content)\n      if (!blocks.length) return `Das Dokument „${documentId}“ hat keine Blöcke.`\n      return JSON.stringify({ documentId, blocks })\n    },\n  }\n\n  const readBlocks: ToolProvider = {\n    name: 'read_blocks',\n    tool: tool({\n      description: `Liest Blöcke eines Dokuments als Markdown, bis zu ${READ_BLOCKS_MAX} auf einmal, in der angegebenen Reihenfolge. Ohne documentId aus dem im Chat geöffneten Dokument in seinem aktuellen Stand, mit documentId aus einem anderen lesbaren Dokument. Ein Block enthält die in ihm verschachtelten Blöcke. Block-IDs stammen aus document_outline oder find_blocks. Ein Block über ${READ_BLOCK_LIMIT} Zeichen wird gekürzt; ab ${READ_BLOCKS_TOTAL_LIMIT} Zeichen insgesamt werden die übrigen Blöcke ausgelassen und sind mit einem weiteren Aufruf zu lesen.`,\n      inputSchema: jsonSchema<{ documentId?: string, blockIds: string[] }>({\n        type: 'object',\n        properties: {\n          documentId: { type: 'string', description: 'ID des Dokuments; ohne Angabe das geöffnete Dokument.' },\n          blockIds: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: READ_BLOCKS_MAX, description: 'IDs der Blöcke im Dokument.' },\n        },\n        required: ['blockIds'],\n      }),\n    }),\n    async handle(ctx, input) {\n      const checked = parsed(readBlocksInput, input)\n      if ('problem' in checked) return checked.problem\n      const documentId = checked.value.documentId ?? ctx.documentId\n      if (!documentId) return NO_DOCUMENT\n      const blockIds = [...new Set(checked.value.blockIds)]\n      const content = await readableContent(ctx, documentId)\n      const parts: string[] = []\n      let total = 0\n      for (const [i, blockId] of blockIds.entries()) {\n        if (total >= READ_BLOCKS_TOTAL_LIMIT) {\n          const rest = blockIds.slice(i)\n          parts.push(`[… ${rest.length} weitere Blöcke ausgelassen, die Grenze von ${READ_BLOCKS_TOTAL_LIMIT} Zeichen ist erreicht: ${rest.join(', ')}]`)\n          break\n        }\n        const node = content && findBlock(content, blockId)\n        if (!node) {\n          parts.push(unreadableBlock(documentId, blockId))\n          continue\n        }\n        const title = titleOf(node)\n        const head = `Dokument „${documentId}“, Block „${blockId}“ (${isTypedBlock(node) ? typeIdOf(node) : node.type ?? ''}${title ? `, ${title}` : ''}):`\n        const body = markdownOf()([node]).trim()\n        const shown = body.length > READ_BLOCK_LIMIT ? `${body.slice(0, READ_BLOCK_LIMIT)}\\n\\n[… gekürzt, ${body.length - READ_BLOCK_LIMIT} Zeichen fehlen]` : body\n        total += Math.min(body.length, READ_BLOCK_LIMIT)\n        parts.push(`${head}\\n\\n${shown}`)\n      }\n      return parts.join('\\n\\n---\\n\\n')\n    },\n  }\n\n  return [documentOutline, readBlocks]\n}\n"],"mappings":"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"}

package/dist/server/handlers/ai.d.ts

@@ -130,7 +130,8 @@ export declare const chatBodySchema: z.ZodObject<{
  * Operations of the open Document (`documentId` absent or the body's) are `ops`; operations naming another Document the
  * user may edit (`mayEditDocument`) become one `ChangeSet` (`ChangeSetStore`) for the user to review per Document, when the
  * host has the `changeSets` port and a mutator; else such an operation is a `document` problem the model retries. All
- * operations share one numbering (`op<n>`).
+ * operations share one numbering (`op<n>`). With a host agent (`AiHandlerContext.chatAgent` answers one for the user) the
+ * agent answers the turn in place of the model loop (`agentChat`), with the same checks and events.
  */
 export declare function chatPost(ctx: AiHandlerContext, request: HandlerRequest): Promise<HandlerResponse>;
 /** Short inline continuation (ghost text) of the text before the caret. Plain JSON: `{ text }`, empty when nothing fits. */