Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

27.1 KB
Raw Blame
import { generateText, stepCountIs } from 'ai';
import { noteTurnModel, runWithExposure } from '../security/provenance.js';
import { isFailedToolResult } from './execute-guard.js';
import { summarizeSilentTurn, type TurnAction } from './silent-turn.js';
import type { ChannelMessage } from '../types/channel.js';
import type { SubAgentConfig, SubAgentResult, SubAgentStatus } from '../types/agent.js';
import type { ProviderRegistry } from '../providers/registry.js';
import type { Identity } from '../soul/identity.js';
import type { ShortTermMemory, LongTermMemory, EpisodicMemory } from '../memory/store.js';
import type { UserMemoryStore } from '../memory/user-memory.js';
import type { MercuryConfig } from '../utils/config.js';
import type { TokenBudget } from '../utils/tokens.js';
import type { CapabilityRegistry } from '../capabilities/registry.js';
import type { FileLockManager } from './file-lock.js';
import type { TaskBoard } from './task-board.js';
import type { SaverMode } from './saver-mode.js';
import type { SubAgentSupervisor } from './supervisor.js';
import { createDelegateTaskTool, createListAgentsTool, createStopAgentTool } from '../capabilities/subagents/index.js';
import { getHeapStatistics } from 'node:v8';
import { memoryGovernorThresholds, memoryGovernorVerdict, CONVERSATION_TOOL_BUDGET_CHARS, TOOL_RESULT_KEEP_RECENT, summarizeToolResult } from './memory-governor.js';
import { classifyStreamCompletion } from './stream-completion.js';
import { resolveChildTools, childMayUse, filterToolsByAllowlist } from '../utils/tool-filter.js';
import { deriveChildContext, type PermissionContext } from '../capabilities/permission-context.js';
import { logger } from '../utils/logger.js';

export type ProgressCallback = (agentId: string, progress: string) => void;
export type CompletionCallback = (result: SubAgentResult) => void;
export type CommentCheckCallback = (agentId: string) => { id: string; author: string; content: string; timestamp: number }[];
export type PostCommentCallback = (agentId: string, content: string) => void;

export class SubAgent {
  readonly config: SubAgentConfig;
  private status: SubAgentStatus = 'pending';
  private abortController: AbortController;
  /** Every tool step, for a report when the model ends without text. */
  private actions: TurnAction[] = [];
  private startTime: number = 0;
  private result: SubAgentResult | null = null;
  private filesModified: string[] = [];

  private totalInputTokens: number = 0;
  private totalOutputTokens: number = 0;

  private agentConfig: MercuryConfig;
  private providers: ProviderRegistry;
  private identity: Identity;
  private shortTerm: ShortTermMemory;
  private longTerm: LongTermMemory;
  private episodic: EpisodicMemory;
  private userMemory: UserMemoryStore | null;
  private capabilities: CapabilityRegistry;
  private tokenBudget: TokenBudget;
  private fileLockManager: FileLockManager;
  private taskBoard: TaskBoard;
  private saverMode?: SaverMode;
  private supervisor?: SubAgentSupervisor;

  private onProgress?: ProgressCallback;
  private onComplete?: CompletionCallback;
  private onCheckComments?: CommentCheckCallback;
  private onPostComment?: PostCommentCallback;
  private lastSeenCommentTimestamp: number = 0;

  constructor(
    config: SubAgentConfig,
    dependencies: {
      agentConfig: MercuryConfig;
      providers: ProviderRegistry;
      identity: Identity;
      shortTerm: ShortTermMemory;
      longTerm: LongTermMemory;
      episodic: EpisodicMemory;
      userMemory: UserMemoryStore | null;
      capabilities: CapabilityRegistry;
      tokenBudget: TokenBudget;
      fileLockManager: FileLockManager;
      taskBoard: TaskBoard;
      saverMode?: SaverMode;
      /** Needed only to hand out lineage-scoped orchestration tools. */
      supervisor?: SubAgentSupervisor;
    },
  ) {
    this.config = config;
    this.abortController = new AbortController();

    this.agentConfig = dependencies.agentConfig;
    this.providers = dependencies.providers;
    this.identity = dependencies.identity;
    this.shortTerm = dependencies.shortTerm;
    this.longTerm = dependencies.longTerm;
    this.episodic = dependencies.episodic;
    this.userMemory = dependencies.userMemory;
    this.capabilities = dependencies.capabilities;
    this.tokenBudget = dependencies.tokenBudget;
    this.fileLockManager = dependencies.fileLockManager;
    this.taskBoard = dependencies.taskBoard;
    this.saverMode = dependencies.saverMode;
    this.supervisor = dependencies.supervisor;
  }

  getStatus(): SubAgentStatus {
    return this.status;
  }

  abort(): void {
    this.abortController.abort();
    logger.info({ agentId: this.config.id }, 'Sub-agent abort signal sent');
  }

  isAborted(): boolean {
    return this.abortController.signal.aborted;
  }

  setProgressCallback(cb: ProgressCallback): void {
    this.onProgress = cb;
  }

  setCompletionCallback(cb: CompletionCallback): void {
    this.onComplete = cb;
  }

  setCommentCheckCallback(cb: CommentCheckCallback): void {
    this.onCheckComments = cb;
  }

  setPostCommentCallback(cb: PostCommentCallback): void {
    this.onPostComment = cb;
  }

  private permissionContext?: PermissionContext;

  /**
   * This agent's frozen permission context: the one the supervisor derived
   * at spawn time, or (when constructed directly) one derived now from the
   * current context. Child ⊆ parent; see permission-context.ts.
   */
  getPermissionContext(): PermissionContext | undefined {
    if (this.permissionContext) return this.permissionContext;
    if (this.config.permissionContext) {
      this.permissionContext = this.config.permissionContext;
    } else {
      const permissions = this.capabilities.permissions as any;
      if (typeof permissions?.currentContext !== 'function') return undefined;
      this.permissionContext = deriveChildContext(permissions.currentContext(), {
        channelType: this.config.sourceChannelType || 'internal',
        channelId: this.config.sourceChannelId || 'internal',
        allowedTools: this.config.allowedTools,
      });
    }
    return this.permissionContext;
  }

  /**
   * Run the task under this agent's own permission context. Every tool it
   * invokes — through any depth of the AI SDK's promise chain — resolves
   * permissions against that context via AsyncLocalStorage, so a concurrent
   * change to the main agent's context (an internal turn's allow-all) never
   * reaches it (#75/#99 residual).
   */
  async run(): Promise<SubAgentResult> {
    const ctx = this.getPermissionContext();
    const permissions = this.capabilities.permissions as any;
    // What the delegating turn had read goes with it (ADR-044).
    const inner = () => (this.config.exposure ? runWithExposure(this.config.exposure, () => this.runInContext()) : this.runInContext());
    if (ctx && typeof permissions?.withContext === 'function') {
      return permissions.withContext(ctx, inner);
    }
    return inner();
  }

  private async runInContext(): Promise<SubAgentResult> {
    this.status = 'running';
    this.startTime = Date.now();

    this.taskBoard.update(this.config.id, {
      status: 'running',
      startedAt: this.startTime,
      progress: 'Starting task...',
    });

    logger.info({ agentId: this.config.id, task: this.config.task.slice(0, 80) }, 'Sub-agent starting');

    try {
      const systemPrompt = this.buildSystemPrompt();
      const messages: any[] = [];

      // Conversation budget: compacts old tool results once retained tool
      // output exceeds the budget. A sub-agent analyzing a whole project
      // must not hold every file read verbatim for the entire run.
      const enforceConversationBudget = () => {
        const toolIdx: number[] = [];
        let total = 0;
        for (let i = 0; i < messages.length; i++) {
          const m = messages[i];
          if (m.role !== 'tool' || typeof m.content !== 'string') continue;
          toolIdx.push(i);
          total += m.content.length;
        }
        if (total <= CONVERSATION_TOOL_BUDGET_CHARS) return;
        const cutoff = toolIdx.slice(0, Math.max(0, toolIdx.length - TOOL_RESULT_KEEP_RECENT));
        for (const idx of cutoff) {
          messages[idx] = { ...messages[idx], content: summarizeToolResult(messages[idx].content) };
        }
        logger.info({ agentId: this.config.id, compacted: cutoff.length }, 'Sub-agent conversation budget enforced');
      };

      const governorThresholds = memoryGovernorThresholds({
        heapSizeLimit: getHeapStatistics().heap_size_limit,
        baselineHeapUsed: process.memoryUsage().heapUsed,
        reservedHeapBytes: 384 * 1024 * 1024,
      });

      messages.push({
        role: 'user',
        content: this.config.task,
      });

      this.taskBoard.update(this.config.id, { progress: 'Processing...' });

      const originalCwd = this.capabilities.getCwd();
      if (this.config.workingDirectory) {
        this.capabilities.setCwd(this.config.workingDirectory);
      }

      // Channel routing comes from this agent's permission context (set in
      // run()); the shared registry's main-agent channel is left alone.

      try {
        const provider = this.providers.getDefault();
        const baseMaxSteps = this.config.maxSteps || 25;
        const maxSteps = this.saverMode?.isActive() ? this.saverMode.adjustMaxSteps(baseMaxSteps) : baseMaxSteps;
        let stepsRemaining = maxSteps;

        logger.info({ agentId: this.config.id, provider: provider.name, maxSteps }, 'Sub-agent generating response');

        if (this.onProgress) {
          this.onProgress(this.config.id, 'Calling LLM provider...');
        }

        // Track last result for final output
        let lastResult: any = null;

        // Execution loop: run generateText, then check for new comments.
        // If new comments found, inject them as user messages and continue.
        while (stepsRemaining > 0 && !this.abortController.signal.aborted) {
          // Step-level memory checkpoint before each provider round-trip.
          const verdict = memoryGovernorVerdict(process.memoryUsage().heapUsed, governorThresholds);
          if (verdict === 'exit') {
            logger.error({ agentId: this.config.id }, 'Sub-agent: heap beyond exit threshold — exiting to preserve process');
            process.exit(0);
          }
          if (verdict === 'abort') {
            this.abortController.abort(new Error('Sub-agent stopped: task memory safety limit reached'));
            break;
          }
          enforceConversationBudget();
          noteTurnModel(provider.getModel());
          const result = await generateText({
            model: provider.getModelInstance(),
            system: systemPrompt,
            messages,
            tools: this.resolveTools(),
            stopWhen: stepCountIs(stepsRemaining),
            abortSignal: this.abortController.signal,
            // Stop the SDK retaining raw HTTP bodies in every step's result
            // (same O(N²) heap growth as the main agent loop).
            experimental_include: { requestBody: false, responseBody: false },
            onStepFinish: async ({ toolCalls, toolResults, usage }) => {
              if (this.abortController.signal.aborted) return;
              stepsRemaining--;

              // Mid-loop memory checkpoint: abort generation if the heap
              // crosses the emergency ceiling (the sub-agent runs on the
              // shared process, so its blowup kills the whole app).
              const midVerdict = memoryGovernorVerdict(process.memoryUsage().heapUsed, governorThresholds);
              if (midVerdict === 'exit') {
                logger.error({ agentId: this.config.id }, 'Sub-agent: heap beyond exit threshold mid-step — exiting');
                process.exit(0);
              }
              if (midVerdict === 'abort') {
                this.abortController.abort(new Error('Sub-agent stopped: task memory safety limit reached'));
                return;
              }

              // Accumulate live token usage
              if (usage) {
                this.totalInputTokens += usage.inputTokens ?? 0;
                this.totalOutputTokens += usage.outputTokens ?? 0;
                const liveTotal = this.totalInputTokens + this.totalOutputTokens;
                this.taskBoard.update(this.config.id, {
                  tokenUsage: { input: this.totalInputTokens, output: this.totalOutputTokens, total: liveTotal },
                });
              }

              if (toolCalls && toolResults && toolCalls.length > 0) {
                const names = toolCalls.map((tc: any) => tc.toolName).join(', ');
                logger.info({ agentId: this.config.id, tools: names }, 'Sub-agent tool step');

                for (let i = 0; i < toolCalls.length; i++) {
                  const tc = toolCalls[i];
                  const toolName = tc.toolName as string;
                  {
                    type StepResult = { toolCallId?: string; output?: unknown; result?: unknown };
                    const results = toolResults as unknown as StepResult[];
                    const callId = (tc as { toolCallId?: string }).toolCallId;
                    const tr = results.find((r) => r?.toolCallId !== undefined && r.toolCallId === callId) ?? results[i];
                    const out = (tr?.output ?? tr?.result) as { type?: string; value?: unknown } | string | undefined;
                    const text = typeof out === 'string' ? out : typeof out?.value === 'string' ? out.value : JSON.stringify(out ?? '');
                    const failed = (typeof out === 'object' && (out?.type === 'error-text' || out?.type === 'error-json')) || isFailedToolResult(text);
                    this.actions.push({ tool: toolName, input: tc.input, ok: tr !== undefined && !failed });
                  }

                  if (['write_file', 'edit_file', 'create_file', 'delete_file'].includes(toolName)) {
                    const filePath = (tc.input as any)?.path || (tc.input as any)?.filePath;
                    if (filePath) {
                      const acquired = this.fileLockManager.acquire(filePath, this.config.id, 'write');
                      if (!acquired) {
                        this.filesModified.push(filePath);
                      }
                    }
                  }

                  if (['read_file', 'list_dir'].includes(toolName)) {
                    const filePath = (tc.input as any)?.path || (tc.input as any)?.filePath;
                    if (filePath) {
                      this.fileLockManager.acquire(filePath, this.config.id, 'read');
                    }
                  }
                }

                if (this.onProgress) {
                  this.onProgress(this.config.id, `Using: ${names}`);
                }
              }
            },
          });

          lastResult = result;

          // Stream integrity: generateText can resolve with finishReason
          // 'other' when the provider dropped the connection mid-generation
          // (no terminal chunk). Treat as a failure so the sub-agent reports
          // honestly instead of completing with truncated/empty output.
          const completion = classifyStreamCompletion({
            finishReason: (result as any)?.finishReason,
            hasText: Boolean(result?.text),
            hasToolCalls: true,
          });
          if (completion === 'interrupted') {
            logger.warn({ agentId: this.config.id, finishReason: (result as any)?.finishReason }, 'Sub-agent generation ended without a provider finish signal');
            throw new Error('Generation was interrupted before completion (no finish signal from provider)');
          }

          // Append the assistant response to the conversation history
          if (result.text) {
            messages.push({ role: 'assistant', content: result.text });

            // If this was a response to user comments, post the reply as an agent comment
            if (this.onPostComment && this.lastSeenCommentTimestamp > 0) {
              const replyText = result.text.trim();
              if (replyText.length > 0 && replyText !== '(no text response)') {
                this.onPostComment(this.config.id, replyText.length > 500 ? replyText.slice(0, 500) + '...' : replyText);
              }
            }
          }

          // Check for new user comments on this card
          if (this.onCheckComments && !this.abortController.signal.aborted && stepsRemaining > 0) {
            const newComments = this.onCheckComments(this.config.id)
              .filter(c => c.timestamp > this.lastSeenCommentTimestamp);

            if (newComments.length > 0) {
              this.lastSeenCommentTimestamp = Math.max(...newComments.map(c => c.timestamp));
              const commentText = newComments
                .map(c => `[${c.author}]: ${c.content}`)
                .join('\n');

              logger.info({ agentId: this.config.id, count: newComments.length }, 'Sub-agent received new comments');

              messages.push({
                role: 'user',
                content: `The admin has left new comments on your task card. Please read, reflect, and adjust your approach if needed. Then reply with your thoughts and continue working.\n\n${commentText}`,
              });

              if (this.onProgress) {
                this.onProgress(this.config.id, `Reviewing ${newComments.length} new comment${newComments.length > 1 ? 's' : ''}...`);
              }

              // Continue the loop — generateText will be called again with the comments
              continue;
            }
          }

          // No new comments — we're done
          break;
        }

        const result = lastResult;

        if (this.abortController.signal.aborted) {
          this.status = 'halted';
          const duration = Date.now() - this.startTime;
          this.result = {
            agentId: this.config.id,
            task: this.config.task,
            status: 'halted',
            output: 'Task was halted by user.',
            filesModified: this.filesModified,
            duration,
            tokenUsage: {
              input: result?.usage?.inputTokens ?? this.totalInputTokens,
              output: result?.usage?.outputTokens ?? this.totalOutputTokens,
            },
          };

          this.taskBoard.update(this.config.id, {
            status: 'halted',
            completedAt: Date.now(),
            result: this.result.output,
          });

          return this.result;
        }

        // Completion contract: the loop exited because the step budget ran
        // out while the last round still had tool calls pending. That is a
        // pause, never a completion — the supervisor resumes with a fresh
        // budget; reporting 'completed' here shipped half-done work behind a
        // success status.
        if (stepsRemaining <= 0 && (result as any)?.finishReason === 'tool-calls') {
          this.status = 'paused';
          const duration = Date.now() - this.startTime;
          this.result = {
            agentId: this.config.id,
            task: this.config.task,
            status: 'paused',
            output: 'Step budget reached before the task completed — work so far is preserved; resuming with a fresh budget.',
            filesModified: this.filesModified,
            duration,
            tokenUsage: {
              input: this.totalInputTokens,
              output: this.totalOutputTokens,
            },
          };
          this.taskBoard.update(this.config.id, {
            status: 'paused',
            completedAt: Date.now(),
            progress: 'Step budget reached — resuming',
          });
          logger.info({ agentId: this.config.id, duration }, 'Sub-agent paused at step budget (completion contract)');
          return this.result;
        }

        // Ended on tool calls without a word: report what it did instead.
        const finalText = (result?.text || '').trim() || summarizeSilentTurn(this.actions);

        this.tokenBudget.recordUsage({
          provider: provider.name,
          model: provider.getModel(),
          inputTokens: this.totalInputTokens,
          outputTokens: this.totalOutputTokens,
          totalTokens: this.totalInputTokens + this.totalOutputTokens,
          channelType: 'internal',
        });

        this.episodic.record({
          type: 'message',
          summary: `Sub-agent ${this.config.id}: ${this.config.task.slice(0, 60)} → ${finalText.slice(0, 60)}`,
          channelType: 'internal',
        });

        this.status = 'completed';
        const duration = Date.now() - this.startTime;
        this.result = {
          agentId: this.config.id,
          task: this.config.task,
          status: 'completed',
          output: finalText,
          filesModified: this.filesModified,
          duration,
          tokenUsage: {
            input: this.totalInputTokens,
            output: this.totalOutputTokens,
          },
        };

        this.taskBoard.update(this.config.id, {
          status: 'completed',
          completedAt: Date.now(),
          result: finalText,
          progress: 'Task completed',
        });

        logger.info({ agentId: this.config.id, duration }, 'Sub-agent completed');

        return this.result;
      } finally {
        if (this.config.workingDirectory) {
          this.capabilities.setCwd(originalCwd);
        }
        this.capabilities.permissions.clearElevation();
        this.fileLockManager.releaseAll(this.config.id);
      }
    } catch (err: any) {
      if (this.abortController.signal.aborted) {
        this.status = 'halted';
        const duration = Date.now() - this.startTime;
        this.result = {
          agentId: this.config.id,
          task: this.config.task,
          status: 'halted',
          output: 'Task was halted by user.',
          filesModified: this.filesModified,
          duration,
          tokenUsage: { input: 0, output: 0 },
        };

        this.taskBoard.update(this.config.id, {
          status: 'halted',
          completedAt: Date.now(),
          result: this.result.output,
        });

        return this.result;
      }

      this.status = 'failed';
      const duration = Date.now() - this.startTime;
      this.result = {
        agentId: this.config.id,
        task: this.config.task,
        status: 'failed',
        output: `Task failed: ${err.message}`,
        error: err.message,
        filesModified: this.filesModified,
        duration,
        tokenUsage: { input: 0, output: 0 },
      };

      this.taskBoard.update(this.config.id, {
        status: 'failed',
        completedAt: Date.now(),
        result: this.result.output,
        error: err.message,
      });

      logger.error({ agentId: this.config.id, err }, 'Sub-agent failed');

      return this.result;
    }
  }

  /**
   * Tools handed to the model. `allowedTools` is a real runtime restriction:
   * when set, the child never sees tools outside the list. The orchestration
   * tools (delegate_task, list_agents, stop_agent) are stripped unless the
   * parent granted them by name, and a granted one is re-bound to THIS
   * agent's id so the supervisor confines it to this agent's descendants —
   * the shared registry instance carries the main agent's authority (#74).
   */
  private resolveTools() {
    let tools = resolveChildTools(this.capabilities.getTools(), this.config.allowedTools);
    // The context's allowlist is the parent's ∩ this agent's: a grandchild
    // can never be granted a tool its parent did not have.
    const ctxTools = this.getPermissionContext()?.allowedTools;
    if (ctxTools) tools = filterToolsByAllowlist(tools, ctxTools);
    const ctxAllows = (name: string) => !ctxTools || ctxTools.includes(name);
    if (this.supervisor) {
      const scoped = { callerId: this.config.id };
      if (childMayUse('delegate_task', this.config.allowedTools) && ctxAllows('delegate_task')) {
        tools.delegate_task = createDelegateTaskTool(this.supervisor, this.capabilities, scoped);
      }
      if (childMayUse('list_agents', this.config.allowedTools) && ctxAllows('list_agents')) {
        tools.list_agents = createListAgentsTool(this.supervisor, scoped);
      }
      if (childMayUse('stop_agent', this.config.allowedTools) && ctxAllows('stop_agent')) {
        tools.stop_agent = createStopAgentTool(this.supervisor, scoped);
      }
    }
    return tools;
  }

  /** Names of the tools this agent actually receives. */
  getToolNames(): string[] {
    return Object.keys(this.resolveTools());
  }

  private buildSystemPrompt(): string {
    let prompt = this.identity.getSystemPrompt(this.agentConfig.identity);

    prompt += `\n\nYou are a sub-agent (ID: ${this.config.id}) working independently on a specific task.`;
    prompt += `\nTask: ${this.config.task}`;
    prompt += `\n${this.describePermissions()}`;
    prompt += `\nFocus only on completing this task efficiently.`;
    if (this.config.workingDirectory) {
      prompt += `\nWorking directory: ${this.config.workingDirectory}`;
    }
    if (this.config.allowedTools && this.config.allowedTools.length > 0) {
      prompt += `\nAllowed tools: ${this.config.allowedTools.join(', ')}`;
    }
    prompt += `\nWhen done, provide a clear summary of what you accomplished.`;

    const budgetStatus = this.tokenBudget.getStatusText();
    prompt += '\n\n' + budgetStatus;
    if (this.tokenBudget.getUsagePercentage() > 70) {
      prompt += '\nBe concise to conserve tokens.';
    }
    const saverSuffix = this.saverMode?.getSystemPromptSuffix() ?? '';
    if (saverSuffix) {
      prompt += saverSuffix;
    }

    prompt += `\n\nEnvironment:\n- Platform: ${process.platform}\n- Working directory: ${this.capabilities.getCwd()}`;

    prompt += `\n\nAvailable tools: ${this.getToolNames().join(', ')}`;

    return prompt;
  }

  /**
   * An accurate statement of what this agent may do: it runs under the same
   * permission state as the agent that delegated it — the same approved
   * scopes, the same shell approval prompt — never with elevated rights.
   */
  private describePermissions(): string {
    const permissions = this.capabilities.permissions;
    const readable: string[] = [];
    const writable: string[] = [];
    for (const scope of [...permissions.getManifest().capabilities.filesystem.scopes, ...(this.getPermissionContext()?.scopes ?? [])]) {
      if (scope.write) writable.push(scope.path);
      else if (scope.read) readable.push(scope.path);
    }
    const parts: string[] = [];
    parts.push('You run with the same permissions as the agent that delegated you, not more.');
    const ctx = this.getPermissionContext();
    if (ctx ? ctx.autoApprove : permissions.isAutoApproveAll()) {
      parts.push('This session is in Allow All mode, so approved-scope actions run without prompts.');
    } else {
      parts.push('File writes and non-read-only shell commands go to the user for approval (reads inside approved scopes do not); a denial is final — do not retry it or work around it.');
    }
    if (writable.length > 0) parts.push(`Writable scopes: ${writable.join(', ')}.`);
    if (readable.length > 0) parts.push(`Read-only scopes: ${readable.join(', ')}.`);
    parts.push('Use approve_scope to request a path outside these scopes.');
    if (this.config.allowedTools?.some(t => ['delegate_task', 'list_agents', 'stop_agent'].includes(t))) {
      parts.push('Your delegate_task/list_agents/stop_agent only reach agents you delegated yourself.');
    }
    return parts.join(' ');
  }
}