@ixo/oracle-runtime 0.0.1

package/dist/plugins/editor/mint-invocation-tool.d.ts

@@ -0,0 +1,72 @@
+import type { MatrixClient } from 'matrix-js-sdk';
+import { z } from 'zod';
+import type { RuntimeContext } from '../../plugin-api/types.js';
+import { type AppConfig } from './provider.js';
+/**
+ * Minimal UCAN surface the tool depends on. Decoupled from the concrete
+ * `UcanService` class so the editor plugin can pass `rtCtx.ucan` directly
+ * (the runtime adapter exposes exactly these methods).
+ */
+export interface UcanMintCapable {
+    hasSigningKey(): boolean;
+    createInvocationFromDelegation: RuntimeContext['ucan']['createInvocationFromDelegation'];
+}
+/** Same narrow shape for the blob store, taken from `rtCtx.blobStore`. */
+export type BlobStoreCapable = Pick<RuntimeContext['blobStore'], 'put'>;
+export interface CreateMintInvocationEditorToolParams {
+    matrixClient: MatrixClient;
+    appConfig: AppConfig;
+    roomId: string;
+    ucanService: UcanMintCapable;
+    /** When provided alongside `userDid`, the minted invocation is stored in
+     * the blob store and the tool result includes a `blobId` the main agent
+     * can pass to `sandbox_write_blob` — avoiding LLM relay of the CAR. */
+    blobStore?: BlobStoreCapable;
+    /** Owner of the blob — used as the cache namespace. Required for blob
+     * storage; without it the tool falls back to returning only the raw CAR. */
+    userDid?: string;
+}
+/**
+ * Editor-scoped `mint_invocation` tool.
+ *
+ * Lives on the editor agent (not the main agent) because minting requires
+ * Y.Doc access via Matrix to fetch the user's delegation by CID — and the
+ * editor agent is the only one with `matrixClient` + `roomId` in its
+ * closure. The main agent invokes it through `call_editor_agent`.
+ *
+ * Two input modes — at least one must be provided:
+ *
+ *   1. `delegationCid` (preferred). The tool opens the flow's Y.Doc, looks
+ *      up the delegation entry by CID, and reads its `delegation` field
+ *      (the base64 CAR) directly. The 580-char base64 string never leaves
+ *      this process and never crosses the LLM, so it can't be corrupted in
+ *      transit.
+ *
+ *   2. `delegationCar` (legacy / external callers). Pass the base64 CAR
+ *      directly — used when the caller already has the bytes in hand and
+ *      doesn't want a Y.Doc lookup.
+ *
+ * Either way, the tool calls `ucanService.createInvocationFromDelegation`
+ * and returns a fresh single-use base64 CAR invocation that the caller
+ * (typically a sandbox skill) writes to its expected token file.
+ */
+export declare const createMintInvocationEditorTool: ({ matrixClient, appConfig, roomId: _roomId, ucanService, blobStore, userDid, }: CreateMintInvocationEditorToolParams) => import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    delegationCid: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    delegationCar: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    serviceUrl: z.ZodString;
+    can: z.ZodString;
+    withResource: z.ZodString;
+}, z.core.$strip>, {
+    serviceUrl: string;
+    can: string;
+    withResource: string;
+    delegationCid?: string | null | undefined;
+    delegationCar?: string | null | undefined;
+}, {
+    serviceUrl: string;
+    can: string;
+    withResource: string;
+    delegationCid?: string | null | undefined;
+    delegationCar?: string | null | undefined;
+}, string, unknown, "mint_invocation">;
+//# sourceMappingURL=mint-invocation-tool.d.ts.map

package/dist/plugins/editor/mint-invocation-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mint-invocation-tool.d.ts","sourceRoot":"","sources":["../../../src/plugins/editor/mint-invocation-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,OAAO,EAAE,KAAK,SAAS,EAAyB,MAAM,eAAe,CAAC;AAItE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,IAAI,OAAO,CAAC;IACzB,8BAA8B,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,gCAAgC,CAAC,CAAC;CAC1F;AAED,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC;AAExE,MAAM,WAAW,oCAAoC;IACnD,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,eAAe,CAAC;IAC7B;;2EAEuE;IACvE,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B;gFAC4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,8BAA8B,GAAI,gFAW5C,oCAAoC;;;;;;;;;;;;;;;;;;sCA2KpC,CAAC"}

package/dist/plugins/editor/mint-invocation-tool.js

@@ -0,0 +1,173 @@
+import { tool } from '@langchain/core/tools';
+import { Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { readDelegations } from './blocknote-helper.js';
+import { MatrixProviderManager } from './provider.js';
+const logger = new Logger('mint_invocation');
+/**
+ * Editor-scoped `mint_invocation` tool.
+ *
+ * Lives on the editor agent (not the main agent) because minting requires
+ * Y.Doc access via Matrix to fetch the user's delegation by CID — and the
+ * editor agent is the only one with `matrixClient` + `roomId` in its
+ * closure. The main agent invokes it through `call_editor_agent`.
+ *
+ * Two input modes — at least one must be provided:
+ *
+ *   1. `delegationCid` (preferred). The tool opens the flow's Y.Doc, looks
+ *      up the delegation entry by CID, and reads its `delegation` field
+ *      (the base64 CAR) directly. The 580-char base64 string never leaves
+ *      this process and never crosses the LLM, so it can't be corrupted in
+ *      transit.
+ *
+ *   2. `delegationCar` (legacy / external callers). Pass the base64 CAR
+ *      directly — used when the caller already has the bytes in hand and
+ *      doesn't want a Y.Doc lookup.
+ *
+ * Either way, the tool calls `ucanService.createInvocationFromDelegation`
+ * and returns a fresh single-use base64 CAR invocation that the caller
+ * (typically a sandbox skill) writes to its expected token file.
+ */
+export const createMintInvocationEditorTool = ({ matrixClient, appConfig, 
+// roomId is part of the shared tool-factory contract but not used by
+// this specific tool — minting only needs the userDid, ucanService and
+// the delegation source (cid via blobStore, or inline CAR). Prefixed
+// with `_` so the unused-vars rule lets it through.
+roomId: _roomId, ucanService, blobStore, userDid, }) => tool(async ({ delegationCid = null, delegationCar = null, serviceUrl, can, withResource, }) => {
+    logger.log(`🪙 mint_invocation invoked (service=${serviceUrl}, can=${can}, with=${withResource}, mode=${delegationCid ? 'cid' : 'car'})`);
+    if (!ucanService.hasSigningKey()) {
+        return JSON.stringify({
+            success: false,
+            error: 'Oracle has no UCAN signing key configured. Check SERVICE_ED25519_MNEMONIC.',
+        });
+    }
+    let resolvedCar = null;
+    if (delegationCid && typeof delegationCid === 'string') {
+        // Preferred path: look up the delegation in this flow's Y.Doc by CID.
+        // No string ever crosses the LLM, so corruption-in-relay is impossible.
+        const providerManager = new MatrixProviderManager(matrixClient, appConfig);
+        try {
+            const { doc } = await providerManager.init();
+            const { delegations } = readDelegations(doc);
+            const match = delegations.find((d) => d['cid'] === delegationCid);
+            if (!match) {
+                return JSON.stringify({
+                    success: false,
+                    error: `Delegation with cid "${delegationCid}" not found in this flow's permissions store. The user may not have signed it yet, or Matrix sync has not delivered it to the oracle. Re-check the cid in the companion prompt and confirm the delegation exists via read_permissions.`,
+                });
+            }
+            const car = match['delegation'];
+            if (typeof car !== 'string' || !car) {
+                return JSON.stringify({
+                    success: false,
+                    error: `Delegation entry for cid "${delegationCid}" has no \`delegation\` (base64 CAR) field. Stored entry shape may be legacy/unsupported.`,
+                });
+            }
+            resolvedCar = car.trim();
+        }
+        catch (error) {
+            return JSON.stringify({
+                success: false,
+                error: `Failed to read delegation by cid: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+        finally {
+            await providerManager.dispose();
+        }
+    }
+    else if (delegationCar && typeof delegationCar === 'string') {
+        resolvedCar = delegationCar.trim();
+    }
+    else {
+        return JSON.stringify({
+            success: false,
+            error: 'Either `delegationCid` (preferred — the tool will look up the CAR from the Y.Doc) or `delegationCar` (the base64 CAR string directly) must be provided.',
+        });
+    }
+    try {
+        const result = await ucanService.createInvocationFromDelegation(resolvedCar, serviceUrl, { can, with: withResource });
+        if ('error' in result) {
+            return JSON.stringify({ success: false, error: result.error });
+        }
+        // Store the freshly-minted invocation in the blob store so the main
+        // agent can write it to the sandbox via `sandbox_write_blob` without
+        // ever relaying the long base64 CAR through the LLM. The CAR is
+        // STILL returned as `invocation` for back-compat / debugging — the
+        // recommended path is for callers to use `blobId`.
+        let blobId;
+        if (blobStore && userDid) {
+            try {
+                // TTL = invocation lifetime + 30s headroom for sandbox write.
+                // 90s default is enough since the worker rejects expired tokens
+                // immediately and replay protection makes a longer window pointless.
+                blobId = await blobStore.put({
+                    userDid,
+                    name: 'ucan_invocation',
+                    value: result.invocation,
+                    ttlSeconds: 90,
+                });
+            }
+            catch (err) {
+                logger.warn(`🪙 failed to store invocation in blob store: ${err instanceof Error ? err.message : String(err)} — caller will need to relay CAR directly`);
+            }
+        }
+        return JSON.stringify({
+            success: true,
+            ...(blobId ? { blobId } : {}),
+            invocation: result.invocation,
+            audienceResolvedFrom: serviceUrl,
+            capability: { can, with: withResource },
+            note: blobId
+                ? 'Single-use. Pass `blobId` to `sandbox_write_blob` (preferred — keeps the CAR out of the LLM context). The `invocation` field is the same value verbatim if you must handle it directly. Mint a fresh invocation before each protected call.'
+                : 'Single-use. Mint a fresh invocation before each protected service call.',
+        });
+    }
+    catch (error) {
+        return JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}, {
+    name: 'mint_invocation',
+    description: `Mint a fresh, single-use UCAN invocation against any UCAN-gated service, using a delegation the user already signed in the editor.
+
+USE THIS TOOL whenever a skill needs to authenticate against an external service that requires a UCAN bearer token. Each invocation is single-use; mint a fresh one before every protected request (services typically reject reused invocation CIDs as replays).
+
+WORKFLOW (preferred — \`delegationCid\` mode):
+1. The companion prompt provides a \`delegationCid\` (the user's signed delegation to this oracle) and a \`serviceUrl\` (the target service's base URL).
+2. Call this tool with the cid + serviceUrl + the route's required capability \`{ can, with }\`. The tool itself reads the CAR from the flow's Y.Doc — you do NOT need to call \`read_permissions\` first.
+3. It returns \`{ success, blobId, invocation, ... }\`. **Use \`blobId\` — pass it to \`sandbox_write_blob\` to write the invocation to the skill's token path.** That way the long base64 CAR never enters the LLM context where it can get corrupted. The \`invocation\` field is the same value verbatim and only there for back-compat / debugging.
+4. Run the protected command in the sandbox.
+
+LEGACY (\`delegationCar\` mode): if you already have the base64 CAR string in hand from somewhere else, you can pass it directly via \`delegationCar\`. NOT recommended — long base64 strings can get mangled when an LLM relays them.
+
+The audience is auto-resolved by fetching \`<serviceUrl>/.well-known/did.json\`. The invocation is signed by THIS oracle's key, with the user's delegation embedded as proof. Service validators walk the chain back to the user (the root issuer) and accept the call iff the user is on their root-issuers allowlist.
+
+Returns:
+  { success: true, invocation: "<base64 CAR>", capability, audienceResolvedFrom }
+or
+  { success: false, error: "<reason>" } — surface the error verbatim if it indicates a setup problem (missing/expired delegation, audience mismatch, did:web unreachable, signing key not configured).`,
+    schema: z.object({
+        delegationCid: z
+            .string()
+            .optional()
+            .nullable()
+            .describe('PREFERRED. The CID of a UCAN delegation stored in this flow. The tool looks up the base64 CAR from the Y.Doc itself, so you only ever pass a short ~59-char CID — no risk of string corruption. Use the value from the companion prompt\'s "UCAN delegation CID:" field.'),
+        delegationCar: z
+            .string()
+            .optional()
+            .nullable()
+            .describe("LEGACY. The base64-encoded delegation CAR string. Only use this when you cannot use delegationCid (e.g. the delegation lives outside the flow's Y.Doc). Long strings are vulnerable to LLM relay corruption — prefer delegationCid."),
+        serviceUrl: z
+            .string()
+            .url()
+            .describe('Base URL of the target service (used to resolve did:web). Use the URL from the companion prompt verbatim — do NOT swap to a default or guess.'),
+        can: z
+            .string()
+            .describe('The capability action the route requires, e.g. "service/action" or "service/*". Defined by the target service; check SKILL.md or service docs.'),
+        withResource: z
+            .string()
+            .describe('The capability resource URI, e.g. "ixo:my-service". Defined by the target service.'),
+    }),
+});

package/dist/plugins/editor/page-functions.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Page management functions — reusable from services, API routes, and tests.
+ */
+import type { MatrixClient } from 'matrix-js-sdk';
+import { type MatrixConfig, type ProviderConfig } from './provider.js';
+export interface CreatePageParams {
+    matrixClient: MatrixClient;
+    matrixConfig: Omit<MatrixConfig, 'room'>;
+    providerConfig: ProviderConfig;
+    title: string;
+    topic?: string;
+    content?: string;
+    parentSpaceId?: string;
+    inviteUserIds?: string[];
+}
+export interface CreatePageResult {
+    roomId: string;
+    alias: string;
+    title: string;
+    ownerDid: string;
+    createdAt: string;
+    blockCount: number;
+}
+export interface ReadPageParams {
+    matrixClient: MatrixClient;
+    matrixConfig: Omit<MatrixConfig, 'room'>;
+    providerConfig: ProviderConfig;
+    roomId: string;
+}
+export interface ReadPageResult {
+    roomId: string;
+    metadata: Record<string, unknown>;
+    blocks: Array<{
+        id: string;
+        type: string;
+        properties: Record<string, unknown>;
+        text?: string;
+    }>;
+    blockCount: number;
+}
+/**
+ * Create a new page.
+ *
+ * - Generates a FE-compatible `page-{timestamp}` alias
+ * - Invites specified users and grants them power level 50
+ * - Accepts optional markdown `content` which is parsed into BlockNote blocks
+ */
+export declare function createPage(params: CreatePageParams): Promise<CreatePageResult>;
+export interface UpdatePageParams {
+    matrixClient: MatrixClient;
+    matrixConfig: Omit<MatrixConfig, 'room'>;
+    providerConfig: ProviderConfig;
+    roomId: string;
+    title?: string;
+    topic?: string;
+    content?: string;
+    appendContent?: string;
+}
+export interface PageDiff {
+    title?: {
+        old: string;
+        new: string;
+    };
+    topic?: {
+        old: string;
+        new: string;
+    };
+    content?: {
+        old: string;
+        new: string;
+    };
+}
+export interface UpdatePageResult {
+    roomId: string;
+    title: string;
+    ownerDid: string;
+    updatedAt: string;
+    updatedFields: string[];
+    blockCount: number;
+    diff: PageDiff;
+}
+/**
+ * Update an existing page — title, topic, content, or append content.
+ *
+ * - `title` updates the Y.Text 'title' shared type
+ * - `topic` updates the Matrix room topic
+ * - `content` replaces all blocks with parsed markdown
+ * - `appendContent` appends parsed markdown blocks to existing content
+ *
+ * Returns the page title, ownerDid, timestamp, and a diff object showing
+ * old vs new values for each changed field (for GitHub-style change rendering).
+ */
+export declare function updatePage(params: UpdatePageParams): Promise<UpdatePageResult>;
+/**
+ * Read an existing page by room ID.
+ *
+ * Returns metadata (title, owner, creation date) and all blocks.
+ */
+export declare function readPage(params: ReadPageParams): Promise<ReadPageResult>;
+//# sourceMappingURL=page-functions.d.ts.map

package/dist/plugins/editor/page-functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-functions.d.ts","sourceRoot":"","sources":["../../../src/plugins/editor/page-functions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAQlD,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAwBvB,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACzC,cAAc,EAAE,cAAc,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACzC,cAAc,EAAE,cAAc,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAqCD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAuI3B;AAID,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACzC,cAAc,EAAE,cAAc,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,OAAO,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAgJ3B;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,cAAc,CAAC,CAsCzB"}

package/dist/plugins/editor/page-functions.js

@@ -0,0 +1,317 @@
+/**
+ * Page management functions — reusable from services, API routes, and tests.
+ */
+import { ServerBlockNoteEditor } from '@blocknote/server-util';
+import { Logger } from '@nestjs/common';
+import { Preset, Visibility } from 'matrix-js-sdk';
+import { collectAllBlocks, readFlowMetadata, simplifyBlockForAgent, } from './blocknote-helper.js';
+import { MatrixProviderManager, } from './provider.js';
+/**
+ * Converts a Matrix user ID in hyphen-delimited DID form (`@did-ixo-…`)
+ * to the canonical colon-delimited DID (`did:ixo:…`).
+ */
+function normalizeDid(input) {
+    const username = input.split(':')[0] ?? '';
+    const parts = username.split('-');
+    if (parts.length < 3 || parts[0] !== '@did') {
+        throw new Error(`Invalid DID format: ${input}`);
+    }
+    const namespace = parts[1];
+    const identifier = parts.slice(2).join('-');
+    return `did:${namespace}:${identifier}`;
+}
+const logger = new Logger('PageFunctions');
+// Singleton — reuse across calls (stateless, thread-safe)
+const serverEditor = ServerBlockNoteEditor.create();
+// ── Helpers ───────────────────────────────────────────────────────────
+function validateMatrixRoomId(roomId) {
+    if (!/^!.+:.+$/.test(roomId)) {
+        throw new Error(`Invalid Matrix room ID '${roomId}'. Room IDs must start with '!' followed by the room identifier and homeserver (e.g., '!abc123:matrix.org').`);
+    }
+}
+function createPageAlias() {
+    return `page-${Date.now()}`;
+}
+function buildPageAppConfig(matrixConfig, providerConfig, roomId) {
+    return {
+        matrix: {
+            ...matrixConfig,
+            room: { type: 'id', value: roomId },
+        },
+        provider: providerConfig,
+        blocknote: { mutableAttributeKeys: [] },
+    };
+}
+function extractHomeserver(baseUrl) {
+    return baseUrl.replace(/^https?:\/\//, '');
+}
+// ── Core Functions ────────────────────────────────────────────────────
+/**
+ * Create a new page.
+ *
+ * - Generates a FE-compatible `page-{timestamp}` alias
+ * - Invites specified users and grants them power level 50
+ * - Accepts optional markdown `content` which is parsed into BlockNote blocks
+ */
+export async function createPage(params) {
+    const { matrixClient, matrixConfig, providerConfig, title, topic, content, parentSpaceId, inviteUserIds, } = params;
+    const alias = createPageAlias();
+    const creatorId = matrixClient.getUserId();
+    const homeserver = extractHomeserver(matrixConfig.baseUrl);
+    // Build power levels — creator gets 100, invited users get 50
+    const users = { [creatorId]: 100 };
+    if (inviteUserIds) {
+        for (const userId of inviteUserIds) {
+            users[userId] = 50;
+        }
+    }
+    // Build initial state events (matching FE pattern)
+    const initialState = [
+        {
+            type: 'm.room.history_visibility',
+            state_key: '',
+            content: { history_visibility: 'shared' },
+        },
+        {
+            type: 'm.room.guest_access',
+            state_key: '',
+            content: { guest_access: 'forbidden' },
+        },
+    ];
+    if (parentSpaceId) {
+        initialState.push({
+            type: 'm.space.parent',
+            state_key: parentSpaceId,
+            content: { via: [homeserver], canonical: true },
+        });
+    }
+    logger.log(`Creating page room with alias: ${alias}`);
+    const createRoomResponse = await matrixClient.createRoom({
+        room_alias_name: alias,
+        name: title,
+        topic: topic ?? 'Page',
+        visibility: Visibility.Private,
+        preset: Preset.PrivateChat,
+        invite: inviteUserIds ?? [],
+        initial_state: initialState,
+        power_level_content_override: {
+            events_default: 50,
+            state_default: 50,
+            users_default: 0,
+            users,
+            events: {
+                'com.yjs.webrtc.announce': 0,
+                'com.yjs.webrtc.signal': 0,
+            },
+        },
+    });
+    const roomId = createRoomResponse.room_id;
+    logger.log(`Page room created: ${roomId}`);
+    // If parent space exists, add the room as a child of the space
+    if (parentSpaceId) {
+        try {
+            await matrixClient.sendStateEvent(parentSpaceId, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'm.space.child', { via: [homeserver] }, roomId);
+        }
+        catch (error) {
+            logger.warn(`Failed to add page as child of space ${parentSpaceId}: ${error}`);
+        }
+    }
+    // Parse markdown content into BlockNote blocks if provided
+    const blocks = content
+        ? await serverEditor.tryParseMarkdownToBlocks(content)
+        : [];
+    // Initialize Y.Doc with metadata and blocks
+    const appConfig = buildPageAppConfig(matrixConfig, providerConfig, roomId);
+    const providerManager = new MatrixProviderManager(matrixClient, appConfig);
+    const createdAt = new Date().toISOString();
+    const ownerDid = normalizeDid(creatorId);
+    try {
+        const { doc } = await providerManager.init();
+        // Set page metadata
+        doc.transact(() => {
+            const root = doc.getMap('root');
+            root.set('@context', 'https://ixo.world/page/0.1');
+            root.set('createdAt', createdAt);
+            root.set('ownerDid', ownerDid);
+            doc.getText('title').insert(0, title);
+        });
+        // Write parsed blocks into the document fragment
+        if (blocks.length > 0) {
+            const fragment = doc.getXmlFragment('document');
+            serverEditor.blocksToYXmlFragment(blocks, fragment);
+        }
+    }
+    finally {
+        await providerManager.dispose();
+    }
+    logger.log(`Page initialized: ${title} (${blocks.length} blocks)`);
+    return {
+        roomId,
+        alias,
+        title,
+        ownerDid,
+        createdAt,
+        blockCount: blocks.length,
+    };
+}
+/**
+ * Update an existing page — title, topic, content, or append content.
+ *
+ * - `title` updates the Y.Text 'title' shared type
+ * - `topic` updates the Matrix room topic
+ * - `content` replaces all blocks with parsed markdown
+ * - `appendContent` appends parsed markdown blocks to existing content
+ *
+ * Returns the page title, ownerDid, timestamp, and a diff object showing
+ * old vs new values for each changed field (for GitHub-style change rendering).
+ */
+export async function updatePage(params) {
+    const { matrixClient, matrixConfig, providerConfig, roomId, title, topic, content, appendContent, } = params;
+    validateMatrixRoomId(roomId);
+    const updatedFields = [];
+    const diff = {};
+    // Ensure the client is in the room (same pattern as readPage)
+    const isInRoom = matrixClient.getRoom(roomId)?.getMember(matrixClient.getUserId() ?? '')
+        ?.membership === 'join';
+    if (!isInRoom) {
+        try {
+            await matrixClient.joinRoom(roomId);
+            logger.log(`Joined room ${roomId}`);
+        }
+        catch (error) {
+            logger.warn(`Could not join room ${roomId}: ${error}`);
+        }
+    }
+    // Capture old topic before updating
+    if (topic !== undefined) {
+        const room = matrixClient.getRoom(roomId);
+        const oldTopic = room?.currentState?.getStateEvents('m.room.topic', '')?.getContent()
+            ?.topic ?? '';
+        try {
+            await matrixClient.setRoomTopic(roomId, topic);
+            updatedFields.push('topic');
+            diff.topic = { old: oldTopic, new: topic };
+        }
+        catch (error) {
+            logger.warn(`Failed to update room topic for ${roomId}: ${error}`);
+        }
+    }
+    // Parse content if provided
+    const contentBlocks = content
+        ? await serverEditor.tryParseMarkdownToBlocks(content)
+        : [];
+    const appendBlocks = appendContent
+        ? await serverEditor.tryParseMarkdownToBlocks(appendContent)
+        : [];
+    const appConfig = buildPageAppConfig(matrixConfig, providerConfig, roomId);
+    const providerManager = new MatrixProviderManager(matrixClient, appConfig);
+    let blockCount = 0;
+    let currentTitle = '';
+    let ownerDid = '';
+    try {
+        const { doc } = await providerManager.init();
+        // Read metadata before mutations
+        const metadata = readFlowMetadata(doc);
+        ownerDid = metadata.ownerDid ?? '';
+        const oldTitle = doc.getText('title').toString();
+        // Snapshot old content as markdown (for diff) before any mutations
+        let oldContentMd = '';
+        if (content !== undefined || appendContent !== undefined) {
+            const oldBlocks = serverEditor.yXmlFragmentToBlocks(doc.getXmlFragment('document'));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            oldContentMd = await serverEditor.blocksToMarkdownLossy(oldBlocks);
+        }
+        doc.transact(() => {
+            // Update title
+            if (title !== undefined) {
+                const titleText = doc.getText('title');
+                titleText.delete(0, titleText.length);
+                titleText.insert(0, title);
+                updatedFields.push('title');
+                diff.title = { old: oldTitle, new: title };
+            }
+            // Replace all content
+            if (content !== undefined && contentBlocks.length > 0) {
+                const fragment = doc.getXmlFragment('document');
+                // Clear existing content
+                while (fragment.length > 0) {
+                    fragment.delete(0, 1);
+                }
+                serverEditor.blocksToYXmlFragment(contentBlocks, fragment);
+                updatedFields.push('content');
+            }
+            // Append content
+            if (appendContent !== undefined && appendBlocks.length > 0) {
+                const fragment = doc.getXmlFragment('document');
+                serverEditor.blocksToYXmlFragment(appendBlocks, fragment);
+                updatedFields.push('appendContent');
+            }
+        });
+        // Snapshot new content as markdown (for diff) after mutations
+        if (content !== undefined || appendContent !== undefined) {
+            const newBlocks = serverEditor.yXmlFragmentToBlocks(doc.getXmlFragment('document'));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const newContentMd = await serverEditor.blocksToMarkdownLossy(newBlocks);
+            diff.content = { old: oldContentMd, new: newContentMd };
+        }
+        // Read final title
+        currentTitle = doc.getText('title').toString();
+        // Count final blocks
+        const fragment = doc.getXmlFragment('document');
+        const allBlocks = collectAllBlocks(fragment);
+        blockCount = allBlocks.length;
+    }
+    finally {
+        await providerManager.dispose();
+    }
+    logger.log(`Page updated: ${roomId} (fields: ${updatedFields.join(', ')})`);
+    return {
+        roomId,
+        title: currentTitle,
+        ownerDid,
+        updatedAt: new Date().toISOString(),
+        updatedFields,
+        blockCount,
+        diff,
+    };
+}
+/**
+ * Read an existing page by room ID.
+ *
+ * Returns metadata (title, owner, creation date) and all blocks.
+ */
+export async function readPage(params) {
+    const { matrixClient, matrixConfig, providerConfig, roomId } = params;
+    validateMatrixRoomId(roomId);
+    // Ensure the client is in the room
+    const isInRoom = matrixClient.getRoom(roomId)?.getMember(matrixClient.getUserId() ?? '')
+        ?.membership === 'join';
+    if (!isInRoom) {
+        try {
+            await matrixClient.joinRoom(roomId);
+            logger.log(`Joined room ${roomId}`);
+        }
+        catch (error) {
+            logger.warn(`Could not join room ${roomId}: ${error}`);
+        }
+    }
+    const appConfig = buildPageAppConfig(matrixConfig, providerConfig, roomId);
+    const providerManager = new MatrixProviderManager(matrixClient, appConfig);
+    try {
+        const { doc } = await providerManager.init();
+        const metadata = readFlowMetadata(doc);
+        const rawBlocks = collectAllBlocks(doc.getXmlFragment('document'));
+        const simplifiedBlocks = rawBlocks.map((b) => simplifyBlockForAgent(b));
+        return {
+            roomId,
+            metadata,
+            blocks: simplifiedBlocks,
+            blockCount: simplifiedBlocks.length,
+        };
+    }
+    finally {
+        await providerManager.dispose();
+    }
+}