@attentionform/astra-mcp-server 0.0.0-stage → 0.1.0

package/dist/lib/mcp/tool-names.d.ts

@@ -0,0 +1,15 @@
+export declare const MCP_RESEARCH_FLAG = "--with-research";
+/** Legacy helper: reports argv intent only; server startup accepts no such flag. */
+export declare function isResearchEnabled(argv?: readonly string[]): boolean;
+/** Lean-6 tool names (locked, no single_op). */
+export declare const LEAN6_TOOL_NAMES: readonly ["open_document", "inspect_document", "search_content", "execute_batch", "save_document", "close_document"];
+export type Lean6ToolName = (typeof LEAN6_TOOL_NAMES)[number];
+export declare function getLean6ToolNames(): Lean6ToolName[];
+/** Git-history tool names (history browsing + preview + revert + redo; registered alongside lean-6). */
+export declare const GIT_HISTORY_TOOL_NAMES: readonly ["get_document_history", "preview_revert", "revert_document", "redo_document"];
+export type GitHistoryToolName = (typeof GIT_HISTORY_TOOL_NAMES)[number];
+export declare function getGitHistoryToolNames(): GitHistoryToolName[];
+/** Document-audit tool names (read-only preflight + census + scrub + canonical repair + file ingest). */
+export declare const PARITY_TOOL_NAMES: readonly ["validate_document", "get_stats", "sanitize_document", "normalize_document", "import_document"];
+export type ParityToolName = (typeof PARITY_TOOL_NAMES)[number];
+export declare function getParityToolNames(): ParityToolName[];

package/dist/lib/mcp-tool-adapter.d.ts

@@ -0,0 +1,12 @@
+export * from './mcp/normalize-read';
+export * from './mcp/tool-names';
+export * from './mcp/errors';
+export * from './mcp/diff';
+export * from './mcp/descriptions';
+export * from './mcp/schemas';
+export * from './mcp/handlers/open-inspect';
+export * from './mcp/handlers/search-batch';
+export * from './mcp/handlers/save-close';
+export * from './mcp/handlers/history';
+export * from './mcp/handlers/export-audit';
+export * from './mcp/registry';

package/dist/lib/session-store.d.ts

@@ -0,0 +1,422 @@
+import { type DocumentAST, type DocxParserMacroOptions, DocxParser, OperationEngine, ToonGenerator, canonicalizeForAsset as canonicalizeForMcp, type StyleGuideConfig } from '@attentionform/astra-engine';
+/**
+ * Sprint-2 Muse session store (MCP Lean-6 backing).
+ *
+ * Sessions: Map<sessionId,DocHandle> (multi-doc; replaces the single active-document holder).
+ * - LRU 10 docs, 200MB total cap, idle 30min evict.
+ * - Per-session revision (bumped on every successful execute_batch).
+ * - Per-session mutex (each DocHandle owns its lock; no shared global lock).
+ *
+ * There is intentionally no shared module-level instance here:
+ * callers construct their own store via createMcpSessionStore().
+ */
+export declare const MCP_SESSION_MAX_DOCS = 10;
+export declare const MCP_SESSION_MAX_BYTES: number;
+export declare const MCP_SESSION_IDLE_MS: number;
+/**
+ * Redo-stack quotas (per session, in-memory). High defaults so normal
+ * revert/redo chains (1-5 entries, KBs) never hit them; only runaway
+ * rapid-revert loops do. Configurable via store options or env.
+ */
+export declare const SESSION_REDO_MAX_DEPTH = 100;
+export declare const SESSION_REDO_MAX_BYTES: number;
+/** Env overrides for the redo quotas (positive integers, bytes for the latter). */
+export declare const SESSION_REDO_MAX_DEPTH_ENV = "ASTRA_REDO_MAX_DEPTH";
+export declare const SESSION_REDO_MAX_BYTES_ENV = "ASTRA_REDO_MAX_BYTES";
+/** L1 upper clamps: env/explicit values above these are capped (env-driven memory exhaustion). */
+export declare const SESSION_REDO_MAX_DEPTH_CLAMP = 10000;
+export declare const SESSION_REDO_MAX_BYTES_CLAMP: number;
+/** Error code for quota refusals (shared with history sidecar caps). */
+export declare const SESSION_QUOTA_CODE: "E_QUOTA";
+/** Prefix for every server-minted session id (`sess_<uuid>`). */
+export declare const MCP_SESSION_ID_PREFIX = "sess_";
+/** CLI flag enabling deterministic client-supplied ids (tests only, default off). */
+export declare const CLIENT_SESSION_ID_FLAG = "--allow-client-session-ids";
+/** Env var mirroring the flag (accepted values: 1/true, case-insensitive). */
+export declare const CLIENT_SESSION_ID_ENV = "ASTRA_ALLOW_CLIENT_SESSION_IDS";
+export interface McpSessionStoreOptions {
+    maxDocs?: number;
+    maxBytes?: number;
+    idleMs?: number;
+    /** Redo-stack depth cap (entries). Defaults to SESSION_REDO_MAX_DEPTH / env. */
+    redoMaxDepth?: number;
+    /** Redo-stack bytes cap (sum of snapshot bytes). Defaults to SESSION_REDO_MAX_BYTES / env. */
+    redoMaxBytes?: number;
+    /**
+     * Hatch for deterministic ids in tests. Default off: client-supplied
+     * sessionIds are rejected with E_VALIDATION and every open mints
+     * `sess_<uuid>`. Also enabled via --allow-client-session-ids /
+     * ASTRA_ALLOW_CLIENT_SESSION_IDS.
+     */
+    allowClientSessionIds?: boolean;
+}
+/** True when the deterministic-id hatch is enabled via env. */
+export declare function isClientSessionIdHatchEnabledByEnv(env?: NodeJS.ProcessEnv): boolean;
+/** True when argv carries --allow-client-session-ids before any `--` marker. */
+export declare function hasClientSessionIdHatch(argv?: readonly string[]): boolean;
+/** Client-facing rejection for a squatted sessionId (E_VALIDATION + remedy). */
+export declare function buildClientSessionIdRejection(tool: string, raw: unknown): {
+    code: 'E_VALIDATION';
+    message: string;
+    remedy: string;
+};
+/** Resolves the redo depth cap (explicit > env > default). Never below 1. L1: clamped to SESSION_REDO_MAX_DEPTH_CLAMP. */
+export declare function resolveRedoMaxDepth(explicit?: number, env?: NodeJS.ProcessEnv): number;
+/** Resolves the redo bytes cap (explicit > env > default). Never below 1. L1: clamped to SESSION_REDO_MAX_BYTES_CLAMP. */
+export declare function resolveRedoMaxBytes(explicit?: number, env?: NodeJS.ProcessEnv): number;
+/** Byte size of one package snapshot (sum of part lengths). */
+export declare function redoSnapshotByteSize(snap: Map<string, Buffer>): number;
+/** Per-session async mutex (promise-chain, no global lock). */
+export declare class SessionMutex {
+    private tail;
+    private inflight;
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * M1: real locked state (queued + running).
+     * True while any runExclusive section is queued or holding the lock.
+     * Used by closeDocument to fail closed with E_CONFLICT instead of racing
+     * a concurrent batch.
+     */
+    isLocked(): boolean;
+}
+export interface DocHandle {
+    sessionId: string;
+    filePath: string;
+    parser: DocxParser;
+    ast: DocumentAST;
+    engine: OperationEngine;
+    toon: ToonGenerator;
+    revision: number;
+    /**
+     * Phase C: revision at the last successful save_document. dirty =
+     * revision !== savedRevision (in-memory session holds unsaved
+     * execute_batch edits vs the last file written to disk). Set to 1 on
+     * open, re-synced on every successful save.
+     */
+    savedRevision: number;
+    byteSize: number;
+    lastAccess: number;
+    mutex: SessionMutex;
+    /**
+     * History redo stack: full package snapshots captured before each
+     * revert_document restore (newest last). redo_document pops one entry,
+     * restores it, and commits it as a new head. Cleared by the next
+     * successful execute_batch (a fresh edit invalidates the redo chain) and
+     * dropped with the session on close/evict.
+     *
+     * R-2 exactness: entries are immutable pristine copies (the stack
+     * deep-copies every pushed map, so later live-package mutations can never
+     * corrupt a stored source), each bound to the sha256 fingerprint recorded
+     * at push time. A redo must restore EXACTLY the stored pre-revert bytes or
+     * fail with E_STATE (see assertRedoSnapshotExact) — never a third mixed
+     * state. The stack stays Array-compatible (push/pop/index/length) so the
+     * existing session-boundary semantics (cleared on fresh edit, dies with
+     * the session) are unchanged.
+     */
+    redoStack: SessionRedoStack;
+    /**
+     * Audit depth (in-memory, per-session): operations + touched node ids
+     * accumulated since the last successful save/revert/redo. Consumed at the
+     * next history commit to fill the entry's op count + affected node ids,
+     * then reset by markSaved. Best-effort and bounded (never fails a batch);
+     * it dies with the session and is NOT durable history (see the HOLD note
+     * on export_audit_trail: .astra/ itself is deletable local state).
+     */
+    pendingAudit: {
+        ops: number;
+        nodeIds: string[];
+    };
+    /**
+     * Attached style guide ("aesthetic skin"): set at session creation via
+     * new_document/compose_document `styleGuide`, persists for the session,
+     * mirrored onto `engine` so batches inherit it when they omit their own.
+     * Per-batch `styleGuide` overrides apply to that batch only (restored
+     * after). No detach API — open a new session to change guides.
+     */
+    styleGuide?: StyleGuideConfig;
+    /** Raw guide ref the session guide was resolved from (name or file path). */
+    styleGuideRef?: string;
+}
+/**
+ * Per-commit audit metadata recorded alongside each history commit.
+ * Keyed by commit oid in a store-level map (in-memory only: re-opens in a
+ * fresh store lose pre-existing entries, and deleting .astra/ wipes the
+ * underlying history itself — see the HOLD retention note).
+ */
+export interface CommitAuditMeta {
+    author: string;
+    /** Wall-clock epoch millis at commit time (git stamps seconds only). */
+    timestampMs: number;
+    /** Operations folded into this commit (saves: since last save; reverts: steps back; redos: 1). */
+    opCount: number;
+    /** Node ids touched by this commit (bounded, document order, best-effort). */
+    affectedNodeIds: string[];
+}
+/** Cap on affected node ids retained per commit (bounded envelope). */
+export declare const COMMIT_AUDIT_NODE_IDS_MAX = 100;
+/** Cap on commit-meta entries retained per store (bounded ring, oldest dropped). */
+export declare const COMMIT_AUDIT_META_MAX = 2000;
+/** Error code for exact-state violations (redo/restore source diverged). */
+export declare const REDO_EXACTNESS_CODE: "E_STATE";
+/** sha256 hex over one package-part buffer (redo integrity binding). */
+export declare function hashRedoBytes(buf: Buffer): string;
+/** Integrity fingerprint of one full package snapshot (stable key order). */
+export interface RedoSnapshotIntegrity {
+    /** sha256 over word/document.xml bytes ('' when the part is absent). */
+    docXmlHash: string;
+    /** sha256 over every entry (name + bytes, sorted by name). */
+    packageHash: string;
+    /** Sorted entry names captured in the snapshot. */
+    entryNames: string[];
+    /** Total snapshot bytes across all entries. */
+    byteSize: number;
+}
+/** Deep-copies a package snapshot (new map, copied buffers). */
+export declare function clonePackageSnapshot(snap: Map<string, Buffer>): Map<string, Buffer>;
+/** Fingerprints a package snapshot without mutating it. */
+export declare function fingerprintPackageSnapshot(snap: Map<string, Buffer>): RedoSnapshotIntegrity;
+/**
+ * R-2 session-bound redo stack.
+ *
+ * Array-compatible (push/pop/index/length behave like the plain array the
+ * callers already use, including `length = 0` truncation to invalidate the
+ * chain), with two hardening guarantees on top:
+ * - push() stores an immutable pristine copy (later live-package mutations
+ *   can never corrupt the redo source by aliasing);
+ * - every stored copy is bound to the fingerprint recorded at push time,
+ *   retrievable via integrityOf() for exactness proofs.
+ *
+ * Integrity metadata lives in a WeakMap keyed by the stored copy, so
+ * `length = 0` truncation or close/evict simply orphans the metadata (no
+ * parallel-array bookkeeping to go stale) and entries are never shared
+ * back out for mutation.
+ */
+export declare class SessionRedoStack extends Array<Map<string, Buffer>> {
+    private readonly integrity;
+    private readonly maxDepth;
+    private readonly maxBytes;
+    constructor(opts?: {
+        maxDepth?: number;
+        maxBytes?: number;
+    });
+    getMaxDepth(): number;
+    getMaxBytes(): number;
+    /** Sum of stored snapshot bytes (recomputed so pop/length-truncation stay exact). */
+    currentBytes(): number;
+    push(...items: Array<Map<string, Buffer>>): number;
+    /** Newest entry without consuming (undefined when the stack is empty). */
+    peek(): Map<string, Buffer> | undefined;
+    /**
+     * Push-time fingerprint of a stored entry (undefined for foreign maps
+     * that bypassed push, e.g. entries built by hand in tests).
+     */
+    integrityOf(entry: Map<string, Buffer>): RedoSnapshotIntegrity | undefined;
+}
+/**
+ * R-2 exact-or-error check: asserts that a restored live snapshot is
+ * byte-identical to the redo source it must equal (pre-revert on success,
+ * post-revert when the restore was rolled back). Throws E_STATE with a
+ * remedy naming the divergent parts when exact restore is impossible, so
+ * callers fail loudly instead of serving a third mixed state.
+ */
+export declare function assertRedoSnapshotExact(expected: Map<string, Buffer>, actual: Map<string, Buffer>, context: string): void;
+export interface McpSessionStats {
+    sessions: number;
+    totalBytes: number;
+    maxDocs: number;
+    maxBytes: number;
+    idleMs: number;
+}
+/**
+ * M3: workspace jail for MCP document paths.
+ * Mirrors the narrow sandbox (cwd/documents, tmpdir, app Drafts, extra roots)
+ * without importing the template-palette owner's modules (zero overlap).
+ * Every candidate is canonicalized (symlinks/junctions resolved, with
+ * nearest-existing-ancestor fallback for not-yet-created save targets) and
+ * containment is checked on the CANONICAL path.
+ *
+ * H2/D3: `ASTRA_ALLOWED_DIR` is NOT honored here (dropped: roots come only
+ * from explicit `--allowed-dir` flags, which the server entrypoint folds into
+ * `ASTRA_EXTRA_DOC_ROOTS`, plus the fixed base roots below). Any
+ * `ASTRA_ALLOWED_DIR` value in the environment is ignored.
+ * H2: delimiter-split `ASTRA_EXTRA_DOC_ROOTS` entries are existence-checked
+ * (must resolve to an existing directory) before joining the jail — phantom
+ * entries never widen anything. Primitives (`isMcpPathInsideDir`,
+ * `canonicalizeForMcp`) are the Q0a shared module (`@attentionform/astra-engine`
+ * sandbox/paths), so MCP/engine verdicts can never disagree on semantics.
+ */
+export declare function getMcpAllowedRoots(): string[];
+export { canonicalizeForMcp };
+/**
+ * M3: jailed document-path validator.
+ * Returns the resolved absolute path. Throws E_SANDBOX (with remedy) on:
+ * non-string/empty, null byte, line break, `..` traversal, hidden segments,
+ * or canonical location outside the workspace roots. Throws E_VALIDATION on
+ * non-.docx extension. Symlinks/junctions are resolved BEFORE containment.
+ */
+export declare function validateDocPath(rawPath: unknown): string;
+/**
+ * M3: save-target validator (same jail as open).
+ * Save targets that don't exist yet are canonicalized via their nearest
+ * existing ancestor, so a symlinked parent dir pointing outside still fails.
+ */
+export declare function validateSaveTarget(rawPath: unknown): string;
+/**
+ * L4: openBuffer label validator (jails the `.astra` git sidecar).
+ * Absolute labels go through the full `validateDocPath` jail (E_SANDBOX on
+ * escape, E_VALIDATION on non-.docx) so `/etc/x.docx` can never become a
+ * sidecar write at `/etc/.astra/x.docx`. Relative memory labels are
+ * sanitized to a bare `.docx` basename (`memory.docx` fallback) and never
+ * produce an absolute sidecar path (git init skips non-absolute handles).
+ */
+export declare function validateOpenBufferLabel(rawLabel: unknown): string;
+/**
+ * Collects the versioned package extras (media/rels/styles/headers) for git.
+ * document.xml is committed separately; everything matching
+ * isTrackedPackageFile is snapshotted alongside it.
+ */
+export declare function collectTrackedExtrasForGit(parser: DocxParser): Record<string, Buffer>;
+/**
+ * Ensures the sidecar git repo exists for `docPath`, creating it with the
+ * current package state as the initial baseline when absent.
+ * Returns true when the repo already existed, false when freshly created.
+ * Best-effort at open (callers swallow failures so open semantics never
+ * change); hard requirement before commitChange at save/revert/redo.
+ */
+export declare function ensureGitRepo(docPath: string, xml: string, extras: Record<string, Buffer>): Promise<boolean>;
+/** Outcome of McpSessionStore.closeDocument (dirty state read under the delete lock). */
+export interface CloseDocumentOutcome {
+    closed: boolean;
+    /** True when the dropped session held unsaved edits (discarded with the close). */
+    wasDirty: boolean;
+    /** Pending revisions discarded with the close (0 when clean). */
+    discardedRevisions: number;
+}
+export declare class McpSessionStore {
+    private readonly sessions;
+    private readonly maxDocs;
+    private readonly maxBytes;
+    private readonly idleMs;
+    private readonly allowClientSessionIds;
+    private readonly redoMaxDepth;
+    private readonly redoMaxBytes;
+    /**
+     * Phase C-4: ring of sessionIds dropped by eviction (LRU/byte-cap/idle),
+     * so later unknown-session failures can report a capacity-specific
+     * E_SESSION remedy instead of a generic unknown-id error. Explicit
+     * close_document deletes are NOT recorded here. Bounded (last 200).
+     */
+    private readonly evictionHistory;
+    /** Ids evicted by the most recent open (drained by handleOpenDocument for `evicted[]`). */
+    private lastOpenEvicted;
+    /**
+     * Store-level commit audit metadata (oid -> meta). In-memory only: fresh
+     * stores start empty and .astra/ deletion wipes the history it annotates.
+     */
+    private readonly commitMeta;
+    constructor(opts?: McpSessionStoreOptions);
+    getAllowClientSessionIds(): boolean;
+    getMaxDocs(): number;
+    getMaxBytes(): number;
+    getIdleMs(): number;
+    getRedoMaxDepth(): number;
+    getRedoMaxBytes(): number;
+    /** Fresh redo stack bound to this store's quotas. */
+    createRedoStack(): SessionRedoStack;
+    size(): number;
+    totalBytes(): number;
+    getStats(): McpSessionStats;
+    listSessionIds(): string[];
+    /** Evicts sessions idle longer than idleMs. Locked/dirty sessions are refused (never dropped). Returns evicted ids. */
+    evictExpired(now?: number): string[];
+    /** Phase C-4: record evicted ids (bounded ring) for capacity-aware remedies. */
+    private recordEvicted;
+    /** Phase C-4: true when `id` was dropped by eviction (not explicit close). */
+    wasEvicted(sessionId: string): boolean;
+    /**
+     * Phase C-4: ids evicted by the most recent openDocument/openBuffer call.
+     * Drained (cleared) on read so each open reports only its own evictions.
+     */
+    drainLastOpenEvicted(): string[];
+    /** Phase C-1b: true when the in-memory session holds unsaved edits. */
+    isDirty(handle: DocHandle): boolean;
+    /** Phase C-1b: re-syncs the saved marker after a successful save_document. */
+    markSaved(handle: DocHandle): void;
+    /**
+     * Audit depth: appends one batch's footprint to the since-save accumulator.
+     * Dedupes ids, preserves first-seen order, caps the list (best-effort:
+     * never throws, so a batch can never fail on audit bookkeeping).
+     */
+    accumulatePendingAudit(handle: DocHandle, appliedCount: number, nodeIds: readonly string[]): void;
+    /** Clears the since-save audit accumulator (called by markSaved). */
+    resetPendingAudit(handle: DocHandle): void;
+    /** Records per-commit audit metadata (bounded ring; oldest entries dropped). */
+    recordCommitMeta(oid: string, meta: CommitAuditMeta): void;
+    /** Reads per-commit audit metadata (undefined for commits made before tracking). */
+    getCommitMeta(oid: string): CommitAuditMeta | undefined;
+    /** LRU + byte-cap eviction (oldest insertion first). Never evicts `protectId`, locked, or dirty sessions. Returns evicted ids. */
+    private evictToFit;
+    private touch;
+    private newSessionId;
+    /** Mints an id no live session holds (retries on the near-impossible clash). */
+    private mintUniqueSessionId;
+    /**
+     * Resolves the session id for an open: omitted/blank mints a fresh
+     * `sess_<uuid>`; a supplied id is rejected with E_VALIDATION unless the
+     * deterministic-id hatch is on, and an id already held by a live session
+     * fails with E_CONFLICT — the live entry is never replaced.
+     */
+    private resolveOpenSessionId;
+    /**
+     * Opens a .docx file into a new (or reused) session.
+     * Revision starts at 1. LRU/byte/idle eviction runs before insert.
+     * Macro/active content refuses by default (E_VALIDATION naming the parts);
+     * pass {allowMacros:true} to preserve or {stripMacros:true} to strip.
+     */
+    openDocument(filePath: string, sessionId?: string, macroOpts?: DocxParserMacroOptions): Promise<DocHandle>;
+    /**
+     * Opens a document from an in-memory buffer (tests / headless flows).
+     * `labelPath` is the display path recorded on the handle. L4: absolute
+     * labels are jailed through validateDocPath (same jail as open) so a
+     * future production caller cannot turn the `.astra` git sidecar into a
+     * write primitive outside the jail (e.g. label `/etc/x.docx` → sidecar
+     * `/etc/.astra/x.docx`). Relative memory labels (e.g. `memory.docx`) are
+     * sanitized to a bare basename and never touch git (init skips non-absolute
+     * paths). Macro/active content refuses by default; pass {allowMacros:true}
+     * or {stripMacros:true}.
+     */
+    openBuffer(buf: Buffer, labelPath?: string, sessionId?: string, macroOpts?: DocxParserMacroOptions): Promise<DocHandle>;
+    /** Returns the live handle (refreshes LRU). Throws E_SESSION with remedy when missing/expired. */
+    get(sessionId: string): DocHandle;
+    has(sessionId: string): boolean;
+    /**
+     * Runs `fn` under the handle's own mutex (per-session, never global).
+     * Serializes concurrent execute_batch/save races on the same session while
+     * leaving other sessions fully parallel.
+     * H2: re-validates liveness AFTER acquiring the lock — a concurrent
+     * closeDocument that won the race deletes first, and this call fails with
+     * E_CONFLICT (not use-after-close).
+     */
+    withSession<T>(sessionId: string, fn: (handle: DocHandle) => Promise<T>): Promise<T>;
+    /** Bumps the per-session revision after a successful mutation. */
+    bumpRevision(handle: DocHandle): number;
+    /** Best-effort byte-size refresh after mutations (drives the 200MB cap). */
+    refreshByteSize(handle: DocHandle): number;
+    /**
+     * H2: lock-aware close. Acquires the SAME per-session SessionMutex instead
+     * of deleting without a lock (which raced withSession's critical section).
+     * - Unknown id -> { closed: false } (already closed/expired; adapter maps to E_SESSION).
+     * - Session busy (batch/save/inspect holding the lock) -> throws E_CONFLICT
+     *   with remedy (caller retries after the in-flight op finishes).
+     * - Otherwise the delete itself runs under the mutex, so a withSession that
+     *   queued between the busy-check and the delete either sees the live handle
+     *   (if close lost) or fails its post-lock liveness check (if close won).
+     * The outcome names the dropped dirty state (wasDirty + discardedRevisions,
+     * read under the same lock as the delete) so callers never silently lose
+     * unsaved edits: a dirty close warns instead of vanishing quietly.
+     */
+    closeDocument(sessionId: string): Promise<CloseDocumentOutcome>;
+    clear(): void;
+}
+/** Factory (no singleton): each server/test constructs its own store. */
+export declare function createMcpSessionStore(opts?: McpSessionStoreOptions): McpSessionStore;

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

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { type EngineErrorCode, type ResolvedStyleGuide, type StyleGuideConfig, type StyleGuideSummary } from '@attentionform/astra-engine';
+import { type DocHandle, type McpSessionStore } from '../lib/session-store';
+import { type BatchOpCreatedIds } from '../lib/mcp-tool-adapter';
+/** Upper bound on the Markdown source per call (chars). Larger sources should be split by the caller. */
+export declare const COMPOSE_MARKDOWN_MAX = 500000;
+export interface McpGuideJail {
+    /**
+     * Explicit jail directory (already validated against the MCP roots, e.g.
+     * the batch/compose `allowedDir`). Wins over the session anchor.
+     */
+    allowedDir?: string;
+    /**
+     * Session filesystem anchor (absolute open-document path): file guide
+     * refs resolve under its directory (same trust as batch image reads).
+     */
+    sessionFilePath?: string;
+}
+/**
+ * Resolves a `styleGuide` ref under the MCP jail. Named guides resolve to
+ * bundled files (unknown names fail closed E_VALIDATION naming the
+ * available set); file refs resolve under the explicit `allowedDir` else
+ * the session anchor directory; remote URLs fail closed. A file-backed ref
+ * with no anchor (in-memory session, no allowedDir) fails E_SANDBOX —
+ * same rule as batch image `filePath` (never silently cwd-anchored).
+ */
+export declare function resolveMcpStyleGuide(ref: string, jail?: McpGuideJail): ResolvedStyleGuide;
+/**
+ * Attaches a resolved guide to a session (persists for the session,
+ * mirrored onto the session engine so later batches inherit it).
+ */
+export declare function attachSessionStyleGuide(handle: DocHandle, ref: string, resolved: ResolvedStyleGuide): StyleGuideConfig;
+export declare const ComposeDocumentSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    markdown: z.ZodString;
+    allowedDir: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodEnum<{
+        report: "report";
+        memo: "memo";
+        blank: "blank";
+    }>>;
+    styleGuide: z.ZodOptional<z.ZodString>;
+    dollarMath: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ComposeDocumentInput = z.infer<typeof ComposeDocumentSchema>;
+export declare const COMPOSE_DOCUMENT_DESCRIPTION: string;
+type ComposeDocumentOk = {
+    ok: true;
+    sessionId: string;
+    /** Operations the source compiled to (before chunking). */
+    opCount: number;
+    appliedCount: number;
+    revision: number;
+    /** True when the in-memory session differs from the last saved file (always true after a compose). */
+    dirty: boolean;
+    /** New node ids created by this compose, in post-compose document order. */
+    createdNodeIds: string[];
+    /**
+     * Created paragraph ids (`md_0003`) mapped to the w14:paraId the saved file carries (what
+     * a reopened session reports). Absent when nothing mapped; tables have no paraId and are
+     * renumbered by position on reopen.
+     */
+    persistentIds?: Record<string, string>;
+    /** Per-op attribution (same rule as execute_batch: exact id claims, remainder best-effort). */
+    results: BatchOpCreatedIds[];
+    /** Read-only post-compose OOXML verdict (proof the composed package validates; save re-gates before writing). */
+    validation: {
+        valid: boolean;
+        errorCount: number;
+        errors: Array<{
+            description: string;
+            xPath?: string;
+        }>;
+    };
+    skippedIds: string[];
+    warnings: string[];
+    revisionsPending: number;
+    revisionsRemedy?: string;
+    possiblyStaleBodyRefs: {
+        nodeId: string;
+        preview: string;
+    }[];
+    normalized: string[];
+    /** True only when this compose dropped a non-empty redo stack (absent otherwise). */
+    redoCleared?: boolean;
+    /** Names the dropped redo depth (present only when redoCleared). */
+    redoClearedWarning?: string;
+    /** Compact summary of the guide this compose attached (absent when none attached). */
+    styleGuide?: StyleGuideSummary;
+    /** Parser diagnostics of the attached guide (present only when this compose attached one). */
+    styleGuideWarnings?: string[];
+};
+type ComposeDocumentErr = {
+    ok: false;
+    code: EngineErrorCode;
+    message: string;
+    remedy: string;
+};
+/**
+ * Q0b-gap: pure mapper for compose-stage failures (exported for the E-code
+ * contract test). Every engine code survives verbatim via the shared
+ * getEngineErrorCode table; E_VALIDATION stays the fallback for uncoded
+ * failures. Previously E_LIMIT/E_SECURITY/E_DEPENDENCY/E_AUTH collapsed to
+ * E_VALIDATION via the local KNOWN_COMPOSE_CODES allowlist.
+ */
+export declare function composeErrorFrom(err: unknown, fallbackRemedy: string): ComposeDocumentErr;
+/**
+ * Jail check for the asset directory: the resolved canonical location must
+ * sit inside one of the workspace roots. Returns the canonical absolute path.
+ * Throws E_SANDBOX (with remedy) when the directory escapes the roots.
+ */
+export declare function assertPathAllowed(allowedDir: string, roots: string[]): string;
+/**
+ * Compile Markdown and apply it to an open session through the engine compose
+ * path. The compile is pure (runs before the session lock, so input errors
+ * write nothing and touch no session); execution delegates to
+ * `composeDocument` on the session parser (chunked at the engine op cap with
+ * template-seed check, then inline-span run splitting), so the strict schema
+ * gate, quotas, structural checks and per-chunk atomic rollback all apply
+ * exactly as they do for execute_batch, plus spans. Never throws — every
+ * failure maps to {ok:false,code,remedy}.
+ */
+export declare function handleComposeDocument(store: McpSessionStore, rawArgs: unknown): Promise<ComposeDocumentOk | ComposeDocumentErr>;
+export {};

package/dist/tools/export.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { McpSessionStore } from '../lib/session-store';
+import { type PreflightIssue } from '@attentionform/astra-engine';
+export declare const ExportDocumentSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    format: z.ZodEnum<{
+        markdown: "markdown";
+        html: "html";
+        md: "md";
+        pdf: "pdf";
+    }>;
+    outPath: z.ZodOptional<z.ZodString>;
+    tagged_pdf: z.ZodOptional<z.ZodBoolean>;
+    tagged: z.ZodOptional<z.ZodBoolean>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ExportDocumentArgs = z.infer<typeof ExportDocumentSchema>;
+export declare const EXPORT_DOCUMENT_DESCRIPTION: string;
+/**
+ * Q0b: pure mapper for export-stage failures (exported for the E-code
+ * contract test). Every engine code survives verbatim via
+ * getEngineErrorCode; E_IO stays the fallback for uncoded failures.
+ */
+export declare function mapExportError(err: unknown): {
+    code: string;
+    message: string;
+    remedy: string;
+};
+export declare function validateExportTarget(rawPath: unknown, expectedFormat: 'html' | 'markdown' | 'md' | 'pdf'): string;
+export declare function handleExportDocument(store: McpSessionStore, rawArgs: unknown): Promise<{
+    ok: boolean;
+    format?: string;
+    path?: string;
+    bytes?: number;
+    content?: string;
+    dirty?: boolean;
+    revision?: number;
+    warnings?: PreflightIssue[];
+    blockers?: PreflightIssue[];
+    message?: string;
+    code?: string;
+    remedy?: string;
+}>;

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

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { type EngineErrorCode, type StyleGuideSummary } from '@attentionform/astra-engine';
+import { type McpSessionStore } from '../lib/session-store';
+/** Templates mirrored from the CLI `create` command (cli.ts CREATE_TEMPLATES). */
+export declare const NEW_DOCUMENT_TEMPLATES: readonly ["report", "memo", "blank"];
+export type NewDocumentTemplate = (typeof NEW_DOCUMENT_TEMPLATES)[number];
+export declare const NewDocumentSchema: z.ZodObject<{
+    outPath: z.ZodString;
+    template: z.ZodOptional<z.ZodEnum<{
+        report: "report";
+        memo: "memo";
+        blank: "blank";
+    }>>;
+    force: z.ZodOptional<z.ZodBoolean>;
+    styleGuide: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type NewDocumentInput = z.infer<typeof NewDocumentSchema>;
+export declare const NEW_DOCUMENT_DESCRIPTION: string;
+type NewDocumentOk = {
+    ok: true;
+    path: string;
+    sessionId: string;
+    revision: number;
+    template: NewDocumentTemplate;
+    bytes: number;
+    /** Compact summary of the guide attached at creation (absent when none). */
+    styleGuide?: StyleGuideSummary;
+    /** Parser diagnostics of the attached guide (present only when attached). */
+    styleGuideWarnings?: string[];
+};
+type NewDocumentErr = {
+    ok: false;
+    code: EngineErrorCode;
+    message: string;
+    remedy: string;
+};
+/**
+ * Q0b-gap: resolve the engine code verbatim via the shared table; fallback
+ * applies only when the error carries no known code (previously E_LIMIT/
+ * E_SECURITY/E_DEPENDENCY/E_AUTH and any other non-listed code collapsed to
+ * the per-site fallback). Exported for the E-code contract test.
+ */
+export declare function resolveNewDocumentCode(err: unknown, fallback: EngineErrorCode): EngineErrorCode;
+/**
+ * Create a template document on disk and open it into the session store.
+ * Mirrors CLI `create` semantics (template gate + validate-before-write);
+ * the write target is jailed to the MCP allowed roots (same jail as save).
+ * Never throws — every failure maps to {ok:false,code,remedy}.
+ */
+export declare function handleNewDocument(store: McpSessionStore, rawArgs: unknown): Promise<NewDocumentOk | NewDocumentErr>;
+export {};