toolcraft 0.0.787 → 0.0.788

package/composition.json

@@ -138,7 +138,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.787",
+      "version": "0.0.788",
       "license": "MIT"
     },
     {
@@ -148,7 +148,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.787",
+      "version": "0.0.788",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -138,7 +138,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.787",
+      "version": "0.0.788",
       "license": "MIT"
     },
     {
@@ -148,7 +148,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.787",
+      "version": "0.0.788",
       "license": "MIT"
     },
     {

package/node_modules/@poe-code/safe-fs/README.md

@@ -10,6 +10,11 @@ working data. Supply `{fs, cwd, env, signal}` and an optional page-cache count
 `env.TMPDIR` or `cwd`, with conditional unlink and cleanup through `close()`.
 Providers must support those capabilities; there is no host fallback. Use an
 external backend for large data because memory filesystems retain spilled bytes.
+To bound aggregate pages across multiple live stores, pass the same
+`new PagedStorageCache(16)` as the third argument to each `PagedStorage` constructor.
+This shares a 256 KiB resident-page budget; `cache.residentBytes` reports current
+page retention. Eviction uses each store's filesystem, and each store still owns
+its `close()` cleanup. The budget excludes caller buffers and backend storage.
 `IntegerTable.entries()` replays records in unsigned key order with a fixed
 16-level node stack and batches of at most 128 records. It accepts zero-filled
 caller storage with `allocate`, `read` and `write`; mutation during traversal

package/node_modules/@poe-code/safe-fs/dist/core.d.ts

@@ -18,4 +18,4 @@ export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
 export { readFileStream } from "./fs/read-file-stream.js";
-export { PagedStorage, IntegerTable, type PagedStorageContext } from "./storage.js";
+export { PagedStorage, PagedStorageCache, IntegerTable, type PagedStorageContext } from "./storage.js";

package/node_modules/@poe-code/safe-fs/dist/core.js

@@ -16,4 +16,4 @@ export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
 export { readFileStream } from "./fs/read-file-stream.js";
-export { PagedStorage, IntegerTable } from "./storage.js";
+export { PagedStorage, PagedStorageCache, IntegerTable } from "./storage.js";

package/node_modules/@poe-code/safe-fs/dist/storage.d.ts

@@ -5,12 +5,31 @@ export interface PagedStorageContext {
     readonly env: Readonly<Record<string, string | undefined>>;
     readonly signal: AbortSignal;
 }
+type Page = {
+    bytes: Uint8Array;
+    dirty: boolean;
+};
+/** Shares one resident-page limit across stores, retaining each store's caller
+ * filesystem and cleanup ownership. Serializes cache users through eviction IO. */
+export declare class PagedStorageCache {
+    private readonly maxPages;
+    private readonly pages;
+    private active;
+    constructor(maxPages: number);
+    get residentBytes(): number;
+    run<T>(action: () => Promise<T>): Promise<T>;
+    acquire(): Promise<Page>;
+    retain(page: Page, release: () => Promise<void>): void;
+    touch(page: Page): void;
+    forget(page: Page): void;
+}
 /** A bounded page cache backed only by the caller filesystem. The default is
  * one MiB; callers own close() on every outcome. Memory filesystems still retain
  * spilled data in RAM, so large workloads require an external backing provider. */
 export declare class PagedStorage {
     private readonly context;
     private readonly maxPages;
+    private readonly cache?;
     private readonly pages;
     private readonly controller;
     private readonly signal;
@@ -23,7 +42,7 @@ export declare class PagedStorage {
     private end;
     private active;
     private closing;
-    constructor(context: PagedStorageContext, maxPages?: number);
+    constructor(context: PagedStorageContext, maxPages?: number, cache?: PagedStorageCache | undefined);
     allocate(length: number): number;
     private operation;
     private spill;
@@ -55,3 +74,4 @@ export declare class IntegerTable {
     private lookup;
     private persist;
 }
+export {};

package/node_modules/@poe-code/safe-fs/dist/storage.js

@@ -1,12 +1,50 @@
 import { FsError, isFsError } from "./contracts/errors.js";
 const pageBytes = 16 * 1024;
 let serial = 0;
+/** Shares one resident-page limit across stores, retaining each store's caller
+ * filesystem and cleanup ownership. Serializes cache users through eviction IO. */
+export class PagedStorageCache {
+    maxPages;
+    pages = new Map();
+    active = Promise.resolve();
+    constructor(maxPages) {
+        this.maxPages = maxPages;
+        if (!Number.isSafeInteger(maxPages) || maxPages < 1)
+            throw new RangeError("Invalid storage page cache size");
+    }
+    get residentBytes() { return this.pages.size * pageBytes; }
+    run(action) {
+        const work = this.active.then(action);
+        this.active = work.then(() => undefined, () => undefined);
+        return work;
+    }
+    async acquire() {
+        if (this.pages.size < this.maxPages)
+            return { bytes: new Uint8Array(pageBytes), dirty: false };
+        const [page, release] = this.pages.entries().next().value;
+        await release();
+        this.pages.delete(page);
+        page.bytes.fill(0);
+        return page;
+    }
+    retain(page, release) {
+        this.pages.delete(page);
+        this.pages.set(page, release);
+    }
+    touch(page) {
+        const release = this.pages.get(page);
+        this.pages.delete(page);
+        this.pages.set(page, release);
+    }
+    forget(page) { this.pages.delete(page); }
+}
 /** A bounded page cache backed only by the caller filesystem. The default is
  * one MiB; callers own close() on every outcome. Memory filesystems still retain
  * spilled data in RAM, so large workloads require an external backing provider. */
 export class PagedStorage {
     context;
     maxPages;
+    cache;
     pages = new Map();
     controller = new AbortController();
     signal;
@@ -19,9 +57,10 @@ export class PagedStorage {
     end = 8; // Zero is the absent-pointer sentinel.
     active = Promise.resolve();
     closing;
-    constructor(context, maxPages = 64) {
+    constructor(context, maxPages = 64, cache) {
         this.context = context;
         this.maxPages = maxPages;
+        this.cache = cache;
         if (!Number.isSafeInteger(maxPages) || maxPages < 1)
             throw new RangeError("Invalid storage page cache size");
         this.signal = AbortSignal.any([context.signal, this.controller.signal]);
@@ -36,10 +75,11 @@ export class PagedStorage {
     }
     operation(action) {
         this.signal.throwIfAborted();
-        const work = this.active.then(() => {
+        const execute = () => {
             this.signal.throwIfAborted();
             return action();
-        });
+        };
+        const work = this.active.then(() => this.cache ? this.cache.run(execute) : execute());
         this.active = work.then(() => undefined, () => undefined);
         return work;
     }
@@ -101,6 +141,7 @@ export class PagedStorage {
         if (cached) {
             this.pages.delete(number);
             this.pages.set(number, cached);
+            this.cache?.touch(cached);
             return cached;
         }
         let reusable;
@@ -110,11 +151,14 @@ export class PagedStorage {
             const [oldNumber, oldPage] = this.pages.entries().next().value;
             await this.flush(oldNumber, oldPage);
             this.pages.delete(oldNumber);
+            this.cache?.forget(oldPage);
             reusable = oldPage;
         }
         // Flush owns the bytes until its awaited write completes. Reuse only then;
         // zero new/unwritten ranges so the previous page cannot leak into them.
-        const page = reusable ?? { bytes: new Uint8Array(pageBytes), dirty: false };
+        const page = reusable ?? (this.cache ? await this.cache.acquire() : { bytes: new Uint8Array(pageBytes), dirty: false });
+        // Shared eviction may await IO owned by a different, still-live signal.
+        this.signal.throwIfAborted();
         if (reusable)
             page.bytes.fill(0);
         if (number * pageBytes < this.diskLength) {
@@ -128,6 +172,12 @@ export class PagedStorage {
             }
         }
         this.pages.set(number, page);
+        this.cache?.retain(page, async () => {
+            if (!this.descriptor)
+                await this.spill();
+            await this.flush(number, page);
+            this.pages.delete(number);
+        });
         return page;
     }
     write(position, bytes) {
@@ -168,28 +218,33 @@ export class PagedStorage {
         this.controller.abort(new FsError("ECANCELED"));
         return this.closing ??= (async () => {
             await this.active.catch(() => { });
-            this.pages.clear();
-            const descriptor = this.descriptor;
-            if (!descriptor)
-                return;
-            const cancellation = new FsError("ECANCELED");
-            try {
-                if (!this.unlinked) {
-                    const expected = this.initial ?? await descriptor.stat();
-                    await this.context.fs.removeFileConditional(this.path, { parent: this.parent, expected }).catch(error => {
-                        if (!isFsError(error) || error.code !== "ENOENT")
+            const retire = async () => {
+                for (const page of this.pages.values())
+                    this.cache?.forget(page);
+                this.pages.clear();
+                const descriptor = this.descriptor;
+                if (!descriptor)
+                    return;
+                const cancellation = new FsError("ECANCELED");
+                try {
+                    if (!this.unlinked) {
+                        const expected = this.initial ?? await descriptor.stat();
+                        await this.context.fs.removeFileConditional(this.path, { parent: this.parent, expected }).catch(error => {
+                            if (!isFsError(error) || error.code !== "ENOENT")
+                                throw error;
+                        });
+                    }
+                }
+                finally {
+                    // Conditional descriptors must discard their private staged writes, not
+                    // publish the scratch data when the command retires its handle.
+                    await descriptor.close({ signal: AbortSignal.abort(cancellation) }).catch(error => {
+                        if (error !== cancellation)
                             throw error;
                     });
                 }
-            }
-            finally {
-                // Conditional descriptors must discard their private staged writes, not
-                // publish the scratch data when the command retires its handle.
-                await descriptor.close({ signal: AbortSignal.abort(cancellation) }).catch(error => {
-                    if (error !== cancellation)
-                        throw error;
-                });
-            }
+            };
+            await (this.cache ? this.cache.run(retire) : retire());
         })();
     }
 }

package/node_modules/@poe-code/xml-ast/README.md

@@ -26,7 +26,10 @@ Pass positive integer limits for depth, element and content counts, attributes,
 `parseXmlSteps` yields work counts so a host can account for parsing and yield between checkpoints. Syntax errors and resource limits remain errors by default; parsing never fetches external entities.
 Pass `recover: message => report(message)` to repair truncated elements,
 mismatched closing tags, and undeclared entities. Each repair calls the callback.
-Resource limits and the prohibition on DTDs remain in force.
+Resource limits and the prohibition on DTDs remain in force. With `retainTree: false`,
+`parseXmlSteps` discards completed nodes and can emit synchronous `events`, including
+repaired closing events. Drain events between generator checkpoints to await
+external storage; the source string and open parser frames remain resident.
 
 `parseXmlStream` consumes each chunk before requesting the next and calls the optional asynchronous checkpoint with at most 512 UTF-16 units. It preserves the buffered parser’s tree shape, namespaces and retained content. The source is closed on parsing or checkpoint failure. Decode byte sources incrementally before passing their strings. This avoids a full source string; the resulting tree and individual XML tokens still reside in memory. Recovery remains available through the buffered parser.
 

package/node_modules/@poe-code/xml-ast/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type { XmlStreamEvent } from "./stream.js";
 export { XmlLimitError } from "./errors.js";
 export interface XmlName {
     readonly name: string;
@@ -40,6 +41,13 @@ export interface XmlLimits {
     readonly maxTextLength?: number;
     readonly onElement?: (element: XmlName, parent: XmlName | undefined, depth: number) => void;
 }
-export declare function parseXmlSteps(input: string, limits?: XmlLimits): Generator<number, XmlElement, void>;
+export interface XmlStepLimits extends XmlLimits {
+    /** Return root metadata without retaining descendants or text. */
+    readonly retainTree?: boolean;
+    /** Synchronous ordered events, including repaired closes. Requires retainTree:
+     * false. Drive the step iterator to await external consumers between windows. */
+    readonly events?: (event: XmlStreamEvent) => void;
+}
+export declare function parseXmlSteps(input: string, limits?: XmlStepLimits): Generator<number, XmlElement, void>;
 export declare function parseXml(input: string, limits?: XmlLimits): XmlElement;
 export { parseXmlStream, type XmlStreamLimits, type XmlStreamEvent } from "./stream.js";

package/node_modules/@poe-code/xml-ast/dist/index.js

@@ -187,6 +187,10 @@ export function* parseXmlSteps(input, limits = {}) {
     const maxNodes = limits.maxNodes ?? Infinity;
     const maxAttributes = limits.maxAttributes ?? Infinity;
     const retainContent = limits.retainContent !== false;
+    const retainTree = limits.retainTree !== false;
+    const retain = retainTree && retainContent;
+    if (limits.events && retainTree)
+        throw new TypeError("XML events require retainTree: false");
     const maxContentNodes = limits.maxContentNodes ?? Infinity;
     const emptyContent = Object.freeze([]);
     const emptyAttributes = Object.freeze([]);
@@ -323,11 +327,13 @@ export function* parseXmlSteps(input, limits = {}) {
             admitText(resolved);
             const parent = stack.at(-1);
             if (parent) {
-                parent.element.text += resolved;
+                if (retainTree)
+                    parent.element.text += resolved;
                 if (resolved.length) {
                     admitContent();
-                    if (retainContent)
+                    if (retain)
                         parent.content.push({ kind: "text", text: resolved });
+                    limits.events?.({ type: "content", content: { kind: "text", text: resolved }, parent: parent.element });
                 }
             }
             else {
@@ -347,8 +353,9 @@ export function* parseXmlSteps(input, limits = {}) {
                 }
                 if (resolved.length) {
                     admitContent();
-                    if (retainContent)
+                    if (retain)
                         (root ? epilog : prolog).push({ kind: "text", text: resolved });
+                    limits.events?.({ type: "content", content: { kind: "text", text: resolved }, parent: undefined });
                 }
             }
             offset = endPos;
@@ -362,9 +369,10 @@ export function* parseXmlSteps(input, limits = {}) {
             const text = source.slice(offset + 4, end);
             admitText(text);
             admitContent();
-            if (retainContent) {
+            if (retain) {
                 (parent?.content ?? (root ? epilog : prolog)).push({ kind: "comment", text });
             }
+            limits.events?.({ type: "content", content: { kind: "comment", text }, parent: parent?.element });
             offset = end + 3;
         }
         else if (source.startsWith("<![CDATA[", offset)) {
@@ -376,10 +384,12 @@ export function* parseXmlSteps(input, limits = {}) {
             const cdataText = source.slice(offset + 9, end);
             admitText(cdataText);
             const parent = stack.at(-1);
-            parent.element.text += cdataText;
+            if (retainTree)
+                parent.element.text += cdataText;
             admitContent();
-            if (retainContent)
+            if (retain)
                 parent.content.push({ kind: "cdata", text: cdataText });
+            limits.events?.({ type: "content", content: { kind: "cdata", text: cdataText }, parent: parent.element });
             offset = end + 3;
         }
         else if (source.startsWith("<?", offset)) {
@@ -417,9 +427,10 @@ export function* parseXmlSteps(input, limits = {}) {
                 const text = content.slice(wsStart);
                 admitText(text);
                 admitContent();
-                if (retainContent) {
+                if (retain) {
                     (parent?.content ?? (root ? epilog : prolog)).push({ kind: "processing-instruction", target, text });
                 }
+                limits.events?.({ type: "content", content: { kind: "processing-instruction", target, text }, parent: parent?.element });
             }
             offset = end + 2;
         }
@@ -434,11 +445,14 @@ export function* parseXmlSteps(input, limits = {}) {
                 yield 512;
                 pendingWork -= 512;
             }
-            if (source[offset++] !== ">" || stack.pop()?.name !== name) {
+            const closed = source[offset++] === ">" ? stack.pop() : undefined;
+            if (closed?.name !== name) {
                 if (!limits.recover)
                     invalid("mismatched closing tag");
                 limits.recover("mismatched closing tag");
             }
+            if (closed)
+                limits.events?.({ type: "close", element: closed.element, parent: stack.at(-1)?.element });
         }
         else {
             offset++;
@@ -581,12 +595,14 @@ export function* parseXmlSteps(input, limits = {}) {
                 yield 512;
                 pendingWork -= 512;
             }
-            const content = retainContent ? [] : undefined;
+            const content = retain ? [] : undefined;
             const element = { kind: "element", name, namespace, localName, children: [], text: "", content: content ?? emptyContent, attributes: retainContent ? retainedAttributes : emptyAttributes, namespaces: retainContent ? namespaces : emptyNamespaces, ...(root === undefined && retainContent ? { prolog, epilog, ...(declaration === undefined ? {} : { declaration }) } : {}) };
             const parent = stack.at(-1);
             if (parent) {
-                parent.element.children.push(element);
-                parent.content?.push(element);
+                if (retainTree) {
+                    parent.element.children.push(element);
+                    parent.content?.push(element);
+                }
             }
             else if (root)
                 invalid("multiple root elements");
@@ -604,8 +620,11 @@ export function* parseXmlSteps(input, limits = {}) {
             // every admission counter still run for each distinct physical element.
             if (empty && !attributes && name.length <= 512 && source.slice(offset - name.length - 3, offset) === `<${name}/>`)
                 previousEmpty = { suffix: name + "/>", name, prefix, localName };
+            limits.events?.({ type: "open", element, parent: parent?.element });
             if (!empty)
                 stack.push({ element, content, name, namespaces });
+            else
+                limits.events?.({ type: "close", element, parent: parent?.element });
         }
     }
     if (pendingWork > 0) {
@@ -618,6 +637,11 @@ export function* parseXmlSteps(input, limits = {}) {
         if (!limits.recover)
             invalid("incomplete document");
         limits.recover("incomplete document");
+        while (stack.length) {
+            const closed = stack.pop();
+            limits.events?.({ type: "close", element: closed.element, parent: stack.at(-1)?.element });
+            yield 1;
+        }
     }
     return root;
 }

package/node_modules/tiny-stdio-mcp-server/dist/composition.json

@@ -8,7 +8,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.787",
+      "version": "0.0.788",
       "license": "MIT"
     }
   ]

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.787",
+  "version": "0.0.788",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.787",
+  "version": "0.0.788",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -177,7 +177,7 @@
     "saxes"
   ],
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.787",
+    "toolcraft-schema": "0.0.788",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*",
     "@poe-code/agent-mcp-config": "*",