@attentionform/astra-mcp-server 0.4.2 → 0.5.0

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

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/schemas.d.ts

@@ -971,3 +971,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.0",
   "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.0",
+    "@attentionform/ooxml-validator": "^0.5.0",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",