IModelMessage

Interface representing a model message within the swarm system. Encapsulates a single message exchanged between agents, tools, users, or the system, used extensively in agent workflows (e.g., ClientAgent) for history tracking, completion generation, and event emission. Messages are stored in history (e.g., via IHistory.push), generated by completions (e.g., ICompletion.getCompletion), and emitted via the bus (e.g., IBus.emit), serving as the core data structure for communication and state management.

Properties

role

role: "tool" | "user" | "assistant" | "system" | "resque" | "flush"
Copy

The role of the message sender, defining its origin or purpose in the conversation flow. Observed in ClientAgent usage:

• "assistant": Generated by the model (e.g., getCompletion output, commitAssistantMessage).
• "system": System-level notifications (e.g., commitSystemMessage).
• "tool": Tool outputs or tool-related messages (e.g., commitToolOutput, resurrection prompts).
• "user": User-initiated messages (e.g., commitUserMessage, EXECUTE_FN input).
• "resque": Error recovery messages during model resurrection (e.g., _resurrectModel).
• "flush": Markers for history resets (e.g., commitFlush).

agentName

agentName: string
Copy

The name of the agent associated with the message. Links the message to a specific agent instance (e.g., this.params.agentName in ClientAgent), ensuring context within multi-agent swarms. Used consistently in history pushes and bus events (e.g., context.agentName in IBus.emit).

content

content: string
Copy

The content of the message, representing the primary data or text being communicated. Examples from ClientAgent:

• User input (e.g., incoming in execute).
• Tool output (e.g., content in commitToolOutput).
• Model response (e.g., result from getCompletion).
• Error reasons or placeholders (e.g., _resurrectModel). May be empty (e.g., "" in flush messages) or trimmed for consistency.

mode

mode: ExecutionMode
Copy

The execution mode indicating the source or context of the message. Aligns with ExecutionMode ("user" or "tool") from Session.interface:

• "user": Messages from user input or stateless runs (e.g., commitUserMessage, RUN_FN).
• "tool": Messages from tool outputs or system actions (e.g., commitToolOutput, _resurrectModel). Drives processing logic, such as validation or tool call handling in ClientAgent.

tool_calls

tool_calls: IToolCall[]
Copy

Optional array of tool calls associated with the message, present when the model requests tool execution. Populated in getCompletion responses (e.g., ClientAgent EXECUTE_FN), mapped to IToolCall objects for execution. Example: { function: { name: "func", arguments: { key: "value" } }, id: "tool-id" }. Absent in user, system, or tool output messages unless explicitly triggered by the model.

images

images: string[] | Uint8Array[]
Copy

tool_call_id

tool_call_id: string
Copy

Optional identifier of the tool call this message responds to, linking tool outputs to their requests. Set in tool-related messages (e.g., commitToolOutput in ClientAgent) to correlate with a prior tool_calls entry. Example: tool_call_id: "tool-id" ties a tool’s output to its originating call. Undefined for non-tool-response messages (e.g., user input, assistant responses without tools).

payload

payload: Payload
Copy

Optional payload data attached to the message, providing additional context or metadata. Can be an object of any shape or null if no payload is needed; undefined if not present. Example: { image_id: <uuid> } when user send a message