@tencent-ai/agent-sdk 0.2.1 → 0.2.3

package/lib/acp/tool-converter.js

@@ -0,0 +1,437 @@
+"use strict";
+/**
+ * Tool Converter Utility
+ *
+ * Converts SDK internal tool formats to ACP (Agent Client Protocol) format and vice versa.
+ *
+ * Uses official @agentclientprotocol/sdk types for compatibility with the ACP specification.
+ *
+ * Critical Design Principle: NO DATA LOSS
+ * - SDK tool inputs are preserved completely in rawInput
+ * - Tool IDs are maintained throughout the conversion
+ * - Tool results are preserved with error state tracking
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertSdkToolUseToAcpToolCall = convertSdkToolUseToAcpToolCall;
+exports.convertAcpToolResultToSdk = convertAcpToolResultToSdk;
+exports.extractToolUseBlocks = extractToolUseBlocks;
+exports.extractTextContent = extractTextContent;
+// ============= Conversion: SDK Tool Use → ACP Tool Call =============
+/**
+ * Convert SDK ToolUseContentBlock to ACP Tool Call
+ * Preserves all input data in rawInput field
+ *
+ * @param toolUse - SDK tool use block
+ * @returns ACP tool call with complete data preservation
+ */
+function convertSdkToolUseToAcpToolCall(toolUse) {
+    const toolName = toolUse.name;
+    const toolInput = toolUse.input;
+    return {
+        toolCallId: toolUse.id,
+        status: 'pending',
+        title: generateToolTitle(toolName, toolInput),
+        kind: getToolKind(toolName),
+        rawInput: toolInput,
+        content: generateToolContent(toolName, toolInput),
+        locations: extractToolLocations(toolName, toolInput),
+    };
+}
+// ============= Title Generation by Tool Type =============
+function generateToolTitle(toolName, input) {
+    switch (toolName) {
+        case 'Read':
+        case 'read': {
+            const filePath = input.file_path;
+            const offset = input.offset;
+            const limit = input.limit;
+            if (!filePath)
+                return 'Read';
+            if (limit) {
+                return `Read ${filePath} (${(offset !== null && offset !== void 0 ? offset : 0) + 1} - ${(offset !== null && offset !== void 0 ? offset : 0) + limit})`;
+            }
+            else if (offset) {
+                return `Read ${filePath} (from line ${(offset !== null && offset !== void 0 ? offset : 0) + 1})`;
+            }
+            return `Read ${filePath}`;
+        }
+        case 'Write':
+        case 'write': {
+            const filePath = input.file_path;
+            return filePath ? `Write ${filePath}` : 'Write';
+        }
+        case 'Edit':
+        case 'edit':
+        case 'MultiEdit': {
+            const filePath = input.file_path;
+            return filePath ? `Edit \`${filePath}\`` : 'Edit';
+        }
+        case 'Bash':
+        case 'bash': {
+            const command = input.command;
+            if (!command)
+                return 'Terminal';
+            // Escape backticks in command (replace all occurrences)
+            const escaped = command.split('`').join('\\`');
+            return `\`${escaped}\``;
+        }
+        case 'BashOutput':
+        case 'bash_output':
+            return 'Tail Logs';
+        case 'KillShell':
+        case 'kill_shell':
+            return 'Kill Process';
+        case 'Glob':
+        case 'glob': {
+            let label = 'Find';
+            const path = input.path;
+            const pattern = input.pattern;
+            if (path)
+                label += ` \`${path}\``;
+            if (pattern)
+                label += ` \`${pattern}\``;
+            return label;
+        }
+        case 'Grep':
+        case 'grep': {
+            let label = 'grep';
+            // Add flags
+            if (input['-i'])
+                label += ' -i';
+            if (input['-n'])
+                label += ' -n';
+            if (input['-C'] !== undefined)
+                label += ` -C ${input['-C']}`;
+            if (input['-A'] !== undefined)
+                label += ` -A ${input['-A']}`;
+            if (input['-B'] !== undefined)
+                label += ` -B ${input['-B']}`;
+            if (input.multiline)
+                label += ' -P';
+            if (input.glob)
+                label += ` --include="${input.glob}"`;
+            if (input.type)
+                label += ` --type=${input.type}`;
+            // Add pattern and path
+            const pattern = input.pattern;
+            const path = input.path;
+            if (pattern)
+                label += ` "${pattern}"`;
+            if (path)
+                label += ` ${path}`;
+            return label;
+        }
+        case 'WebFetch':
+        case 'web_fetch': {
+            const url = input.url;
+            return url ? `Fetch ${url}` : 'Fetch';
+        }
+        case 'WebSearch':
+        case 'web_search': {
+            const query = input.query;
+            if (!query)
+                return 'Search';
+            let label = `"${query}"`;
+            const allowedDomains = input.allowed_domains;
+            const blockedDomains = input.blocked_domains;
+            if (allowedDomains === null || allowedDomains === void 0 ? void 0 : allowedDomains.length)
+                label += ` (allowed: ${allowedDomains.join(', ')})`;
+            if (blockedDomains === null || blockedDomains === void 0 ? void 0 : blockedDomains.length)
+                label += ` (blocked: ${blockedDomains.join(', ')})`;
+            return label;
+        }
+        case 'NotebookRead':
+        case 'notebook_read': {
+            const path = input.notebook_path;
+            return path ? `Read Notebook ${path}` : 'Read Notebook';
+        }
+        case 'NotebookEdit':
+        case 'notebook_edit': {
+            const path = input.notebook_path;
+            return path ? `Edit Notebook ${path}` : 'Edit Notebook';
+        }
+        case 'Task':
+        case 'task': {
+            const description = input.description;
+            return description || 'Task';
+        }
+        case 'TodoWrite':
+        case 'todo_write': {
+            return 'Update TODOs';
+        }
+        case 'AskUserQuestion':
+        case 'ask_user_question':
+            return 'Ask User';
+        case 'SlashCommand':
+        case 'slash_command': {
+            const command = input.command;
+            return command ? `Run: ${command}` : 'Slash Command';
+        }
+        case 'Skill':
+        case 'skill': {
+            const command = input.command;
+            return command ? `Skill: ${command}` : 'Skill';
+        }
+        case 'LSP':
+        case 'lsp': {
+            const operation = input.operation;
+            return operation ? `LSP: ${operation}` : 'LSP';
+        }
+        case 'EnterPlanMode':
+        case 'enter_plan_mode':
+            return 'Enter Plan Mode';
+        case 'ExitPlanMode':
+        case 'exit_plan_mode':
+            return 'Exit Plan Mode';
+        case 'TaskOutput':
+        case 'task_output':
+            return 'Get Task Output';
+        default:
+            return toolName || 'Unknown Tool';
+    }
+}
+// ============= Tool Kind Classification =============
+function getToolKind(toolName) {
+    switch (toolName) {
+        case 'Read':
+        case 'read':
+        case 'NotebookRead':
+        case 'notebook_read':
+        case 'Glob':
+        case 'glob':
+            return 'read';
+        case 'Write':
+        case 'write':
+        case 'Edit':
+        case 'edit':
+        case 'MultiEdit':
+        case 'NotebookEdit':
+        case 'notebook_edit':
+            return 'edit';
+        case 'Bash':
+        case 'bash':
+        case 'BashOutput':
+        case 'bash_output':
+        case 'KillShell':
+        case 'kill_shell':
+        case 'TaskOutput':
+        case 'task_output':
+            return 'execute';
+        case 'Grep':
+        case 'grep':
+        case 'WebSearch':
+        case 'web_search':
+            return 'search';
+        case 'WebFetch':
+        case 'web_fetch':
+            return 'fetch';
+        case 'Task':
+        case 'task':
+        case 'TodoWrite':
+        case 'todo_write':
+        case 'EnterPlanMode':
+        case 'enter_plan_mode':
+        case 'ExitPlanMode':
+        case 'exit_plan_mode':
+            return 'think';
+        default:
+            return 'other';
+    }
+}
+// ============= Content Generation by Tool Type =============
+/**
+ * Generate content metadata for tool calls.
+ * Returns ToolCallContent for operations that have displayable content like:
+ * - Diff content for Edit tools (before/after comparison)
+ * - Text content for Bash/Task/WebFetch (descriptions/prompts)
+ */
+function generateToolContent(toolName, input) {
+    const content = [];
+    switch (toolName) {
+        case 'Edit':
+        case 'edit':
+        case 'MultiEdit': {
+            const filePath = input.file_path;
+            const oldString = input.old_string;
+            const newString = input.new_string;
+            if (filePath && oldString !== undefined && newString !== undefined) {
+                content.push({
+                    type: 'diff',
+                    path: filePath,
+                    oldText: oldString || null,
+                    newText: newString,
+                });
+            }
+            break;
+        }
+        case 'Bash':
+        case 'bash': {
+            const description = input.description;
+            if (description) {
+                content.push({
+                    type: 'content',
+                    content: { type: 'text', text: description },
+                });
+            }
+            break;
+        }
+        case 'Task':
+        case 'task': {
+            const prompt = input.prompt;
+            if (prompt) {
+                content.push({
+                    type: 'content',
+                    content: { type: 'text', text: prompt },
+                });
+            }
+            break;
+        }
+        case 'WebFetch':
+        case 'web_fetch': {
+            const prompt = input.prompt;
+            if (prompt) {
+                content.push({
+                    type: 'content',
+                    content: { type: 'text', text: prompt },
+                });
+            }
+            break;
+        }
+    }
+    return content.length > 0 ? content : undefined;
+}
+// ============= Location Extraction by Tool Type =============
+function extractToolLocations(toolName, input) {
+    const locations = [];
+    // File path based tools
+    const filePath = input.file_path;
+    const notebookPath = input.notebook_path;
+    const path = input.path;
+    // Add file location if present
+    if (filePath) {
+        locations.push({
+            path: filePath,
+            line: input.offset,
+        });
+    }
+    else if (notebookPath) {
+        locations.push({ path: notebookPath });
+    }
+    else if (path && (toolName === 'Glob' || toolName === 'glob')) {
+        locations.push({ path });
+    }
+    return locations.length > 0 ? locations : undefined;
+}
+// ============= Content Format Conversion =============
+/**
+ * Convert ACP content format to SDK content format for tool results
+ */
+function formatAcpContentForSdk(toolCallContent) {
+    var _a;
+    if (toolCallContent.length === 0) {
+        return '';
+    }
+    const blocks = [];
+    for (const item of toolCallContent) {
+        // Handle diff content
+        if (item.type === 'diff') {
+            const diff = item;
+            const diffText = `--- ${diff.path}
++++ ${diff.path}
+${formatDiffHunk((_a = diff.oldText) !== null && _a !== void 0 ? _a : null, diff.newText)}`;
+            blocks.push({
+                type: 'text',
+                text: diffText,
+            });
+        }
+        // Handle regular content (text, image, etc.)
+        else if (item.type === 'content') {
+            const contentItem = item;
+            if (contentItem.content && contentItem.content.type === 'text' && contentItem.content.text) {
+                blocks.push({
+                    type: 'text',
+                    text: contentItem.content.text,
+                });
+            }
+        }
+        // Handle terminal content
+        else if (item.type === 'terminal') {
+            const terminalItem = item;
+            if (terminalItem.terminalId) {
+                blocks.push({
+                    type: 'text',
+                    text: `[Terminal: ${terminalItem.terminalId}]`,
+                });
+            }
+        }
+    }
+    // If all content was text, return as string for simplicity
+    if (blocks.length === 1 && blocks[0].type === 'text') {
+        return blocks[0].text;
+    }
+    return blocks.length > 0 ? blocks : '';
+}
+/**
+ * Format diff hunks for display
+ */
+function formatDiffHunk(oldText, newText) {
+    const oldLines = oldText ? oldText.split('\n') : [];
+    const newLines = newText.split('\n');
+    const hunks = [];
+    hunks.push(`@@ -1,${oldLines.length} +1,${newLines.length} @@`);
+    // Add old lines
+    for (const line of oldLines) {
+        hunks.push(`-${line}`);
+    }
+    // Add new lines
+    for (const line of newLines) {
+        hunks.push(`+${line}`);
+    }
+    return hunks.join('\n');
+}
+// ============= Conversion: ACP Tool Result → SDK Tool Result =============
+/**
+ * Convert ACP Tool Result to SDK ToolResultContentBlock
+ * Preserves tool_use_id and ensures error state is tracked
+ *
+ * @param toolCallId - Original tool call ID
+ * @param acpResult - ACP tool result
+ * @returns SDK ToolResultContentBlock
+ */
+function convertAcpToolResultToSdk(toolCallId, acpResult) {
+    const isError = acpResult.status === 'failed';
+    const content = acpResult.content ? formatAcpContentForSdk(acpResult.content) : '';
+    return {
+        type: 'tool_result',
+        tool_use_id: toolCallId,
+        content: content,
+        is_error: isError,
+    };
+}
+// ============= Helper: Extract Tool Use Blocks =============
+/**
+ * Extract tool use blocks from content blocks array
+ */
+function extractToolUseBlocks(contentBlocks) {
+    if (!Array.isArray(contentBlocks))
+        return [];
+    return contentBlocks.filter((block) => typeof block === 'object' &&
+        block !== null &&
+        'type' in block &&
+        block.type === 'tool_use');
+}
+/**
+ * Extract text content from content blocks array
+ */
+function extractTextContent(contentBlocks) {
+    if (!Array.isArray(contentBlocks))
+        return '';
+    return contentBlocks
+        .filter((block) => typeof block === 'object' &&
+        block !== null &&
+        'type' in block &&
+        block.type === 'text')
+        .map((block) => block.text)
+        .join('\n');
+}
+//# sourceMappingURL=tool-converter.js.map

package/lib/acp/tool-converter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-converter.js","sourceRoot":"","sources":["../../src/acp/tool-converter.ts"],"names":[],"mappings":"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"}

package/lib/connect.d.ts

@@ -0,0 +1,94 @@
+/**
+ * CLI Connection Module
+ *
+ * Provides prewarmed transport queue to reduce first message latency
+ * by pre-spawning CLI processes before they're needed.
+ *
+ * Design principles:
+ * - One transport per query - no sharing to avoid message mixing
+ * - FIFO queue - connectCLI() pushes, query() pops from front
+ * - Options matching - only use prewarmed transport if options match
+ */
+import { type ProcessTransportOptions, type Transport } from './transport';
+/**
+ * Options for connectCLI prewarming.
+ */
+export interface ConnectCLIOptions extends ProcessTransportOptions {
+    /**
+     * If true, send initialize request during prewarming to complete CLI boot.
+     * This moves the CLI boot time (~1.5s) from the first query to the prewarm phase.
+     * Default: true
+     */
+    prewarmInitialize?: boolean;
+}
+/**
+ * Pre-connect a CLI process in advance.
+ *
+ * Call this at application startup to reduce latency for queries.
+ * Each call creates a new transport and adds it to the prewarmed queue.
+ * Multiple calls create multiple prewarmed transports for concurrent queries.
+ *
+ * By default, this also sends an initialize request to complete CLI boot,
+ * which moves ~1.5s of latency from the first query to the prewarm phase.
+ *
+ * @param options - Optional transport options. If not provided, default options are used.
+ * @returns A promise that resolves when the CLI process is ready.
+ *
+ * @example
+ * ```typescript
+ * import { connectCLI, query } from '@anthropic/agent-sdk';
+ *
+ * // Prewarm multiple transports for concurrent queries
+ * await Promise.all([
+ *   connectCLI(),
+ *   connectCLI(),
+ *   connectCLI(),
+ * ]);
+ *
+ * // Later queries will use prewarmed transports
+ * const [q1, q2, q3] = [
+ *   query({ prompt: 'Hello 1' }),
+ *   query({ prompt: 'Hello 2' }),
+ *   query({ prompt: 'Hello 3' }),
+ * ];
+ * ```
+ */
+export declare function connectCLI(options?: ConnectCLIOptions): Promise<void>;
+/**
+ * Result of getConnectedTransport.
+ */
+export interface PrewarmedTransportResult {
+    transport: Transport;
+    /** Whether the transport has been pre-initialized (initialize request already sent) */
+    preInitialized: boolean;
+}
+/**
+ * Get a prewarmed transport from the queue if available and matching options.
+ * Used internally by the SDK.
+ *
+ * @param options - The options to match against.
+ * @returns The connected transport and initialization state if available and matching, null otherwise.
+ * @internal
+ */
+export declare function getConnectedTransport(options?: ProcessTransportOptions): PrewarmedTransportResult | null;
+/**
+ * Clear all prewarmed transports.
+ * Useful for testing or when you want to release all prewarmed CLI processes.
+ */
+export declare function clearConnectedTransport(): void;
+/**
+ * Acquire a lock for a session ID to prevent concurrent resume.
+ *
+ * @param sessionId - The session ID to lock.
+ * @returns true if lock acquired, false if session is already in use.
+ * @internal
+ */
+export declare function acquireSessionLock(sessionId: string): boolean;
+/**
+ * Release a session lock.
+ *
+ * @param sessionId - The session ID to unlock.
+ * @internal
+ */
+export declare function releaseSessionLock(sessionId: string): void;
+//# sourceMappingURL=connect.d.ts.map

package/lib/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAmB,KAAK,uBAAuB,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAuC5F;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAC9D;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAc3E;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB,uFAAuF;IACvF,cAAc,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,wBAAwB,GAAG,IAAI,CAaxG;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAK9C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE1D"}