@agent-api/sdk 1.4.3 → 1.4.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — @agent-api/sdk
 
+## 1.4.5
+
+### Fixed
+
+- Made local workdir summaries honor `maxDepth`, and aligned model-facing summarize options with the direct SDK API.
+
+## 1.4.4
+
+### Added
+
+- Added a model-facing `local_pause` tool primitive for bounded local workflow waits, with early-resume hooks for host runtimes.
+
 ## 1.4.3
 
 ### Fixed

package/README.md

@@ -219,7 +219,7 @@ await workdir.patchLines("src/index.ts", {
   replacement: "console.log('patched');",
 });
 
-const summary = await workdir.summarize();
+const summary = await workdir.summarize({ maxDepth: 3, maxFiles: 500 });
 ```
 
 For project/workdir roots, prefer `local.workdir()` so SDK defaults protect common generated directories such as `.git`, `node_modules`, `dist`, and build caches.

package/dist/local/core.d.ts

@@ -157,6 +157,7 @@ export interface LocalSummarizeParams {
     maxPreviews?: number;
     previewBytes?: number;
     topPaths?: number;
+    maxDepth?: number;
     ignore?: LocalListOptions["ignore"];
 }
 export interface LocalSummaryPreview {

package/dist/local/core.js

@@ -374,7 +374,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, ignore: params.ignore });
+        const stats = await this.list(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);

package/dist/local/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./core.js";
 export * from "./context.js";
+export * from "./pause.js";
 export * from "./shell.js";
 export * from "./tools.js";

package/dist/local/index.js

@@ -1,4 +1,5 @@
 export * from "./core.js";
 export * from "./context.js";
+export * from "./pause.js";
 export * from "./shell.js";
 export * from "./tools.js";

package/dist/local/pause.d.ts

@@ -0,0 +1,42 @@
+import type { FunctionTool } from "../types/tools.js";
+export interface LocalPauseRequest {
+    durationMs: number;
+    reason?: string;
+}
+export interface LocalPauseResult extends Record<string, unknown> {
+    ok: true;
+    tool: string;
+    action: "pause";
+    requested_ms: number;
+    elapsed_ms: number;
+    status: "completed" | "cancelled";
+    reason?: string;
+    resume_message?: string;
+}
+export interface LocalPauseHandle {
+    readonly request: LocalPauseRequest;
+    resume(message?: string): void;
+}
+export interface LocalPauseToolRegistryOptions {
+    maxDurationMs?: number;
+    toolName?: string;
+    onPauseStart?: (handle: LocalPauseHandle) => void;
+    onPauseEnd?: (result: LocalPauseResult) => void;
+}
+export interface LocalPauseToolRegistry {
+    readonly maxDurationMs: number;
+    readonly toolName: string;
+    definitions(): FunctionTool[];
+    handlers(): Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>>;
+    execute(name: string, args: Record<string, unknown>, context?: {
+        signal?: AbortSignal;
+    }): Promise<Record<string, unknown>>;
+    requiresApproval(name: string, args?: Record<string, unknown>): boolean;
+}
+export declare function createLocalPauseToolRegistry(options?: LocalPauseToolRegistryOptions): LocalPauseToolRegistry;
+export declare function localPauseToolDefinition(name?: string, options?: {
+    maxDurationMs?: number;
+}): FunctionTool;
+export declare function localPauseToolInstructions(options?: {
+    maxDurationMs?: number;
+}): string;

package/dist/local/pause.js

@@ -0,0 +1,122 @@
+const defaultMaxDurationMs = 5 * 60 * 1000;
+export function createLocalPauseToolRegistry(options = {}) {
+    const toolName = options.toolName ?? "local_pause";
+    const maxDurationMs = Math.max(1, Math.floor(options.maxDurationMs ?? defaultMaxDurationMs));
+    const definition = localPauseToolDefinition(toolName, { maxDurationMs });
+    return {
+        maxDurationMs,
+        toolName,
+        definitions: () => [{ ...definition }],
+        handlers: () => ({ [toolName]: (args) => executeLocalPause(toolName, args, { maxDurationMs, ...options }) }),
+        execute: async (name, args, context = {}) => {
+            if (name !== toolName) {
+                throw new Error(`unknown local pause tool: ${name}`);
+            }
+            return await executeLocalPause(toolName, args, { maxDurationMs, signal: context.signal, ...options });
+        },
+        requiresApproval: (name) => name === toolName && false,
+    };
+}
+export function localPauseToolDefinition(name = "local_pause", options = {}) {
+    return {
+        type: "function",
+        name,
+        description: localPauseToolInstructions(options),
+        parameters: localPauseToolParameters(options),
+        strict: false,
+    };
+}
+export function localPauseToolInstructions(options = {}) {
+    const maxDurationMs = Math.max(1, Math.floor(options.maxDurationMs ?? defaultMaxDurationMs));
+    return [
+        "Pause the local agentic workflow for a bounded amount of time, then continue automatically.",
+        "Use this only when waiting for external state such as CI, deployment rollout, rate-limit cooldown, file sync, or another asynchronous process.",
+        "The pause is local runtime control, not reasoning time. Keep the reason concrete.",
+        `Maximum duration: ${maxDurationMs} ms. The user may resume the pause early; early resume returns status=cancelled with elapsed_ms.`,
+    ].join(" ");
+}
+function localPauseToolParameters(options = {}) {
+    const maxDurationMs = Math.max(1, Math.floor(options.maxDurationMs ?? defaultMaxDurationMs));
+    return {
+        type: "object",
+        properties: {
+            duration_ms: {
+                type: "integer",
+                minimum: 1,
+                maximum: maxDurationMs,
+                description: "How long to wait before continuing automatically, in milliseconds.",
+            },
+            reason: {
+                type: "string",
+                description: "Short reason for the wait, such as the external state being awaited.",
+            },
+        },
+        required: ["duration_ms"],
+        additionalProperties: false,
+    };
+}
+async function executeLocalPause(toolName, args, options) {
+    const request = pauseRequest(args, options.maxDurationMs);
+    const startedAt = Date.now();
+    let settled = false;
+    let timer = null;
+    let abortHandler = null;
+    return await new Promise((resolve, reject) => {
+        const finish = (status, resumeMessage) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (abortHandler)
+                options.signal?.removeEventListener("abort", abortHandler);
+            const result = {
+                ok: true,
+                tool: toolName,
+                action: "pause",
+                requested_ms: request.durationMs,
+                elapsed_ms: Math.max(0, Date.now() - startedAt),
+                status,
+                ...(request.reason ? { reason: request.reason } : {}),
+                ...(resumeMessage ? { resume_message: resumeMessage } : {}),
+            };
+            options.onPauseEnd?.(result);
+            resolve(result);
+        };
+        abortHandler = () => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            reject(new Error("local_pause aborted"));
+        };
+        if (options.signal?.aborted) {
+            abortHandler();
+            return;
+        }
+        options.signal?.addEventListener("abort", abortHandler);
+        options.onPauseStart?.({
+            request,
+            resume(message) {
+                finish("cancelled", message);
+            },
+        });
+        timer = setTimeout(() => finish("completed"), request.durationMs);
+    });
+}
+function pauseRequest(args, maxDurationMs) {
+    const raw = args.duration_ms ?? args.durationMs;
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+        throw new Error("local_pause duration_ms must be a finite number");
+    }
+    const durationMs = Math.floor(raw);
+    if (durationMs < 1) {
+        throw new Error("local_pause duration_ms must be at least 1");
+    }
+    if (durationMs > maxDurationMs) {
+        throw new Error(`local_pause duration_ms must be <= ${maxDurationMs}`);
+    }
+    const reason = typeof args.reason === "string" && args.reason.trim() ? args.reason.trim() : undefined;
+    return { durationMs, reason };
+}

package/dist/local/tools.js

@@ -202,6 +202,9 @@ function summaryArgs(args) {
         path: optionalStringArg(args, "path"),
         maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
         maxPreviews: optionalNumberArg(args, "maxPreviews", "max_previews"),
+        previewBytes: optionalNumberArg(args, "previewBytes", "preview_bytes"),
+        topPaths: optionalNumberArg(args, "topPaths", "top_paths"),
+        maxDepth: optionalNumberArg(args, "maxDepth", "max_depth"),
     };
 }
 function grepArgs(args) {

package/dist/version.d.ts

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

package/dist/version.js

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

package/dist-cjs/local/core.js

@@ -389,7 +389,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, ignore: params.ignore });
+        const stats = await this.list(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);

package/dist-cjs/local/index.js

@@ -16,5 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./core.js"), exports);
 __exportStar(require("./context.js"), exports);
+__exportStar(require("./pause.js"), exports);
 __exportStar(require("./shell.js"), exports);
 __exportStar(require("./tools.js"), exports);

package/dist-cjs/local/pause.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLocalPauseToolRegistry = createLocalPauseToolRegistry;
+exports.localPauseToolDefinition = localPauseToolDefinition;
+exports.localPauseToolInstructions = localPauseToolInstructions;
+const defaultMaxDurationMs = 5 * 60 * 1000;
+function createLocalPauseToolRegistry(options = {}) {
+    const toolName = options.toolName ?? "local_pause";
+    const maxDurationMs = Math.max(1, Math.floor(options.maxDurationMs ?? defaultMaxDurationMs));
+    const definition = localPauseToolDefinition(toolName, { maxDurationMs });
+    return {
+        maxDurationMs,
+        toolName,
+        definitions: () => [{ ...definition }],
+        handlers: () => ({ [toolName]: (args) => executeLocalPause(toolName, args, { maxDurationMs, ...options }) }),
+        execute: async (name, args, context = {}) => {
+            if (name !== toolName) {
+                throw new Error(`unknown local pause tool: ${name}`);
+            }
+            return await executeLocalPause(toolName, args, { maxDurationMs, signal: context.signal, ...options });
+        },
+        requiresApproval: (name) => name === toolName && false,
+    };
+}
+function localPauseToolDefinition(name = "local_pause", options = {}) {
+    return {
+        type: "function",
+        name,
+        description: localPauseToolInstructions(options),
+        parameters: localPauseToolParameters(options),
+        strict: false,
+    };
+}
+function localPauseToolInstructions(options = {}) {
+    const maxDurationMs = Math.max(1, Math.floor(options.maxDurationMs ?? defaultMaxDurationMs));
+    return [
+        "Pause the local agentic workflow for a bounded amount of time, then continue automatically.",
+        "Use this only when waiting for external state such as CI, deployment rollout, rate-limit cooldown, file sync, or another asynchronous process.",
+        "The pause is local runtime control, not reasoning time. Keep the reason concrete.",
+        `Maximum duration: ${maxDurationMs} ms. The user may resume the pause early; early resume returns status=cancelled with elapsed_ms.`,
+    ].join(" ");
+}
+function localPauseToolParameters(options = {}) {
+    const maxDurationMs = Math.max(1, Math.floor(options.maxDurationMs ?? defaultMaxDurationMs));
+    return {
+        type: "object",
+        properties: {
+            duration_ms: {
+                type: "integer",
+                minimum: 1,
+                maximum: maxDurationMs,
+                description: "How long to wait before continuing automatically, in milliseconds.",
+            },
+            reason: {
+                type: "string",
+                description: "Short reason for the wait, such as the external state being awaited.",
+            },
+        },
+        required: ["duration_ms"],
+        additionalProperties: false,
+    };
+}
+async function executeLocalPause(toolName, args, options) {
+    const request = pauseRequest(args, options.maxDurationMs);
+    const startedAt = Date.now();
+    let settled = false;
+    let timer = null;
+    let abortHandler = null;
+    return await new Promise((resolve, reject) => {
+        const finish = (status, resumeMessage) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (abortHandler)
+                options.signal?.removeEventListener("abort", abortHandler);
+            const result = {
+                ok: true,
+                tool: toolName,
+                action: "pause",
+                requested_ms: request.durationMs,
+                elapsed_ms: Math.max(0, Date.now() - startedAt),
+                status,
+                ...(request.reason ? { reason: request.reason } : {}),
+                ...(resumeMessage ? { resume_message: resumeMessage } : {}),
+            };
+            options.onPauseEnd?.(result);
+            resolve(result);
+        };
+        abortHandler = () => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            reject(new Error("local_pause aborted"));
+        };
+        if (options.signal?.aborted) {
+            abortHandler();
+            return;
+        }
+        options.signal?.addEventListener("abort", abortHandler);
+        options.onPauseStart?.({
+            request,
+            resume(message) {
+                finish("cancelled", message);
+            },
+        });
+        timer = setTimeout(() => finish("completed"), request.durationMs);
+    });
+}
+function pauseRequest(args, maxDurationMs) {
+    const raw = args.duration_ms ?? args.durationMs;
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+        throw new Error("local_pause duration_ms must be a finite number");
+    }
+    const durationMs = Math.floor(raw);
+    if (durationMs < 1) {
+        throw new Error("local_pause duration_ms must be at least 1");
+    }
+    if (durationMs > maxDurationMs) {
+        throw new Error(`local_pause duration_ms must be <= ${maxDurationMs}`);
+    }
+    const reason = typeof args.reason === "string" && args.reason.trim() ? args.reason.trim() : undefined;
+    return { durationMs, reason };
+}

package/dist-cjs/local/tools.js

@@ -209,6 +209,9 @@ function summaryArgs(args) {
         path: optionalStringArg(args, "path"),
         maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
         maxPreviews: optionalNumberArg(args, "maxPreviews", "max_previews"),
+        previewBytes: optionalNumberArg(args, "previewBytes", "preview_bytes"),
+        topPaths: optionalNumberArg(args, "topPaths", "top_paths"),
+        maxDepth: optionalNumberArg(args, "maxDepth", "max_depth"),
     };
 }
 function grepArgs(args) {

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

package/package.json

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