@book.dev/sdk 1.76.2 → 2.1.0

package/dist/ai.d.ts

@@ -31,7 +31,7 @@ export type AiEffort = 'low' | 'med' | 'high';
  *  claude all set up at once and switch between them per agent run. */
 export interface AiProviderSettings {
     /** Model identifier: a GGUF filename (llama), an MLX model id (mlx), a served
-     *  model name (openai), or a Claude model id (e.g. `claude-sonnet-4-6`). */
+     *  model name (openai), or a Claude model id (e.g. `claude-opus-4-8`). */
     model?: string;
     /** Base URL for `mlx` / `openai` / `claude`. Defaults: mlx
      *  http://127.0.0.1:8080, openai http://127.0.0.1:11434, claude
@@ -271,13 +271,18 @@ export type AgentChatEvent = {
     result: string;
 }
 /**
- * The agent is asking to apply its edits DIRECTLY (without the review pane).
- * The UI shows an allow/keep-reviewing prompt; granting it makes subsequent
- * edits in this conversation apply immediately (see {@link apply}).
+ * The agent is asking for a sticky, per-conversation permission. `kind`
+ * distinguishes them (default `direct_edits` for back-compat):
+ *  - `direct_edits` — apply its edits DIRECTLY (without the review pane);
+ *    granting makes subsequent edits apply immediately (see {@link apply}).
+ *  - `external_tools` — call EXTERNAL MCP tools (`mcp__*`), which send inputs
+ *    off the workspace; granting lets the agent use them for this conversation.
+ * The UI shows an allow / keep-reviewing prompt either way.
  */
  | {
     type: 'permission_request';
     summary: string;
+    kind?: 'direct_edits' | 'external_tools';
 }
 /** The agent is asking the user a multi-step interview; answers return as the
  *  user's next message. */
@@ -346,6 +351,105 @@ export interface AgentChatOptions {
      *  via an {@link AgentChatEvent.apply} event instead of becoming review
      *  suggestions. Sticky for the conversation once granted. */
     allowDirectEdits?: boolean;
+    /** When true (the user consented), the agent may call EXTERNAL MCP tools
+     *  (`mcp__*`) without pausing. Sticky for the conversation; the first external
+     *  call otherwise emits a `permission_request` with `kind:'external_tools'`. */
+    allowExternalTools?: boolean;
+    /** When true, an external MCP tool was already used earlier in this conversation
+     *  — the client re-sends it (set once it sees any `mcp__*` tool event) so taint
+     *  (edits routed through review) stays sticky for the rest of the conversation,
+     *  not just the run that made the external call. */
+    externalToolsUsed?: boolean;
+}
+/**
+ * How the in-app agent reaches an external MCP server:
+ *  - `stdio` — spawn a local child process and speak MCP over its stdio. This is
+ *    host **command execution** (the child runs as the server user and can reach
+ *    loopback services the identity layer trusts as the machine owner), so it is
+ *    permitted ONLY on a desktop / UNCLAIMED instance. On a claimed multi-user
+ *    instance the server rejects a `stdio` registration and the UI hides it.
+ *  - `http` — a remote (or loopback) Streamable-HTTP MCP endpoint, authed with a
+ *    static bearer token. The only transport offered on a claimed instance.
+ */
+export type McpTransport = 'stdio' | 'http';
+/**
+ * One registered external MCP server. Admin-managed (see {@link McpClientConfig});
+ * connections are pooled server-side and its tools are merged into an agent run
+ * namespaced `mcp__<id>__<tool>` (so `id` forbids underscores — the delimiter).
+ */
+export interface McpServerConfig {
+    /** Stable slug, `^[a-z0-9][a-z0-9-]{0,31}$` (NO underscores — the namespace
+     *  delimiter). Unique within {@link McpClientConfig.servers}. */
+    id: string;
+    /** Optional display name (defaults to {@link id}). */
+    name?: string;
+    /** Per-server enable. Default false — a registered server does nothing until
+     *  explicitly enabled (and the global {@link McpClientConfig.enabled} is on). */
+    enabled: boolean;
+    transport: McpTransport;
+    /** The executable to spawn (stdio). */
+    command?: string;
+    /** Arguments for {@link command} (stdio). NEVER carries the auth token. */
+    args?: string[];
+    /** Extra environment for the child (stdio). Overlaid on a MINIMAL default env
+     *  (never the server's own `process.env`); the auth token is injected under
+     *  {@link authEnvVar}, not here. */
+    env?: Record<string, string>;
+    /** Env var name the auth token is injected under (stdio). Default `MCP_AUTH_TOKEN`. */
+    authEnvVar?: string;
+    /** The Streamable-HTTP MCP endpoint (http). */
+    url?: string;
+    /** Extra request headers (http). The auth token is sent as `Authorization:
+     *  Bearer <token>`, NOT here. */
+    headers?: Record<string, string>;
+    /**
+     * The static bearer token (http) or injected secret (stdio). **Write-only
+     * across the wire** — the server never returns it. Same three-way contract as
+     * {@link AiProviderSettings.apiKey}:
+     *   • omitted / empty string → PRESERVE the stored token;
+     *   • a non-empty string     → set a new token;
+     *   • explicit `null`        → CLEAR the stored token.
+     */
+    authToken?: string | null;
+    /** Response-only signal: the server holds a non-empty token for this server.
+     *  Set by `GET /api/ai/mcp` in place of the redacted {@link authToken}. */
+    authTokenSet?: boolean;
+    /** Per-call timeout for this server's tools, ms. Default 30000, clamped
+     *  1000..120000. */
+    timeoutMs?: number;
+}
+/**
+ * The workspace's external-tool (MCP client) configuration, persisted server-side
+ * under the `ai.mcp` settings key. Admin-managed. OFF and empty by default —
+ * nothing connects until an admin adds a server, enables it, and flips the global
+ * switch. A deployment env kill-switch (`OPENBOOK_MCP_CLIENTS=0`) hard-disables
+ * the whole subsystem regardless.
+ */
+export interface McpClientConfig {
+    /** Global kill-switch. Default false — with it off no server connects, even an
+     *  individually-enabled one. */
+    enabled: boolean;
+    servers: McpServerConfig[];
+}
+/**
+ * `GET /api/ai/mcp` (admin only): the redacted config (every {@link
+ * McpServerConfig.authToken} stripped, {@link McpServerConfig.authTokenSet}
+ * flagged) plus `stdioAllowed` — whether this instance's trust level permits the
+ * `stdio` transport (true on a desktop / unclaimed instance, false once claimed).
+ * The UI hides the stdio option when false; the PUT route enforces the same rule.
+ */
+export interface McpConfigResponse {
+    config: McpClientConfig;
+    stdioAllowed: boolean;
+}
+/** Result of `POST /api/ai/mcp/test` (admin only): a connect + list-tools dry-run
+ *  against one server config. Never returns secrets. */
+export interface McpTestResult {
+    ok: boolean;
+    /** Tool names discovered on a successful connect. */
+    tools?: string[];
+    /** A human-readable failure reason (error class / message), never headers/env. */
+    error?: string;
 }
 /**
  * A user-authored prompt/recipe skill: markdown instructions the agent can

package/dist/authorize.js

@@ -32,12 +32,15 @@ export function isEmailAuthoritative(principal, config) {
  * satisfy an `account.book.pub`-scoped email grant.
  */
 function matchAcl(principal, acl, ctx) {
-    const isJws = principal.verifiedVia === 'jws';
+    // A **subject** entry matches a `jws` OR a `pat` principal with that subject: an
+    // agent PAT (AGENT-6) rides the exact subject-keyed grants its bound user has. An
+    // **email** entry stays jws-only (a PAT carries no persona email — see below).
+    const subjectEligible = principal.verifiedVia === 'jws' || principal.verifiedVia === 'pat';
     let best = null;
     for (const entry of acl) {
         let matches = false;
         if (entry.subject) {
-            matches = isJws && entry.subject === principal.subject;
+            matches = subjectEligible && entry.subject === principal.subject;
         }
         else if (entry.email) {
             matches =
@@ -62,8 +65,9 @@ function scopeAllowsRead(principal, ctx, guestBlocked) {
             // guest when `guestAccess='off'` (rule 6 / footnote ¹).
             return !guestBlocked;
         case 'authenticated':
-            // Any signed-in (jws) user; guests denied (N8).
-            return principal.verifiedVia === 'jws';
+            // Any signed-in (jws) user, or an agent PAT bound to one (AGENT-6); guests
+            // denied (N8).
+            return principal.verifiedVia === 'jws' || principal.verifiedVia === 'pat';
         case 'members':
             // Only active roster members — an active row resolves to a non-null role.
             // A signed-in non-member or invited/suspended persona (role null) gets
@@ -94,13 +98,20 @@ export function authorize(principal, page, ctx) {
     const { config } = ctx;
     const isLocal = principal.verifiedVia === 'local';
     const isJws = principal.verifiedVia === 'jws';
+    // An agent PAT (AGENT-6) rides the SUBJECT-keyed rungs its bound user would —
+    // owner-content (rule 2), subject-ACL (rule 3), authenticated-read (rule 5), and
+    // the unclaimed rule-0 short-circuit — but is NEVER a roster member (rule 4:
+    // `ctx.role` is jws-only via `resolveMemberRole`, so a PAT can't ride the
+    // admin/viewer rung) and carries no persona email (no email-ACL). Its write
+    // ceiling is additionally enforced out-of-band by the HTTP scope-gate.
+    const isPat = principal.verifiedVia === 'pat';
     // Rule 0 — unclaimed instance: legacy short-circuit, preserving today's
     // loopback behaviour exactly. Roster/scope/ACL don't exist until claimed; the
     // in-process (`local`) and any `jws` caller always read+write (truth-table
     // footer), everyone else is judged by the guest gate. Reachable only on
     // loopback (the §2.6 exposure invariant — a claim is required before exposure).
     if (config.ownerSubject === undefined) {
-        const privileged = isJws || isLocal;
+        const privileged = isJws || isLocal || isPat;
         return {
             canRead: config.guestAccess !== 'off' || privileged,
             canWrite: config.guestAccess === 'write' || privileged,
@@ -108,7 +119,7 @@ export function authorize(principal, page, ctx) {
         };
     }
     // ── Claimed instance ──────────────────────────────────────────────────────
-    const isOwner = isJws && principal.subject === config.ownerSubject; // rule 2
+    const isOwner = (isJws || isPat) && principal.subject === config.ownerSubject; // rule 2
     const aclMatch = matchAcl(principal, page.acl, ctx); // rule 3
     const isAdmin = ctx.role === 'admin'; // rule 4
     const isViewer = ctx.role === 'viewer'; // rule 4
@@ -120,7 +131,7 @@ export function authorize(principal, page, ctx) {
     // past the `guestAccess='off'` floor onto a `public` page either (defence in
     // depth behind the middleware, which already rejects such principals at the gate
     // on an identity-enabled instance).
-    const guestBlocked = !isJws && !isLocal && config.guestAccess === 'off';
+    const guestBlocked = !isJws && !isLocal && !isPat && config.guestAccess === 'off';
     const scopeRead = scopeAllowsRead(principal, ctx, guestBlocked); // rule 5
     // WRITE — only rules 1/2/3(write)/4(admin) ever grant it. `viewer` is locked,
     // jws-non-members and guests are read-only on a claimed instance.

package/dist/authorize.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2EH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAoB,EACpB,MAA8C;IAE9C,OAAO,CACL,SAAS,CAAC,WAAW,KAAK,KAAK;QAC/B,CAAC,CAAC,MAAM,CAAC,cAAc;QACvB,SAAS,CAAC,MAAM,KAAK,MAAM,CAAC,cAAc,CAC3C,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,QAAQ,CAAC,SAAoB,EAAE,GAAe,EAAE,GAAc;IACrE,iFAAiF;IACjF,kFAAkF;IAClF,+EAA+E;IAC/E,MAAM,eAAe,GAAG,SAAS,CAAC,WAAW,KAAK,KAAK,IAAI,SAAS,CAAC,WAAW,KAAK,KAAK,CAAC;IAC3F,IAAI,IAAI,GAAoB,IAAI,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,GAAG,eAAe,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,OAAO,CAAC;QACnE,CAAC;aAAM,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YACvB,OAAO;gBACL,GAAG,CAAC,oBAAoB;oBACxB,CAAC,CAAC,SAAS,CAAC,KAAK;oBACjB,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE;oBAC3D,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC;QAC/C,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO;gBAAE,OAAO,OAAO,CAAC;YAC5C,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,kFAAkF;AAClF,SAAS,eAAe,CAAC,SAAoB,EAAE,GAAc,EAAE,YAAqB;IAClF,QAAQ,GAAG,CAAC,mBAAmB,EAAE,CAAC;QAClC,KAAK,QAAQ;YACX,uEAAuE;YACvE,wDAAwD;YACxD,OAAO,CAAC,YAAY,CAAC;QACvB,KAAK,eAAe;YAClB,2EAA2E;YAC3E,eAAe;YACf,OAAO,SAAS,CAAC,WAAW,KAAK,KAAK,IAAI,SAAS,CAAC,WAAW,KAAK,KAAK,CAAC;QAC5E,KAAK,SAAS;YACZ,0EAA0E;YAC1E,uEAAuE;YACvE,oDAAoD;YACpD,OAAO,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC;QAC3B,KAAK,YAAY;YACf,8DAA8D;YAC9D,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,SAAoB,EAAE,IAAgB,EAAE,GAAc;IAC9E,MAAM,EAAC,MAAM,EAAC,GAAG,GAAG,CAAC;IACrB,MAAM,OAAO,GAAG,SAAS,CAAC,WAAW,KAAK,OAAO,CAAC;IAClD,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,KAAK,KAAK,CAAC;IAC9C,8EAA8E;IAC9E,iFAAiF;IACjF,6EAA6E;IAC7E,0EAA0E;IAC1E,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,KAAK,KAAK,CAAC;IAE9C,wEAAwE;IACxE,8EAA8E;IAC9E,2EAA2E;IAC3E,wEAAwE;IACxE,gFAAgF;IAChF,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,UAAU,GAAG,KAAK,IAAI,OAAO,IAAI,KAAK,CAAC;QAC7C,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,WAAW,KAAK,KAAK,IAAI,UAAU;YACnD,QAAQ,EAAE,MAAM,CAAC,WAAW,KAAK,OAAO,IAAI,UAAU;YACtD,MAAM,EAAE,mBAAmB;SAC5B,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,SAAS,CAAC,OAAO,KAAK,MAAM,CAAC,YAAY,CAAC,CAAC,SAAS;IACxF,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS;IAC9D,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,SAAS;IAC/C,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,SAAS;IACjD,wEAAwE;IACxE,sEAAsE;IACtE,+EAA+E;IAC/E,0EAA0E;IAC1E,gFAAgF;IAChF,6EAA6E;IAC7E,iFAAiF;IACjF,oCAAoC;IACpC,MAAM,YAAY,GAAG,CAAC,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,WAAW,KAAK,KAAK,CAAC;IAClF,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS;IAE1E,8EAA8E;IAC9E,kEAAkE;IAClE,MAAM,QAAQ,GAAG,OAAO,IAAI,OAAO,IAAI,QAAQ,KAAK,OAAO,IAAI,OAAO,CAAC;IAEvE,mDAAmD;IACnD,MAAM,OAAO,GAAG,OAAO,IAAI,OAAO,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,IAAI,SAAS,CAAC;IAEhF,IAAI,MAAc,CAAC;IACnB,IAAI,OAAO;QAAE,MAAM,GAAG,aAAa,CAAC;SAC/B,IAAI,OAAO;QAAE,MAAM,GAAG,OAAO,CAAC;SAC9B,IAAI,QAAQ,KAAK,OAAO;QAAE,MAAM,GAAG,WAAW,CAAC;SAC/C,IAAI,OAAO;QAAE,MAAM,GAAG,OAAO,CAAC;SAC9B,IAAI,QAAQ,KAAK,MAAM;QAAE,MAAM,GAAG,UAAU,CAAC;SAC7C,IAAI,QAAQ;QAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC;SAChE,IAAI,OAAO;QAAE,MAAM,GAAG,kBAAkB,CAAC;SACzC,IAAI,YAAY;QAAE,MAAM,GAAG,gBAAgB,CAAC;;QAC5C,MAAM,GAAG,UAAU,CAAC;IAEzB,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAC,CAAC;AACrC,CAAC"}

package/dist/backup.d.ts

@@ -12,7 +12,7 @@
 import type { StoredPage } from './types';
 import type { StoredDatabase } from './database';
 export declare const BACKUP_VERSION = 1;
-export interface SpaceBackup {
+export interface LibraryBackup {
     version: number;
     exportedAt: string;
     pages: StoredPage[];

package/dist/bookFolder.d.ts

@@ -3,7 +3,7 @@ import type { StoredDatabase } from './database';
 /**
  * Whole-space → folder-of-files serialisation, shared by every "dump my books
  * to a folder" surface: the desktop's native folder export and the web app's
- * File System Access export both call {@link spaceToBookFiles}, and the layout
+ * File System Access export both call {@link libraryToBookFiles}, and the layout
  * is byte-compatible with the server's on-disk {@link BookMirror} (OB-134) so a
  * folder written by one can be re-imported by the other.
  *
@@ -19,33 +19,49 @@ export interface BookFolderFile {
     path: string;
     contents: string;
 }
-/** Everything in a space, as returned by `DataClient.exportSpace`. */
-export interface SpaceSnapshot {
+/** Everything in a space, as returned by `DataClient.exportLibrary`. */
+export interface LibrarySnapshot {
     pages: StoredPage[];
     databases: StoredDatabase[];
 }
-/** Lossless structured sidecar, parsed back by {@link parseBookFolder}. */
-export declare const SPACE_BUNDLE_FILE = "openbook.space.json";
+/**
+ * Lossless structured sidecar filename that NEW exports write, parsed back by
+ * {@link parseBookFolder}. Renamed from the legacy `openbook.space.json`
+ * (LIB-4): the writer emits only this, while the reader also accepts
+ * {@link LEGACY_SPACE_BUNDLE_FILE} so folders exported before the rename still
+ * re-import losslessly.
+ */
+export declare const SPACE_BUNDLE_FILE = "openbook.library.json";
+/**
+ * The pre-LIB-4 sidecar filename. READ-ONLY back-compat: {@link parseBookFolder}
+ * falls back to it so already-exported book folders keep importing. The writer
+ * never emits it.
+ */
+export declare const LEGACY_SPACE_BUNDLE_FILE = "openbook.space.json";
 /**
  * The whole-space **source-island** payload embedded in a standalone *site* HTML
- * export: the full {@link SpaceSnapshot} (pages + databases + nesting via each
+ * export: the full {@link LibrarySnapshot} (pages + databases + nesting via each
  * page's `parentId`/`databaseId`) plus the root id shown first. Same structure as
  * {@link SPACE_BUNDLE_FILE}, so a site export re-imports with structure intact.
  */
-export interface SpaceIsland {
+export interface LibraryIsland {
     version: 1;
     rootId: string;
-    space: SpaceSnapshot;
+    space: LibrarySnapshot;
 }
 /** Wrap a whole-space bundle as its source-island `<script>` (versioned, escaped). */
-export declare function spaceIslandScript(rootId: string, space: SpaceSnapshot, opts?: {
+export declare function libraryIslandScript(rootId: string, space: LibrarySnapshot, opts?: {
     attrs?: string;
     indent?: string;
 }): string;
-/** Read a site export's space island back, or `null` when absent/corrupt. */
-export declare function readSpaceIsland(html: string): SpaceIsland | null;
-/** Options for {@link spaceToBookFiles}. */
-export interface SpaceToBookFilesOptions {
+/**
+ * Read a site export's space island back, or `null` when absent/corrupt.
+ * Dual-read: prefer the new `library` key, fall back to the legacy `space` key
+ * so bundles published before LIB-4 still import.
+ */
+export declare function readLibraryIsland(html: string): LibraryIsland | null;
+/** Options for {@link libraryToBookFiles}. */
+export interface LibraryToBookFilesOptions {
     /** Include the lossless {@link SPACE_BUNDLE_FILE} sidecar. Default true. */
     includeBundle?: boolean;
     /**
@@ -63,14 +79,15 @@ export interface SpaceToBookFilesOptions {
  * Serialise a space to its on-disk files. By default includes the lossless
  * {@link SPACE_BUNDLE_FILE}; pass `includeBundle: false` for the human-readable
  * HTML files only. Pass `runtime` (the viewer bundle source) to make the folder
- * self-hydrating — see {@link SpaceToBookFilesOptions.runtime}.
+ * self-hydrating — see {@link LibraryToBookFilesOptions.runtime}.
  */
-export declare function spaceToBookFiles(snapshot: SpaceSnapshot, opts?: SpaceToBookFilesOptions): BookFolderFile[];
+export declare function libraryToBookFiles(snapshot: LibrarySnapshot, opts?: LibraryToBookFilesOptions): BookFolderFile[];
 /**
- * Reconstruct a space from a folder's files. Prefers the lossless
- * {@link SPACE_BUNDLE_FILE} when present; otherwise falls back to parsing the
- * `.html` files into a flat list of pages (no databases, no nesting — the most
- * a human-readable folder can recover). Returns `null` if nothing parseable was
- * found, so the caller can surface "not an OpenBook folder".
+ * Reconstruct a space from a folder's files. Prefers the lossless structured
+ * sidecar ({@link SPACE_BUNDLE_FILE}, or the legacy {@link LEGACY_SPACE_BUNDLE_FILE}
+ * for folders exported before LIB-4) when present; otherwise falls back to
+ * parsing the `.html` files into a flat list of pages (no databases, no nesting
+ * — the most a human-readable folder can recover). Returns `null` if nothing
+ * parseable was found, so the caller can surface "not an OpenBook folder".
  */
-export declare function parseBookFolder(files: BookFolderFile[]): SpaceSnapshot | null;
+export declare function parseBookFolder(files: BookFolderFile[]): LibrarySnapshot | null;

package/dist/bookFolder.js

@@ -1,22 +1,40 @@
 import { pageToBookHtml, bookHtmlToPage, slugify, BOOK_RUNTIME_FILE } from './bookfile';
 import { islandScript, readIsland } from './island';
-/** Lossless structured sidecar, parsed back by {@link parseBookFolder}. */
-export const SPACE_BUNDLE_FILE = 'openbook.space.json';
+/**
+ * Lossless structured sidecar filename that NEW exports write, parsed back by
+ * {@link parseBookFolder}. Renamed from the legacy `openbook.space.json`
+ * (LIB-4): the writer emits only this, while the reader also accepts
+ * {@link LEGACY_SPACE_BUNDLE_FILE} so folders exported before the rename still
+ * re-import losslessly.
+ */
+export const SPACE_BUNDLE_FILE = 'openbook.library.json';
+/**
+ * The pre-LIB-4 sidecar filename. READ-ONLY back-compat: {@link parseBookFolder}
+ * falls back to it so already-exported book folders keep importing. The writer
+ * never emits it.
+ */
+export const LEGACY_SPACE_BUNDLE_FILE = 'openbook.space.json';
 /** Wrap a whole-space bundle as its source-island `<script>` (versioned, escaped). */
-export function spaceIslandScript(rootId, space, opts = {}) {
-    return islandScript({ version: 1, rootId, space }, opts);
+export function libraryIslandScript(rootId, space, opts = {}) {
+    // Writer emits ONLY the new `library` key; the reader dual-reads for back-compat.
+    return islandScript({ version: 1, rootId, library: space }, opts);
 }
-/** Read a site export's space island back, or `null` when absent/corrupt. */
-export function readSpaceIsland(html) {
+/**
+ * Read a site export's space island back, or `null` when absent/corrupt.
+ * Dual-read: prefer the new `library` key, fall back to the legacy `space` key
+ * so bundles published before LIB-4 still import.
+ */
+export function readLibraryIsland(html) {
     const parsed = readIsland(html);
-    if (!parsed || !parsed.space || !Array.isArray(parsed.space.pages))
+    const bundle = parsed?.library ?? parsed?.space;
+    if (!bundle || !Array.isArray(bundle.pages))
         return null;
     return {
         version: 1,
-        rootId: parsed.rootId ?? '',
+        rootId: parsed?.rootId ?? '',
         space: {
-            pages: parsed.space.pages,
-            databases: Array.isArray(parsed.space.databases) ? parsed.space.databases : [],
+            pages: bundle.pages,
+            databases: Array.isArray(bundle.databases) ? bundle.databases : [],
         },
     };
 }
@@ -47,9 +65,9 @@ function rootOf(page, byId, dbHost) {
  * Serialise a space to its on-disk files. By default includes the lossless
  * {@link SPACE_BUNDLE_FILE}; pass `includeBundle: false` for the human-readable
  * HTML files only. Pass `runtime` (the viewer bundle source) to make the folder
- * self-hydrating — see {@link SpaceToBookFilesOptions.runtime}.
+ * self-hydrating — see {@link LibraryToBookFilesOptions.runtime}.
  */
-export function spaceToBookFiles(snapshot, opts = {}) {
+export function libraryToBookFiles(snapshot, opts = {}) {
     const { pages, databases } = snapshot;
     const byId = new Map(pages.map((p) => [p.id, p]));
     const dbHost = new Map(databases.map((d) => [d.id, d.pageId]));
@@ -73,15 +91,21 @@ export function spaceToBookFiles(snapshot, opts = {}) {
     }
     return files;
 }
+/** Match a sidecar file by basename — the new name first, then the legacy one. */
+const isSpaceBundleFile = (path) => path === SPACE_BUNDLE_FILE ||
+    path.endsWith(`/${SPACE_BUNDLE_FILE}`) ||
+    path === LEGACY_SPACE_BUNDLE_FILE ||
+    path.endsWith(`/${LEGACY_SPACE_BUNDLE_FILE}`);
 /**
- * Reconstruct a space from a folder's files. Prefers the lossless
- * {@link SPACE_BUNDLE_FILE} when present; otherwise falls back to parsing the
- * `.html` files into a flat list of pages (no databases, no nesting — the most
- * a human-readable folder can recover). Returns `null` if nothing parseable was
- * found, so the caller can surface "not an OpenBook folder".
+ * Reconstruct a space from a folder's files. Prefers the lossless structured
+ * sidecar ({@link SPACE_BUNDLE_FILE}, or the legacy {@link LEGACY_SPACE_BUNDLE_FILE}
+ * for folders exported before LIB-4) when present; otherwise falls back to
+ * parsing the `.html` files into a flat list of pages (no databases, no nesting
+ * — the most a human-readable folder can recover). Returns `null` if nothing
+ * parseable was found, so the caller can surface "not an OpenBook folder".
  */
 export function parseBookFolder(files) {
-    const bundle = files.find((f) => f.path === SPACE_BUNDLE_FILE || f.path.endsWith(`/${SPACE_BUNDLE_FILE}`));
+    const bundle = files.find((f) => isSpaceBundleFile(f.path));
     if (bundle) {
         try {
             const parsed = JSON.parse(bundle.contents);

package/dist/bookFolder.js.map

@@ -1 +1 @@
-{"version":3,"file":"bookFolder.js","sourceRoot":"","sources":["../src/bookFolder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bookFolder.js","sourceRoot":"","sources":["../src/bookFolder.ts"],"names":[],"mappings":"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"}

package/dist/bookfile.d.ts

@@ -121,7 +121,7 @@ export interface BookHtmlOptions {
      * Reference the folder's shared viewer runtime (`_openbook/viewer.js`) so the
      * file, opened directly in a browser, hydrates into the interactive locked
      * viewer. Pass true ONLY when the writer also ships the bundle into the folder
-     * (sdk `spaceToBookFiles({runtime})` / server `BookMirror` with `runtimeBundle`)
+     * (sdk `libraryToBookFiles({runtime})` / server `BookMirror` with `runtimeBundle`)
      * — a reference without the bundle degrades gracefully (static article), but
      * writers keep the invariant anyway. Emitters MUST agree on this flag for the
      * SDK/server byte-compatibility contract to hold.

package/dist/client.d.ts

@@ -1,8 +1,9 @@
 import { type CompactResult } from './routes';
 import type { PluginPackage, StoredPlugin } from './plugins';
-import type { AgentChatEvent, AgentChatMessage, AgentChatOptions, AiConfig, AiPricingResponse, AiPricingTable, AiUsageResponse, AiSearchResponse, AiSkill, AiStatus, AiTasksResponse } from './ai';
+import type { AgentChatEvent, AgentChatMessage, AgentChatOptions, AiConfig, AiPricingResponse, AiPricingTable, AiUsageResponse, AiSearchResponse, AiSkill, AiStatus, AiTasksResponse, McpClientConfig, McpConfigResponse, McpServerConfig, McpTestResult } from './ai';
 import type { AclLevel, Member, MemberRole, MemberStatus, PageAcl, PageInput, PageMeta, PageVisibility, StoredPage } from './types';
 import type { InstanceConfig, InstanceInfo, StoredEdit } from './provenance';
+import type { AgentTokenMeta, AgentTokenScope } from './identity';
 import type { BackupCadence, BackupConfig, BackupStatus, ImportRequest, ImportResult } from './backup';
 import type { DatabaseInput, DatabaseRow, DatabaseUpdate, RowInput, RowUpdate, StoredDatabase } from './database';
 import type { CommentInput, StoredComment, StoredSuggestion, SuggestionInput, SuggestionStatus, SuggestionUpdate } from './suggestions';
@@ -13,6 +14,23 @@ export interface PageSubscription {
     /** The page was deleted. */
     onDeleted?: (id: string) => void;
 }
+/** Input to {@link DataClient.createAgentToken}. `scope` defaults to `read`;
+ *  `expiresInDays` defaults to 90 server-side, and `null` mints a no-expiry token. */
+export interface CreateAgentTokenInput {
+    name: string;
+    scope?: AgentTokenScope;
+    expiresInDays?: number | null;
+}
+/** The one-time create response: the plaintext `token` (shown ONCE) + its meta. */
+export interface CreatedAgentToken {
+    token: string;
+    meta: AgentTokenMeta;
+}
+/** The agent-token management view: the dark `agentApi` on/off state + the list. */
+export interface AgentTokenList {
+    enabled: boolean;
+    tokens: AgentTokenMeta[];
+}
 /**
  * Storage-agnostic data access used by the document UI.
  *
@@ -90,6 +108,16 @@ export interface DataClient {
     setAiUsageRetention(days: number): Promise<{
         days: number;
     }>;
+    /** Read the external-tools (MCP client) config (admin only): redacted config +
+     *  whether the stdio transport is permitted on this instance. */
+    getMcpConfig(): Promise<McpConfigResponse>;
+    /** Save the external-tools (MCP client) config (admin only). Auth tokens are
+     *  write-only (omit/blank preserves, a value sets, `null` clears). Returns the
+     *  redacted result. */
+    putMcpConfig(config: McpClientConfig): Promise<McpConfigResponse>;
+    /** Dry-run one MCP server config (admin only): connect + list tools; never
+     *  returns secrets. */
+    testMcpServer(server: McpServerConfig): Promise<McpTestResult>;
     listPlugins(): Promise<StoredPlugin[]>;
     installPlugin(pkg: PluginPackage): Promise<StoredPlugin>;
     setPluginEnabled(id: string, enabled: boolean): Promise<StoredPlugin>;
@@ -101,12 +129,12 @@ export interface DataClient {
      */
     deletePage(id: string): Promise<boolean>;
     /** Export the whole space: every live page (full data) + every database. */
-    exportSpace(): Promise<{
+    exportLibrary(): Promise<{
         pages: StoredPage[];
         databases: StoredDatabase[];
     }>;
     /** Restore a (client-selected) set of pages/databases; see {@link ImportRequest}. */
-    importSpace(req: ImportRequest): Promise<ImportResult>;
+    importLibrary(req: ImportRequest): Promise<ImportResult>;
     /** List the trash (most-recently-deleted first). */
     listTrash(): Promise<PageMeta[]>;
     /** Restore a trashed page, or `null` if it isn't in the trash. */
@@ -269,6 +297,17 @@ export interface DataClient {
     }): Promise<Member>;
     /** Revoke a roster row by id. `true` if one was removed. */
     removeMember(id: string): Promise<boolean>;
+    /** List minted agent tokens (redacted) plus the dark `agentApi` on/off state. */
+    listAgentTokens(): Promise<AgentTokenList>;
+    /** Toggle the dark `agentApi` setting on/off. Returns the new state. */
+    setAgentApiEnabled(enabled: boolean): Promise<{
+        enabled: boolean;
+    }>;
+    /** Mint a token (requires `agentApi` enabled). The plaintext `token` comes back
+     *  exactly ONCE — store it now; only its hash is kept server-side. */
+    createAgentToken(input: CreateAgentTokenInput): Promise<CreatedAgentToken>;
+    /** Revoke a token by id. `true` if one was removed. */
+    revokeAgentToken(id: string): Promise<boolean>;
     /** Scheduled-backup policy + per-cadence status. */
     getBackupStatus(): Promise<BackupStatus>;
     /** Update the backup policy (enable, cadences, retention, folder). Owner-only. */
@@ -404,11 +443,11 @@ export declare class HttpDataClient implements DataClient {
         orderedIds: string[];
     }): Promise<StoredPage>;
     deletePage(id: string): Promise<boolean>;
-    exportSpace(): Promise<{
+    exportLibrary(): Promise<{
         pages: StoredPage[];
         databases: StoredDatabase[];
     }>;
-    importSpace(req: ImportRequest): Promise<ImportResult>;
+    importLibrary(req: ImportRequest): Promise<ImportResult>;
     listTrash(): Promise<PageMeta[]>;
     restorePage(id: string): Promise<StoredPage | null>;
     purgePage(id: string): Promise<boolean>;
@@ -501,6 +540,12 @@ export declare class HttpDataClient implements DataClient {
     }): Promise<Member>;
     /** Revoke a roster row by id. `true` if one was removed. */
     removeMember(id: string): Promise<boolean>;
+    listAgentTokens(): Promise<AgentTokenList>;
+    setAgentApiEnabled(enabled: boolean): Promise<{
+        enabled: boolean;
+    }>;
+    createAgentToken(input: CreateAgentTokenInput): Promise<CreatedAgentToken>;
+    revokeAgentToken(id: string): Promise<boolean>;
     /** A page's stored visibility scope (raw — `inherit` not yet resolved), or
      *  `null` if the page does not exist. Gated on read of the page. */
     getPageVisibility(pageId: string): Promise<PageVisibility | null>;
@@ -554,6 +599,9 @@ export declare class HttpDataClient implements DataClient {
     aiDeleteSkill(name: string): Promise<boolean>;
     getAiPricing(): Promise<AiPricingResponse>;
     setAiPricing(override: AiPricingTable): Promise<AiPricingResponse>;
+    getMcpConfig(): Promise<McpConfigResponse>;
+    putMcpConfig(config: McpClientConfig): Promise<McpConfigResponse>;
+    testMcpServer(server: McpServerConfig): Promise<McpTestResult>;
     getAiUsage(): Promise<AiUsageResponse>;
     setAiUsageRetention(days: number): Promise<{
         days: number;