@attentionform/astra-mcp-server 0.4.2 → 0.5.1

package/dist/lib/mcp/handlers/history.d.ts

@@ -1,3 +1,5 @@
+import { handleExportOriginalDocument, handleRestoreOriginalDocument } from './original';
+import { type OriginalInfo } from '@attentionform/astra-engine';
 import type { McpSessionStore } from '../../session-store';
 import type { McpErrorShape } from '../errors';
 import type { ChangedValue, DiscardedUnsavedSummary } from '../diff';
@@ -24,6 +26,7 @@ export declare function handleGetDocumentHistory(store: McpSessionStore, input:
     history: HistoryEntry[];
     /** R-6 sidecar-removal warning (string when a regenerated chain replaced recorded history, else null). Additive, never a failure. */
     warning: string | null;
+    original: OriginalInfo;
 } | McpErrorShape>;
 export declare function handleRevertDocument(store: McpSessionStore, input: unknown): Promise<{
     ok: true;
@@ -94,6 +97,8 @@ export declare function handlePreviewRevert(store: McpSessionStore, input: unkno
 } | McpErrorShape>;
 /** Git-history dispatch table (registered alongside lean-6 in index.ts). */
 export declare const GIT_HISTORY_HANDLERS: {
+    readonly export_original_document: typeof handleExportOriginalDocument;
+    readonly restore_original_document: typeof handleRestoreOriginalDocument;
     readonly get_document_history: typeof handleGetDocumentHistory;
     readonly preview_revert: typeof handlePreviewRevert;
     readonly revert_document: typeof handleRevertDocument;

package/dist/lib/mcp/handlers/open-inspect.d.ts

@@ -17,6 +17,8 @@ export declare function handleOpenDocument(store: McpSessionStore, input: unknow
     evicted: string[];
     pendingNormalizations: string[];
     validation: OpenValidationField;
+    original?: import('@attentionform/astra-engine').OriginalInfo;
+    originalWarning?: string;
 } | McpErrorShape>;
 /**
  * Phase C-2: docs rendering under ~2000 tokens return the full TOON
@@ -25,6 +27,15 @@ export declare function handleOpenDocument(store: McpSessionStore, input: unknow
  * full dump to first window — the navigation remedy teaches paging.
  */
 export declare const INSPECT_FULL_TOON_TOKEN_THRESHOLD = 2000;
+/** What the `outline` tier counts, over the whole document: rows of that tier are headings only. */
+export interface OutlineCounts {
+    /** Headings in the document (all of them, whatever `sectionId`, `offset` or `limit` selected). */
+    headings: number;
+    nodes: number;
+    tables: number;
+    images: number;
+    words: number;
+}
 export interface InspectWindowEnvelope {
     totalNodes: number;
     returnedNodes: number;
@@ -66,6 +77,12 @@ export declare function handleInspectDocument(store: McpSessionStore, input: unk
     truncated: boolean;
     /** Present when windowed: teaches search -> aroundNode zoom -> offset paging. */
     remedy?: string;
+    /** Outline tier only: whole-document counts, because rowCount/totalNodes count heading rows there. */
+    outline?: OutlineCounts;
+    /** Outline tier with aroundNode: the heading the node resolved to (null before the first heading). */
+    aroundResolvedTo?: string | null;
+    /** Outline tier: why a window is empty or not centred where aroundNode pointed. */
+    note?: string;
     /** Compact summary of the session style guide (absent when none attached). */
     styleGuide?: StyleGuideSummary;
     comments?: unknown;

package/dist/lib/mcp/handlers/original.d.ts

@@ -0,0 +1,25 @@
+import type { McpSessionStore } from '../../session-store';
+/** Read-only export with respect to the live session. Overwriting its own path is deliberately refused. */
+export declare function handleExportOriginalDocument(store: McpSessionStore, input: unknown): Promise<import("../errors").McpErrorShape | {
+    ok: true;
+    sessionId: string;
+    path: string;
+    original: import("@attentionform/astra-engine").OriginalInfo;
+}>;
+/** Exact-byte restore. Candidate session is staged separately; normal serialization never overwrites the result. */
+export declare function handleRestoreOriginalDocument(store: McpSessionStore, input: unknown): Promise<import("../errors").McpErrorShape | {
+    warning?: string | undefined;
+    durabilityUnconfirmed?: boolean | undefined;
+    ok: true;
+    sessionId: string;
+    path: string;
+    revision: number;
+    dirty: false;
+    commitOid: string;
+    original: {
+        available: true;
+        sha256: string;
+        bytes: number;
+        capturedAt: string;
+    };
+}>;

package/dist/lib/mcp/handlers/parity.d.ts

@@ -37,6 +37,12 @@ export declare function handleGetStats(store: McpSessionStore, input: unknown):
     callouts: number;
     images: number;
     pages: number;
+    pageTerms: {
+        words: number;
+        tables: number;
+        images: number;
+        pageBreaks: number;
+    };
 } | McpErrorShape>;
 export interface SanitizeDocumentOk {
     ok: true;

package/dist/lib/mcp/schemas.d.ts

@@ -11,6 +11,7 @@ export declare const OpenDocumentSchema: z.ZodObject<{
 export declare const InspectDocumentSchema: z.ZodObject<{
     sessionId: z.ZodString;
     fidelity: z.ZodOptional<z.ZodEnum<{
+        outline: "outline";
         compact: "compact";
         standard: "standard";
         full: "full";
@@ -203,7 +204,25 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
             fontSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
             sz: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
             fontFamily: z.ZodOptional<z.ZodString>;
-            highlight: z.ZodOptional<z.ZodString>;
+            highlight: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                red: "red";
+                green: "green";
+                blue: "blue";
+                black: "black";
+                white: "white";
+                yellow: "yellow";
+                cyan: "cyan";
+                magenta: "magenta";
+                darkBlue: "darkBlue";
+                darkCyan: "darkCyan";
+                darkGreen: "darkGreen";
+                darkMagenta: "darkMagenta";
+                darkRed: "darkRed";
+                darkYellow: "darkYellow";
+                darkGray: "darkGray";
+                lightGray: "lightGray";
+            }>>;
             lineSpacing: z.ZodOptional<z.ZodNumber>;
             spacingBefore: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
             spacingAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
@@ -237,7 +256,25 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
             fontSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
             sz: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
             fontFamily: z.ZodOptional<z.ZodString>;
-            highlight: z.ZodOptional<z.ZodString>;
+            highlight: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                red: "red";
+                green: "green";
+                blue: "blue";
+                black: "black";
+                white: "white";
+                yellow: "yellow";
+                cyan: "cyan";
+                magenta: "magenta";
+                darkBlue: "darkBlue";
+                darkCyan: "darkCyan";
+                darkGreen: "darkGreen";
+                darkMagenta: "darkMagenta";
+                darkRed: "darkRed";
+                darkYellow: "darkYellow";
+                darkGray: "darkGray";
+                lightGray: "lightGray";
+            }>>;
             lineSpacing: z.ZodOptional<z.ZodNumber>;
             spacingBefore: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
             spacingAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
@@ -270,7 +307,25 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         fontSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         sz: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         fontFamily: z.ZodOptional<z.ZodString>;
-        highlight: z.ZodOptional<z.ZodString>;
+        highlight: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            red: "red";
+            green: "green";
+            blue: "blue";
+            black: "black";
+            white: "white";
+            yellow: "yellow";
+            cyan: "cyan";
+            magenta: "magenta";
+            darkBlue: "darkBlue";
+            darkCyan: "darkCyan";
+            darkGreen: "darkGreen";
+            darkMagenta: "darkMagenta";
+            darkRed: "darkRed";
+            darkYellow: "darkYellow";
+            darkGray: "darkGray";
+            lightGray: "lightGray";
+        }>>;
         lineSpacing: z.ZodOptional<z.ZodNumber>;
         spacingBefore: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         spacingAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
@@ -377,7 +432,7 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
         }>>;
         border: z.ZodOptional<z.ZodString>;
         color: z.ZodOptional<z.ZodString>;
-        sz: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        sz: z.ZodOptional<z.ZodNumber>;
         vAlign: z.ZodOptional<z.ZodString>;
         align: z.ZodOptional<z.ZodPreprocess<z.ZodEnum<{
             center: "center";
@@ -777,7 +832,7 @@ export declare const ExecuteBatchSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         action: z.ZodLiteral<"pageBorder">;
         style: z.ZodOptional<z.ZodString>;
-        sz: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        sz: z.ZodOptional<z.ZodNumber>;
         fontSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         color: z.ZodOptional<z.ZodString>;
         marginOffset: z.ZodOptional<z.ZodEnum<{
@@ -971,3 +1026,13 @@ export type GetStatsInput = z.infer<typeof GetStatsSchema>;
 export type SanitizeDocumentInput = z.infer<typeof SanitizeDocumentSchema>;
 export type NormalizeDocumentInput = z.infer<typeof NormalizeDocumentSchema>;
 export type ImportDocumentInput = z.infer<typeof ImportDocumentSchema>;
+/** Exact retained-input recovery. These paths never serialize the exported original. */
+export declare const ExportOriginalDocumentSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    outPath: z.ZodString;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const RestoreOriginalDocumentSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    discard: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;

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

@@ -6,7 +6,7 @@ export declare const LEAN6_TOOL_NAMES: readonly ["open_document", "inspect_docum
 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 declare const GIT_HISTORY_TOOL_NAMES: readonly ["get_document_history", "export_original_document", "restore_original_document", "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). */

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

@@ -10,3 +10,4 @@ export * from './mcp/handlers/save-close';
 export * from './mcp/handlers/history';
 export * from './mcp/handlers/export-audit';
 export * from './mcp/registry';
+export * from './mcp/handlers/original';

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

@@ -1,4 +1,4 @@
-import { type DocumentAST, type DocxParserMacroOptions, DocxParser, OperationEngine, ToonGenerator, canonicalizeForAsset as canonicalizeForMcp, type StyleGuideConfig, type ValidationBaseline } from '@attentionform/astra-engine';
+import { type DocumentAST, type DocxParserMacroOptions, DocxParser, OperationEngine, ToonGenerator, canonicalizeForAsset as canonicalizeForMcp, type OriginalInfo, type StyleGuideConfig, type ValidationBaseline } from '@attentionform/astra-engine';
 /**
  * Sprint-2 Muse session store (MCP Lean-6 backing).
  *
@@ -146,6 +146,22 @@ export interface DocHandle {
     openBaseline?: ValidationBaseline | null;
     /** sha256 of the file bytes read at open, to tell whether the file on disk is still the opened one. */
     openSha256?: string;
+    /** Fingerprint of the last bytes read or successfully written by ASTra. */
+    lastWrittenSha256?: string;
+    /** Status of the retained original as this session last learned it. Read it through `resolveSessionOriginal`. */
+    originalInfo?: OriginalInfo;
+    /**
+     * What this session pinned about the retained original, so a later check cannot hand it another history's
+     * original: `retained` is the SHA-256 of the verified retained original read at open; `input` is the SHA-256 of
+     * the file this session opened, for a session that opened while history initialization was still running.
+     * No pin: this session has no claim on any original.
+     */
+    originalPin?: {
+        kind: 'retained' | 'input';
+        sha256: string;
+    };
+    originalWarning?: string;
+    macroPolicy?: DocxParserMacroOptions;
 }
 /**
  * Per-commit audit metadata recorded alongside each history commit.
@@ -290,6 +306,9 @@ 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.
+ *
+ * Throws when the package snapshot cannot be collected. An empty record would be committed as a complete
+ * snapshot with no package parts, and a later revert would then remove the real parts as if that were intended.
  */
 export declare function collectTrackedExtrasForGit(parser: DocxParser): Record<string, Buffer>;
 /**
@@ -299,7 +318,18 @@ export declare function collectTrackedExtrasForGit(parser: DocxParser): Record<s
  * 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>;
+export declare function ensureGitRepo(docPath: string, xml: string, extras: Record<string, Buffer>, originalBytes?: Buffer): Promise<boolean>;
+/**
+ * The retained original's status for this session, checked now. A session pins one hash when it opens (see
+ * `DocHandle.originalPin`); the working document's own bytes are never compared with the original, because an
+ * edited document legitimately differs from it.
+ * - `retained` pin: the stored original must still verify and still have the pinned SHA-256.
+ * - `input` pin (the session opened while another process was initializing the history): the session becomes
+ *   eligible only once that initialization is complete and the verified original has the SHA-256 of the file
+ *   this session opened. Until then it reports `initializing`; a different original never upgrades it.
+ * - no pin: the status recorded at open stands.
+ */
+export declare function resolveSessionOriginal(handle: DocHandle): Promise<OriginalInfo>;
 /** Outcome of McpSessionStore.closeDocument (dirty state read under the delete lock). */
 export interface CloseDocumentOutcome {
     closed: boolean;
@@ -389,7 +419,7 @@ export declare class McpSessionStore {
      * 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>;
+    openDocument(filePath: string, sessionId?: string, macroOpts?: DocxParserMacroOptions, captureInput?: boolean): Promise<DocHandle>;
     /**
      * Opens a document from an in-memory buffer (tests / headless flows).
      * `labelPath` is the display path recorded on the handle. L4: absolute

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@attentionform/astra-mcp-server",
   "mcpName": "com.attentionform/astra-mcp-server",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Official Model Context Protocol (MCP) server for ASTra document IDE",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -42,8 +42,8 @@
     "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
   },
   "dependencies": {
-    "@attentionform/astra-engine": "^0.4.2",
-    "@attentionform/ooxml-validator": "^0.4.2",
+    "@attentionform/astra-engine": "^0.5.1",
+    "@attentionform/ooxml-validator": "^0.5.1",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",