@agent-api/sdk 1.4.6 → 1.4.8

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog — @agent-api/sdk
 
+## 1.4.8
+
+### Changed
+
+- Restored `LocalFileStore.list()` to strict complete-or-fail scan semantics while keeping `listWithWarnings()` as the explicit tolerant partial-scan API.
+- Made local context packages leave recursive scan depth uncapped unless callers provide `maxDepth`.
+- Moved local skill discovery onto the same warning-aware filesystem scan primitive used by workdir summaries and context packages.
+
+## 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

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 = optionalPositiveInt(params.maxDepth);
     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,
     };
@@ -148,6 +151,10 @@ function positiveInt(value, fallback) {
     const parsed = Number(value);
     return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : fallback;
 }
+function optionalPositiveInt(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : undefined;
+}
 async function sha256File(workdir, relativePath) {
     const fullPath = workdir.files.resolvePath(relativePath);
     return createHash("sha256").update(await readFile(fullPath)).digest("hex");

package/dist/local/core.d.ts

@@ -68,6 +68,10 @@ export interface LocalEntryList {
     entries: LocalEntry[];
     scan_warnings?: LocalScanWarning[];
 }
+export interface LocalFileStatList {
+    stats: LocalFileStat[];
+    warnings: LocalScanWarning[];
+}
 export interface LocalScanWarning {
     path: string;
     code?: string;
@@ -286,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>;
@@ -317,7 +322,6 @@ export declare class LocalFileStore {
     grep(params: LocalGrepParams): Promise<LocalGrepResponse>;
     private grepCandidates;
     summarize(params?: LocalSummarizeParams): Promise<LocalSummary>;
-    private listWithWarnings;
     private walk;
 }
 export declare class LocalConfigStore {
@@ -348,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,7 +139,19 @@ export class LocalFileStore {
         return fullPath;
     }
     async list(relativePath = ".", options = {}) {
-        return (await this.listWithWarnings(relativePath, options)).stats;
+        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));
+    }
+    async listWithWarnings(relativePath = ".", options = {}) {
+        const base = this.resolvePath(relativePath);
+        const maxDepth = options.recursive ? options.maxDepth ?? Number.POSITIVE_INFINITY : 1;
+        const out = [];
+        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, warnings } = await this.listWithWarnings(relativePath, { ...options, includeDirectories: options.includeDirectories ?? true });
@@ -408,21 +420,13 @@ export class LocalFileStore {
             scan_truncated: scanTruncated,
         }, warnings);
     }
-    async listWithWarnings(relativePath = ".", options = {}) {
-        const base = this.resolvePath(relativePath);
-        const maxDepth = options.recursive ? options.maxDepth ?? Number.POSITIVE_INFINITY : 1;
-        const out = [];
-        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 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)) {
+            if (warnings && dir !== scanRoot && recordScanWarning(warnings, toPortablePath(path.relative(storeRoot, dir)), error)) {
                 return;
             }
             throw error;
@@ -562,6 +566,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));
     }
@@ -817,8 +824,9 @@ function defaultDirs(platform, env, home, authorSegment, appSegment, baseDir) {
     };
 }
 async function discoverSkillDirectories(root, options) {
+    const rootStore = new LocalFileStore(root);
     try {
-        const info = await stat(root);
+        const info = await stat(rootStore.root);
         if (!info.isDirectory()) {
             return [];
         }
@@ -829,27 +837,20 @@ async function discoverSkillDirectories(root, options) {
         }
         throw error;
     }
+    const { stats } = await rootStore.listWithWarnings(".", {
+        recursive: options.recursive ?? false,
+        includeDirectories: true,
+        maxDepth: options.maxDepth,
+        ignore: [".git", "node_modules", "__pycache__"],
+    });
+    const dirs = [rootStore.root, ...stats.filter((item) => item.type === "directory").map((item) => item.fullPath)];
     const out = [];
-    const maxDepth = options.recursive ? options.maxDepth ?? Number.POSITIVE_INFINITY : 1;
-    await walkSkillDirectories(root, root, out, maxDepth);
-    return out;
-}
-async function walkSkillDirectories(root, dir, out, maxDepth) {
-    if (await fileExists(path.join(dir, "SKILL.md"))) {
-        out.push(dir);
-    }
-    const relative = path.relative(root, dir);
-    const depth = relative ? relative.split(path.sep).length : 0;
-    if (depth >= maxDepth) {
-        return;
-    }
-    const entries = await readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        if (!entry.isDirectory() || ignoredDirectoryName(entry.name)) {
-            continue;
+    for (const dir of dirs) {
+        if (await fileExists(path.join(dir, "SKILL.md"))) {
+            out.push(dir);
         }
-        await walkSkillDirectories(root, path.join(dir, entry.name), out, maxDepth);
     }
+    return out;
 }
 async function fileExists(fullPath) {
     try {

package/dist/local/scan.d.ts

@@ -0,0 +1,13 @@
+export interface LocalScanWarning {
+    path: string;
+    code?: string;
+    message: string;
+}
+export interface LocalScanWarningList<T> {
+    value: T;
+    warnings: LocalScanWarning[];
+}
+export declare function withScanWarnings<T>(value: T, warnings: LocalScanWarning[]): T & {
+    scan_warnings?: LocalScanWarning[];
+};
+export declare function recordScanWarning(warnings: LocalScanWarning[], relativePath: string, error: unknown): boolean;

package/dist/local/scan.js

@@ -0,0 +1,24 @@
+const maxScanWarnings = 20;
+const ignorableScanErrorCodes = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ENOTCONN", "ELOOP", "EINVAL"]);
+export function withScanWarnings(value, warnings) {
+    const out = value;
+    if (warnings.length > 0) {
+        out.scan_warnings = warnings;
+    }
+    return out;
+}
+export 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;
+}

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.6";
-export declare const USER_AGENT = "@agent-api/sdk/1.4.6";
+export declare const VERSION = "1.4.8";
+export declare const USER_AGENT = "@agent-api/sdk/1.4.8";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "1.4.6";
+export const VERSION = "1.4.8";
 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 = optionalPositiveInt(params.maxDepth);
     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,
     };
@@ -152,6 +155,10 @@ function positiveInt(value, fallback) {
     const parsed = Number(value);
     return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : fallback;
 }
+function optionalPositiveInt(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : undefined;
+}
 async function sha256File(workdir, relativePath) {
     const fullPath = workdir.files.resolvePath(relativePath);
     return (0, node_crypto_1.createHash)("sha256").update(await (0, promises_1.readFile)(fullPath)).digest("hex");

package/dist-cjs/local/core.js

@@ -154,7 +154,19 @@ class LocalFileStore {
         return fullPath;
     }
     async list(relativePath = ".", options = {}) {
-        return (await this.listWithWarnings(relativePath, options)).stats;
+        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));
+    }
+    async listWithWarnings(relativePath = ".", options = {}) {
+        const base = this.resolvePath(relativePath);
+        const maxDepth = options.recursive ? options.maxDepth ?? Number.POSITIVE_INFINITY : 1;
+        const out = [];
+        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, warnings } = await this.listWithWarnings(relativePath, { ...options, includeDirectories: options.includeDirectories ?? true });
@@ -423,21 +435,13 @@ class LocalFileStore {
             scan_truncated: scanTruncated,
         }, warnings);
     }
-    async listWithWarnings(relativePath = ".", options = {}) {
-        const base = this.resolvePath(relativePath);
-        const maxDepth = options.recursive ? options.maxDepth ?? Number.POSITIVE_INFINITY : 1;
-        const out = [];
-        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 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)) {
+            if (warnings && dir !== scanRoot && recordScanWarning(warnings, toPortablePath(node_path_1.default.relative(storeRoot, dir)), error)) {
                 return;
             }
             throw error;
@@ -580,6 +584,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));
     }
@@ -837,8 +844,9 @@ function defaultDirs(platform, env, home, authorSegment, appSegment, baseDir) {
     };
 }
 async function discoverSkillDirectories(root, options) {
+    const rootStore = new LocalFileStore(root);
     try {
-        const info = await (0, promises_1.stat)(root);
+        const info = await (0, promises_1.stat)(rootStore.root);
         if (!info.isDirectory()) {
             return [];
         }
@@ -849,27 +857,20 @@ async function discoverSkillDirectories(root, options) {
         }
         throw error;
     }
+    const { stats } = await rootStore.listWithWarnings(".", {
+        recursive: options.recursive ?? false,
+        includeDirectories: true,
+        maxDepth: options.maxDepth,
+        ignore: [".git", "node_modules", "__pycache__"],
+    });
+    const dirs = [rootStore.root, ...stats.filter((item) => item.type === "directory").map((item) => item.fullPath)];
     const out = [];
-    const maxDepth = options.recursive ? options.maxDepth ?? Number.POSITIVE_INFINITY : 1;
-    await walkSkillDirectories(root, root, out, maxDepth);
-    return out;
-}
-async function walkSkillDirectories(root, dir, out, maxDepth) {
-    if (await fileExists(node_path_1.default.join(dir, "SKILL.md"))) {
-        out.push(dir);
-    }
-    const relative = node_path_1.default.relative(root, dir);
-    const depth = relative ? relative.split(node_path_1.default.sep).length : 0;
-    if (depth >= maxDepth) {
-        return;
-    }
-    const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        if (!entry.isDirectory() || ignoredDirectoryName(entry.name)) {
-            continue;
+    for (const dir of dirs) {
+        if (await fileExists(node_path_1.default.join(dir, "SKILL.md"))) {
+            out.push(dir);
         }
-        await walkSkillDirectories(root, node_path_1.default.join(dir, entry.name), out, maxDepth);
     }
+    return out;
 }
 async function fileExists(fullPath) {
     try {

package/dist-cjs/local/scan.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withScanWarnings = withScanWarnings;
+exports.recordScanWarning = recordScanWarning;
+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;
+}

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.6";
+exports.VERSION = "1.4.8";
 exports.USER_AGENT = `@agent-api/sdk/${exports.VERSION}`;

package/package.json

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