actoviq-agent-sdk 0.4.12 → 0.4.13

package/dist/src/runtime/agentClient.js

@@ -41,6 +41,7 @@ import { policyPermissionMode, policyPermissionRules, } from '../policy/runtimeP
 import { TeammateStore } from '../storage/teammateStore.js';
 import { createCheckpointTools, FileChangeJournal, FileCheckpointService, } from '../checkpoint/index.js';
 import { SandboxExecutor } from '../sandbox/sandboxExecutor.js';
+import { resolveSandboxPolicy } from '../sandbox/policyResolver.js';
 import { CodeIntelligenceService, createCodeIntelligenceTools, LanguageServerRegistry, } from '../codeIntel/index.js';
 import { HookRunner } from '../hooks/hookRunner.js';
 import { createPromptHookHandler } from '../hooks/handlers/promptHook.js';
@@ -52,6 +53,10 @@ import { createGitWorktreeWorkspace, } from '../workspace/hadamardWorkspace.js';
 import { HADAMARD_RUN_STATE_KEY, HadamardAgentsApi, createHadamardRunToolState, createHadamardTaskTool, summarizeHadamardAgentDefinition, } from './hadamardAgents.js';
 import { getDefaultHadamardAgents } from './defaultHadamardAgents.js';
 import { loadHadamardAgentDefinitions } from './hadamardAgentDefinitions.js';
+import { migrateAgentProfilesToMarkdown } from '../config/agentDefinitionMigration.js';
+import { resolveTargetRef } from '../manager/resolveTargetRef.js';
+import { isExternalAgentRuntime, runExternalAgentOnce } from './externalAgentRunner.js';
+import { resolveEffectiveAgentRunOptions } from './effectiveAgentRunOptions.js';
 import { HadamardSkillsApi, getDefaultHadamardBundledSkills, loadHadamardSkillDefinitions, resolveHadamardSkillPrompt, skillPathsMatch, summarizeHadamardSkillDefinition, } from './hadamardSkills.js';
 import { loadHadamardExternalSkillDefinitions } from './externalSkillRuntime.js';
 import { HadamardBackgroundTaskManager, HadamardBackgroundTasksApi, } from './hadamardBackgroundTasks.js';
@@ -454,6 +459,10 @@ export class HadamardAgentClient {
     sessionManager;
     sessionTurnCoordinator = new SessionTurnCoordinator();
     agentDefinitions;
+    /** §6-6: per-agent-session model clients resolved from definition.bridgeConfig. */
+    agentSessionModelClients = new Map();
+    /** External-CLI delegation runner (injectable for tests via CreateAgentSdkOptions). */
+    externalAgentRunner;
     skillDefinitions;
     /** Names of `paths:`-conditional skills activated by touching matching files. */
     activatedConditionalSkills = new Set();
@@ -474,7 +483,7 @@ export class HadamardAgentClient {
      * Idle restores never push; nested runs each own a slot.
      */
     conversationRestoreStack = [];
-    constructor(config, store, executionStore, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, hooks, agentDefinitions = [], skillDefinitions = [], defaultPermissionMode, defaultPermissions, defaultClassifier, defaultApprover, sessionManagerConfig, maxSubagentDepth = 1, maxSubagentFanout = 8, taskWorktreeCoordinator) {
+    constructor(config, store, executionStore, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, hooks, agentDefinitions = [], skillDefinitions = [], defaultPermissionMode, defaultPermissions, defaultClassifier, defaultApprover, sessionManagerConfig, maxSubagentDepth = 1, maxSubagentFanout = 8, taskWorktreeCoordinator, externalAgentRunner) {
         this.config = config;
         this.store = store;
         this.backgroundTaskStore = backgroundTaskStore;
@@ -487,6 +496,7 @@ export class HadamardAgentClient {
         this.hooks = hooks;
         this.maxSubagentDepth = maxSubagentDepth;
         this.maxSubagentFanout = maxSubagentFanout;
+        this.externalAgentRunner = externalAgentRunner ?? runExternalAgentOnce;
         this.sessionManager = new SessionManager(this.store, sessionManagerConfig);
         this.sessionGraph = new SessionGraph(this.store);
         this.sessionForks = new SessionForkService(this.store);
@@ -798,6 +808,9 @@ export class HadamardAgentClient {
                 ...(options.skills ?? []),
             ]
             : [...loadedSkills, ...(options.skills ?? [])];
+        // Unified agent store (S1a): auto-migrate legacy agent-configs.json into
+        // agents/*.md before loading definitions (idempotent, no-op once migrated).
+        migrateAgentProfilesToMarkdown(config.homeDir, path.join(config.homeDir, 'agents'));
         const loadedAgents = await loadHadamardAgentDefinitions({
             homeDir: config.homeDir,
             workDir: config.workDir,
@@ -841,7 +854,7 @@ export class HadamardAgentClient {
         client = new HadamardAgentClient(config, store, executionStore, backgroundTaskStore, mailboxStore, teammateStore, modelApi, mcpManager, defaultTools, defaultMcpServers, options.hooks, agentDefinitions, skillDefinitions, policyPermissionMode(config.effectivePolicy) ?? options.permissionMode, [
             ...policyPermissionRules(config.effectivePolicy),
             ...(options.permissions ?? []),
-        ], options.classifier, options.approver, options.sessionManager, options.maxSubagentDepth, options.maxSubagentFanout, taskWorktreeCoordinator);
+        ], options.classifier, options.approver, options.sessionManager, options.maxSubagentDepth, options.maxSubagentFanout, taskWorktreeCoordinator, options.externalAgentRunner);
         const interruptedTasks = await client.backgroundTaskManager.reconcileInterruptedTasks();
         await client.reconcileInterruptedAgentExecutions(interruptedTasks);
         return client;
@@ -1165,24 +1178,101 @@ export class HadamardAgentClient {
         }
     }
     listAgentDefinitions() {
-        return [...this.agentDefinitions.values()].map(summarizeHadamardAgentDefinition);
+        // subagent === false (§6-1): main-chat-only agents stay out of the
+        // Agent/Task tool's available-subagents listing.
+        return [...this.agentDefinitions.values()]
+            .filter(definition => definition.subagent !== false)
+            .map(summarizeHadamardAgentDefinition);
     }
     getAgentDefinition(agent) {
         const definition = this.agentDefinitions.get(agent);
-        return definition ? cloneAgentDefinition(definition) : undefined;
+        // subagent === false: not resolvable as a delegation target, but still
+        // activatable as a main-chat agent (requireAgentDefinition is unfiltered).
+        if (!definition || definition.subagent === false)
+            return undefined;
+        return cloneAgentDefinition(definition);
     }
     async runWithAgent(agent, input, options = {}) {
         const definition = this.requireAgentDefinition(agent);
+        if (isExternalAgentRuntime(definition.runtime)) {
+            // External-CLI delegation (09 Aug 2026): one-shot bridge run on the
+            // definition's runtime — no SDK session, no model-client resolution.
+            const prompt = typeof input === 'string' ? input : extractTextFromContent(input);
+            return this.runExternalDefinition(definition, prompt, {
+                cwd: definition.cwd ?? this.config.workDir,
+                signal: options.signal,
+            });
+        }
+        // §6-6 model priority: caller-passed model/modelApi > definition's own
+        // bridgeConfig client > inherited session client.
+        const modelClient = options.model || options.modelApi
+            ? undefined
+            : await this.resolveDefinitionModelClient(definition);
         const mergedOptions = this.mergeAgentRunOptions(definition, options);
+        if (modelClient) {
+            mergedOptions.model = modelClient.model;
+            mergedOptions.modelApi = modelClient.modelApi;
+        }
         return this.run(input, mergedOptions);
     }
+    /**
+     * Run a definition on its external CLI runtime and fabricate the
+     * AgentRunResult. The bridge result's native session id is intentionally
+     * NOT exposed as a Hadamard sessionId — external runs are not resumable
+     * through SendMessage.
+     */
+    async runExternalDefinition(definition, prompt, options) {
+        const startedAt = nowIso();
+        const run = await this.externalAgentRunner({
+            runtime: definition.runtime.trim(),
+            agentName: definition.name,
+            prompt,
+            systemPrompt: definition.systemPrompt,
+            cwd: options.cwd,
+            signal: options.signal,
+            model: definition.model,
+            permissionMode: definition.permissionMode,
+            homeDir: this.config.homeDir,
+        });
+        const model = definition.model ?? definition.runtime ?? 'external';
+        return {
+            runId: createId(),
+            model,
+            text: run.text,
+            message: {
+                id: createId(),
+                type: 'message',
+                role: 'assistant',
+                model,
+                content: [{ type: 'text', text: run.text }],
+                stop_reason: 'end_turn',
+                stop_sequence: null,
+                usage: { input_tokens: 0, output_tokens: 0 },
+            },
+            messages: [
+                { role: 'user', content: prompt },
+                { role: 'assistant', content: run.text },
+            ],
+            stopReason: 'end_turn',
+            requests: [],
+            toolCalls: [],
+            startedAt,
+            completedAt: nowIso(),
+        };
+    }
     async createAgentSession(agent, options = {}) {
         const definition = this.requireAgentDefinition(agent);
-        return this.createSession({
+        const effective = resolveEffectiveAgentRunOptions(definition, {
+            permissionModeOverride: options.permissionMode,
+        });
+        const session = await this.createSession({
             ...options,
             kind: options.kind ?? 'agent',
             model: options.model ?? definition.model,
-            systemPrompt: joinPromptParts(definition.systemPrompt, options.systemPrompt),
+            // Keep the caller prompt as session state; the definition is composed at
+            // send time so `extend` does not duplicate and `replace` stays exact.
+            systemPrompt: options.systemPrompt,
+            permissionMode: effective.permissionMode,
             metadata: {
                 ...(definition.metadata ?? {}),
                 ...(options.metadata ?? {}),
@@ -1195,6 +1285,15 @@ export class HadamardAgentClient {
                 },
             },
         });
+        // §6-6: a definition with bridgeConfig runs on its own provider config.
+        // Resolve the client once per agent session; resolveSessionAgentOptions
+        // (sync) applies it to every send on this session.
+        if (definition.bridgeConfig && !options.model) {
+            const modelClient = await this.resolveDefinitionModelClient(definition);
+            if (modelClient)
+                this.agentSessionModelClients.set(session.id, modelClient);
+        }
+        return session;
     }
     listSkillDefinitions() {
         return [...this.skillDefinitions.values()].map(summarizeHadamardSkillDefinition);
@@ -1267,6 +1366,7 @@ export class HadamardAgentClient {
             ...options,
             listAgentDefinitions: () => this.listAgentDefinitions(),
             getAgentDefinition: (agent) => this.getAgentDefinition(agent),
+            listAvailableTools: () => this.defaultTools,
             runAgent: (agent, prompt, runOptions, delegation) => this.runDelegatedAgentTask(agent, prompt, runOptions, delegation),
             maxDepth: this.maxSubagentDepth,
             maxFanout: this.maxSubagentFanout,
@@ -1881,6 +1981,7 @@ export class HadamardAgentClient {
     }
     async executeRun(runId, input, options, session, streaming = false, emit, augmentations, skipRunStartedEvent = false, liveSession, deferPromptTooLongSettlement = false, skipInitialInput = false, onInitialInputCheckpointed) {
         const workDir = this.resolveRunWorkDir(options);
+        let activeWorkDir = workDir;
         const model = this.resolveModel(options.model ?? session?.model);
         const goalService = await this.resolveGoalService(session, liveSession);
         let goalExecutionDecision = { kind: 'run', mode: 'work' };
@@ -1955,7 +2056,13 @@ export class HadamardAgentClient {
             ...serializeAgentExecutionIdentity(executionIdentity),
             [HADAMARD_RUN_STATE_KEY]: createHadamardRunToolState(),
         };
-        const mergedTools = filterAgentTools(mergeUniqueByName(options.__hadamardUseDefaultTools === false ? [] : this.defaultTools, options.tools ?? []), options.__hadamardAllowedTools, options.__hadamardDisallowedTools);
+        const workspaceAccess = options.__hadamardWorkspaceAccess ?? options.workspaceAccess;
+        const sandboxExecutor = this.sandboxExecutorForWorkDir(workDir, workspaceAccess);
+        const workspaceProcessDenylist = workspaceAccess === 'workspace'
+            && !sandboxExecutor.capability.filesystemIsolation
+            ? ['Bash', 'PowerShell', 'EnterWorktree', 'ExitWorktree']
+            : [];
+        const mergedTools = filterAgentTools(mergeUniqueByName(options.__hadamardUseDefaultTools === false ? [] : this.defaultTools, options.tools ?? []), options.__hadamardAllowedTools ?? options.allowedTools, [...(options.__hadamardDisallowedTools ?? []), ...workspaceProcessDenylist]);
         // Goal runtime contract: when a session exists, expose the active goal to
         // the model (short context in the system prompt + GetGoal/CreateGoal/
         // UpdateGoal tools). The GoalService is the single authority over goal
@@ -1971,7 +2078,7 @@ export class HadamardAgentClient {
             const goal = await goalService.read();
             goalPromptPart = buildGoalPrompt(goal, { decision: goalExecutionDecision });
             const toolsWithGoal = mergeUniqueByName(goalTools, createGoalTools({ getGoalService: () => goalService }));
-            goalTools = filterAgentTools(toolsWithGoal, options.__hadamardAllowedTools, options.__hadamardDisallowedTools);
+            goalTools = filterAgentTools(toolsWithGoal, options.__hadamardAllowedTools ?? options.allowedTools, [...(options.__hadamardDisallowedTools ?? []), ...workspaceProcessDenylist]);
         }
         // Collect tool prompts for system prompt assembly
         const toolPromptParts = await collectToolPrompts(goalTools, {
@@ -1983,15 +2090,15 @@ export class HadamardAgentClient {
             ...(goalPromptPart ? [goalPromptPart] : []),
             ...toolPromptParts,
         ]);
-        const sandboxExecutor = this.sandboxExecutorForWorkDir(workDir);
-        const runtimeConfig = options.__hadamardMaxToolIterations || workDir !== this.config.workDir
+        const runMaxToolIterations = options.__hadamardMaxToolIterations ?? options.maxToolIterations;
+        const runtimeConfig = runMaxToolIterations || workDir !== this.config.workDir
             ? {
                 ...this.config,
                 workDir,
                 sandbox: sandboxExecutor.policy,
                 sandboxCapabilities: sandboxExecutor.capability,
-                ...(options.__hadamardMaxToolIterations
-                    ? { maxToolIterations: options.__hadamardMaxToolIterations }
+                ...(runMaxToolIterations
+                    ? { maxToolIterations: runMaxToolIterations }
                     : {}),
             }
             : this.config;
@@ -2103,7 +2210,7 @@ export class HadamardAgentClient {
                             updatedAt: nowIso(),
                             metadata: {
                                 ...current.metadata,
-                                __hadamardWorkDir: workDir,
+                                __hadamardWorkDir: activeWorkDir,
                                 ...(options.metadata ?? {}),
                                 ...serializeAgentExecutionIdentity(executionIdentity),
                             },
@@ -2134,6 +2241,15 @@ export class HadamardAgentClient {
                 modelApi: options.modelApi ?? this.modelApi,
                 config: runtimeConfig,
                 mcpManager: this.mcpManager,
+                sessionWorkDir: activeWorkDir,
+                onSessionWorkDirChange: (nextWorkDir) => {
+                    activeWorkDir = nextWorkDir;
+                    options.__hadamardWorkDir = nextWorkDir;
+                    options.metadata = {
+                        ...(options.metadata ?? {}),
+                        __hadamardWorkDir: nextWorkDir,
+                    };
+                },
                 fileChangeJournal: fileCheckpointStarted ? this.fileChangeJournal : undefined,
                 sandboxExecutor,
                 typedHookRunner: this.typedHookRunner,
@@ -2782,6 +2898,23 @@ export class HadamardAgentClient {
         });
         let edgeStarted = false;
         try {
+            if (isExternalAgentRuntime(definition.runtime)) {
+                // External-CLI delegation: one-shot bridge run in the prepared (maybe
+                // worktree-isolated) workspace; no Hadamard session is created.
+                edgeStarted = await this.tryStartExecutionEdge(execution.edge);
+                const result = await this.runExternalDefinition(definition, prompt, {
+                    cwd: prepared.workDir,
+                    signal: runOptions.signal,
+                });
+                const retained = await this.finalizeDelegatedWorkspace(prepared.workspace);
+                await this.tryCompleteExecutionEdge(execution.edge, result.text);
+                return {
+                    result,
+                    sessionId: '',
+                    worktreePath: retained ? prepared.workspace?.path : undefined,
+                    worktreeBranch: retained ? prepared.workspace?.metadata.branch : undefined,
+                };
+            }
             const session = await this.createAgentSession(agent, {
                 id: childSessionId,
                 kind: 'agent',
@@ -3041,6 +3174,13 @@ export class HadamardAgentClient {
     }
     async launchBackgroundAgentTask(agent, prompt, options, runOptions = {}, delegation = { description: prompt }) {
         const definition = this.requireAgentDefinition(agent);
+        if (isExternalAgentRuntime(definition.runtime)) {
+            // External runtimes are one-shot CLI runs — there is no Hadamard session
+            // to drive in the background, so fail loudly instead of silently
+            // falling back to the SDK.
+            throw new Error(`Agent "${definition.name}" uses external runtime "${definition.runtime}"; `
+                + 'background delegation is not supported for external runtimes yet — run it in the foreground.');
+        }
         const prepared = await this.prepareDelegatedWorkspace(definition, delegation);
         const childSessionId = createId();
         const execution = this.delegatedExecutionContext(definition, delegation, runOptions, prepared.workDir, childSessionId, options);
@@ -3716,8 +3856,16 @@ export class HadamardAgentClient {
             internal.__hadamardPersistedWorkDir ??
             this.config.workDir);
     }
-    sandboxExecutorForWorkDir(workDir) {
+    sandboxExecutorForWorkDir(workDir, workspaceAccess) {
         const resolved = path.resolve(workDir);
+        if (workspaceAccess === 'workspace') {
+            return new SandboxExecutor(resolveSandboxPolicy(resolved, this.config.sandbox, {
+                readRoots: [resolved],
+                writableRoots: [resolved],
+                allowUserDisable: false,
+                source: 'agent:workspace',
+            }));
+        }
         if (resolved === path.resolve(this.config.workDir))
             return this.sandboxExecutor;
         const remap = (roots) => roots.map(root => {
@@ -3755,6 +3903,7 @@ export class HadamardAgentClient {
             : undefined;
         const sessionOptions = {
             ...options,
+            systemPrompt: options.systemPrompt ?? session.systemPrompt,
             __hadamardPersistedWorkDir: persistedWorkDir,
         };
         const agentName = typeof session.metadata.__hadamardAgentDefinition === 'string'
@@ -3763,7 +3912,33 @@ export class HadamardAgentClient {
         if (!agentName) {
             return sessionOptions;
         }
-        return this.mergeAgentRunOptions(this.requireAgentDefinition(agentName), sessionOptions);
+        const merged = this.mergeAgentRunOptions(this.requireAgentDefinition(agentName), sessionOptions);
+        // §6-6: apply the session's definition-resolved model client (see
+        // createAgentSession); a caller-passed model/modelApi still wins.
+        const modelClient = this.agentSessionModelClients.get(session.id);
+        if (modelClient && !sessionOptions.modelApi) {
+            merged.model = sessionOptions.model ?? modelClient.model;
+            merged.modelApi = modelClient.modelApi;
+        }
+        return merged;
+    }
+    /**
+     * §6-6: resolve a definition's own model client from its bridgeConfig via
+     * the central target resolver. A missing config throws BrokenReferenceError
+     * — in plain SDK context that surfaces as a hard delegation error (the GUI
+     * fallback-toggle semantics live in the GUI layer, not here).
+     */
+    async resolveDefinitionModelClient(definition) {
+        if (!definition.bridgeConfig?.trim())
+            return undefined;
+        const resolved = resolveTargetRef({ kind: 'model', config: definition.bridgeConfig.trim(), model: definition.model ?? '' }, { homeDir: this.config.homeDir });
+        const routed = await buildRouteModelApi({
+            model: resolved.model || 'default',
+            provider: resolved.provider,
+            baseURL: resolved.baseURL,
+            apiKey: resolved.apiKey,
+        });
+        return { model: routed.model, modelApi: routed.modelApi };
     }
     mergeAgentRunOptions(definition, options) {
         const availableMcpServers = new Set([
@@ -3776,12 +3951,24 @@ export class HadamardAgentClient {
             throw new Error(`Agent "${definition.name}" requires unavailable MCP servers: ${missingMcpServers.join(', ')}.`);
         }
         const nestedAgentDenylist = definition.allowNestedAgents === true ? [] : ['Agent', 'Task'];
+        const effective = resolveEffectiveAgentRunOptions(definition, {
+            systemPrompt: options.systemPrompt,
+            permissionModeOverride: options.permissionMode,
+            effortOverride: options.effort,
+        });
+        const signal = typeof definition.timeoutMs === 'number' && definition.timeoutMs > 0
+            ? combineAbortSignals(options.signal, AbortSignal.timeout(definition.timeoutMs))
+            : options.signal;
         return {
             ...options,
-            systemPrompt: joinPromptParts(definition.systemPrompt, options.systemPrompt),
+            systemPrompt: effective.systemPrompt,
             model: options.model ?? definition.model,
-            effort: options.effort ?? definition.effort,
-            permissionMode: options.permissionMode ?? definition.permissionMode,
+            effort: effective.effort,
+            permissionMode: effective.permissionMode,
+            maxTokens: options.maxTokens ?? effective.maxTokens,
+            temperature: options.temperature ?? effective.temperature,
+            topP: options.topP ?? effective.topP,
+            signal,
             metadata: {
                 ...(definition.metadata ?? {}),
                 ...(options.metadata ?? {}),
@@ -3792,10 +3979,11 @@ export class HadamardAgentClient {
             mcpServers: [...(definition.mcpServers ?? []), ...(options.mcpServers ?? [])],
             __hadamardUseDefaultTools: definition.inheritDefaultTools !== false,
             __hadamardUseDefaultMcpServers: definition.inheritDefaultMcpServers !== false,
-            __hadamardMaxToolIterations: definition.maxToolIterations ?? definition.maxTurns,
-            __hadamardAllowedTools: definition.allowedTools
-                ? [...definition.allowedTools]
+            __hadamardMaxToolIterations: effective.maxToolIterations ?? definition.maxTurns,
+            __hadamardAllowedTools: options.allowedTools ?? effective.allowedTools
+                ? [...(options.allowedTools ?? effective.allowedTools)]
                 : undefined,
+            __hadamardWorkspaceAccess: options.workspaceAccess ?? effective.workspaceAccess,
             __hadamardDisallowedTools: [
                 ...(definition.disallowedTools ?? []),
                 ...nestedAgentDenylist,