actoviq-agent-sdk 0.4.6 → 0.4.7

package/dist/src/runtime/agentClient.js

@@ -7,6 +7,7 @@ import { createActoviqBuddyApi } from '../buddy/actoviqBuddy.js';
 import { createActoviqComputerUseMcpServer, createActoviqComputerUseTools, } from '../computer/actoviqComputerUse.js';
 import { resolveRuntimeConfig } from '../config/resolveRuntimeConfig.js';
 import { resolveActoviqModelReference } from '../config/modelTiers.js';
+import { recordCompatUsage } from '../compat/diagnostics.js';
 import { mergeActoviqHooks, normalizeActoviqHookMessages, resolveActoviqPostRunHooks, resolveActoviqSessionStartHooks, } from '../hooks/actoviqHooks.js';
 import { createActoviqMemoryApi } from '../memory/actoviqMemory.js';
 import { appendMessagesToTranscript } from '../memory/actoviqTranscriptLogger.js';
@@ -19,8 +20,9 @@ import { SessionStore } from '../storage/sessionStore.js';
 import { TeammateStore } from '../storage/teammateStore.js';
 import { ActoviqSwarmApi } from '../swarm/actoviqSwarm.js';
 import { createActoviqFileTools } from '../tools/actoviqFileTools.js';
+import { BASH_TOOL_NAME, createBashTool } from '../tools/bash/BashTool.js';
 import { createGitWorktreeWorkspace, } from '../workspace/actoviqWorkspace.js';
-import { ActoviqAgentsApi, createActoviqTaskTool, summarizeActoviqAgentDefinition, } from './actoviqAgents.js';
+import { ACTOVIQ_RUN_STATE_KEY, ActoviqAgentsApi, createActoviqRunToolState, createActoviqTaskTool, summarizeActoviqAgentDefinition, } from './actoviqAgents.js';
 import { getDefaultActoviqAgents } from './defaultActoviqAgents.js';
 import { loadActoviqAgentDefinitions } from './actoviqAgentDefinitions.js';
 import { ActoviqSkillsApi, loadActoviqSkillDefinitions, resolveActoviqSkillPrompt, skillPathsMatch, summarizeActoviqSkillDefinition, } from './actoviqSkills.js';
@@ -37,6 +39,8 @@ import { getActoviqCompactBoundarySummary } from '../memory/actoviqMemory.js';
 import { createActoviqModelApi } from './actoviqModelApi.js';
 import { createOpenaiModelApi } from '../provider/openai-model-api.js';
 import { AgentRunStream } from './asyncQueue.js';
+import { SessionTurnCoordinator } from './sessionTurnCoordinator.js';
+import { withDeadline } from './deadline.js';
 import { executeConversation } from './conversationEngine.js';
 import { asError, createId, deepClone, isRecord, nowIso, truncateText } from './helpers.js';
 import { tool } from './tools.js';
@@ -125,7 +129,8 @@ export class AgentSessionsApi {
     }
     async continueMostRecent(options = {}) {
         const sessions = await this.store.list();
-        const mostRecent = sessions.find(session => session.status !== 'closed') ?? sessions[0];
+        const chatSessions = sessions.filter(session => session.kind !== 'manager');
+        const mostRecent = chatSessions.find(session => session.status !== 'closed') ?? chatSessions[0];
         if (!mostRecent) {
             throw new Error('No stored sessions are available to resume.');
         }
@@ -369,6 +374,7 @@ export class ActoviqAgentClient {
     slashCommands;
     workflow;
     sessionManager;
+    sessionTurnCoordinator = new SessionTurnCoordinator();
     agentDefinitions;
     skillDefinitions;
     /** Names of `paths:`-conditional skills activated by touching matching files. */
@@ -470,6 +476,12 @@ export class ActoviqAgentClient {
                 ...new Set([...(existingDelegationTool.aliases ?? []), 'Agent']),
             ];
         }
+        if (this.defaultTools.some(tool => tool.name === BASH_TOOL_NAME)) {
+            this.replaceDefaultTool(createBashTool({
+                backgroundTaskManager: this.backgroundTaskManager,
+                onBackgroundTaskSettled: task => this.enqueueTaskNotification(task),
+            }));
+        }
         this.replaceDefaultTool(this.createSendMessageTool());
         this.replaceDefaultTool(this.createBackgroundTaskListTool());
         this.replaceDefaultTool(this.createBackgroundTaskGetTool());
@@ -530,6 +542,8 @@ export class ActoviqAgentClient {
         const mcpManager = new McpConnectionManager({
             name: config.clientName,
             version: config.clientVersion,
+        }, {
+            requestTimeoutMs: config.mcpTimeoutMs,
         });
         const loadedSkills = await loadActoviqSkillDefinitions({
             homeDir: config.homeDir,
@@ -577,10 +591,14 @@ export class ActoviqAgentClient {
     stream(input, options = {}) {
         const runId = createId();
         return new AgentRunStream(async (controller) => {
+            const runOptions = {
+                ...options,
+                signal: combineAbortSignals(options.signal, controller.signal),
+            };
             try {
-                const augmentations = await this.prepareRunAugmentations(runId, input, options);
-                const result = await this.executeRun(runId, input, options, undefined, true, controller.emit, augmentations);
-                const hookOutcome = await this.applyPostRunHooks(runId, input, options, result);
+                const augmentations = await this.prepareRunAugmentations(runId, input, runOptions);
+                const result = await this.executeRun(runId, input, runOptions, undefined, true, controller.emit, augmentations);
+                const hookOutcome = await this.applyPostRunHooks(runId, input, runOptions, result);
                 if (hookOutcome.sessionMetadata) {
                     result.sessionHookMetadata = hookOutcome.sessionMetadata;
                 }
@@ -610,7 +628,7 @@ export class ActoviqAgentClient {
                 });
                 throw error;
             }
-        });
+        }, { signal: options.signal });
     }
     async parallel(tasks, options) {
         return parallel(tasks, options);
@@ -1347,9 +1365,13 @@ export class ActoviqAgentClient {
             return result;
         });
     }
-    async runOnSession(session, input, options = {}) {
+    runOnSession(session, input, options = {}) {
+        return this.sessionTurnCoordinator.runExclusive(session.id, () => this.runOnSessionExclusive(session, input, options));
+    }
+    async runOnSessionExclusive(session, input, options) {
         const runId = createId();
-        const initialSnapshot = session.snapshot();
+        const initialSnapshot = await this.store.load(session.id);
+        session.replace(initialSnapshot);
         const resolvedOptions = this.applySessionRuntimeOverrides(session.id, this.resolveSessionAgentOptions(initialSnapshot, options));
         const execution = await this.executeSessionRunWithReactiveCompact({
             runId,
@@ -1364,14 +1386,20 @@ export class ActoviqAgentClient {
         }
         await this.persistSessionAfterRun(session, execution.snapshot, input, execution.result, resolvedOptions, execution.augmentations.surfacedMemories, hookOutcome);
         await this.sessionManager.touch(session.id);
+        session.replace(await this.store.load(session.id));
         return execution.result;
     }
     streamOnSession(session, input, options = {}) {
         const runId = createId();
-        const initialSnapshot = session.snapshot();
-        return new AgentRunStream(async (controller) => {
+        return new AgentRunStream((controller) => this.sessionTurnCoordinator.runExclusive(session.id, async () => {
+            const runOptions = {
+                ...options,
+                signal: combineAbortSignals(options.signal, controller.signal),
+            };
             try {
-                const resolvedOptions = this.applySessionRuntimeOverrides(session.id, this.resolveSessionAgentOptions(initialSnapshot, options));
+                const initialSnapshot = await this.store.load(session.id);
+                session.replace(initialSnapshot);
+                const resolvedOptions = this.applySessionRuntimeOverrides(session.id, this.resolveSessionAgentOptions(initialSnapshot, runOptions));
                 const execution = await this.executeSessionRunWithReactiveCompact({
                     runId,
                     session,
@@ -1386,6 +1414,8 @@ export class ActoviqAgentClient {
                     execution.result.sessionHookMetadata = hookOutcome.sessionMetadata;
                 }
                 await this.persistSessionAfterRun(session, execution.snapshot, input, execution.result, resolvedOptions, execution.augmentations.surfacedMemories, hookOutcome);
+                await this.sessionManager.touch(session.id);
+                session.replace(await this.store.load(session.id));
                 controller.emit({
                     type: 'response.completed',
                     runId,
@@ -1408,21 +1438,17 @@ export class ActoviqAgentClient {
                 });
                 throw error;
             }
-        });
+        }), { signal: options.signal });
     }
-    async executeRun(runId, input, options, session, streaming = false, emit, augmentations, skipRunStartedEvent = false) {
+    async executeRun(runId, input, options, session, streaming = false, emit, augmentations, skipRunStartedEvent = false, liveSession) {
         const metadata = {
             ...this.config.metadata,
             ...(session?.metadata ?? {}),
             ...(augmentations?.metadata ?? {}),
             ...(options.metadata ?? {}),
+            [ACTOVIQ_RUN_STATE_KEY]: createActoviqRunToolState(),
         };
-        // Resolve working directory: sessionWorkDir (from worktree) takes priority
-        // unless inheritWorktree is explicitly false.
-        const inheritWorktree = options.inheritWorktree !== false;
-        const workDir = inheritWorktree
-            ? (options.__actoviqWorkDir ?? options.sessionWorkDir ?? options.workDir ?? this.config.workDir)
-            : (options.__actoviqWorkDir ?? options.workDir ?? this.config.workDir);
+        const workDir = this.resolveRunWorkDir(options);
         const mergedTools = filterAgentTools(mergeUniqueByName(options.__actoviqUseDefaultTools === false ? [] : this.defaultTools, options.tools ?? []), options.__actoviqAllowedTools, options.__actoviqDisallowedTools);
         // Collect tool prompts for system prompt assembly
         const toolPromptParts = await collectToolPrompts(mergedTools, {
@@ -1440,13 +1466,21 @@ export class ActoviqAgentClient {
             }
             : this.config;
         const notificationKey = session?.id ?? runId;
-        const drainQueuedInputs = notificationKey || options.drainQueuedInputs
+        const drainQueuedInputs = notificationKey || options.drainQueuedInputs || liveSession
             ? () => [
+                ...(liveSession?.drainSteeringInputs() ?? []),
                 ...(options.drainQueuedInputs?.() ?? []),
                 ...this.drainRuntimeNotifications(notificationKey),
             ]
             : undefined;
-        return executeConversation({
+        const drainFollowUpInputs = options.drainFollowUpInputs || liveSession
+            ? () => [
+                ...(liveSession?.drainFollowUpInputs() ?? []),
+                ...(options.drainFollowUpInputs?.() ?? []),
+            ]
+            : undefined;
+        let checkpointSession = session ? deepClone(session) : undefined;
+        return withDeadline(`Agent run ${runId}`, runtimeConfig.runTimeoutMs, options.signal, ({ signal }) => executeConversation({
             runId,
             input,
             messages: session?.messages,
@@ -1462,7 +1496,7 @@ export class ActoviqAgentClient {
             toolChoice: options.toolChoice,
             userId: options.userId ?? this.config.userId,
             metadata,
-            signal: options.signal,
+            signal,
             permissionMode: options.permissionMode ?? this.defaultPermissionMode,
             permissions: options.permissions ?? this.defaultPermissions,
             classifier: options.classifier ?? this.defaultClassifier,
@@ -1470,19 +1504,37 @@ export class ActoviqAgentClient {
             canUseTool: options.canUseTool,
             hooks: augmentations?.hooks,
             drainQueuedInputs,
+            drainFollowUpInputs,
             streaming,
             // Activate paths-conditional skills when the agent touches matching files.
             emit: (event) => {
                 this.activateConditionalSkillsFromEvent(event);
                 emit?.(event);
             },
+            onConversationCheckpoint: checkpointSession
+                ? async (messages) => {
+                    const snap = deepClone(checkpointSession);
+                    snap.messages = deepClone(messages);
+                    snap.updatedAt = nowIso();
+                    snap.metadata = {
+                        ...snap.metadata,
+                        __actoviqWorkDir: workDir,
+                        ...(options.metadata ?? {}),
+                    };
+                    await this.store.save(snap);
+                    checkpointSession = snap;
+                    // Keep the live AgentSession (if any) in sync so a subsequent
+                    // persistSessionAfterRun / reactive compact sees the checkpoint.
+                    liveSession?.replace(snap);
+                }
+                : undefined,
             skipRunStartedEvent,
             // Per-run model client override (the /model router uses this to route a
             // turn to a different model/provider); falls back to the SDK default.
             modelApi: options.modelApi ?? this.modelApi,
             config: runtimeConfig,
             mcpManager: this.mcpManager,
-        }).then(result => ({
+        })).then(result => ({
             ...result,
             surfacedMemories: augmentations?.surfacedMemories.length
                 ? deepClone(augmentations.surfacedMemories)
@@ -1499,13 +1551,13 @@ export class ActoviqAgentClient {
         let attempts = 0;
         while (true) {
             try {
-                const result = await this.executeRun(args.runId, args.input, args.options, currentSnapshot, args.streaming ?? false, args.emit, currentAugmentations, attempts > 0);
+                const result = await this.executeRun(args.runId, args.input, args.options, currentSnapshot, args.streaming ?? false, args.emit, currentAugmentations, attempts > 0, args.session);
                 if (lastReactiveCompact) {
                     result.reactiveCompact = lastReactiveCompact;
                 }
                 return {
                     result,
-                    snapshot: currentSnapshot,
+                    snapshot: args.session.snapshot(),
                     augmentations: currentAugmentations,
                 };
             }
@@ -1559,7 +1611,7 @@ export class ActoviqAgentClient {
         const agentMemoryMessages = session
             ? await this.prepareAgentMemoryMessages(session, internalOptions)
             : [];
-        const preloadedSkillMessages = await this.preparePreloadedAgentSkillMessages(internalOptions.__actoviqPreloadedSkills, session?.id, internalOptions.__actoviqWorkDir ?? internalOptions.workDir ?? this.config.workDir);
+        const preloadedSkillMessages = await this.preparePreloadedAgentSkillMessages(internalOptions.__actoviqPreloadedSkills, session?.id, this.resolveRunWorkDir(internalOptions));
         const hooks = mergeActoviqHooks(this.hooks, options.hooks);
         const prefixedMessages = [
             ...notificationMessages,
@@ -1572,15 +1624,15 @@ export class ActoviqAgentClient {
         const systemPromptParts = [];
         const metadata = {};
         for (const hook of resolveActoviqSessionStartHooks(hooks)) {
-            const result = await hook({
+            const result = await withDeadline('sessionStart hook', this.config.hookTimeoutMs, options.signal, ({ signal }) => hook({
                 runId,
                 input,
                 promptText,
                 sessionId: session?.id,
                 session: session ? deepClone(session) : undefined,
-                workDir: internalOptions.__actoviqWorkDir ?? internalOptions.workDir ?? this.config.workDir,
-                options,
-            });
+                workDir: this.resolveRunWorkDir(internalOptions),
+                options: { ...options, signal },
+            }));
             if (!result) {
                 continue;
             }
@@ -1640,7 +1692,7 @@ export class ActoviqAgentClient {
             typeof agentName !== 'string') {
             return [];
         }
-        const workDir = options.__actoviqWorkDir ?? options.workDir ?? this.config.workDir;
+        const workDir = this.resolveRunWorkDir(options);
         const root = scope === 'user'
             ? path.join(this.config.homeDir, 'agent-memory', agentName)
             : scope === 'project'
@@ -1671,18 +1723,16 @@ export class ActoviqAgentClient {
         const sessionMetadata = {};
         const tags = new Set();
         for (const hook of resolveActoviqPostRunHooks(hooks)) {
-            const output = await hook({
+            const output = await withDeadline('postRun hook', this.config.hookTimeoutMs, options.signal, ({ signal }) => hook({
                 runId,
                 input,
                 promptText,
                 sessionId: session?.id,
                 session: session ? deepClone(session) : undefined,
-                workDir: options.__actoviqWorkDir ??
-                    options.workDir ??
-                    this.config.workDir,
-                options,
+                workDir: this.resolveRunWorkDir(options),
+                options: { ...options, signal },
                 result,
-            });
+            }));
             if (!output) {
                 continue;
             }
@@ -1855,7 +1905,7 @@ export class ActoviqAgentClient {
             force: true,
             trigger: 'reactive',
         }, {
-            workDir: this.config.workDir,
+            workDir: this.resolveRunWorkDir(options),
             systemPrompt: snapshot.systemPrompt ?? this.config.systemPrompt,
             model: this.resolveModel(options.model ?? snapshot.model),
             modelApi: this.modelApi,
@@ -2454,6 +2504,7 @@ export class ActoviqAgentClient {
         return extraction;
     }
     async persistSessionAfterRun(session, snapshot, input, result, options, surfacedMemories = [], hookOutcome = {}) {
+        const workDir = this.resolveRunWorkDir(options);
         const next = deepClone(snapshot);
         next.model = result.model;
         next.systemPrompt = options.systemPrompt ?? next.systemPrompt;
@@ -2462,7 +2513,7 @@ export class ActoviqAgentClient {
         next.lastRunAt = result.completedAt;
         next.metadata = {
             ...next.metadata,
-            __actoviqWorkDir: this.config.workDir,
+            __actoviqWorkDir: workDir,
             ...(options.metadata ?? {}),
             ...(hookOutcome.sessionMetadata ?? {}),
         };
@@ -2559,7 +2610,7 @@ export class ActoviqAgentClient {
         const newMessages = next.messages.slice(prevMessageCount);
         if (newMessages.length > 0) {
             const paths = await this.memory.paths();
-            await appendMessagesToTranscript(paths.projectStateDir, session.id, this.config.workDir, newMessages);
+            await appendMessagesToTranscript(paths.projectStateDir, session.id, workDir, newMessages);
         }
         const extraction = await this.performSessionMemoryExtraction(next, {
             model: this.resolveModel(options.model ?? next.model),
@@ -2570,7 +2621,7 @@ export class ActoviqAgentClient {
         });
         await this.applySessionMemoryState(session, next, extraction.state);
         const compacted = await compactActoviqSession(next, { trigger: 'auto' }, {
-            workDir: this.config.workDir,
+            workDir,
             systemPrompt: next.systemPrompt ?? this.config.systemPrompt,
             model: this.resolveModel(options.model ?? next.model),
             modelApi: this.modelApi,
@@ -2608,14 +2659,33 @@ export class ActoviqAgentClient {
         }
         return cloneSkillDefinition(definition);
     }
+    resolveRunWorkDir(options) {
+        const internal = options;
+        if (options.inheritWorktree === false) {
+            return internal.__actoviqWorkDir ?? options.workDir ?? this.config.workDir;
+        }
+        return (internal.__actoviqWorkDir ??
+            options.sessionWorkDir ??
+            options.workDir ??
+            internal.__actoviqPersistedWorkDir ??
+            this.config.workDir);
+    }
     resolveSessionAgentOptions(session, options) {
+        const persistedWorkDir = typeof session.metadata.__actoviqWorkDir === 'string' &&
+            session.metadata.__actoviqWorkDir.trim().length > 0
+            ? session.metadata.__actoviqWorkDir
+            : undefined;
+        const sessionOptions = {
+            ...options,
+            __actoviqPersistedWorkDir: persistedWorkDir,
+        };
         const agentName = typeof session.metadata.__actoviqAgentDefinition === 'string'
             ? session.metadata.__actoviqAgentDefinition
             : undefined;
         if (!agentName) {
-            return options;
+            return sessionOptions;
         }
-        return this.mergeAgentRunOptions(this.requireAgentDefinition(agentName), options);
+        return this.mergeAgentRunOptions(this.requireAgentDefinition(agentName), sessionOptions);
     }
     mergeAgentRunOptions(definition, options) {
         const availableMcpServers = new Set([
@@ -2687,6 +2757,7 @@ export class ActoviqAgentClient {
     }
 }
 export async function createAgentSdk(options = {}) {
+    recordCompatUsage('createAgentSdk');
     return ActoviqAgentClient.create(options);
 }
 function resolveTaskId(input) {
@@ -2725,6 +2796,14 @@ function joinPromptParts(...parts) {
     }
     return normalized.join('\n\n');
 }
+function combineAbortSignals(...signals) {
+    const available = signals.filter((signal) => signal != null);
+    if (available.length === 0)
+        return undefined;
+    if (available.length === 1)
+        return available[0];
+    return AbortSignal.any(available);
+}
 function mergeAgentDefinitions(...groups) {
     const merged = new Map();
     for (const group of groups) {
@@ -2749,6 +2828,9 @@ function formatTaskNotification(task) {
     const result = task.status === 'completed'
         ? task.text ?? task.partialText ?? ''
         : task.partialText ?? '';
+    const actor = task.subagentType === 'bash'
+        ? `Background command "${task.description}"`
+        : `Agent "${task.agentName ?? task.subagentType}"`;
     return [
         '<task_notification>',
         `<task_id>${escapeXml(task.id)}</task_id>`,
@@ -2756,8 +2838,8 @@ function formatTaskNotification(task) {
         task.agentName ? `<agent_name>${escapeXml(task.agentName)}</agent_name>` : undefined,
         `<status>${task.status}</status>`,
         `<summary>${escapeXml(task.status === 'completed'
-            ? `Agent "${task.agentName ?? task.subagentType}" completed.`
-            : `Agent "${task.agentName ?? task.subagentType}" ${task.status}.`)}</summary>`,
+            ? `${actor} completed.`
+            : `${actor} ${task.status}.`)}</summary>`,
         result ? `<result>${escapeXml(result)}</result>` : undefined,
         task.error ? `<error>${escapeXml(task.error)}</error>` : undefined,
         `<usage><requests>${task.requestCount ?? 0}</requests><tool_uses>${task.toolCallCount ?? 0}</tool_uses><tool_errors>${task.toolErrorCount ?? 0}</tool_errors></usage>`,