@f5-sales-demo/pi-agent-core 21.25.0 → 21.27.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/pi-agent-core",
-	"version": "21.25.0",
+	"version": "21.27.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -35,8 +35,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@f5-sales-demo/pi-ai": "21.25.0",
-		"@f5-sales-demo/pi-utils": "21.25.0"
+		"@f5-sales-demo/pi-ai": "21.27.0",
+		"@f5-sales-demo/pi-utils": "21.27.0"
 	},
 	"devDependencies": {
 		"@sinclair/typebox": "0.34.52",

package/src/agent-loop.ts

@@ -12,6 +12,7 @@ import {
 } from "@f5-sales-demo/pi-ai";
 import { logger } from "@f5-sales-demo/pi-utils";
 import emptyToolSuccess from "./prompts/empty-tool-success.md" with { type: "text" };
+import { AgentToolError } from "./tool-error";
 import type {
 	AgentContext,
 	AgentEvent,
@@ -21,6 +22,7 @@ import type {
 	AgentToolResult,
 	StreamFn,
 } from "./types";
+import { getToolExecutionKind } from "./types";
 
 /**
  * Start an agent loop with a new prompt message.
@@ -224,7 +226,7 @@ async function runLoop(
 			}
 
 			// Stream assistant response
-			const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn);
+			const message = await streamAssistantResponse(currentContext, newMessages, config, signal, stream, streamFn);
 			newMessages.push(message);
 			let steeringMessagesFromExecution: AgentMessage[] | undefined;
 
@@ -300,6 +302,7 @@ async function runLoop(
  */
 async function streamAssistantResponse(
 	context: AgentContext,
+	newMessages: AgentMessage[],
 	config: AgentLoopConfig,
 	signal: AbortSignal | undefined,
 	stream: EventStream<AgentEvent, AgentMessage[]>,
@@ -310,6 +313,14 @@ async function streamAssistantResponse(
 	if (config.transformContext) {
 		messages = await logger.ttftAttr("ttft.transform-context", () => config.transformContext!(messages, signal));
 	}
+	const injected = signal?.aborted ? [] : (config.getContextMessages?.(messages) ?? []);
+	for (const message of injected) {
+		context.messages.push(message);
+		newMessages.push(message);
+		stream.push({ type: "message_start", message });
+		stream.push({ type: "message_end", message });
+	}
+	if (injected.length > 0 && messages !== context.messages) messages = [...messages, ...injected];
 
 	// Convert to LLM-compatible messages (AgentMessage[] → Message[])
 	const llmMessages = await logger.ttftAttr("ttft.convert-to-llm", () => config.convertToLlm(messages));
@@ -504,12 +515,14 @@ async function executeToolCalls(
 		const normalizedResult = normalizeToolResult(result, isError);
 		const { toolCall } = record;
 		if (!record.started) {
+			const executionKind = getToolExecutionKind(record.tool, record.args);
 			stream.push({
 				type: "tool_execution_start",
 				toolCallId: toolCall.id,
 				toolName: toolCall.name,
 				args: record.args,
 				intent: toolCall.intent,
+				...(executionKind ? { executionKind } : {}),
 			});
 		}
 		const isWarning = Boolean(normalizedResult.isWarning);
@@ -559,12 +572,14 @@ async function executeToolCalls(
 		}
 		record.args = argsForExecution;
 		record.started = true;
+		const executionKind = getToolExecutionKind(tool, argsForExecution);
 		stream.push({
 			type: "tool_execution_start",
 			toolCallId: toolCall.id,
 			toolName: toolCall.name,
 			args: argsForExecution,
 			intent: toolCall.intent,
+			...(executionKind ? { executionKind } : {}),
 		});
 
 		let result: AgentToolResult<any>;
@@ -607,10 +622,13 @@ async function executeToolCalls(
 				toolContext,
 			);
 		} catch (e) {
-			result = {
-				content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
-				details: {},
-			};
+			result =
+				e instanceof AgentToolError
+					? e.result
+					: {
+							content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+							details: {},
+						};
 			isError = true;
 		}
 

package/src/agent.ts

@@ -257,6 +257,7 @@ export class Agent {
 	#listeners = new Set<(e: AgentEvent) => void>();
 	#abortController?: AbortController;
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+	#contextMessages?: AgentLoopConfig["getContextMessages"];
 	#transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
 	#steeringQueue: AgentMessage[] = [];
 	#followUpQueue: AgentMessage[] = [];
@@ -534,6 +535,14 @@ export class Agent {
 		this.#state.messages = ms.slice();
 	}
 
+	/** Install the owning session's model-context provider. It must not start work. */
+	setContextMessagesProvider(provider?: AgentLoopConfig["getContextMessages"]): () => void {
+		this.#contextMessages = provider;
+		return () => {
+			if (this.#contextMessages === provider) this.#contextMessages = undefined;
+		};
+	}
+
 	appendMessage(m: AgentMessage) {
 		this.#state.messages = [...this.#state.messages, m];
 	}
@@ -804,6 +813,7 @@ export class Agent {
 				kimiApiFormat: this.#kimiApiFormat,
 				preferWebsockets: this.#preferWebsockets,
 				convertToLlm: this.#convertToLlm,
+				getContextMessages: messages => this.#contextMessages?.(messages) ?? [],
 				transformContext: this.#transformContext,
 				// Per-turn: compose the extension hook with any server-tool injection for
 				// THIS prompt (e.g. Office "Search the web"). No-op when neither is present.

package/src/index.ts

@@ -6,5 +6,7 @@ export * from "./agent-loop";
 export * from "./proxy";
 // Thinking selectors
 export * from "./thinking";
+// Structured execution failures
+export * from "./tool-error";
 // Types
 export * from "./types";

package/src/tool-error.ts

@@ -0,0 +1,12 @@
+import type { AgentToolResult } from "./types";
+
+/** A failed execution whose structured result must survive the tool/agent boundary. */
+export class AgentToolError<T = unknown> extends Error {
+	constructor(
+		message: string,
+		readonly result: AgentToolResult<T>,
+	) {
+		super(message);
+		this.name = "AgentToolError";
+	}
+}

package/src/types.ts

@@ -64,6 +64,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 
+	/** Session-owned context updates after pruning; emitted and retained like other messages. */
+	getContextMessages?: (messages: readonly AgentMessage[]) => AgentMessage[];
+
 	/**
 	 * Optional transform applied to the context before `convertToLlm`.
 	 *
@@ -242,6 +245,10 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
 	extends Tool<TParameters> {
 	// A human-readable label for the tool to be displayed in UI
 	label: string;
+	/** Host presentation of the actual executor; absent for ordinary dynamic tools. */
+	executionKind?: "command" | "fileChange";
+	/** Pure per-call classification; returning undefined preserves ordinary dynamic-tool presentation. */
+	getExecutionKind?: (params: unknown) => "command" | "fileChange" | undefined;
 	/** If true, tool is excluded unless explicitly listed in --tools or agent's tools field */
 	hidden?: boolean;
 	/** If true, tool can stage a pending action that requires explicit resolution via the resolve tool. */
@@ -293,7 +300,14 @@ export type AgentEvent =
 	| { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
 	| { type: "message_end"; message: AgentMessage }
 	// Tool execution lifecycle
-	| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any; intent?: string }
+	| {
+			type: "tool_execution_start";
+			toolCallId: string;
+			toolName: string;
+			args: any;
+			intent?: string;
+			executionKind?: "command" | "fileChange";
+	  }
 	| { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
 	| {
 			type: "tool_execution_end";
@@ -303,3 +317,10 @@ export type AgentEvent =
 			isError?: boolean;
 			isWarning?: boolean;
 	  };
+
+export function getToolExecutionKind(
+	tool: AgentTool | undefined,
+	params: unknown,
+): "command" | "fileChange" | undefined {
+	return tool?.getExecutionKind ? tool.getExecutionKind(params) : tool?.executionKind;
+}