@json-to-office/mcp-server 1.5.0 → 1.8.0

package/dist/index.d.ts

@@ -338,8 +338,18 @@ declare function createOutputRoot(options?: OutputRootOptions): OutputRoot;
  * failures (see `errors.ts`).
  */
 
+/**
+ * A success may still have something to say.
+ *
+ * `warnings` is how a store reports what did not go wrong enough to fail the
+ * call — a revision that did not reach disk (#290) being the case that
+ * matters: the edit landed, the handle works, and the agent still needs to
+ * know it has stopped being recoverable. Tools fold these into the
+ * `diagnostics` of the result they were already returning.
+ */
 type WorkspaceResult<T> = ({
     ok: true;
+    warnings?: Diagnostic[];
 } & T) | Failure;
 /** RFC 6902 operation. Paths are RFC 6901 pointers — no private dialect (#271). */
 interface JsonPatchOperation {
@@ -363,6 +373,11 @@ interface WorkspaceRecord {
     title?: string;
     /** Revisions pinned by `snapshot`, still retrievable through `get`. */
     pinnedRevisions: number[];
+    /**
+     * Whether this revision is on disk and so survives the connection (#290).
+     * Absent when the store has no durable backing at all, which is the default.
+     */
+    persisted?: boolean;
 }
 interface WorkspaceStore {
     /**
@@ -436,7 +451,9 @@ interface WorkspaceStore {
      *
      * A connection's store is reachable only through its `ToolDeps`, so the
      * documents go when the connection's deps do; this is for a host that wants
-     * the memory back at a moment of its own choosing.
+     * the memory back at a moment of its own choosing. It releases memory only —
+     * a durable store keeps its copies, because an event that ends a connection
+     * is exactly what #290 stops being fatal.
      */
     closeAll(): Promise<void>;
 }
@@ -452,6 +469,140 @@ declare const unavailableWorkspaceStore: WorkspaceStore;
 declare function setWorkspaceStore(store: WorkspaceStore | undefined): void;
 declare function getWorkspaceStore(): WorkspaceStore;
 
+/**
+ * Disk backing for workspaces (#290).
+ *
+ * #271 made the document JSON authoritative and then kept it in exactly one
+ * place: server memory. Anything that ends a connection — a host session
+ * reset, a client restart, a crash — took every revision with it, and
+ * `jto_workspace_snapshot` did not help because the pins lived in the same
+ * `Map`. This module is the durable half: memory stays the fast path and the
+ * only thing tools read from, and every committed revision is mirrored here so
+ * a reconnecting client can resume instead of re-authoring.
+ *
+ * Off unless a root is configured (`--workspace-dir`, `JTO_MCP_WORKSPACE_DIR`),
+ * because turning handles durable turns them cross-connection, and a server
+ * that started leaving documents on a user's disk without being asked would be
+ * a surprise rather than a feature.
+ *
+ * Three properties the layout is chosen for:
+ *
+ * - Crash safety. A revision file is written and renamed into place BEFORE the
+ *   metadata that names it, so `meta.json` never points at bytes that are not
+ *   there. Interrupt this at any point and what is on disk is either the old
+ *   revision or the new one, never half of either.
+ * - Cheap listing. Recovering handles after a reset reads one small
+ *   `meta.json` per workspace; the documents are only paid for when a handle
+ *   is actually used.
+ * - No caller-named paths. A handle is the only thing that reaches the
+ *   filesystem, and it is matched against a whitelist first, so nothing a
+ *   client sends can address a directory of its choosing.
+ *
+ * Nothing here is a tool result, so these functions throw rather than return
+ * diagnostics; the store catches and downgrades a write failure to a warning
+ * (`W_WORKSPACE_NOT_PERSISTED`), because losing durability is worth saying out
+ * loud and is never worth failing an edit over.
+ *
+ * Not a concurrency layer. Individual writes are atomic, so a root two
+ * connections share never tears — but each holds its own memory copy of an
+ * entry, and the second to commit a revision is the one on disk. The intended
+ * arrangement is one root per client, which is what a reconnect is.
+ */
+
+/** Env var that names the workspace root, below the `--workspace-dir` flag. */
+declare const WORKSPACE_DIR_ENV = "JTO_MCP_WORKSPACE_DIR";
+interface PersistenceLimits {
+    /** Workspaces kept on disk; the least recently updated go first. */
+    maxWorkspaces: number;
+    /** Revision files per workspace — the head plus its pinned revisions. */
+    maxRevisionsPerWorkspace: number;
+    /** Ceiling for a single revision file. */
+    maxEntryBytes: number;
+}
+/**
+ * Roomier than the memory limits on purpose.
+ *
+ * Memory bounds protect a process; these bound a directory that outlives it,
+ * where the cost of keeping a document is a few hundred kilobytes of disk and
+ * the cost of dropping one is authoring an agent has to redo. `maxWorkspaces`
+ * is twice the memory ceiling so a reconnecting client still finds what the
+ * previous connection had open, and the revision cap is the head plus the
+ * default eight pins, so a default setup never has to discard a pin it took.
+ */
+declare const DEFAULT_PERSISTENCE_LIMITS: PersistenceLimits;
+/** One retained revision: the serialized document and its size. */
+interface PersistedDocument {
+    revision: number;
+    text: string;
+    bytes: number;
+}
+/** What the store hands over to be made durable. */
+interface PersistedSnapshot {
+    handle: string;
+    format: FormatName;
+    createdAt: number;
+    updatedAt: number;
+    title?: string;
+    /** The current revision. */
+    head: PersistedDocument;
+    /** Revisions pinned by `snapshot`, oldest first. */
+    pins: readonly PersistedDocument[];
+}
+/** A workspace as `list` reports it, without paying for the documents. */
+interface PersistedMeta {
+    handle: string;
+    format: FormatName;
+    revision: number;
+    bytes: number;
+    createdAt: number;
+    updatedAt: number;
+    title?: string;
+    pinnedRevisions: number[];
+}
+/** A workspace read back whole, ready to become a live entry again. */
+interface RestoredWorkspace extends PersistedMeta {
+    head: PersistedDocument;
+    pins: PersistedDocument[];
+}
+interface WorkspacePersistence {
+    /** Absolute path of the root. May not exist on disk until first write. */
+    readonly root: string;
+    readonly limits: PersistenceLimits;
+    /** Mirror a workspace's current state. Overwrites whatever was there. */
+    save(snapshot: PersistedSnapshot): Promise<void>;
+    /** Everything on disk, newest update first. Corrupt entries are skipped. */
+    list(): Promise<PersistedMeta[]>;
+    /** One workspace, documents included, or undefined when it is not there. */
+    load(handle: string): Promise<RestoredWorkspace | undefined>;
+    /**
+     * Forget a workspace durably. Idempotent; answers whether anything was
+     * there, which is how `close` reports a handle it only ever saw on disk.
+     *
+     * Throws when the directory is there and could not be deleted. That has to
+     * reach the caller: `jto_workspace_close` promises the document is gone, and
+     * a swallowed failure would report it closed while the JSON stayed readable
+     * by the next connection to use the handle.
+     */
+    remove(handle: string): Promise<boolean>;
+}
+interface WorkspacePersistenceOptions extends Partial<PersistenceLimits> {
+    /** `--workspace-dir` value, highest precedence. */
+    flagDir?: string;
+    /** Defaults to `process.env`; injectable so the precedence is testable. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Build the persistence layer, or answer `undefined` when none was configured.
+ *
+ * `undefined` rather than a no-op implementation: the store branches on
+ * whether it has durability at all — to decide what `jto_info` reports and
+ * whether an evicted handle is recoverable — and a stand-in that quietly
+ * discarded writes would make that question unanswerable.
+ */
+declare function createWorkspacePersistence(options?: WorkspacePersistenceOptions): WorkspacePersistence | undefined;
+/** The same layer on an explicit directory, for hosts and tests. */
+declare function createWorkspacePersistenceAt(root: string, limits?: Partial<PersistenceLimits>): WorkspacePersistence;
+
 /**
  * What every tool module is handed at registration.
  *
@@ -474,6 +625,15 @@ interface ToolDeps {
      * registered, and a snapshot taken at registration would pin the stand-in.
      */
     workspaces(): WorkspaceStore;
+    /**
+     * Disk backing for that store (#290), when a root was configured.
+     *
+     * Undefined is the default and means memory-only handles. It lives here
+     * rather than inside the store because `tools/workspace.ts` is what builds
+     * the connection's store, and `jto_info` reports the root without touching
+     * one.
+     */
+    workspacePersistence?: WorkspacePersistence;
     /** Ceiling for `outputMode: 'base64'`, in bytes. */
     maxInlineArtifactBytes: number;
 }
@@ -481,6 +641,10 @@ interface CreateToolDepsOptions {
     /** `--output-dir`, or an already-built root (tests hand one in). */
     outputDir?: string;
     outputRoot?: OutputRoot;
+    /** `--workspace-dir`. Absent, `JTO_MCP_WORKSPACE_DIR` decides. */
+    workspaceDir?: string;
+    /** An already-built persistence layer, for hosts and tests. */
+    workspacePersistence?: WorkspacePersistence;
     env?: NodeJS.ProcessEnv;
     serverVersion?: string;
     workspaces?: () => WorkspaceStore;
@@ -724,10 +888,112 @@ declare function parseDocumentJson(text: string, path?: string): {
     document: unknown;
 } | Failure;
 
+/**
+ * The in-memory workspace store (#271).
+ *
+ * Documents are held as **serialized JSON text**, not as live trees. That one
+ * decision buys three of the issue's requirements outright:
+ *
+ * - Isolation. A read is a fresh `JSON.parse`, so a caller can mutate what it
+ *   got and two workspaces can never share a subtree — the structural-sharing
+ *   bug this feature invites cannot be written.
+ * - Atomicity. A commit is a single string assignment after a successful
+ *   apply; a patch that fails leaves the stored bytes untouched, literally.
+ * - Accounting. `bytes` is the real size, already computed, so the count and
+ *   byte budgets are exact rather than estimated.
+ *
+ * The cost is a parse and a stringify per operation, which for documents in
+ * the tens to hundreds of kilobytes this format produces is far below the
+ * round trip that made the agent call us.
+ *
+ * Nothing here throws: an unknown handle, a stale revision and a full store
+ * are answers an agent repairs, so they come back as structured failures
+ * (`lib/errors.ts`) exactly like a bad document does.
+ */
+
+/**
+ * Workspace-lifecycle codes.
+ *
+ * Kept here rather than in `lib/errors.ts` (owned by #203, edited
+ * concurrently); they read as ordinary diagnostic codes to a client. TTL
+ * eviction gets its own code rather than reusing `E_UNKNOWN_HANDLE` because
+ * an agent can reopen and carry on after an idle handle expires.
+ */
+declare const WORKSPACE_ERROR_CODES: {
+    readonly EVICTED: "E_WORKSPACE_EVICTED";
+    readonly LIMIT: "E_WORKSPACE_LIMIT";
+    readonly DOCUMENT_TOO_LARGE: "E_DOCUMENT_TOO_LARGE";
+    readonly INVALID_ROOT: "E_INVALID_DOCUMENT_ROOT";
+    /**
+     * A revision could not be mirrored to disk (#290). A warning, never a
+     * failure: the edit landed and the workspace is usable, but this connection
+     * has stopped being survivable and saying so is the whole point.
+     */
+    readonly NOT_PERSISTED: "W_WORKSPACE_NOT_PERSISTED";
+    /**
+     * A close could not delete the durable copy, so nothing was released (#290).
+     * An error rather than a warning: the agent asked for the document to be
+     * destroyed, and it is still there to be read by the next connection.
+     */
+    readonly NOT_CLOSED: "E_WORKSPACE_NOT_CLOSED";
+};
+interface WorkspaceLimits {
+    /** Open documents at once. */
+    maxWorkspaces: number;
+    /** Ceiling for a single serialized document. */
+    maxDocumentBytes: number;
+    /** Ceiling for every document and pinned snapshot together. */
+    maxTotalBytes: number;
+    /** Idle time after which a handle is dropped. Any read or write resets it. */
+    idleTtlMs: number;
+    /** Snapshots kept retrievable per workspace; new pins are refused at the cap. */
+    maxPinnedRevisions: number;
+}
+/**
+ * Deliberately modest.
+ *
+ * A workspace is a live authoring buffer for one agent on one stdio
+ * connection, not a document store: sixteen open documents is already more
+ * than an agent can hold in context, and the byte ceilings exist to stop a
+ * runaway loop from turning a helper process into the machine's memory
+ * problem. The idle TTL is half an hour because an agent's turn can stall on a
+ * human for a long while, and losing a document mid-conversation is worse than
+ * holding a few megabytes.
+ */
+declare const DEFAULT_WORKSPACE_LIMITS: WorkspaceLimits;
+interface MemoryWorkspaceStoreOptions extends Partial<WorkspaceLimits> {
+    /** Injectable clock; the TTL suite drives it instead of waiting. */
+    now?: () => number;
+    /** Injectable handle source, for tests that need predictable handles. */
+    newHandle?: () => string;
+    /**
+     * Disk backing (#290). Absent is the historical behaviour: memory only, and
+     * everything goes when the connection does.
+     */
+    persistence?: WorkspacePersistence;
+}
+interface MemoryWorkspaceStore extends WorkspaceStore {
+    readonly limits: WorkspaceLimits;
+    /** Live totals, for `jto_workspace_list` to show the agent its budget. */
+    usage(): {
+        workspaces: number;
+        bytes: number;
+    };
+    /**
+     * Where revisions survive the connection, when a root was configured.
+     * Absent means handles are memory-only and end with this process (#290).
+     */
+    readonly persistence?: {
+        root: string;
+        limits: PersistenceLimits;
+    };
+}
+declare function createMemoryWorkspaceStore(options?: MemoryWorkspaceStoreOptions): MemoryWorkspaceStore;
+
 declare const SERVER_VERSION: string;
 /** MCP `serverInfo.name`. Stable: clients key configuration off it. */
 declare const SERVER_NAME = "json-to-office";
 /** npm identity, reported by `jto_info` next to the workspace packages. */
 declare const PACKAGE_NAME = "@json-to-office/mcp-server";
 
-export { type Artifact, type ArtifactMode, type ArtifactOutputInput, type CreateToolDepsOptions, DOCUMENT_SOURCE_RULE, type DeliverArtifactOptions, type DeliverArtifactResult, type Diagnostic, type DiagnosticCounts, type DiagnosticSeverity, type DocumentSourceInput, ERROR_CODES, type ErrorCode, FORMAT_NAMES, type Failure, type JsonPatchOperation, MAX_INLINE_ARTIFACT_BYTES, MIME_TYPES, OPTION_ERROR_CODES, OUTPUT_DIR_ENV, type OutputRoot, type OutputRootOptions, PACKAGE_NAME, type RenderOptionsInput, type ResolvedDocument, type ResolvedOutputPath, S, SERVER_INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, type SourceSummary, type ToolDeps, type ToolEnvelope, type WorkspaceRecord, type WorkspaceResult, type WorkspaceStore, artifactOutputProperties, artifactSchema, checkOutputName, checkRenderer, countDiagnostics, createOutputRoot, createServer, createServerFactory, createToolDeps, deliverArtifact, diagnostic, diagnosticSchema, diagnosticsFromThrown, diagnosticsSchema, documentSourceProperties, documentSourceSchema, envelopeProperties, failure, failureFrom, formatSchema, fromValidationError, fromValidationErrors, getAdapter, getWorkspaceStore, guarded, outputSchema, parseDocumentJson, renderOptionProperties, resetAdapters, resolveDocumentSource, setWorkspaceStore, sourceSummary, sourceSummarySchema, success, toJsonPointer, toolResult, unavailableWorkspaceStore, validationDiagnostics, withRenderer };
+export { type Artifact, type ArtifactMode, type ArtifactOutputInput, type CreateToolDepsOptions, DEFAULT_PERSISTENCE_LIMITS, DEFAULT_WORKSPACE_LIMITS, DOCUMENT_SOURCE_RULE, type DeliverArtifactOptions, type DeliverArtifactResult, type Diagnostic, type DiagnosticCounts, type DiagnosticSeverity, type DocumentSourceInput, ERROR_CODES, type ErrorCode, FORMAT_NAMES, type Failure, type JsonPatchOperation, MAX_INLINE_ARTIFACT_BYTES, MIME_TYPES, type MemoryWorkspaceStore, type MemoryWorkspaceStoreOptions, OPTION_ERROR_CODES, OUTPUT_DIR_ENV, type OutputRoot, type OutputRootOptions, PACKAGE_NAME, type PersistenceLimits, type RenderOptionsInput, type ResolvedDocument, type ResolvedOutputPath, S, SERVER_INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, type SourceSummary, type ToolDeps, type ToolEnvelope, WORKSPACE_DIR_ENV, WORKSPACE_ERROR_CODES, type WorkspaceLimits, type WorkspacePersistence, type WorkspacePersistenceOptions, type WorkspaceRecord, type WorkspaceResult, type WorkspaceStore, artifactOutputProperties, artifactSchema, checkOutputName, checkRenderer, countDiagnostics, createMemoryWorkspaceStore, createOutputRoot, createServer, createServerFactory, createToolDeps, createWorkspacePersistence, createWorkspacePersistenceAt, deliverArtifact, diagnostic, diagnosticSchema, diagnosticsFromThrown, diagnosticsSchema, documentSourceProperties, documentSourceSchema, envelopeProperties, failure, failureFrom, formatSchema, fromValidationError, fromValidationErrors, getAdapter, getWorkspaceStore, guarded, outputSchema, parseDocumentJson, renderOptionProperties, resetAdapters, resolveDocumentSource, setWorkspaceStore, sourceSummary, sourceSummarySchema, success, toJsonPointer, toolResult, unavailableWorkspaceStore, validationDiagnostics, withRenderer };