@prometheus-ai/agent-core 0.5.4 → 0.5.8

package/dist/types/types.d.ts

@@ -1,10 +1,17 @@
-import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TSchema } from "@prometheus-ai/ai";
+import type { ApiKeyResolveContext, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Context, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TSchema } from "@prometheus-ai/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
 /** Stream function - can return sync or Promise for async config lookup */
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+/**
+ * An aside entry: a ready {@link AgentMessage}, or a sync thunk evaluated at
+ * injection time that returns the message to inject or `null` to skip it. Thunks
+ * let the producer make the final inject-or-drop decision against current state
+ * (e.g. dropping late diagnostics a newer edit superseded).
+ */
+export type AsideMessage = AgentMessage | (() => AgentMessage | null);
 /**
  * Configuration for the agent loop.
  */
@@ -16,13 +23,6 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * - "wait" = defer steering until the current turn completes
      */
     interruptMode?: "immediate" | "wait";
-    /**
-     * Maximum completed tool calls to accept from one streamed assistant turn before
-     * cutting the provider stream and executing that batch. The cap is enforced on
-     * `toolcall_end` so every executed call has complete arguments. Undefined disables
-     * batching.
-     */
-    maxToolCallsPerTurn?: number;
     /**
      * Optional session identifier forwarded to LLM providers.
      * Used by providers that support session-based caching (e.g., OpenAI Codex).
@@ -79,21 +79,42 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * ```
      */
     transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Optional transform applied to the final provider context after conversion,
+     * normalization, and append-only context handling, but before telemetry capture
+     * and provider send.
+     */
+    transformProviderContext?: (context: Context, model: Model) => Context;
     /**
      * Resolves an API key dynamically for each LLM call.
      *
      * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire
      * during long-running tool execution phases.
      */
-    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    getApiKey?: (provider: string, ctx?: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
     /**
      * Returns steering messages to inject into the conversation mid-run.
      *
-     * Called after each tool execution to check for user interruptions unless interruptMode is "wait".
-     * If messages are returned, remaining tool calls are skipped and
-     * these messages are added to the context before the next LLM call.
+     * Called at injection boundaries only (loop start and after a tool batch
+     * fully settles), so dequeued messages are immediately injected. The
+     * mid-batch interrupt poll uses {@link hasSteeringMessages} instead and
+     * never consumes the queue.
      */
     getSteeringMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Peeks whether steering messages are queued, without consuming them.
+     *
+     * Called after each tool execution (unless interruptMode is "wait") to decide
+     * whether to skip the remaining tool calls in the batch. The queue keeps
+     * owning its messages until the loop reaches the next injection boundary and
+     * dequeues via {@link getSteeringMessages} — so callers can still cancel or
+     * restore queued messages while in-flight tools settle, and an external
+     * abort in that window leaves the queue intact for a post-abort continue.
+     *
+     * When omitted, steering never interrupts a running tool batch; queued
+     * messages are still delivered at the next injection boundary.
+     */
+    hasSteeringMessages?: () => boolean | Promise<boolean>;
     /**
      * Returns follow-up messages to process after the agent would otherwise stop.
      *
@@ -102,6 +123,17 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * continues with another turn.
      */
     getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Returns non-interrupting "aside" messages to inject at a step boundary.
+     *
+     * Polled after each tool batch (before the next LLM call) AND at the yield
+     * check. Unlike steering, these NEVER abort in-flight tools — they are passive
+     * notifications (e.g. background-job completions, late LSP diagnostics) that
+     * should reach the model between requests without waiting for the agent to
+     * fully stop. Returned messages are appended to the context with normal
+     * message events and keep the loop running so the model can react.
+     */
+    getAsideMessages?: () => Promise<AsideMessage[]>;
     /**
      * Hook fired right before the loop would exit.
      *
@@ -160,6 +192,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * the next model call instead of waiting for the next prompt.
      */
     getReasoning?: () => Effort | undefined;
+    /**
+     * Dynamic reasoning-disable override, resolved per LLM call. When set,
+     * its return value overrides the static `disableReasoning` from
+     * `SimpleStreamOptions` for that request. Pair with `getReasoning` so
+     * mid-run transitions into and out of the explicit `off` state propagate
+     * to the next provider call.
+     */
+    getDisableReasoning?: () => boolean | undefined;
     /**
      * Called after a tool call has been validated and is about to execute.
      *
@@ -237,6 +277,8 @@ export interface AfterToolCallResult {
     details?: unknown;
     /** If provided, replaces the error flag carried with the tool result. */
     isError?: boolean;
+    /** If provided, replaces the contextually-useless flag carried with the tool result. */
+    useless?: boolean;
 }
 /** Context passed to `beforeToolCall`. */
 export interface BeforeToolCallContext {
@@ -273,7 +315,7 @@ export interface AfterToolCallContext {
  *
  * @example
  * ```typescript
- * declare module "@prometheus-ai/agent-core" {
+ * declare module "@prometheus-ai/agent" {
  *   interface CustomAgentMessages {
  *     artifact: ArtifactMessage;
  *     notification: NotificationMessage;
@@ -296,6 +338,7 @@ export interface AgentState {
     systemPrompt: string[];
     model: Model;
     thinkingLevel?: Effort;
+    disableReasoning?: boolean;
     tools: AgentTool<any>[];
     messages: AgentMessage[];
     isStreaming: boolean;
@@ -307,6 +350,8 @@ export interface AgentToolResult<T = any, _TInput = unknown> {
     content: (TextContent | ImageContent)[];
     details?: T;
     isError?: boolean;
+    /** Marks the result as contextually useless: safe for compaction to elide once consumed (e.g. zero matches, wait timeout). Ignored when isError is set. */
+    useless?: boolean;
 }
 export type AgentToolUpdateCallback<T = any, TInput = unknown> = (partialResult: AgentToolResult<T, TInput>) => void;
 /** Options passed to renderResult */
@@ -352,14 +397,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
     loadMode?: "essential" | "discoverable";
     /** Short one-line summary used for tool discovery indexes. */
     summary?: string;
-    /** If true, tool execution ignores abort signals (runs to completion) */
-    nonAbortable?: boolean;
     /**
      * Concurrency mode for tool scheduling when multiple calls are in one turn.
      * - "shared": can run alongside other shared tools (default)
      * - "exclusive": runs alone; other tools wait until it finishes
+     * - function: resolved per call from the (raw, pre-validation) arguments
      */
-    concurrency?: "shared" | "exclusive";
+    concurrency?: "shared" | "exclusive" | ((args: Partial<Static<TParameters>>) => "shared" | "exclusive");
     /** If true, argument validation errors are non-fatal: raw args are passed to execute() instead of returning an error to the LLM. */
     lenientArgValidation?: boolean;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@prometheus-ai/agent-core",
-	"version": "0.5.4",
+	"version": "0.5.8",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://prometheus.trivlab.com",
 	"author": "Uttam Trivedi",
@@ -32,9 +32,11 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@prometheus-ai/ai": "0.5.4",
-		"@prometheus-ai/natives": "0.5.4",
-		"@prometheus-ai/utils": "0.5.4",
+		"@prometheus-ai/ai": "0.5.8",
+		"@prometheus-ai/catalog": "0.5.8",
+		"@prometheus-ai/natives": "0.5.8",
+		"@prometheus-ai/snapcompact": "0.5.8",
+		"@prometheus-ai/utils": "0.5.8",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {