@inkeep/agents-run-api 0.39.5 → 0.41.0

package/dist/tools/distill-conversation-tool.js

@@ -0,0 +1,141 @@
+import { getLogger } from "../logger.js";
+import { ModelFactory } from "@inkeep/agents-core";
+import { Output, generateText } from "ai";
+import { z } from "zod";
+
+//#region src/tools/distill-conversation-tool.ts
+const logger = getLogger("distill-conversation-tool");
+/**
+* Conversation Summary Schema - structured object for maintaining conversation context
+*/
+const ConversationSummarySchema = z.object({
+	type: z.literal("conversation_summary_v1"),
+	session_id: z.string().nullable().optional(),
+	high_level: z.string().describe("1-3 sentences capturing what was discovered and learned"),
+	user_intent: z.string().describe("Current main goal or what the user wants to accomplish"),
+	decisions: z.array(z.string()).describe("Concrete decisions made about approach or implementation (≤5 items)"),
+	open_questions: z.array(z.string()).describe("Unresolved questions about the subject matter (≤5 items)"),
+	next_steps: z.object({
+		for_agent: z.array(z.string()).describe("Content-focused actions: what to discover, analyze, or present. Don't get trapped in an infinite loop of tool calls. You have already done a lot of work that is why you are being compressed. Don't encourage too much more work."),
+		for_user: z.array(z.string()).describe("Actions for user based on discovered content")
+	}),
+	related_artifacts: z.array(z.object({
+		id: z.string().describe("Artifact ID"),
+		name: z.string().describe("Human-readable name describing the content"),
+		tool_name: z.string().describe("Tool that generated this artifact (e.g. search-inkeep-docs)"),
+		tool_call_id: z.string().describe("Specific tool call ID for precise referencing"),
+		content_type: z.string().describe("Type of content (e.g. search_results, api_response, documentation)"),
+		key_findings: z.array(z.string()).describe("2-3 most important findings from this specific artifact")
+	})).optional().describe("Artifacts containing detailed findings with citation info")
+});
+/**
+* Core conversation distillation - takes messages and creates structured summary
+*/
+async function distillConversation(params) {
+	const { messages, conversationId, currentSummary, summarizerModel, toolCallToArtifactMap } = params;
+	try {
+		const modelToUse = summarizerModel;
+		if (!modelToUse?.model?.trim()) throw new Error("Summarizer model is required");
+		const { output: summary } = await generateText({
+			model: ModelFactory.createModel(modelToUse),
+			prompt: `You are a conversation summarization assistant. Your job is to create or update a compact, structured summary that captures VALUABLE CONTENT and FINDINGS, not just operational details.
+
+${currentSummary ? `**Current summary:**\n\n\`\`\`json\n${JSON.stringify(currentSummary, null, 2)}\n\`\`\`` : "**Current summary:** None (first distillation)"}
+
+**Messages to summarize:**
+
+\`\`\`text
+${messages.map((msg) => {
+				const parts = [];
+				if (typeof msg.content === "string") parts.push(msg.content);
+				else if (Array.isArray(msg.content)) {
+					for (const block of msg.content) if (block.type === "text") parts.push(block.text);
+					else if (block.type === "tool-call") parts.push(`[TOOL CALL] ${block.toolName}(${JSON.stringify(block.input)}) [ID: ${block.toolCallId}]`);
+					else if (block.type === "tool-result") {
+						const artifactId = toolCallToArtifactMap?.[block.toolCallId];
+						const artifactInfo = artifactId ? `\n[ARTIFACT CREATED: ${artifactId}]` : "";
+						parts.push(`[TOOL RESULT] ${block.toolName} [ID: ${block.toolCallId}]${artifactInfo}\nResult: ${JSON.stringify(block.output)}`);
+					}
+				} else if (msg.content?.text) parts.push(msg.content.text);
+				return parts.length > 0 ? `${msg.role || "system"}: ${parts.join("\n")}` : "";
+			}).filter((line) => line.trim().length > 0).join("\n\n")}
+\`\`\`
+
+Create/update a summary using this exact JSON schema:
+
+\`\`\`json
+{
+  "type": "conversation_summary_v1",
+  "session_id": "<conversationId>",
+  "high_level": "<1–3 sentences capturing what was discovered and learned>",
+  "user_intent": "<current main goal>",
+  "decisions": ["<concrete decisions made>"],
+  "open_questions": ["<unresolved issues>"],
+  "next_steps": {
+    "for_agent": ["<what agent should do>"],
+    "for_user": ["<what user should do>"]
+  },
+  "related_artifacts": [
+    {
+      "id": "<artifact_id>",
+      "name": "<descriptive name>",
+      "tool_name": "<tool_name>",
+      "tool_call_id": "<tool_call_id>",
+      "content_type": "<search_results|api_response|documentation>",
+      "key_findings": ["<important finding 1>", "<important finding 2>"]
+    }
+  ]
+}
+\`\`\`
+
+**CRITICAL RULES - FOCUS ON CONTENT NOT OPERATIONS:**
+🎯 **EXTRACT VALUABLE FINDINGS**: Capture the actual information discovered, data retrieved, insights gained
+🎯 **IGNORE OPERATIONAL DETAILS**: Don't mention "tool was used", "artifact was created", "messages were compressed"
+🎯 **PRESERVE SUBSTANCE**: Include specific facts, features, capabilities, configurations, results found
+🎯 **BUILD KNOWLEDGE**: When updating existing summary, ADD new discoveries to existing knowledge
+🎯 **BE CONCRETE**: Use specific details from tool results, not generic descriptions
+🎯 **BE CONCISE**: Keep ALL fields brief - you are compressing to save context, not writing a report
+🎯 **LIMIT NEXT STEPS**: Agent has already done substantial work - suggest minimal follow-up actions only
+🎯 **HANDLE TRANSFERS SIMPLY**: Agent transfers/delegations are just routing - don't look for reasons or justifications. Simply note "conversation transferred to [specialist]" if relevant.
+
+**Examples:**
+❌ BAD: "Assistant used search tool and created artifacts"
+✅ GOOD: "Inkeep supports streaming structured objects, OpenAI-compatible APIs, analytics logging, and Zendesk integration"
+
+❌ BAD: "Tool calls were made to gather information"  
+✅ GOOD: "Platform includes 10 feature categories: chat widgets, knowledge base, analytics, integrations, theming options"
+
+❌ BAD: "Assistant needed to transfer to QA because user required specialized testing help"
+✅ GOOD: "Conversation transferred to QA specialist"
+
+**Focus on WHAT WAS LEARNED, not HOW IT WAS LEARNED**
+
+Return **only** valid JSON.`,
+			output: Output.object({ schema: ConversationSummarySchema })
+		});
+		summary.session_id = conversationId;
+		return summary;
+	} catch (error) {
+		logger.error({
+			conversationId,
+			messageCount: messages.length,
+			error: error instanceof Error ? error.message : "Unknown error"
+		}, "Failed to distill conversation");
+		return {
+			type: "conversation_summary_v1",
+			session_id: conversationId,
+			high_level: "Ongoing conversation session",
+			user_intent: "Continue working on current task",
+			related_artifacts: [],
+			decisions: [],
+			open_questions: ["Review recent work and determine next steps"],
+			next_steps: {
+				for_agent: ["Continue with current task"],
+				for_user: ["Provide additional guidance if needed"]
+			}
+		};
+	}
+}
+
+//#endregion
+export { ConversationSummarySchema, distillConversation };

package/dist/tools/sandbox-utils.d.ts

@@ -0,0 +1,18 @@
+//#region src/tools/sandbox-utils.d.ts
+/**
+ * Shared utilities for sandbox executors
+ */
+/**
+ * Create an execution wrapper that handles input/output for function tools
+ * This is used by both Native and Vercel sandbox executors
+ */
+declare function createExecutionWrapper(executeCode: string, args: Record<string, unknown>): string;
+/**
+ * Parse execution result from stdout
+ * Returns the parsed result or the raw stdout if parsing fails
+ */
+declare function parseExecutionResult(stdout: string, functionId: string, logger?: {
+  warn: (obj: unknown, msg: string) => void;
+}): unknown;
+//#endregion
+export { createExecutionWrapper, parseExecutionResult };

package/dist/tools/sandbox-utils.js

@@ -0,0 +1,53 @@
+//#region src/tools/sandbox-utils.ts
+/**
+* Shared utilities for sandbox executors
+*/
+/**
+* Create an execution wrapper that handles input/output for function tools
+* This is used by both Native and Vercel sandbox executors
+*/
+function createExecutionWrapper(executeCode, args) {
+	return `
+// Function tool execution wrapper
+const args = ${JSON.stringify(args, null, 2)};
+
+// User's function code
+const execute = ${executeCode}
+
+// Execute the function and output the result
+(async () => {
+  try {
+    const result = await execute(args);
+    // Output result as JSON on the last line
+    console.log(JSON.stringify({ success: true, result }));
+  } catch (error) {
+    console.error(JSON.stringify({ 
+      success: false, 
+      error: error instanceof Error ? error.message : String(error) 
+    }));
+    process.exit(1);
+  }
+})();
+`;
+}
+/**
+* Parse execution result from stdout
+* Returns the parsed result or the raw stdout if parsing fails
+*/
+function parseExecutionResult(stdout, functionId, logger) {
+	try {
+		const outputLines = stdout.split("\n").filter((line) => line.trim());
+		const resultLine = outputLines[outputLines.length - 1];
+		return JSON.parse(resultLine);
+	} catch (parseError) {
+		if (logger) logger.warn({
+			functionId,
+			stdout,
+			parseError
+		}, "Failed to parse execution result");
+		return stdout;
+	}
+}
+
+//#endregion
+export { createExecutionWrapper, parseExecutionResult };

package/dist/types/chat.d.ts

@@ -0,0 +1,27 @@
+//#region src/types/chat.d.ts
+type ContentItem = {
+  type: string;
+  text?: string;
+};
+type Message = {
+  role: 'system' | 'user' | 'assistant' | 'function' | 'tool';
+  content: string | ContentItem[];
+  name?: string;
+};
+type ChatCompletionRequest = {
+  model: string;
+  messages: Message[];
+  temperature?: number;
+  top_p?: number;
+  n?: number;
+  stream?: boolean;
+  max_tokens?: number;
+  presence_penalty?: number;
+  frequency_penalty?: number;
+  logit_bias?: Record<string, number>;
+  user?: string;
+  tools?: Record<string, unknown>;
+  runConfig?: Record<string, unknown>;
+};
+//#endregion
+export { ChatCompletionRequest, ContentItem, Message };

package/dist/types/chat.js

@@ -0,0 +1 @@
+export {  };

package/dist/types/execution-context.d.ts

@@ -0,0 +1,46 @@
+import { ExecutionContext } from "@inkeep/agents-core";
+
+//#region src/types/execution-context.d.ts
+
+/**
+ * Extract userId from execution context metadata (when available)
+ * Only available when request originates from an authenticated user session (e.g., playground)
+ */
+declare function getUserIdFromContext(ctx: ExecutionContext): string | undefined;
+/**
+ * Create execution context from middleware values
+ */
+declare function createExecutionContext(params: {
+  apiKey: string;
+  tenantId: string;
+  projectId: string;
+  agentId: string;
+  apiKeyId: string;
+  subAgentId?: string;
+  baseUrl?: string;
+  metadata?: {
+    teamDelegation?: boolean;
+    originAgentId?: string;
+    initiatedBy?: {
+      type: 'user' | 'api_key';
+      id: string;
+    };
+  };
+}): ExecutionContext;
+interface CommonSandboxConfig {
+  runtime: 'node22' | 'typescript';
+  timeout?: number;
+  vcpus?: number;
+}
+interface NativeSandboxConfig extends CommonSandboxConfig {
+  provider: 'native';
+}
+interface VercelSandboxConfig extends CommonSandboxConfig {
+  provider: 'vercel';
+  teamId: string;
+  projectId: string;
+  token: string;
+}
+type SandboxConfig = NativeSandboxConfig | VercelSandboxConfig;
+//#endregion
+export { NativeSandboxConfig, SandboxConfig, VercelSandboxConfig, createExecutionContext, getUserIdFromContext };

package/dist/types/execution-context.js

@@ -0,0 +1,27 @@
+//#region src/types/execution-context.ts
+/**
+* Extract userId from execution context metadata (when available)
+* Only available when request originates from an authenticated user session (e.g., playground)
+*/
+function getUserIdFromContext(ctx) {
+	const metadata = ctx.metadata;
+	return metadata?.initiatedBy?.type === "user" ? metadata.initiatedBy.id : void 0;
+}
+/**
+* Create execution context from middleware values
+*/
+function createExecutionContext(params) {
+	return {
+		apiKey: params.apiKey,
+		tenantId: params.tenantId,
+		projectId: params.projectId,
+		agentId: params.agentId,
+		baseUrl: params.baseUrl || process.env.API_URL || "http://localhost:3003",
+		apiKeyId: params.apiKeyId,
+		subAgentId: params.subAgentId,
+		metadata: params.metadata || {}
+	};
+}
+
+//#endregion
+export { createExecutionContext, getUserIdFromContext };

package/dist/types/xml.d.ts

@@ -0,0 +1,5 @@
+//#region src/types/xml.d.ts
+declare module '*.xml?raw' {
+  const content: string;
+  export default content;
+}

package/dist/utils/SchemaProcessor.d.ts

@@ -0,0 +1,52 @@
+//#region src/utils/SchemaProcessor.d.ts
+interface SchemaValidationResult {
+  isValid: boolean;
+  errors: string[];
+  transformedSchema?: any;
+}
+interface JMESPathValidationResult {
+  isLiteral: boolean;
+  isValidSelector: boolean;
+  suggestions?: string[];
+}
+/**
+ * Centralized schema processing and validation utilities
+ */
+declare class SchemaProcessor {
+  private static logger;
+  /**
+   * Transform complex schema types to strings for JMESPath compatibility
+   */
+  static transformSchemaForJMESPath(schema: any): any;
+  /**
+   * Validate if a selector looks like a valid JMESPath expression
+   */
+  static validateJMESPathSelector(selector: string): JMESPathValidationResult;
+  /**
+   * Check if a selector looks like a JMESPath expression
+   */
+  private static looksLikeJMESPath;
+  /**
+   * Check if a selector appears to be a literal value rather than a JMESPath expression
+   */
+  private static isLiteralValue;
+  /**
+   * Safely extract data using JMESPath with validation
+   */
+  static safeJMESPathSearch(data: any, selector: string, fallback?: any): any;
+  /**
+   * Validate schema structure for artifact components
+   */
+  static validateArtifactSchema(schema: any): SchemaValidationResult;
+  /**
+   * Extract property value with proper type conversion and validation
+   */
+  static extractPropertyValue(data: any, _propName: string, selector: string, expectedType?: string): any;
+  /**
+   * Enhance schema with JMESPath guidance for artifact component schemas
+   * Transforms all schema types to string selectors with helpful descriptions
+   */
+  static enhanceSchemaWithJMESPathGuidance(schema: Record<string, unknown> | null | undefined): Record<string, unknown>;
+}
+//#endregion
+export { JMESPathValidationResult, SchemaProcessor, SchemaValidationResult };

package/dist/utils/SchemaProcessor.js

@@ -0,0 +1,182 @@
+import { getLogger } from "../logger.js";
+import jmespath from "jmespath";
+
+//#region src/utils/SchemaProcessor.ts
+/**
+* Centralized schema processing and validation utilities
+*/
+var SchemaProcessor = class SchemaProcessor {
+	static logger = getLogger("SchemaProcessor");
+	/**
+	* Transform complex schema types to strings for JMESPath compatibility
+	*/
+	static transformSchemaForJMESPath(schema) {
+		if (!schema || typeof schema !== "object") return schema;
+		const transform = (obj) => {
+			if (Array.isArray(obj)) return obj.map(transform);
+			if (obj && typeof obj === "object") {
+				const result = {};
+				for (const [key, value] of Object.entries(obj)) if (key === "type" && typeof value === "string") result[key] = value === "string" ? "string" : "string";
+				else result[key] = transform(value);
+				return result;
+			}
+			return obj;
+		};
+		return transform(schema);
+	}
+	/**
+	* Validate if a selector looks like a valid JMESPath expression
+	*/
+	static validateJMESPathSelector(selector) {
+		if (SchemaProcessor.isLiteralValue(selector)) return {
+			isLiteral: true,
+			isValidSelector: false
+		};
+		if (SchemaProcessor.looksLikeJMESPath(selector)) return {
+			isLiteral: false,
+			isValidSelector: true
+		};
+		return {
+			isLiteral: false,
+			isValidSelector: false
+		};
+	}
+	/**
+	* Check if a selector looks like a JMESPath expression
+	*/
+	static looksLikeJMESPath(selector) {
+		if (/^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$/.test(selector)) return true;
+		if (/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$/.test(selector)) return true;
+		if (/\[\d+\]/.test(selector) || /\[\*\]/.test(selector)) return true;
+		if (/\[.*?\]/.test(selector) && /[=<>!]/.test(selector)) return true;
+		if (selector.includes("|")) return true;
+		return false;
+	}
+	/**
+	* Check if a selector appears to be a literal value rather than a JMESPath expression
+	*/
+	static isLiteralValue(selector) {
+		if (SchemaProcessor.looksLikeJMESPath(selector)) return false;
+		if (/^https?:\/\//.test(selector)) return true;
+		if (/^[0-9]+$/.test(selector)) return true;
+		if (selector.includes(" ") && !selector.includes("[")) return true;
+		if (/^[a-zA-Z0-9\s\-_,;:!?.'"+()]+$/.test(selector) && selector.length > 20) return true;
+		return false;
+	}
+	/**
+	* Safely extract data using JMESPath with validation
+	*/
+	static safeJMESPathSearch(data, selector, fallback = null) {
+		try {
+			const validation = SchemaProcessor.validateJMESPathSelector(selector);
+			if (validation.isLiteral) {
+				SchemaProcessor.logger.debug({ selector }, "Selector appears to be literal value, returning as-is");
+				return selector;
+			}
+			if (!validation.isValidSelector) {
+				SchemaProcessor.logger.warn({ selector }, "Selector does not appear to be valid JMESPath");
+				return fallback;
+			}
+			return jmespath.search(data, selector) || fallback;
+		} catch (error) {
+			SchemaProcessor.logger.warn({
+				selector,
+				error: error instanceof Error ? error.message : String(error)
+			}, "JMESPath search failed");
+			return fallback;
+		}
+	}
+	/**
+	* Validate schema structure for artifact components
+	*/
+	static validateArtifactSchema(schema) {
+		const errors = [];
+		if (!schema || typeof schema !== "object") {
+			errors.push("Schema must be an object");
+			return {
+				isValid: false,
+				errors
+			};
+		}
+		if (!schema.type || schema.type !== "object") errors.push("Schema must have type \"object\"");
+		if (!schema.properties || typeof schema.properties !== "object") errors.push("Schema must have properties object");
+		const transformedSchema = SchemaProcessor.transformSchemaForJMESPath(schema);
+		return {
+			isValid: errors.length === 0,
+			errors,
+			transformedSchema
+		};
+	}
+	/**
+	* Extract property value with proper type conversion and validation
+	*/
+	static extractPropertyValue(data, _propName, selector, expectedType) {
+		const value = SchemaProcessor.safeJMESPathSearch(data, selector);
+		if (value === null || value === void 0) return null;
+		if (expectedType) switch (expectedType) {
+			case "string": return String(value);
+			case "number": {
+				const num = Number(value);
+				return Number.isNaN(num) ? null : num;
+			}
+			case "boolean": return Boolean(value);
+			case "array": return Array.isArray(value) ? value : [value];
+			default: return value;
+		}
+		return value;
+	}
+	/**
+	* Enhance schema with JMESPath guidance for artifact component schemas
+	* Transforms all schema types to string selectors with helpful descriptions
+	*/
+	static enhanceSchemaWithJMESPathGuidance(schema) {
+		if (!schema || typeof schema !== "object") return schema || {};
+		const transformToSelectorSchema = (obj, path = "") => {
+			if (!obj || typeof obj !== "object") return obj;
+			if (obj.type === "array") {
+				obj.items?.description;
+				const arrayDescription = obj.description || "array data";
+				path.includes("content");
+				return {
+					type: "string",
+					description: `🎯 ARRAY SELECTOR: Provide JMESPath selector for ${arrayDescription}. RELATIVE to base selector - this will be applied to the item selected by base_selector. Example: "content.blocks" or "items" (NOT absolute paths like "result.content.blocks")`
+				};
+			}
+			if (obj.type === "object" && !obj.properties) return {
+				type: "string",
+				description: `🎯 OBJECT SELECTOR: Provide JMESPath selector for ${obj.description || "object data"}. RELATIVE to base selector - this will be applied to the item selected by base_selector. Example: "metadata" or "spec.details" (NOT absolute paths)`
+			};
+			if (obj.type === "object" && obj.properties) {
+				const transformedProperties = {};
+				Object.entries(obj.properties).forEach(([propertyName, property]) => {
+					transformedProperties[propertyName] = transformToSelectorSchema(property, path ? `${path}.${propertyName}` : propertyName);
+				});
+				return {
+					type: "object",
+					properties: transformedProperties,
+					required: obj.required || [],
+					description: `${obj.description || "Object containing JMESPath selectors"} - Each property should be a selector RELATIVE to the base_selector`
+				};
+			}
+			if ([
+				"string",
+				"number",
+				"boolean"
+			].includes(obj.type)) {
+				const originalDescription = obj.description || `${obj.type} value`;
+				return {
+					type: "string",
+					description: `🎯 FIELD SELECTOR: Provide JMESPath selector for ${originalDescription}. RELATIVE to base selector (e.g., "title", "metadata.category", "properties.value"). For nested data: use field paths like "content.details", "attributes.data", "specifications.info". NOT absolute paths and NOT literal values like "${originalDescription}". The base_selector finds the item, this selector extracts the field FROM that item.`
+				};
+			}
+			return {
+				type: "string",
+				description: `🎯 SELECTOR: Provide JMESPath selector RELATIVE to base selector. Example: "fieldName" or "nested.path" (NOT absolute paths)`
+			};
+		};
+		return transformToSelectorSchema(schema);
+	}
+};
+
+//#endregion
+export { SchemaProcessor };

package/dist/utils/agent-operations.d.ts

@@ -0,0 +1,62 @@
+import { DataOperationEvent } from "@inkeep/agents-core";
+
+//#region src/utils/agent-operations.d.ts
+
+/**
+ * Agent initialization operation event
+ */
+interface AgentInitializingEvent {
+  type: 'agent_initializing';
+  details: {
+    sessionId: string;
+    agentId: string;
+  };
+}
+/**
+ * Completion operation event
+ */
+interface CompletionEvent {
+  type: 'completion';
+  details: {
+    agent: string;
+    iteration: number;
+  };
+}
+/**
+ * Unified error event structure
+ * Can be used for both operational errors (with agent context) and general stream errors
+ */
+interface ErrorEvent {
+  type: 'error';
+  message: string;
+  agent?: string;
+  severity?: 'error' | 'warning' | 'info';
+  code?: string;
+  timestamp?: number;
+}
+/**
+ * Discriminated union of all operation events
+ */
+type OperationEvent = AgentInitializingEvent | CompletionEvent | ErrorEvent | DataOperationEvent;
+/**
+ * Creates an agent initializing operation
+ */
+declare function agentInitializingOp(sessionId: string, agentId: string): AgentInitializingEvent;
+/**
+ * Creates a completion operation
+ */
+declare function completionOp(subAgentId: string, iterations: number): CompletionEvent;
+/**
+ * Creates a unified error event
+ * @param message - Error message
+ * @param subAgentId - Optional agent ID for context
+ * @param severity - Error severity level
+ * @param code - Optional error code
+ */
+declare function errorOp(message: string, subAgentId?: string, severity?: 'error' | 'warning' | 'info', code?: string): ErrorEvent;
+/**
+ * Generate a unique tool execution ID for lifecycle tracking
+ */
+declare function generateToolId(): string;
+//#endregion
+export { AgentInitializingEvent, CompletionEvent, ErrorEvent, OperationEvent, agentInitializingOp, completionOp, errorOp, generateToolId };

package/dist/utils/agent-operations.js

@@ -0,0 +1,53 @@
+import { generateId } from "@inkeep/agents-core";
+
+//#region src/utils/agent-operations.ts
+/**
+* Creates an agent initializing operation
+*/
+function agentInitializingOp(sessionId, agentId) {
+	return {
+		type: "agent_initializing",
+		details: {
+			sessionId,
+			agentId
+		}
+	};
+}
+/**
+* Creates a completion operation
+*/
+function completionOp(subAgentId, iterations) {
+	return {
+		type: "completion",
+		details: {
+			agent: subAgentId,
+			iteration: iterations
+		}
+	};
+}
+/**
+* Creates a unified error event
+* @param message - Error message
+* @param subAgentId - Optional agent ID for context
+* @param severity - Error severity level
+* @param code - Optional error code
+*/
+function errorOp(message, subAgentId, severity = "error", code) {
+	return {
+		type: "error",
+		message,
+		agent: subAgentId,
+		severity,
+		code,
+		timestamp: Date.now()
+	};
+}
+/**
+* Generate a unique tool execution ID for lifecycle tracking
+*/
+function generateToolId() {
+	return `tool_${generateId(8)}`;
+}
+
+//#endregion
+export { agentInitializingOp, completionOp, errorOp, generateToolId };