@agent-api/sdk 1.4.2 → 1.4.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — @agent-api/sdk
 
+## 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
+
+- Made successful `local_workdir.apply_edits` results compact by keeping rollback backups internal and reporting changed files plus edit counts.
+
 ## 1.4.2
 
 ### Added

package/dist/local/core.d.ts

@@ -229,10 +229,8 @@ export interface LocalWorkdirEditPlan {
 }
 export interface LocalWorkdirEditResult {
     applied: LocalFileLinesPatch[];
-    backups: Array<{
-        path: string;
-        content: string;
-    }>;
+    changed_files: string[];
+    edit_count: number;
 }
 export type LocalPathSensitivity = "normal" | "sensitive" | "secret";
 export interface LocalPathSensitivityInfo {

package/dist/local/core.js

@@ -647,7 +647,11 @@ export class LocalWorkdir {
             }
             throw error;
         }
-        return { applied, backups };
+        return {
+            applied,
+            changed_files: uniqueStrings(applied.map((patch) => patch.path)),
+            edit_count: applied.length,
+        };
     }
     classifyPath(relativePath) {
         return classifyLocalPathSensitivity(relativePath);
@@ -1092,6 +1096,9 @@ function selectLineRange(lines, startLine, endLine) {
     }
     return { lines: lines.slice(startLine - 1, end), endLine: end };
 }
+function uniqueStrings(values) {
+    return Array.from(new Set(values));
+}
 function patchLineRange(content, startLine, endLine, replacement) {
     const lines = splitLines(content);
     const selected = selectLineRange(lines, startLine, endLine);

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/version.d.ts

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

package/dist/version.js

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

package/dist-cjs/local/core.js

@@ -665,7 +665,11 @@ class LocalWorkdir {
             }
             throw error;
         }
-        return { applied, backups };
+        return {
+            applied,
+            changed_files: uniqueStrings(applied.map((patch) => patch.path)),
+            edit_count: applied.length,
+        };
     }
     classifyPath(relativePath) {
         return classifyLocalPathSensitivity(relativePath);
@@ -1112,6 +1116,9 @@ function selectLineRange(lines, startLine, endLine) {
     }
     return { lines: lines.slice(startLine - 1, end), endLine: end };
 }
+function uniqueStrings(values) {
+    return Array.from(new Set(values));
+}
 function patchLineRange(content, startLine, endLine, replacement) {
     const lines = splitLines(content);
     const selected = selectLineRange(lines, startLine, endLine);

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

package/package.json

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