actoviq-agent-sdk 0.3.0 → 0.3.1

package/dist/src/runtime/agentClient.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { z } from 'zod';
 import { createActoviqBuddyApi } from '../buddy/actoviqBuddy.js';
 import { createActoviqComputerUseMcpServer, createActoviqComputerUseTools, } from '../computer/actoviqComputerUse.js';
 import { resolveRuntimeConfig } from '../config/resolveRuntimeConfig.js';
@@ -15,10 +16,12 @@ import { TeammateStore } from '../storage/teammateStore.js';
 import { ActoviqSwarmApi } from '../swarm/actoviqSwarm.js';
 import { createActoviqFileTools } from '../tools/actoviqFileTools.js';
 import { ActoviqAgentsApi, createActoviqTaskTool, summarizeActoviqAgentDefinition, } from './actoviqAgents.js';
+import { getDefaultActoviqAgents } from './defaultActoviqAgents.js';
 import { ActoviqSkillsApi, loadActoviqSkillDefinitions, resolveActoviqSkillPrompt, summarizeActoviqSkillDefinition, } from './actoviqSkills.js';
 import { ActoviqBackgroundTaskManager, ActoviqBackgroundTasksApi, } from './actoviqBackgroundTasks.js';
 import { ActoviqContextApi, ActoviqSlashCommandsApi, } from './actoviqSlashCommands.js';
-import { compactActoviqSession, getPersistedActoviqCompactHistory, getPersistedActoviqCompactState, isActoviqPromptTooLongError, } from './actoviqCompact.js';
+import { compactActoviqSession, getPersistedActoviqCompactHistory, getPersistedActoviqCompactState, isActoviqPromptTooLongError, trackRecentFile, trackRecentSkill, } from './actoviqCompact.js';
+const RECENT_FILE_TOOL_NAMES = new Set(['Read', 'Write', 'Edit', 'NotebookEdit']);
 import { ActoviqToolsApi, buildActoviqCleanToolCatalog, resolveActoviqCleanToolMetadata, } from './actoviqToolCatalog.js';
 import { WorkflowApi } from '../workflow/workflowBuilder.js';
 import { SessionManager } from './sessionManager.js';
@@ -29,6 +32,7 @@ import { createOpenaiModelApi } from '../provider/openai-model-api.js';
 import { AgentRunStream } from './asyncQueue.js';
 import { executeConversation } from './conversationEngine.js';
 import { asError, createId, deepClone, isRecord, nowIso, truncateText } from './helpers.js';
+import { tool } from './tools.js';
 import { buildInvokedSkillMessages, buildRelevantMemoryMessages, extractTextFromContent, } from './messageUtils.js';
 import { AgentSession } from './agentSession.js';
 const RELEVANT_MEMORY_SESSION_STATE_KEY = '__actoviqRelevantMemoryState';
@@ -172,12 +176,35 @@ function getAgentContinuityState(metadata) {
                         count: typeof record.count === 'number' ? record.count : 1,
                         lastInvokedAt: record.lastInvokedAt,
                         lastDescription: typeof record.lastDescription === 'string' ? record.lastDescription : undefined,
+                        lastRunId: typeof record.lastRunId === 'string' ? record.lastRunId : undefined,
+                        lastSessionId: typeof record.lastSessionId === 'string' ? record.lastSessionId : undefined,
+                        lastStatus: record.lastStatus === 'completed' || record.lastStatus === 'async_launched'
+                            ? record.lastStatus
+                            : undefined,
+                        lastTaskId: typeof record.lastTaskId === 'string' ? record.lastTaskId : undefined,
+                        lastTextSummary: typeof record.lastTextSummary === 'string' ? record.lastTextSummary : undefined,
+                        runIds: readStringArray(record.runIds),
+                        sessionIds: readStringArray(record.sessionIds),
+                        taskIds: readStringArray(record.taskIds),
+                        totalToolCallCount: typeof record.totalToolCallCount === 'number'
+                            ? record.totalToolCallCount
+                            : undefined,
+                        totalToolErrorCount: typeof record.totalToolErrorCount === 'number'
+                            ? record.totalToolErrorCount
+                            : undefined,
                     },
                 ];
             })
             : [],
     };
 }
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const values = value.filter((entry) => typeof entry === 'string');
+    return values.length > 0 ? values : undefined;
+}
 function mergeDelegatedAgents(existing, pending) {
     const merged = new Map(existing.map(record => [record.name, { ...record }]));
     for (const record of pending) {
@@ -188,15 +215,51 @@ function mergeDelegatedAgents(existing, pending) {
                 count: 1,
                 lastInvokedAt: record.invokedAt,
                 lastDescription: record.description,
+                lastRunId: record.runId,
+                lastSessionId: record.sessionId,
+                lastStatus: record.status,
+                lastTaskId: record.taskId,
+                lastTextSummary: record.textSummary,
+                runIds: record.runId ? [record.runId] : undefined,
+                sessionIds: record.sessionId ? [record.sessionId] : undefined,
+                taskIds: record.taskId ? [record.taskId] : undefined,
+                totalToolCallCount: record.toolCallCount,
+                totalToolErrorCount: record.toolErrorCount,
             });
             continue;
         }
         current.count += 1;
         current.lastInvokedAt = record.invokedAt;
         current.lastDescription = record.description ?? current.lastDescription;
+        current.lastRunId = record.runId ?? current.lastRunId;
+        current.lastSessionId = record.sessionId ?? current.lastSessionId;
+        current.lastStatus = record.status ?? current.lastStatus;
+        current.lastTaskId = record.taskId ?? current.lastTaskId;
+        current.lastTextSummary = record.textSummary ?? current.lastTextSummary;
+        current.runIds = appendUnique(current.runIds, record.runId);
+        current.sessionIds = appendUnique(current.sessionIds, record.sessionId);
+        current.taskIds = appendUnique(current.taskIds, record.taskId);
+        current.totalToolCallCount = sumOptional(current.totalToolCallCount, record.toolCallCount);
+        current.totalToolErrorCount = sumOptional(current.totalToolErrorCount, record.toolErrorCount);
     }
     return [...merged.values()].sort((left, right) => right.lastInvokedAt.localeCompare(left.lastInvokedAt));
 }
+function appendUnique(existing, value) {
+    if (!value) {
+        return existing;
+    }
+    const next = existing ? [...existing] : [];
+    if (!next.includes(value)) {
+        next.push(value);
+    }
+    return next;
+}
+function sumOptional(current, next) {
+    if (next === undefined) {
+        return current;
+    }
+    return (current ?? 0) + next;
+}
 function getInvokedSkillState(metadata) {
     const raw = metadata?.[INVOKED_SKILLS_STATE_KEY];
     if (!Array.isArray(raw)) {
@@ -359,6 +422,13 @@ export class ActoviqAgentClient {
         if (!this.defaultTools.some(tool => tool.name === 'Task')) {
             this.defaultTools.unshift(this.createTaskTool());
         }
+        this.replaceDefaultTool(this.createBackgroundTaskListTool());
+        this.replaceDefaultTool(this.createBackgroundTaskGetTool());
+        this.replaceDefaultTool(this.createBackgroundTaskStopTool());
+        this.replaceDefaultTool(this.createBackgroundTaskOutputTool());
+        if (this.listSkillDefinitions().length > 0) {
+            this.replaceDefaultTool(this.createSkillRegistryTool());
+        }
     }
     async listToolMetadata(options) {
         return resolveActoviqCleanToolMetadata({
@@ -419,6 +489,9 @@ export class ActoviqAgentClient {
             disableDefaultSkills: options.disableDefaultSkills,
             loadDefaultSkillDirectories: options.loadDefaultSkillDirectories,
         });
+        const agentDefinitions = options.disableDefaultAgents === true
+            ? [...(options.agents ?? [])]
+            : [...getDefaultActoviqAgents(), ...(options.agents ?? [])];
         const defaultTools = [...(options.tools ?? [])];
         const defaultMcpServers = [...(options.mcpServers ?? [])];
         if (options.computerUse) {
@@ -430,7 +503,7 @@ export class ActoviqAgentClient {
                 defaultTools.push(...createActoviqComputerUseTools(computerUseOptions));
             }
         }
-        return new ActoviqAgentClient(config, store, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, options.hooks, options.agents ?? [], [...loadedSkills, ...(options.skills ?? [])], options.permissionMode, options.permissions, options.classifier, options.approver, options.sessionManager);
+        return new ActoviqAgentClient(config, store, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, options.hooks, agentDefinitions, [...loadedSkills, ...(options.skills ?? [])], options.permissionMode, options.permissions, options.classifier, options.approver, options.sessionManager);
     }
     async run(input, options = {}) {
         const runId = createId();
@@ -492,6 +565,7 @@ export class ActoviqAgentClient {
     }
     async createSession(options = {}) {
         const stored = await this.store.create({
+            id: options.id,
             title: options.title,
             systemPrompt: options.systemPrompt ?? this.config.systemPrompt,
             model: options.model ?? this.config.model,
@@ -529,6 +603,7 @@ export class ActoviqAgentClient {
         return this.dream.maybeAutoDream(options);
     }
     async close() {
+        this.sessionManager.dispose();
         await this.mcpManager.closeAll();
     }
     listAgentDefinitions() {
@@ -588,18 +663,189 @@ export class ActoviqAgentClient {
     createTaskTool(options = {}) {
         return createActoviqTaskTool({
             ...options,
+            listAgentDefinitions: () => this.listAgentDefinitions(),
             getAgentDefinition: (agent) => this.getAgentDefinition(agent),
             runAgent: (agent, prompt, runOptions) => this.runWithAgent(agent, prompt, runOptions),
-            onDelegated: ({ subagentType, description, parentSessionId, parentRunId }) => {
+            onDelegated: ({ subagentType, description, parentSessionId, parentRunId, runId, sessionId, status, taskId, toolCallCount, toolErrorCount, textSummary, }) => {
                 this.recordPendingDelegation(parentSessionId ?? parentRunId, {
                     name: subagentType,
                     description,
                     invokedAt: nowIso(),
+                    runId,
+                    sessionId,
+                    status,
+                    taskId,
+                    toolCallCount,
+                    toolErrorCount,
+                    textSummary,
                 });
             },
             launchBackgroundAgent: (agent, prompt, backgroundOptions, runOptions) => this.launchBackgroundAgentTask(agent, prompt, backgroundOptions, runOptions),
         });
     }
+    replaceDefaultTool(replacement) {
+        const existingIndex = this.defaultTools.findIndex(tool => tool.name === replacement.name);
+        if (existingIndex >= 0) {
+            this.defaultTools.splice(existingIndex, 1, replacement);
+            return;
+        }
+        this.defaultTools.push(replacement);
+    }
+    /**
+     * Model-facing Skill tool backed by the real skill registry. Loads the
+     * resolved skill content into the conversation as the tool result
+     * (progressive disclosure), instead of the former no-op stub.
+     */
+    createSkillRegistryTool() {
+        return tool({
+            name: 'Skill',
+            description: 'Load a registered skill by name. The skill content (workflow, checklist, or domain knowledge) is returned so you can follow it for the current task.',
+            inputSchema: z.strictObject({
+                skill: z.string().describe('The name of the skill to load'),
+                args: z.string().optional().describe('Optional arguments for the skill'),
+            }),
+            isReadOnly: () => true,
+            prompt: () => {
+                const names = this.listSkillDefinitions()
+                    .filter((definition) => definition.disableModelInvocation !== true)
+                    .map((definition) => definition.description
+                    ? `- ${definition.name}: ${definition.description}`
+                    : `- ${definition.name}`);
+                if (names.length === 0) {
+                    return '';
+                }
+                return [
+                    'Use the Skill tool to load a registered skill when the task matches its description.',
+                    'Available skills:',
+                    ...names,
+                ].join('\n');
+            },
+        }, async ({ skill, args }, context) => {
+            const definition = this.getSkillDefinition(skill);
+            if (!definition || definition.disableModelInvocation === true) {
+                const available = this.listSkillDefinitions()
+                    .filter((entry) => entry.disableModelInvocation !== true)
+                    .map((entry) => entry.name)
+                    .join(', ');
+                throw new Error(`No skill named "${skill}" is registered.${available ? ` Available skills: ${available}.` : ''}`);
+            }
+            const resolved = await resolveActoviqSkillPrompt(definition, args ?? '', {
+                args: args ?? '',
+                workDir: this.config.workDir,
+                homeDir: this.config.homeDir,
+                sessionId: context.sessionId,
+                userId: this.config.userId,
+            });
+            const content = extractTextFromContent(resolved.content);
+            return [
+                `Loaded skill "${definition.name}".`,
+                '',
+                '<skill-content>',
+                content,
+                '</skill-content>',
+                '',
+                'Apply this skill to the current task now.',
+            ].join('\n');
+        });
+    }
+    createBackgroundTaskListTool() {
+        return tool({
+            name: 'TaskList',
+            description: 'List background subagent tasks for the current SDK runtime.',
+            inputSchema: z.strictObject({}),
+            isReadOnly: () => true,
+            serialize: (output) => {
+                if (output.tasks.length === 0) {
+                    return 'No background tasks.';
+                }
+                return output.tasks
+                    .map(task => [
+                    `Task id: ${task.id}`,
+                    `Status: ${task.status}`,
+                    `Subagent: ${task.subagentType}`,
+                    `Description: ${task.description}`,
+                    task.runId ? `Run id: ${task.runId}` : undefined,
+                    task.sessionId ? `Session id: ${task.sessionId}` : undefined,
+                    task.completedAt ? `Completed at: ${task.completedAt}` : undefined,
+                ].filter(Boolean).join('\n'))
+                    .join('\n\n');
+            },
+        }, async () => ({
+            tasks: await this.backgroundTaskManager.list(),
+        }));
+    }
+    createBackgroundTaskGetTool() {
+        return tool({
+            name: 'TaskGet',
+            description: 'Retrieve background subagent task status by ID.',
+            inputSchema: z.strictObject({
+                taskId: z.string().optional().describe('The ID of the task to get'),
+                task_id: z.string().optional().describe('The ID of the task to get'),
+            }).superRefine((input, ctx) => {
+                if (!resolveTaskId(input)) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        path: ['task_id'],
+                        message: 'Provide `task_id` or `taskId`.',
+                    });
+                }
+            }),
+            isReadOnly: () => true,
+            serialize: serializeBackgroundTaskOutput,
+        }, async (input) => {
+            const taskId = resolveTaskId(input);
+            if (!taskId) {
+                throw new Error('TaskGet requires `task_id` or `taskId`.');
+            }
+            const task = await this.backgroundTaskManager.get(taskId);
+            if (!task) {
+                throw new Error(`No background task with id "${taskId}" exists.`);
+            }
+            return task;
+        });
+    }
+    createBackgroundTaskStopTool() {
+        return tool({
+            name: 'TaskStop',
+            description: 'Stop a running background subagent task.',
+            inputSchema: z.strictObject({
+                task_id: z.string().describe('The ID of the task to stop'),
+            }),
+            isConcurrencySafe: () => true,
+            serialize: serializeBackgroundTaskOutput,
+        }, async ({ task_id }) => {
+            const task = await this.backgroundTaskManager.cancel(task_id);
+            if (!task) {
+                throw new Error(`No background task with id "${task_id}" exists.`);
+            }
+            return task;
+        });
+    }
+    createBackgroundTaskOutputTool() {
+        return tool({
+            name: 'TaskOutput',
+            description: 'Retrieve output from a completed or running background subagent task.',
+            inputSchema: z.strictObject({
+                task_id: z.string().describe('The ID of the task to get output for'),
+                block: z.boolean().optional().describe('Wait for task to complete before returning'),
+                timeout: z.number().int().positive().optional().describe('Max wait time in milliseconds'),
+            }),
+            isReadOnly: () => true,
+            serialize: serializeBackgroundTaskOutput,
+        }, async ({ task_id, block, timeout }, context) => {
+            if (block) {
+                return this.backgroundTaskManager.wait(task_id, {
+                    timeoutMs: timeout,
+                    signal: context.signal,
+                });
+            }
+            const task = await this.backgroundTaskManager.get(task_id);
+            if (!task) {
+                throw new Error(`No background task with id "${task_id}" exists.`);
+            }
+            return task;
+        });
+    }
     async prepareSkillExecution(skillName, args, options, sessionId) {
         const definition = this.requireSkillDefinition(skillName);
         const resolved = await resolveActoviqSkillPrompt(definition, args, {
@@ -893,6 +1139,12 @@ export class ActoviqAgentClient {
             permissionMode: options.permissionMode ?? this.defaultPermissionMode,
         });
         const systemPrompt = await this.resolveSystemPrompt(options, session, [...(augmentations?.systemPromptParts ?? []), ...toolPromptParts]);
+        const runtimeConfig = options.__actoviqMaxToolIterations
+            ? {
+                ...this.config,
+                maxToolIterations: options.__actoviqMaxToolIterations,
+            }
+            : this.config;
         return executeConversation({
             runId,
             input,
@@ -919,7 +1171,7 @@ export class ActoviqAgentClient {
             emit,
             skipRunStartedEvent,
             modelApi: this.modelApi,
-            config: this.config,
+            config: runtimeConfig,
             mcpManager: this.mcpManager,
         }).then(result => ({
             ...result,
@@ -1245,6 +1497,7 @@ export class ActoviqAgentClient {
                     model: result.model,
                     text: result.text,
                     toolCallCount: result.toolCalls.length,
+                    toolErrorCount: result.toolCalls.filter(call => call.isError).length,
                 };
             },
         });
@@ -1279,6 +1532,7 @@ export class ActoviqAgentClient {
                     model: result.model,
                     text: result.text,
                     toolCallCount: result.toolCalls.length,
+                    toolErrorCount: result.toolCalls.filter(call => call.isError).length,
                 };
             },
         });
@@ -1575,6 +1829,30 @@ export class ActoviqAgentClient {
             next.metadata[INVOKED_SKILLS_STATE_KEY] = invokedSkills;
             result.invokedSkills = invokedSkills;
         }
+        // Track recently touched files and skills so post-compact context
+        // reminders can point the model back to its working set.
+        for (const call of result.toolCalls) {
+            if (call.isError) {
+                continue;
+            }
+            const callInput = call.input;
+            if (RECENT_FILE_TOOL_NAMES.has(call.publicName)) {
+                const filePath = typeof callInput?.file_path === 'string'
+                    ? callInput.file_path
+                    : typeof callInput?.notebook_path === 'string'
+                        ? callInput.notebook_path
+                        : undefined;
+                if (filePath) {
+                    trackRecentFile(next, filePath);
+                }
+            }
+            if (call.publicName === 'Skill' && typeof callInput?.skill === 'string') {
+                trackRecentSkill(next, callInput.skill);
+            }
+        }
+        for (const record of result.invokedSkills ?? []) {
+            trackRecentSkill(next, record.name);
+        }
         const previousRelevantMemoryState = getRelevantMemorySessionState(next.metadata);
         const surfacedPaths = new Set(previousRelevantMemoryState.surfacedPaths);
         let totalBytes = previousRelevantMemoryState.totalBytes;
@@ -1688,6 +1966,7 @@ export class ActoviqAgentClient {
             mcpServers: [...(definition.mcpServers ?? []), ...(options.mcpServers ?? [])],
             __actoviqUseDefaultTools: definition.inheritDefaultTools !== false,
             __actoviqUseDefaultMcpServers: definition.inheritDefaultMcpServers !== false,
+            __actoviqMaxToolIterations: definition.maxToolIterations,
         };
     }
     mergeSkillRunOptions(definition, options) {
@@ -1719,6 +1998,25 @@ export class ActoviqAgentClient {
 export async function createAgentSdk(options = {}) {
     return ActoviqAgentClient.create(options);
 }
+function resolveTaskId(input) {
+    return [input.task_id, input.taskId]
+        .map(value => value?.trim())
+        .find((value) => Boolean(value));
+}
+function serializeBackgroundTaskOutput(task) {
+    return [
+        `Task id: ${task.id}`,
+        `Status: ${task.status}`,
+        `Subagent: ${task.subagentType}`,
+        task.runId ? `Run id: ${task.runId}` : undefined,
+        task.sessionId ? `Session id: ${task.sessionId}` : undefined,
+        task.model ? `Model: ${task.model}` : undefined,
+        typeof task.toolCallCount === 'number' ? `Tool calls: ${task.toolCallCount}` : undefined,
+        typeof task.toolErrorCount === 'number' ? `Tool errors: ${task.toolErrorCount}` : undefined,
+        task.error ? `Error:\n${task.error}` : undefined,
+        task.text ? `Output:\n${task.text}` : 'Output: <not available yet>',
+    ].filter(Boolean).join('\n');
+}
 function joinPromptParts(...parts) {
     const normalized = parts.filter((value) => typeof value === 'string' && value.trim().length > 0);
     if (normalized.length === 0) {