import type { Agent as RuntimeAgent, CheckpointStore, ExecutionOptions, JSONObject, ObservationLogObserverMemory, ResumeOptions, RunOptions, SideCallUsageReport, TokenUsage } from '@n8n/agents'; import type { User } from '@n8n/db'; import type { AgentTurnRequest } from '../agent-turn-execution.service'; import type { AgentExecutionThread } from '../entities/agent-execution-thread.entity'; import type { ToolRegistry } from '../tool-registry'; import type { StoredAttachmentRef } from '../types/agent-chat-attachment'; import type { AgentExecutionStreamChunk } from '../types/agent-steering'; import type { AgentTurnFinalizeOutcome, AgentTurnStatus, FormattedTurnError } from '../types/agent-turn-outcome'; import type { SystemAgentHostEventEmitter } from './system-agent-host-events'; export type { AgentExecutionStreamChunk, SteeredMessageEvent } from '../types/agent-steering'; export type SystemAgentTurnOptions = Record; export interface SystemAgentSessionGrants { load(): Promise>; grant(key: string): Promise; revoke(key: string): Promise; } interface SystemAgentTurnBase { user: User; thread: AgentExecutionThread; resourceId: string; abortSignal: AbortSignal; workspace?: TLease; memory: ObservationLogObserverMemory; checkpointStore: CheckpointStore; sessionGrants: SystemAgentSessionGrants; emitHostEvent: SystemAgentHostEventEmitter; readFile(fileId: string): Promise; } export interface SystemAgentFile { fileName: string; mimeType: string; sizeBytes: number; readContent(): Promise; } export interface SystemAgentStartTurn extends SystemAgentTurnBase { type: 'start'; executionId?: string; message: string; attachments: StoredAttachmentRef[]; readAttachment(ref: StoredAttachmentRef): Promise; options: SystemAgentTurnOptions; } export interface SystemAgentResumeTurn extends SystemAgentTurnBase, Pick { type: 'resume'; checkpointHostMetadata: JSONObject; resumeData: unknown; } export type SystemAgentTurn = SystemAgentStartTurn | SystemAgentResumeTurn; export type SystemAgentTurnOutcome = Omit & { executionId?: string; }; export interface SystemAgentTurnHandle { agent: RuntimeAgent; toolRegistry?: ToolRegistry; input?: Extract['input']; hostMetadata?: JSONObject; runOptions?: Omit & Partial, 'persistence' | 'onSideCallUsage'>; onChunk?: (chunk: AgentExecutionStreamChunk) => void; withTurnContext?: (run: () => Promise) => Promise; onSideCallUsage?: (report: SideCallUsageReport) => void | Promise; onSettled?: (outcome: SystemAgentTurnOutcome) => Promise; formatError?: (error: unknown) => Promise; } export interface SystemAgentWorkspaceScope { agentId: string; threadId: string; projectId: string; user: User; } export interface SystemAgentWorkspaceDestroyScope { agentId: string; threadId: string; userId?: string; } export interface SystemAgentWorkspaceSource { acquire(scope: SystemAgentWorkspaceScope): Promise; release?(scope: SystemAgentWorkspaceScope, lease: TLease, outcome: SystemAgentTurnOutcome): Promise; destroy?(scope: SystemAgentWorkspaceDestroyScope): Promise; } export interface SystemAgentProvider { readonly agentId: string; readonly name: string; readonly workspace?: SystemAgentWorkspaceSource; authorize(user: User, projectId: string): Promise; prepareTurn(turn: SystemAgentTurn): Promise; formatSetupError?(user: User, error: unknown): Promise; chatTurnOptions?(user: User, thread: AgentExecutionThread, clientContext?: Record): Promise; normalizeResumeData?(resumeData: unknown): unknown; onDelegatedRunUsage?(report: SystemAgentDelegatedRunUsageReport, scope: { thread: AgentExecutionThread; }): void | Promise; onDelegatedSideCallUsage?(report: SystemAgentDelegatedSideCallUsageReport, scope: { thread: AgentExecutionThread; }): void | Promise; } export interface SystemAgentDelegatedRunUsageReport { executionId: string; threadId: string; parentExecutionId: string; status: AgentTurnStatus; model: string | null; usage: TokenUsage; } export interface SystemAgentDelegatedSideCallUsageReport extends SideCallUsageReport { executionId: string; threadId: string; parentExecutionId: string; }