@cursor/july 0.1.102 → 0.1.104

package/dist/internal/filesystem/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../../src/internal/filesystem/walk.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAI1E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD;;;GAGG;AACH,wBAAuB,kBAAkB,CACvC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACzB,MAAM,CAAC,EAAE,MAAM,GACd,cAAc,CAAC,QAAQ,CAAC,CAyB1B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EACvB,IAAI,EAAE,MAAM,GACX,QAAQ,CAgBV;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAC9B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,QAAQ,EAAE,CAAC,CASrB;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAC9B,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,QAAQ,EAAE,CAAC,CASrB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,EACvC,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAC,CAUxD;AAED,wBAAuB,iBAAiB,CACtC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,EAC5D,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,cAAc,CAAC,QAAQ,CAAC,CAK1B;AAaD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,mBAAmB,CAkBrB;AAwFD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,QAAQ,EAAE,CAOZ;AAcD,wBAAsB,UAAU,CAC9B,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,EACvC,IAAI,CAAC,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CACN;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE;QAAE,iBAAiB,EAAE,mBAAmB,CAAA;KAAE,CAAA;CAAE,GACxE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAClD,CAyBA"}

package/dist/internal/filesystem/walk.js

@@ -0,0 +1,339 @@
+/**
+ * Recursive listing, existence probes, and native LS trees. Matches the
+ * change-monitor VFS contract on origin/main: `list` is files-only and
+ * recursive; `stat` tells file / directory / missing apart; composers
+ * merge already-sorted streams with a k-way heap.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { posix } from "node:path";
+import { minimatch } from "minimatch";
+import { normalizeFsPath } from "../../filesystem.js";
+import { mergeSorted } from "./merge.js";
+/** Filename-character ingest budget; matches LocalLsExecutor. */
+export const LS_INGEST_CHARACTER_BUDGET = 2500;
+/**
+ * Yield the files under `prefix`, sorted. A file whose path equals
+ * `prefix` is not under itself.
+ */
+export function listFilesFromPaths(files, prefix) {
+    return __asyncGenerator(this, arguments, function* listFilesFromPaths_1() {
+        const scope = normalizeListPrefix(prefix);
+        const withSlash = scope === "/" ? "/" : `${scope}/`;
+        const matches = [];
+        for (const file of files) {
+            const filePath = normalizeFsPath(file.path);
+            if (scope === "/") {
+                matches.push(file.size === undefined
+                    ? { path: filePath }
+                    : { path: filePath, size: file.size });
+                continue;
+            }
+            if (filePath === scope || !filePath.startsWith(withSlash)) {
+                continue;
+            }
+            matches.push(file.size === undefined
+                ? { path: filePath }
+                : { path: filePath, size: file.size });
+        }
+        matches.sort((left, right) => left.path.localeCompare(right.path));
+        yield __await(yield* __asyncDelegator(__asyncValues(matches)));
+    });
+}
+export function normalizeListPrefix(prefix) {
+    if (prefix === undefined || prefix === "" || prefix === "/") {
+        return "/";
+    }
+    return normalizeFsPath(prefix);
+}
+/**
+ * Existence probe over a flat file-path index. Exact key → file; any
+ * key with this prefix → directory; `""` / `/` → directory; else missing.
+ */
+export function statFromFilePaths(files, path) {
+    const normalized = normalizeListPrefix(path);
+    if (normalized === "/") {
+        return { kind: "directory" };
+    }
+    const prefix = `${normalized}/`;
+    for (const file of files) {
+        const filePath = normalizeFsPath(file);
+        if (filePath === normalized) {
+            return { kind: "file" };
+        }
+        if (filePath.startsWith(prefix)) {
+            return { kind: "directory" };
+        }
+    }
+    return { kind: "missing" };
+}
+export function collectList(root, prefix) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, e_1, _b, _c;
+        const entries = [];
+        if (root.list === undefined) {
+            return entries;
+        }
+        try {
+            for (var _d = true, _e = __asyncValues(root.list(prefix)), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                _c = _f.value;
+                _d = false;
+                const entry = _c;
+                entries.push(entry);
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        return entries;
+    });
+}
+export function collectGlob(root, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, e_2, _b, _c;
+        const entries = [];
+        if (root.glob === undefined) {
+            return entries;
+        }
+        try {
+            for (var _d = true, _e = __asyncValues(root.glob(options.pattern, options.dir)), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                _c = _f.value;
+                _d = false;
+                const entry = _c;
+                entries.push(entry);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        return entries;
+    });
+}
+/**
+ * List, then `stat` only when nothing came back. A non-empty listing is
+ * already a directory (a file is not under itself).
+ */
+export function collectListOrStat(root, path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const files = yield collectList(root, path);
+        if (files.length > 0) {
+            return { kind: "directory", files };
+        }
+        if (root.stat === undefined) {
+            return { kind: "missing", files };
+        }
+        const probe = path === undefined || path === "" ? "." : path;
+        return { kind: (yield root.stat(probe)).kind, files };
+    });
+}
+export function mergeSortedByPath(sources, options) {
+    return __asyncGenerator(this, arguments, function* mergeSortedByPath_1() {
+        yield __await(yield* __asyncDelegator(__asyncValues(mergeSorted(sources, {
+            compare: (left, right) => left.path.localeCompare(right.path),
+            unique: (options === null || options === void 0 ? void 0 : options.unique) === true,
+        }))));
+    });
+}
+function emptyLsNode(absPath) {
+    return {
+        absPath,
+        childrenDirs: [],
+        childrenFiles: [],
+        childrenWereProcessed: true,
+        fullSubtreeExtensionCounts: {},
+        numFiles: 0,
+    };
+}
+/**
+ * Build the native LS tree from a recursive file listing. Applies the
+ * LocalLsExecutor ingest budget so a huge directory truncates the same way.
+ */
+export function buildLsTree(dir, files) {
+    const rootPath = normalizeListPrefix(dir);
+    const root = emptyLsNode(rootPath);
+    const dirNodes = new Map([[rootPath, root]]);
+    const state = {
+        charactersUsed: rootPath.length,
+        budgetExceeded: false,
+    };
+    for (const file of files) {
+        addPathToTree(file.path, rootPath, dirNodes, state, LS_INGEST_CHARACTER_BUDGET);
+    }
+    return root;
+}
+function addPathToTree(filePath, rootPath, dirNodes, state, characterBudget) {
+    var _a;
+    const fileName = posix.basename(filePath);
+    const dirPath = posixParent(filePath);
+    ensureDirectoryPath(dirPath, rootPath, dirNodes, state.budgetExceeded);
+    const parentNode = dirNodes.get(dirPath);
+    if (parentNode === undefined) {
+        return;
+    }
+    const fileCharCost = fileName.length;
+    if (!state.budgetExceeded &&
+        state.charactersUsed + fileCharCost <= characterBudget) {
+        parentNode.childrenFiles.push({ name: fileName });
+        state.charactersUsed += fileCharCost;
+        return;
+    }
+    if (!state.budgetExceeded) {
+        state.budgetExceeded = true;
+        let currentDir = dirPath;
+        while (currentDir.startsWith(rootPath)) {
+            const node = dirNodes.get(currentDir);
+            if (node !== undefined) {
+                node.childrenWereProcessed = false;
+            }
+            const parentDir = posixParent(currentDir);
+            if (parentDir === currentDir) {
+                break;
+            }
+            currentDir = parentDir;
+        }
+    }
+    const extension = posix.extname(filePath);
+    let currentDir = dirPath;
+    while (currentDir.startsWith(rootPath)) {
+        const node = dirNodes.get(currentDir);
+        if (node !== undefined) {
+            node.fullSubtreeExtensionCounts[extension] =
+                ((_a = node.fullSubtreeExtensionCounts[extension]) !== null && _a !== void 0 ? _a : 0) + 1;
+            node.numFiles += 1;
+        }
+        const parentDir = posixParent(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+}
+function ensureDirectoryPath(dirPath, rootPath, dirNodes, budgetExceeded) {
+    if (dirNodes.has(dirPath) || dirPath === rootPath) {
+        return;
+    }
+    const parentPath = posixParent(dirPath);
+    if (parentPath !== dirPath && pathIsUnderRoot(parentPath, rootPath)) {
+        ensureDirectoryPath(parentPath, rootPath, dirNodes, budgetExceeded);
+    }
+    const dirNode = Object.assign(Object.assign({}, emptyLsNode(dirPath)), { childrenWereProcessed: !budgetExceeded });
+    dirNodes.set(dirPath, dirNode);
+    const parentNode = dirNodes.get(parentPath);
+    if (parentNode !== undefined) {
+        parentNode.childrenDirs.push(dirNode);
+    }
+}
+function pathIsUnderRoot(path, rootPath) {
+    return (path === rootPath ||
+        path.startsWith(rootPath === "/" ? "/" : `${rootPath}/`));
+}
+/**
+ * Native LS ignore_globs: a pattern that is not already recursive is
+ * matched at any depth (the same `** /` prefix the Cursor SDK native uses).
+ */
+export function applyIgnores(entries, ignoreGlobs) {
+    if (ignoreGlobs === undefined || ignoreGlobs.length === 0) {
+        return [...entries];
+    }
+    return entries.filter((entry) => !ignoreGlobs.some((glob) => matchesIgnoreGlob(entry.path, glob)));
+}
+function matchesIgnoreGlob(filePath, glob) {
+    const recursivePrefix = "**".concat("/");
+    const pattern = glob.startsWith(recursivePrefix)
+        ? glob
+        : recursivePrefix + glob;
+    const relative = filePath.replace(/^\//, "");
+    return (minimatch(relative, pattern, { dot: true }) ||
+        minimatch(filePath, pattern, { dot: true }));
+}
+export function lsFromList(root, path, ignoreGlobs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const listed = yield collectListOrStat(root, path);
+        const treePath = path !== null && path !== void 0 ? path : inferListedRoot(listed.files);
+        switch (listed.kind) {
+            case "missing":
+                return {
+                    status: "error",
+                    error: { message: `Path does not exist: ${treePath}` },
+                };
+            case "file":
+                return {
+                    status: "error",
+                    error: { message: `Path is not a directory: ${treePath}` },
+                };
+            case "directory":
+                return {
+                    status: "success",
+                    value: {
+                        directoryTreeRoot: buildLsTree(treePath, applyIgnores(listed.files, ignoreGlobs)),
+                    },
+                };
+        }
+    });
+}
+function inferListedRoot(files) {
+    if (files.length === 0) {
+        return "/";
+    }
+    let prefix = posixParent(files[0].path);
+    for (const file of files) {
+        while (prefix !== "/" &&
+            file.path !== prefix &&
+            !file.path.startsWith(`${prefix}/`)) {
+            const parent = posixParent(prefix);
+            if (parent === prefix) {
+                return "/";
+            }
+            prefix = parent;
+        }
+    }
+    return prefix;
+}
+/**
+ * `path.posix.dirname` returns `.` for slash-free paths. Treat that as
+ * the virtual root so LS walks terminate and relative files attach to `/`.
+ */
+function posixParent(path) {
+    const dir = posix.dirname(path);
+    return dir === "." || dir === path ? "/" : dir;
+}

package/dist/internal/framework-file-storage.d.ts

@@ -37,6 +37,14 @@ import type { StorageConfig } from "../storage.js";
 export declare function isFrameworkFileKey(key: string): boolean;
 /** The KV core over a {@link FileSink}: one JSON document per key. */
 export type FileSinkStorageCore = Required<Pick<StorageConfig, "put" | "get" | "delete" | "list">>;
+/**
+ * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
+ * framework-minted (URI-encoded, length-bounded segments — see
+ * {@link storageKeys}), so they are used as file keys verbatim; values are
+ * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
+ * corrupt document must fail the follow-up rather than read as a miss, and
+ * the startup bulk restore already logs-and-skips a throwing `list`.
+ */
 export declare function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore;
 /**
  * Split one storage core by key kind: framework session state to `files`,

package/dist/internal/framework-file-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"framework-file-storage.d.ts","sourceRoot":"","sources":["../../src/internal/framework-file-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,eAAe,CAAC;AAiBjE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAavD;AAED,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CACxC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,CAAC;AA0BF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,mBAAmB,CAuDvE;AA+CD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,EAAE,EAAE,mBAAmB,CAAC;IACxB,KAAK,EAAE,mBAAmB,CAAC;CAC5B,GAAG,mBAAmB,GAAG,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAe1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,GACrC,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CA0BnC"}
+{"version":3,"file":"framework-file-storage.d.ts","sourceRoot":"","sources":["../../src/internal/framework-file-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,eAAe,CAAC;AAiBjE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAavD;AAED,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CACxC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,CAAC;AAkBF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,mBAAmB,CAuDvE;AA+CD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,EAAE,EAAE,mBAAmB,CAAC;IACxB,KAAK,EAAE,mBAAmB,CAAC;CAC5B,GAAG,mBAAmB,GAAG,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAe1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,GACrC,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CA0BnC"}

package/dist/internal/framework-file-storage.js

@@ -68,14 +68,6 @@ export function isFrameworkFileKey(key) {
     const kind = kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
     return FRAMEWORK_FILE_KINDS.has(kind);
 }
-/**
- * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
- * framework-minted (URI-encoded, length-bounded segments — see
- * {@link storageKeys}), so they are used as file keys verbatim; values are
- * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
- * corrupt document must fail the follow-up rather than read as a miss, and
- * the startup bulk restore already logs-and-skips a throwing `list`.
- */
 /** Parallel per-key reads backing `list` (each is presign + object GET). */
 const LIST_READ_CONCURRENCY = 8;
 /**
@@ -90,6 +82,14 @@ function isUnrepresentableFileKey(key) {
         .split("/")
         .some((segment) => segment === "" || segment === "." || segment === "..");
 }
+/**
+ * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
+ * framework-minted (URI-encoded, length-bounded segments — see
+ * {@link storageKeys}), so they are used as file keys verbatim; values are
+ * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
+ * corrupt document must fail the follow-up rather than read as a miss, and
+ * the startup bulk restore already logs-and-skips a throwing `list`.
+ */
 export function fileSinkStorageCore(sink) {
     return {
         put(key, value) {

package/dist/internal/github-fanout.d.ts

@@ -1,5 +1,5 @@
 /**
- * Local fan-out proxy for `agent-serve github forward`.
+ * Local fan-out proxy for `agent-sdk github forward`.
  *
  * `gh webhook forward` can only target a single URL, and GitHub allows just one
  * forwarder per repo/org. To feed several GitHub channels at once, we run one

package/dist/internal/github-fanout.js

@@ -1,5 +1,5 @@
 /**
- * Local fan-out proxy for `agent-serve github forward`.
+ * Local fan-out proxy for `agent-sdk github forward`.
  *
  * `gh webhook forward` can only target a single URL, and GitHub allows just one
  * forwarder per repo/org. To feed several GitHub channels at once, we run one

package/dist/internal/guest-network.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Guest egress readiness for hosted v2.
+ *
+ * `waitForEngineReady` only polls July `/v1/health` (process listening). After
+ * a freeze restore the guest network (DNS, egress programming, dead sockets)
+ * often comes up later. Authored admission/execution that `fetch`es in that
+ * window throws undici `TypeError: fetch failed`, which used to become a
+ * redacted HTTP 500 `internal_error` and a minutes-long Temporal retry.
+ *
+ * TAS waits on GET `/v1/guest-network` (90s, Sand's resume bar) before
+ * opening the hosted POST. The in-POST wait stays a short last-line check
+ * so leftover races still return 503 `guest_network_unavailable` instead of
+ * a redacted 500.
+ *
+ * Quiet guest Connect (`TypeError: fetch failed` with no errno, Connect
+ * `[unknown]`/`[canceled]`/`[unavailable]`, headers/body timeout) is a
+ * stall, not a dead NIC. Those become `guest_connect_stalled` so TAS
+ * retries the same pod — including when `waitForCompletion` resolves
+ * with that message instead of throwing.
+ */
+export declare const GUEST_NETWORK_UNAVAILABLE = "guest_network_unavailable";
+export declare const GUEST_CONNECT_STALLED = "guest_connect_stalled";
+/** Control-plane readiness probe. Auth none, same as `/v1/health`. */
+export declare const GUEST_NETWORK_PATH = "/v1/guest-network";
+/**
+ * Sand `READY_TIMEOUT_MS` / resume reachability bar. The in-POST wait stays
+ * at {@link DEFAULT_WAIT_TIMEOUT_MS}; this budget is for GET `/v1/guest-network`
+ * so TAS does not open a hosted turn on a dead NIC.
+ */
+export declare const GUEST_NETWORK_READY_WAIT_TIMEOUT_MS = 90000;
+export declare class GuestNetworkUnavailableError extends Error {
+    readonly code: typeof GUEST_NETWORK_UNAVAILABLE;
+    readonly waitMs: number;
+    readonly probeAttempts: number;
+    constructor(message?: string, extras?: {
+        waitMs?: number;
+        probeAttempts?: number;
+    });
+}
+/**
+ * True when the error (or anything on its `cause` chain, or inside an
+ * `AggregateError`) is a network-level fetch failure. Connect-web wraps
+ * undici's `TypeError: fetch failed` as `ConnectError` and keeps the
+ * original on `cause`.
+ */
+export declare function isTransientGuestNetworkError(error: unknown): boolean;
+export declare function hasGuestNetworkErrno(error: unknown): boolean;
+/**
+ * Quiet guest Connect: the request left the guest but never produced a
+ * useful RPC outcome. Distinct from {@link isTransientGuestNetworkError}
+ * so the in-POST wait still retries bare `fetch failed`, while the HTTP
+ * mapper can return `guest_connect_stalled` instead of a mystery 503.
+ */
+export declare function isQuietGuestConnectStall(error: unknown): boolean;
+/** Message-only form for `waitForCompletion` outcomes that do not throw. */
+export declare function isQuietGuestConnectStallMessage(message: string): boolean;
+/** Last-line wait inside an already-open hosted POST. */
+export declare const DEFAULT_WAIT_TIMEOUT_MS = 8000;
+export type GuestNetworkWaitOptions = {
+    /**
+     * When omitted, wait is enabled only on hosted engines (probe URL set and
+     * not running under Vitest). Tests pass `true` plus a mock `probe`.
+     */
+    enabled?: boolean;
+    /** Override the allowlisted probe URL. */
+    probeUrl?: string;
+    waitTimeoutMs?: number;
+    pollMs?: number;
+    probeTimeoutMs?: number;
+    probe?: () => Promise<void>;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+};
+export type GuestNetworkWaitOutcome = "ready" | "skipped" | "unavailable";
+export type GuestNetworkWaitResult = {
+    outcome: Exclude<GuestNetworkWaitOutcome, "unavailable">;
+    waitMs: number;
+    probeAttempts: number;
+};
+export type GuestNetworkWaitStats = {
+    outcome: GuestNetworkWaitOutcome;
+    waitMs: number;
+    probeAttempts: number;
+};
+/**
+ * `Server-Timing` metric the control plane scrapes for Datadog
+ * `hosted_*.guest_network_wait_ms`. Any HTTP response (ok or 503) can
+ * carry it so restore time-to-egress is visible on both paths.
+ */
+export declare function formatGuestNetworkServerTiming(stats: GuestNetworkWaitStats): string;
+/**
+ * Poll until a cheap allowlisted GET succeeds or the wait budget expires.
+ * Throws {@link GuestNetworkUnavailableError} on timeout so hosted routes
+ * can return 503 without running authored code.
+ */
+export declare function waitForGuestNetworkReady(options?: GuestNetworkWaitOptions): Promise<GuestNetworkWaitResult>;
+/**
+ * GET `/v1/guest-network`: wait up to
+ * {@link GUEST_NETWORK_READY_WAIT_TIMEOUT_MS} and return 200 (ready/skipped)
+ * or 503 `guest_network_unavailable`. Server-Timing matches the hosted POST
+ * so TAS can scrape the same `guest_net` metric before `postHosted`.
+ */
+export declare function guestNetworkReadinessResponse(options?: GuestNetworkWaitOptions): Promise<Response>;
+//# sourceMappingURL=guest-network.d.ts.map

package/dist/internal/guest-network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-network.d.ts","sourceRoot":"","sources":["../../src/internal/guest-network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAuB1D,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAE,OAAO,yBAAyB,CAA6B;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,YACE,OAAO,SAAsD,EAC7D,MAAM,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,EAMzD;CACF;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAgBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQhE;AAED,4EAA4E;AAC5E,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExE;AA+ED,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAG7C,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AA2CF,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,CAAC;AAE1E,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,OAAO,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,qBAAqB,GAC3B,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAkDjC;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,QAAQ,CAAC,CAsCnB"}