@agent-api/sdk 1.4.5 → 1.4.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog — @agent-api/sdk
 
+## 1.4.7
+
+### Added
+
+- Added warning-aware low-level local workdir listing via `listWithWarnings()`.
+
+### Fixed
+
+- Made local context packages use bounded recursive scans and expose `scan_warnings` for skipped child paths.
+
+## 1.4.6
+
+### Fixed
+
+- Made local workdir scans skip inaccessible or broken child entries with structured `scan_warnings` instead of failing an otherwise valid workdir.
+
 ## 1.4.5
 
 ### Fixed

package/dist/local/context.d.ts

@@ -1,4 +1,4 @@
-import { type LocalFileDeliver, type LocalGrepResponse, type LocalPathSensitivity, type LocalPathSensitivityInfo, type LocalSummary, type LocalWorkdir, type LocalWorkdirSnapshotFile } from "./core.js";
+import { type LocalFileDeliver, type LocalGrepResponse, type LocalPathSensitivity, type LocalPathSensitivityInfo, type LocalScanWarning, type LocalSummary, type LocalWorkdir, type LocalWorkdirSnapshotFile } from "./core.js";
 export interface LocalContextPackageParams {
     path?: string;
     include?: string[];
@@ -7,6 +7,7 @@ export interface LocalContextPackageParams {
     maxFiles?: number;
     maxBytes?: number;
     maxBytesPerFile?: number;
+    maxDepth?: number;
     previewBytes?: number;
     includeContent?: boolean;
     includeHashes?: boolean;
@@ -38,6 +39,7 @@ export interface LocalContextManifest {
     included_bytes: number;
     truncated: boolean;
     files: LocalContextFile[];
+    scan_warnings?: LocalScanWarning[];
     summary?: LocalSummary;
     search?: LocalGrepResponse;
 }

package/dist/local/context.js

@@ -6,13 +6,14 @@ export async function createLocalContextPackage(workdir, params = {}) {
     const maxFiles = positiveInt(params.maxFiles, 80);
     const maxBytes = positiveInt(params.maxBytes, 256 * 1024);
     const maxBytesPerFile = positiveInt(params.maxBytesPerFile, 32 * 1024);
+    const maxDepth = positiveInt(params.maxDepth, 3);
     const previewBytes = positiveInt(params.previewBytes, maxBytesPerFile);
     const includeContent = params.includeContent ?? true;
     const includeHashes = params.includeHashes ?? true;
     const includeSummary = params.includeSummary ?? true;
     const includeSearch = Boolean(params.includeSearch && params.query?.trim());
     const includeSecrets = params.includeSecrets ?? false;
-    const stats = await workdir.list(basePath, { recursive: true });
+    const { stats, warnings } = await workdir.listWithWarnings(basePath, { recursive: true, maxDepth });
     const fileStats = stats
         .filter((item) => item.type === "file")
         .filter((item) => matchesPathFilters(item.path, params.include, params.exclude))
@@ -75,6 +76,7 @@ export async function createLocalContextPackage(workdir, params = {}) {
         ? await workdir.summarize({
             path: basePath,
             maxFiles,
+            maxDepth,
             previewBytes,
             ignore: params.exclude,
         })
@@ -99,6 +101,7 @@ export async function createLocalContextPackage(workdir, params = {}) {
         included_bytes: includedBytes,
         truncated,
         files,
+        scan_warnings: warnings.length ? warnings : undefined,
         summary,
         search,
     };

package/dist/local/core.d.ts

@@ -66,6 +66,16 @@ export interface LocalEntry {
 export interface LocalEntryList {
     object: "list";
     entries: LocalEntry[];
+    scan_warnings?: LocalScanWarning[];
+}
+export interface LocalFileStatList {
+    stats: LocalFileStat[];
+    warnings: LocalScanWarning[];
+}
+export interface LocalScanWarning {
+    path: string;
+    code?: string;
+    message: string;
 }
 export interface LocalSearchEntriesParams {
     query: string;
@@ -174,6 +184,7 @@ export interface LocalSummary {
     text_previews: LocalSummaryPreview[];
     generated_at_unix: number;
     scan_truncated: boolean;
+    scan_warnings?: LocalScanWarning[];
 }
 export interface LocalWorkdirOptions {
     name?: string;
@@ -279,6 +290,7 @@ export declare class LocalFileStore {
     stat(relativePath?: string): Promise<LocalFileStat>;
     mkdir(relativePath?: string): Promise<string>;
     list(relativePath?: string, options?: LocalListOptions): Promise<LocalFileStat[]>;
+    listWithWarnings(relativePath?: string, options?: LocalListOptions): Promise<LocalFileStatList>;
     listEntries(relativePath?: string, options?: LocalListOptions): Promise<LocalEntryList>;
     searchEntries(params: LocalSearchEntriesParams): Promise<LocalEntryList>;
     readText(relativePath: string): Promise<string>;
@@ -340,6 +352,7 @@ export declare class LocalWorkdir {
     child(relativePath: string, options?: LocalWorkdirOptions): LocalWorkdir;
     resolvePath(relativePath?: string): string;
     list(relativePath?: string, options?: LocalListOptions): Promise<LocalFileStat[]>;
+    listWithWarnings(relativePath?: string, options?: LocalListOptions): Promise<LocalFileStatList>;
     listEntries(relativePath?: string, options?: LocalListOptions): Promise<LocalEntryList>;
     searchEntries(params: LocalSearchEntriesParams): Promise<LocalEntryList>;
     readFile(relativePath: string, params: LocalReadFileRawParams): Promise<LocalFileRaw>;

package/dist/local/core.js

@@ -139,15 +139,19 @@ export class LocalFileStore {
         return fullPath;
     }
     async list(relativePath = ".", options = {}) {
+        return (await this.listWithWarnings(relativePath, options)).stats;
+    }
+    async listWithWarnings(relativePath = ".", options = {}) {
         const base = this.resolvePath(relativePath);
         const maxDepth = options.recursive ? options.maxDepth ?? Number.POSITIVE_INFINITY : 1;
         const out = [];
-        await this.walk(this.root, base, base, out, maxDepth, options);
-        return out.sort((a, b) => a.path.localeCompare(b.path));
+        const warnings = [];
+        await this.walk(this.root, base, base, out, maxDepth, options, warnings);
+        return { stats: out.sort((a, b) => a.path.localeCompare(b.path)), warnings };
     }
     async listEntries(relativePath = ".", options = {}) {
-        const stats = await this.list(relativePath, { ...options, includeDirectories: options.includeDirectories ?? true });
-        return { object: "list", entries: stats.map(localEntryFromStat) };
+        const { stats, warnings } = await this.listWithWarnings(relativePath, { ...options, includeDirectories: options.includeDirectories ?? true });
+        return withScanWarnings({ object: "list", entries: stats.map(localEntryFromStat) }, warnings);
     }
     async searchEntries(params) {
         const query = params.query.trim().toLowerCase();
@@ -374,7 +378,7 @@ export class LocalFileStore {
         const maxPreviews = positiveInt(params.maxPreviews, 20);
         const previewBytes = positiveInt(params.previewBytes, 4096);
         const topPaths = positiveInt(params.topPaths, 20);
-        const stats = await this.list(params.path ?? ".", { recursive: true, maxDepth: params.maxDepth, ignore: params.ignore });
+        const { stats, warnings } = await this.listWithWarnings(params.path ?? ".", { recursive: true, maxDepth: params.maxDepth, ignore: params.ignore });
         const files = stats.filter((item) => item.type === "file").slice(0, maxFiles);
         const scanTruncated = stats.filter((item) => item.type === "file").length > files.length;
         const totalBytes = files.reduce((sum, item) => sum + item.size, 0);
@@ -402,7 +406,7 @@ export class LocalFileStore {
                 preview_truncated: truncated || undefined,
             });
         }
-        return {
+        return withScanWarnings({
             summary_path: "",
             file_count: files.length,
             total_bytes: totalBytes,
@@ -410,17 +414,26 @@ export class LocalFileStore {
             text_previews: previews,
             generated_at_unix: Math.floor(Date.now() / 1000),
             scan_truncated: scanTruncated,
-        };
+        }, warnings);
     }
-    async walk(storeRoot, scanRoot, dir, out, maxDepth, options) {
-        const entries = await readdir(dir, { withFileTypes: true });
+    async walk(storeRoot, scanRoot, dir, out, maxDepth, options, warnings) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (dir !== scanRoot && recordScanWarning(warnings, toPortablePath(path.relative(storeRoot, dir)), error)) {
+                return;
+            }
+            throw error;
+        }
         for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
             const relativePath = toPortablePath(path.relative(storeRoot, fullPath));
             if (ignored(relativePath, options.ignore)) {
                 continue;
             }
-            const info = await lstatOptional(fullPath);
+            const info = await lstatOptional(fullPath, relativePath, warnings);
             if (!info) {
                 continue;
             }
@@ -437,7 +450,7 @@ export class LocalFileStore {
                 }
                 const depth = toPortablePath(path.relative(scanRoot, fullPath)).split("/").filter(Boolean).length;
                 if (depth < maxDepth) {
-                    await this.walk(storeRoot, scanRoot, fullPath, out, maxDepth, options);
+                    await this.walk(storeRoot, scanRoot, fullPath, out, maxDepth, options, warnings);
                 }
                 continue;
             }
@@ -549,6 +562,9 @@ export class LocalWorkdir {
     async list(relativePath = ".", options = {}) {
         return await this.files.list(relativePath, this.scopedListOptions(options));
     }
+    async listWithWarnings(relativePath = ".", options = {}) {
+        return await this.files.listWithWarnings(relativePath, this.scopedListOptions(options));
+    }
     async listEntries(relativePath = ".", options = {}) {
         return await this.files.listEntries(relativePath, this.scopedListOptions(options));
     }
@@ -847,11 +863,38 @@ async function fileExists(fullPath) {
         return false;
     }
 }
-async function lstatOptional(fullPath) {
+const maxScanWarnings = 20;
+const ignorableScanErrorCodes = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ENOTCONN", "ELOOP", "EINVAL"]);
+function withScanWarnings(value, warnings) {
+    const out = value;
+    if (warnings.length > 0) {
+        out.scan_warnings = warnings;
+    }
+    return out;
+}
+function recordScanWarning(warnings, relativePath, error) {
+    const scanError = error;
+    const code = typeof scanError?.code === "string" ? scanError.code : undefined;
+    if (!code || !ignorableScanErrorCodes.has(code)) {
+        return false;
+    }
+    if (warnings.length < maxScanWarnings) {
+        warnings.push({
+            path: relativePath || ".",
+            code,
+            message: typeof scanError.message === "string" ? scanError.message : code,
+        });
+    }
+    return true;
+}
+async function lstatOptional(fullPath, relativePath, warnings) {
     try {
         return await lstat(fullPath);
     }
     catch (error) {
+        if (warnings && relativePath && recordScanWarning(warnings, relativePath, error)) {
+            return null;
+        }
         if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
             return null;
         }
@@ -863,7 +906,7 @@ async function readOptionalFile(fullPath) {
         return await readFile(fullPath);
     }
     catch (error) {
-        if (error?.code === "ENOENT" || error?.code === "ENOTDIR" || error?.code === "EISDIR") {
+        if (error?.code === "ENOENT" || error?.code === "ENOTDIR" || error?.code === "EISDIR" || error?.code === "ENOTCONN") {
             return null;
         }
         throw error;

package/dist/local/tools.js

@@ -255,6 +255,7 @@ function contextPackageArgs(args) {
         maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
         maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
         maxBytesPerFile: optionalNumberArg(args, "maxBytesPerFile", "max_bytes_per_file"),
+        maxDepth: optionalNumberArg(args, "maxDepth", "max_depth"),
         includeContent: optionalBooleanArg(args, "includeContent", "include_content"),
         includeSummary: optionalBooleanArg(args, "includeSummary", "include_summary"),
         includeSearch: optionalBooleanArg(args, "includeSearch", "include_search"),

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.4.5";
-export declare const USER_AGENT = "@agent-api/sdk/1.4.5";
+export declare const VERSION = "1.4.7";
+export declare const USER_AGENT = "@agent-api/sdk/1.4.7";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "1.4.5";
+export const VERSION = "1.4.7";
 export const USER_AGENT = `@agent-api/sdk/${VERSION}`;

package/dist-cjs/local/context.js

@@ -10,13 +10,14 @@ async function createLocalContextPackage(workdir, params = {}) {
     const maxFiles = positiveInt(params.maxFiles, 80);
     const maxBytes = positiveInt(params.maxBytes, 256 * 1024);
     const maxBytesPerFile = positiveInt(params.maxBytesPerFile, 32 * 1024);
+    const maxDepth = positiveInt(params.maxDepth, 3);
     const previewBytes = positiveInt(params.previewBytes, maxBytesPerFile);
     const includeContent = params.includeContent ?? true;
     const includeHashes = params.includeHashes ?? true;
     const includeSummary = params.includeSummary ?? true;
     const includeSearch = Boolean(params.includeSearch && params.query?.trim());
     const includeSecrets = params.includeSecrets ?? false;
-    const stats = await workdir.list(basePath, { recursive: true });
+    const { stats, warnings } = await workdir.listWithWarnings(basePath, { recursive: true, maxDepth });
     const fileStats = stats
         .filter((item) => item.type === "file")
         .filter((item) => matchesPathFilters(item.path, params.include, params.exclude))
@@ -79,6 +80,7 @@ async function createLocalContextPackage(workdir, params = {}) {
         ? await workdir.summarize({
             path: basePath,
             maxFiles,
+            maxDepth,
             previewBytes,
             ignore: params.exclude,
         })
@@ -103,6 +105,7 @@ async function createLocalContextPackage(workdir, params = {}) {
         included_bytes: includedBytes,
         truncated,
         files,
+        scan_warnings: warnings.length ? warnings : undefined,
         summary,
         search,
     };

package/dist-cjs/local/core.js

@@ -154,15 +154,19 @@ class LocalFileStore {
         return fullPath;
     }
     async list(relativePath = ".", options = {}) {
+        return (await this.listWithWarnings(relativePath, options)).stats;
+    }
+    async listWithWarnings(relativePath = ".", options = {}) {
         const base = this.resolvePath(relativePath);
         const maxDepth = options.recursive ? options.maxDepth ?? Number.POSITIVE_INFINITY : 1;
         const out = [];
-        await this.walk(this.root, base, base, out, maxDepth, options);
-        return out.sort((a, b) => a.path.localeCompare(b.path));
+        const warnings = [];
+        await this.walk(this.root, base, base, out, maxDepth, options, warnings);
+        return { stats: out.sort((a, b) => a.path.localeCompare(b.path)), warnings };
     }
     async listEntries(relativePath = ".", options = {}) {
-        const stats = await this.list(relativePath, { ...options, includeDirectories: options.includeDirectories ?? true });
-        return { object: "list", entries: stats.map(localEntryFromStat) };
+        const { stats, warnings } = await this.listWithWarnings(relativePath, { ...options, includeDirectories: options.includeDirectories ?? true });
+        return withScanWarnings({ object: "list", entries: stats.map(localEntryFromStat) }, warnings);
     }
     async searchEntries(params) {
         const query = params.query.trim().toLowerCase();
@@ -389,7 +393,7 @@ class LocalFileStore {
         const maxPreviews = positiveInt(params.maxPreviews, 20);
         const previewBytes = positiveInt(params.previewBytes, 4096);
         const topPaths = positiveInt(params.topPaths, 20);
-        const stats = await this.list(params.path ?? ".", { recursive: true, maxDepth: params.maxDepth, ignore: params.ignore });
+        const { stats, warnings } = await this.listWithWarnings(params.path ?? ".", { recursive: true, maxDepth: params.maxDepth, ignore: params.ignore });
         const files = stats.filter((item) => item.type === "file").slice(0, maxFiles);
         const scanTruncated = stats.filter((item) => item.type === "file").length > files.length;
         const totalBytes = files.reduce((sum, item) => sum + item.size, 0);
@@ -417,7 +421,7 @@ class LocalFileStore {
                 preview_truncated: truncated || undefined,
             });
         }
-        return {
+        return withScanWarnings({
             summary_path: "",
             file_count: files.length,
             total_bytes: totalBytes,
@@ -425,17 +429,26 @@ class LocalFileStore {
             text_previews: previews,
             generated_at_unix: Math.floor(Date.now() / 1000),
             scan_truncated: scanTruncated,
-        };
+        }, warnings);
     }
-    async walk(storeRoot, scanRoot, dir, out, maxDepth, options) {
-        const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+    async walk(storeRoot, scanRoot, dir, out, maxDepth, options, warnings) {
+        let entries;
+        try {
+            entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (dir !== scanRoot && recordScanWarning(warnings, toPortablePath(node_path_1.default.relative(storeRoot, dir)), error)) {
+                return;
+            }
+            throw error;
+        }
         for (const entry of entries) {
             const fullPath = node_path_1.default.join(dir, entry.name);
             const relativePath = toPortablePath(node_path_1.default.relative(storeRoot, fullPath));
             if (ignored(relativePath, options.ignore)) {
                 continue;
             }
-            const info = await lstatOptional(fullPath);
+            const info = await lstatOptional(fullPath, relativePath, warnings);
             if (!info) {
                 continue;
             }
@@ -452,7 +465,7 @@ class LocalFileStore {
                 }
                 const depth = toPortablePath(node_path_1.default.relative(scanRoot, fullPath)).split("/").filter(Boolean).length;
                 if (depth < maxDepth) {
-                    await this.walk(storeRoot, scanRoot, fullPath, out, maxDepth, options);
+                    await this.walk(storeRoot, scanRoot, fullPath, out, maxDepth, options, warnings);
                 }
                 continue;
             }
@@ -567,6 +580,9 @@ class LocalWorkdir {
     async list(relativePath = ".", options = {}) {
         return await this.files.list(relativePath, this.scopedListOptions(options));
     }
+    async listWithWarnings(relativePath = ".", options = {}) {
+        return await this.files.listWithWarnings(relativePath, this.scopedListOptions(options));
+    }
     async listEntries(relativePath = ".", options = {}) {
         return await this.files.listEntries(relativePath, this.scopedListOptions(options));
     }
@@ -867,11 +883,38 @@ async function fileExists(fullPath) {
         return false;
     }
 }
-async function lstatOptional(fullPath) {
+const maxScanWarnings = 20;
+const ignorableScanErrorCodes = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ENOTCONN", "ELOOP", "EINVAL"]);
+function withScanWarnings(value, warnings) {
+    const out = value;
+    if (warnings.length > 0) {
+        out.scan_warnings = warnings;
+    }
+    return out;
+}
+function recordScanWarning(warnings, relativePath, error) {
+    const scanError = error;
+    const code = typeof scanError?.code === "string" ? scanError.code : undefined;
+    if (!code || !ignorableScanErrorCodes.has(code)) {
+        return false;
+    }
+    if (warnings.length < maxScanWarnings) {
+        warnings.push({
+            path: relativePath || ".",
+            code,
+            message: typeof scanError.message === "string" ? scanError.message : code,
+        });
+    }
+    return true;
+}
+async function lstatOptional(fullPath, relativePath, warnings) {
     try {
         return await (0, promises_1.lstat)(fullPath);
     }
     catch (error) {
+        if (warnings && relativePath && recordScanWarning(warnings, relativePath, error)) {
+            return null;
+        }
         if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
             return null;
         }
@@ -883,7 +926,7 @@ async function readOptionalFile(fullPath) {
         return await (0, promises_1.readFile)(fullPath);
     }
     catch (error) {
-        if (error?.code === "ENOENT" || error?.code === "ENOTDIR" || error?.code === "EISDIR") {
+        if (error?.code === "ENOENT" || error?.code === "ENOTDIR" || error?.code === "EISDIR" || error?.code === "ENOTCONN") {
             return null;
         }
         throw error;

package/dist-cjs/local/tools.js

@@ -262,6 +262,7 @@ function contextPackageArgs(args) {
         maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
         maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
         maxBytesPerFile: optionalNumberArg(args, "maxBytesPerFile", "max_bytes_per_file"),
+        maxDepth: optionalNumberArg(args, "maxDepth", "max_depth"),
         includeContent: optionalBooleanArg(args, "includeContent", "include_content"),
         includeSummary: optionalBooleanArg(args, "includeSummary", "include_summary"),
         includeSearch: optionalBooleanArg(args, "includeSearch", "include_search"),

package/dist-cjs/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.USER_AGENT = exports.VERSION = void 0;
-exports.VERSION = "1.4.5";
+exports.VERSION = "1.4.7";
 exports.USER_AGENT = `@agent-api/sdk/${exports.VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-api/sdk",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "description": "Production JavaScript SDK for the Managed Agent API",
   "license": "MIT",
   "repository": {