@agent-api/sdk 1.1.3 → 1.1.5

package/dist-cjs/local/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./core.js"), exports);
+__exportStar(require("./context.js"), exports);
+__exportStar(require("./tools.js"), exports);

package/dist-cjs/local/tools.js

@@ -0,0 +1,380 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalWorkspaceDriver = void 0;
+exports.createLocalWorkspaceToolRegistry = createLocalWorkspaceToolRegistry;
+exports.localWorkspaceToolDefinition = localWorkspaceToolDefinition;
+exports.localWorkspaceToolInstructions = localWorkspaceToolInstructions;
+const context_js_1 = require("./context.js");
+class LocalWorkspaceDriver {
+    workspace;
+    accessMode;
+    constructor(workspace, options = {}) {
+        this.workspace = workspace;
+        this.accessMode = options.accessMode ?? "approval";
+    }
+    async dispatch(args) {
+        const action = workspaceAction(args);
+        switch (action) {
+            case "summarize":
+                return localToolResult(action, localSummaryResult(await this.workspace.summarize(summaryArgs(args))));
+            case "list":
+                return localToolResult(action, await this.workspace.listEntries(optionalStringArg(args, "path") ?? ".", listArgs(args)));
+            case "search":
+                return localToolResult(action, await this.workspace.searchEntries(searchEntriesArgs(args)));
+            case "grep":
+                return localToolResult(action, await this.workspace.grep(grepArgs(args)));
+            case "read":
+                return localToolResult(action, await this.workspace.readFile(stringArg(args, "path"), readFileArgs(args)));
+            case "read_lines":
+                return localToolResult(action, await this.workspace.readLines(stringArg(args, "path"), readLinesArgs(args)));
+            case "context":
+                return localToolResult(action, await (0, context_js_1.createLocalContextPackage)(this.workspace, contextPackageArgs(args)));
+            case "snapshot":
+                return localToolResult(action, await this.workspace.snapshot(snapshotArgs(args)));
+            case "classify_path":
+                return localToolResult(action, this.workspace.classifyPath(stringArg(args, "path")));
+            case "preview_edits":
+                return localToolResult(action, await this.workspace.previewEdits(editsArg(args)));
+            case "apply_edits":
+                return await this.dispatchApplyEdits(args);
+            case "write":
+                return await this.dispatchWrite(args);
+            case "mkdir":
+                return await this.dispatchMkdir(args);
+            case "delete":
+                return await this.dispatchDelete(args);
+            default:
+                throw new Error(`unsupported local_workspace action: ${action}`);
+        }
+    }
+    requiresApproval(args) {
+        if (this.accessMode === "full") {
+            return false;
+        }
+        return mutatingLocalWorkspaceActions.has(workspaceAction(args));
+    }
+    async dispatchApplyEdits(args) {
+        const edits = editsArg(args);
+        if (this.accessMode !== "full") {
+            return approvalRequired("apply_edits", args, await this.workspace.previewEdits(edits));
+        }
+        return localToolResult("apply_edits", await this.workspace.applyEdits(edits));
+    }
+    async dispatchWrite(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("write", args);
+        }
+        return localToolResult("write", await this.workspace.writeText(stringArg(args, "path"), stringArg(args, "content")));
+    }
+    async dispatchMkdir(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("mkdir", args);
+        }
+        return localToolResult("mkdir", await this.workspace.createDirectory(stringArg(args, "path")));
+    }
+    async dispatchDelete(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("delete", args);
+        }
+        return localToolResult("delete", await this.workspace.deletePath(stringArg(args, "path")));
+    }
+}
+exports.LocalWorkspaceDriver = LocalWorkspaceDriver;
+function createLocalWorkspaceToolRegistry(workspace, options = {}) {
+    const toolName = options.toolName ?? "local_workspace";
+    const driver = new LocalWorkspaceDriver(workspace, { accessMode: options.accessMode });
+    const definition = localWorkspaceToolDefinition(toolName);
+    return {
+        workspace,
+        accessMode: driver.accessMode,
+        toolName,
+        definitions: () => [{ ...definition }],
+        handlers: () => ({ [toolName]: (args) => driver.dispatch(args) }),
+        execute: async (name, args) => {
+            if (name !== toolName) {
+                throw new Error(`unknown local workspace tool: ${name}`);
+            }
+            return await driver.dispatch(args);
+        },
+        requiresApproval: (name, args = {}) => name === toolName && driver.requiresApproval(args),
+    };
+}
+function localWorkspaceToolDefinition(name = "local_workspace") {
+    return {
+        type: "function",
+        name,
+        description: localWorkspaceToolDescription,
+        parameters: localWorkspaceToolParameters(),
+        strict: false,
+    };
+}
+function localWorkspaceToolInstructions() {
+    return localWorkspaceToolDescription;
+}
+const localWorkspaceActions = [
+    "summarize",
+    "list",
+    "search",
+    "grep",
+    "read",
+    "read_lines",
+    "context",
+    "snapshot",
+    "classify_path",
+    "preview_edits",
+    "apply_edits",
+    "write",
+    "mkdir",
+    "delete",
+];
+const mutatingLocalWorkspaceActions = new Set([
+    "apply_edits",
+    "write",
+    "mkdir",
+    "delete",
+]);
+const localWorkspaceToolDescription = [
+    "Inspect and modify the selected local workspace through one model-facing primitive.",
+    "Use action=list/search/grep/summarize/context to discover files, read/read_lines for file content, preview_edits before edits, and apply_edits/write/mkdir/delete only when mutation is intended.",
+    "In approval mode, mutating actions return requires_approval with a safe preview instead of changing files. In full mode, mutating actions execute immediately.",
+    "Paths are relative to the selected local workspace; never use absolute paths.",
+].join(" ");
+function localWorkspaceToolParameters() {
+    return objectSchema({
+        action: {
+            type: "string",
+            enum: localWorkspaceActions,
+            description: "Workspace operation. Prefer summarize/list/search/grep before reading or editing. Prefer read_lines and apply_edits for source changes.",
+        },
+        path: stringSchema("Relative path. File path for read/write/delete/edit actions; directory base for list/search/grep/summarize/context/snapshot."),
+        query: stringSchema("Path/name query for search, or optional context query."),
+        pattern: stringSchema("Literal text pattern for grep."),
+        content: stringSchema("Text content for write."),
+        start_line: integerSchema("1-based start line for read_lines and edit entries."),
+        end_line: integerSchema("1-based inclusive end line; omit or 0 for EOF when supported."),
+        replacement: stringSchema("Replacement text for simple single edit flows."),
+        edits: {
+            type: "array",
+            minItems: 1,
+            description: "Line edits for preview_edits/apply_edits.",
+            items: objectSchema({
+                path: requiredStringSchema("Relative file path."),
+                start_line: requiredIntegerSchema("1-based start line."),
+                end_line: integerSchema("1-based inclusive end line."),
+                replacement: stringSchema("Replacement text. Empty string deletes the line range."),
+                expected_sha256: stringSchema("Optional expected SHA-256 for conflict detection."),
+            }, ["path", "start_line"]),
+        },
+        options: objectSchema({
+            recursive: booleanSchema("List recursively."),
+            include_directories: booleanSchema("Include directories in list results."),
+            max_depth: integerSchema("Maximum recursive list depth."),
+            limit: integerSchema("Maximum entries or matches."),
+            max_files: integerSchema("Maximum files to scan or package."),
+            max_bytes: integerSchema("Maximum total bytes to read/package."),
+            max_bytes_per_file: integerSchema("Maximum bytes per file."),
+            max_previews: integerSchema("Maximum summary previews."),
+            include_content: booleanSchema("Include file contents in context packages."),
+            include_summary: booleanSchema("Include workspace summary in context packages."),
+            include_search: booleanSchema("Include grep results in context packages when query is set."),
+            include_secrets: booleanSchema("Include likely secret file contents in context packages."),
+            hash: booleanSchema("Include SHA-256 hashes in snapshots."),
+        }),
+    }, ["action"]);
+}
+function workspaceAction(args) {
+    const value = stringArg(args, "action").trim().toLowerCase();
+    if (!localWorkspaceActions.includes(value)) {
+        throw new Error(`unsupported local_workspace action: ${value}`);
+    }
+    return value;
+}
+function summaryArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+        maxPreviews: optionalNumberArg(args, "maxPreviews", "max_previews"),
+    };
+}
+function grepArgs(args) {
+    return {
+        pattern: stringArg(args, "pattern"),
+        path: optionalStringArg(args, "path"),
+        limit: optionalNumberArg(args, "limit"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+    };
+}
+function listArgs(args) {
+    return {
+        recursive: optionalBooleanArg(args, "recursive"),
+        includeDirectories: optionalBooleanArg(args, "includeDirectories", "include_directories"),
+        maxDepth: optionalNumberArg(args, "maxDepth", "max_depth"),
+    };
+}
+function searchEntriesArgs(args) {
+    return {
+        query: stringArg(args, "query"),
+        path: optionalStringArg(args, "path"),
+        limit: optionalNumberArg(args, "limit"),
+    };
+}
+function readFileArgs(args) {
+    return {
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+    };
+}
+function readLinesArgs(args) {
+    return {
+        startLine: numberArg(args, "startLine", "start_line"),
+        endLine: optionalNumberArg(args, "endLine", "end_line"),
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+    };
+}
+function snapshotArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        hash: optionalBooleanArg(args, "hash"),
+        maxBytesPerFile: optionalNumberArg(args, "maxBytesPerFile", "max_bytes_per_file"),
+    };
+}
+function contextPackageArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        query: optionalStringArg(args, "query"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+        maxBytesPerFile: optionalNumberArg(args, "maxBytesPerFile", "max_bytes_per_file"),
+        includeContent: optionalBooleanArg(args, "includeContent", "include_content"),
+        includeSummary: optionalBooleanArg(args, "includeSummary", "include_summary"),
+        includeSearch: optionalBooleanArg(args, "includeSearch", "include_search"),
+        includeSecrets: optionalBooleanArg(args, "includeSecrets", "include_secrets"),
+    };
+}
+function editsArg(args) {
+    const edits = args.edits;
+    if (Array.isArray(edits) && edits.length > 0) {
+        return edits.map((edit) => {
+            if (!edit || typeof edit !== "object") {
+                throw new Error("each edit must be an object");
+            }
+            return editArg(edit);
+        });
+    }
+    if (typeof args.path === "string" && typeof (args.startLine ?? args.start_line) === "number") {
+        return [editArg(args)];
+    }
+    throw new Error("edits must be a non-empty array");
+}
+function editArg(record) {
+    return {
+        path: stringArg(record, "path"),
+        startLine: numberArg(record, "startLine", "start_line"),
+        endLine: optionalNumberArg(record, "endLine", "end_line"),
+        replacement: typeof record.replacement === "string" ? record.replacement : "",
+        expectedSha256: optionalStringArg(record, "expectedSha256", "expected_sha256"),
+    };
+}
+function localSummaryResult(summary) {
+    return summary;
+}
+function localToolResult(action, value) {
+    const result = value;
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        return { ok: true, action, ...result };
+    }
+    return { ok: true, action, result };
+}
+function stringArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${key} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalStringArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null || value === "")
+        return undefined;
+    if (typeof value !== "string") {
+        throw new Error(`${key} must be a string`);
+    }
+    return value;
+}
+function numberArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${key} must be a number`);
+    }
+    return Math.trunc(value);
+}
+function optionalNumberArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${key} must be a number`);
+    }
+    return Math.trunc(value);
+}
+function optionalBooleanArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null)
+        return undefined;
+    if (typeof value !== "boolean") {
+        throw new Error(`${key} must be a boolean`);
+    }
+    return value;
+}
+function approvalRequired(action, args, preview) {
+    return {
+        ok: false,
+        action,
+        requires_approval: true,
+        arguments: args,
+        preview,
+        message: `local_workspace action ${action} requires approval`,
+    };
+}
+function objectSchema(properties, required = []) {
+    return {
+        type: "object",
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}
+function stringSchema(description) {
+    return { type: "string", description };
+}
+function requiredStringSchema(description) {
+    return stringSchema(description);
+}
+function integerSchema(description) {
+    return { type: "integer", description };
+}
+function booleanSchema(description) {
+    return { type: "boolean", description };
+}
+function requiredIntegerSchema(description) {
+    return integerSchema(description);
+}

package/dist-cjs/local-functions.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pendingFunctionCalls = pendingFunctionCalls;
+exports.functionCallOutputInput = functionCallOutputInput;
+exports.runLocalFunctionHandlers = runLocalFunctionHandlers;
+/** Pending client-executed function calls from a requires_action response. */
+function pendingFunctionCalls(response) {
+    if (response.status !== "requires_action") {
+        return [];
+    }
+    return response.output.filter((item) => item.type === "function_call");
+}
+function functionCallOutputInput(callID, output) {
+    return {
+        type: "function_call_output",
+        call_id: callID,
+        output: typeof output === "string" ? output : JSON.stringify(output),
+    };
+}
+/** Run local handlers for pending function calls and return function_call_output input items. */
+async function runLocalFunctionHandlers(response, handlers) {
+    const pending = pendingFunctionCalls(response);
+    const outputs = [];
+    for (const call of pending) {
+        const handler = handlers[call.name];
+        if (!handler) {
+            throw new Error(`no local handler registered for function ${call.name}`);
+        }
+        let args = {};
+        if (call.arguments) {
+            args = JSON.parse(call.arguments);
+        }
+        const result = await handler(args);
+        outputs.push(functionCallOutputInput(call.call_id, result));
+    }
+    return outputs;
+}