@prometheus-ai/agent 0.5.3 → 0.5.8

package/dist/types/tools/eval-render.d.ts

@@ -13,14 +13,6 @@ import type { EvalStatusEvent, EvalToolDetails } from "../eval/types";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme } from "../modes/theme/theme";
 export declare const EVAL_DEFAULT_PREVIEW_LINES = 10;
-/**
- * Rows of source kept in the *pending* eval preview. The window follows the
- * streaming edge (newest lines pinned to the bottom) so you can watch the code
- * being written, while staying bounded — a volatile tool block taller than the
- * viewport would otherwise strand its scrolled-off head out of native scrollback
- * on ED3-risk terminals. Matches the streaming windows used by edit/write.
- */
-export declare const EVAL_STREAMING_PREVIEW_LINES = 12;
 interface EvalRenderCellArg {
     language?: string;
     code?: string;
@@ -56,5 +48,6 @@ export declare const evalToolRenderer: {
     }, uiTheme: Theme, _args?: EvalRenderArgs): Component;
     mergeCallAndResult: boolean;
     inline: boolean;
+    provisionalPendingPreview: string;
 };
 export {};

package/dist/types/tools/eval.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { EvalToolDetails } from "../eval/types";
 import type { ToolSession } from ".";
 export { EVAL_DEFAULT_PREVIEW_LINES, evalToolRenderer } from "./eval-render";
@@ -42,6 +42,14 @@ export type EvalProxyExecutor = (params: EvalToolParams, signal?: AbortSignal) =
 export interface EvalToolDescriptionOptions {
     py?: boolean;
     js?: boolean;
+    /**
+     * Whether `agent()` is allowed in this session. Driven by the parent's
+     * spawn policy (`getSessionSpawns`). Defaults to `true` for backward
+     * compatibility — when the session forbids spawning, the prelude doc
+     * omits the `agent()` entry so the model does not promise itself a
+     * helper that will only ever throw "spawns disabled".
+     */
+    spawns?: boolean;
 }
 export declare function getEvalToolDescription(options?: EvalToolDescriptionOptions): string;
 export interface EvalToolOptions {

package/dist/types/tools/fetch.d.ts

@@ -1,4 +1,5 @@
 import type { AgentToolResult } from "@prometheus-ai/agent-core";
+import type { FetchImpl } from "@prometheus-ai/ai";
 import { type Component } from "@prometheus-ai/tui";
 import type { Settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -17,16 +18,24 @@ export interface ParsedReadUrlTarget {
     ranges?: readonly LineRange[];
 }
 export declare function parseReadUrlTarget(readPath: string): ParsedReadUrlTarget | null;
+/** Reader backends for {@link renderHtmlToText}, in default priority order. */
+export type FetchProvider = "native" | "trafilatura" | "lynx" | "parallel" | "jina";
 /**
- * Render HTML to markdown using Parallel, jina, trafilatura, lynx, then the
- * in-process native converter. The overall `timeout` budget bounds the call,
- * but remote reader requests are additionally capped at `REMOTE_READER_MAX_MS`
- * so that a hung remote endpoint cannot prevent local fallbacks from running.
- * Only a real `userSignal` cancellation aborts the chain — remote per-attempt
- * timeouts and the overall reader-mode timeout still allow later renderers
- * (especially the purely-local native converter) to be tried.
+ * Render HTML to markdown by trying reader backends in priority order: native
+ * (in-process), trafilatura, lynx, Parallel, then Jina. The `providers.fetch`
+ * setting picks the order — `auto` uses the default above; any specific backend
+ * is tried first, then the remaining backends as fallbacks. Every backend's
+ * output must clear the same quality gate (>100 non-whitespace chars and not
+ * {@link isLowQualityOutput}) before it is accepted, otherwise the next backend
+ * is tried.
+ *
+ * The overall `timeout` budget bounds the whole call; remote backends (Parallel,
+ * Jina) are additionally capped at `REMOTE_READER_MAX_MS` so a hung endpoint
+ * cannot starve later renderers — especially the purely-local native converter,
+ * which always works on already-loaded HTML. Only a real `userSignal`
+ * cancellation aborts the chain (#1449).
  */
-export declare function renderHtmlToText(url: string, html: string, timeout: number, settings: Settings, userSignal: AbortSignal | undefined, storage: AgentStorage | null): Promise<{
+export declare function renderHtmlToText(url: string, html: string, timeout: number, settings: Settings, userSignal: AbortSignal | undefined, storage: AgentStorage | null, fetchOverride?: FetchImpl): Promise<{
     content: string;
     ok: boolean;
     method: string;

package/dist/types/tools/find.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
 import type { Component } from "@prometheus-ai/tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import { type TruncationResult } from "../session/streaming-output";
@@ -14,13 +14,6 @@ declare const findSchema: z.ZodObject<{
     timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
 }, z.core.$strict>;
 export type FindToolInput = z.infer<typeof findSchema>;
-/**
- * Group find matches by their directory so the model doesn't pay repeated
- * tokens for shared path prefixes. Preserves the input order: groups appear in
- * the order their first member was emitted (mtime-desc for native glob), and
- * within a group entries keep their relative order.
- */
-export declare function formatFindGroupedOutput(paths: readonly string[]): string;
 export interface FindToolDetails {
     truncation?: TruncationResult;
     resultLimitReached?: number;

package/dist/types/tools/gh-cache-invalidation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Drop `github-cache` rows for any `gh issue|pr <mutating-subcmd>` call
+ * embedded in `command`. Safe to invoke unconditionally; no-op when the
+ * command does not touch GitHub state.
+ */
+export declare function invalidateGithubCacheForBashCommand(command: string): void;

package/dist/types/tools/gh.d.ts

@@ -1,9 +1,12 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolApprovalDecision } from "@prometheus-ai/agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { Settings } from "../config/settings";
+import * as git from "../utils/git";
 import type { ToolSession } from ".";
 import { type CacheStatus } from "./github-cache";
 import type { OutputMeta } from "./output-meta";
+/** Runs `gh --json` for issue data, retrying without optional stateReason on older gh releases. */
+export declare function githubIssueJsonWithStateReasonFallback<T>(cwd: string, args: readonly string[], signal: AbortSignal | undefined, options?: git.GhCommandOptions): Promise<T>;
 declare const githubSchema: z.ZodObject<{
     op: z.ZodEnum<{
         pr_checkout: "pr_checkout";

package/dist/types/tools/github-cache.d.ts

@@ -55,8 +55,27 @@ export interface PutCachedInput<T = unknown> {
 export declare function putCached<T = unknown>(input: PutCachedInput<T>): void;
 /** Drop a specific cache entry. */
 export declare function invalidate(repo: string, kind: CacheKind, number: number, includeComments?: boolean, authKey?: string): void;
+/**
+ * Drop every cached row for a given issue/PR number, regardless of repo,
+ * auth key, include_comments flag, or row kind ({@link CacheKind}). Best-effort:
+ * swallows DB failures the same way {@link invalidate} does.
+ *
+ * Used by the bash-side detector that reacts to `gh issue close` / `gh pr merge`
+ * style mutations. Repo + auth-key narrowing is intentionally skipped because
+ * the bash command often does not name the repo (defaults to cwd's `gh`
+ * config) and resolving the *current* repo from `cwd` for every bash call would
+ * be far more expensive than a write-amplified DELETE.
+ */
+export declare function invalidateAllForNumber(number: number, repo?: string): void;
 /** Drop every cached row. Test helper. */
 export declare function clearAll(): void;
+/**
+ * Drop every cached row for a repo, or all rows when the repo is unknown.
+ * Fallback for current-branch `gh pr merge`/`gh pr close`-style mutations
+ * where the bash command names no PR number or URL, so the target row cannot
+ * be identified. Over-invalidation is deliberate (see module header).
+ */
+export declare function invalidateAllForRepo(repo?: string): void;
 /**
  * Test/maintenance helper. Closes and forgets the cached connection so the
  * next access reopens against (possibly) a different DB path.

package/dist/types/tools/grouped-file-output.d.ts

@@ -1,7 +1,7 @@
 /**
  * One file's contribution to a grouped file output. The header itself is generated
- * by `formatGroupedFiles` (single `#` for root files, `##` for files inside a dir);
- * use `headerSuffix` to tack on extras like ` (1 replacement)`.
+ * by `formatGroupedFiles` (one `#` per nesting level); use `headerSuffix` to tack
+ * on extras like ` (1 replacement)`.
  */
 export interface GroupedFileSection {
     /** Optional suffix appended to the file header. */
@@ -18,19 +18,53 @@ export interface GroupedFilesOutput {
     display: string[];
 }
 /**
- * Render a list of files as directory-grouped sections shared by grep, ast-grep,
- * ast-edit, and the LSP diagnostic formatter.
+ * Render a list of files as a multi-level, prefix-folded directory tree shared by
+ * grep, ast-grep, ast-edit, and the LSP diagnostic formatter.
  *
- * Layout:
- *   # dir/
- *   ## file.ts
+ * Layout (one `#` per level; the shared prefix folds into the top header):
+ *   # packages/pkg/src/
+ *   ## root.ts
  *   …body…
- *
- *   # otherdir/
- *   ## other.ts
+ *   ## nested/
+ *   ### child.ts
  *   …body…
  *
- * Files in the project root (directory `.`) become single-`#` headers without a
- * `## file` line, matching the existing convention.
+ * Files in the (folded) project root become single-`#` headers with no parent
+ * directory line. A blank line precedes every directory header and every
+ * root-level file so the renderers can split the output into collapsible groups.
  */
 export declare function formatGroupedFiles(files: string[], renderFile: (filePath: string) => GroupedFileSection): GroupedFilesOutput;
+/** Per-line classification of grouped output, used by renderers for hyperlinks. */
+export interface GroupedLineContext {
+    /** Directory header, file header, or any non-header body/content line. */
+    kind: "dir" | "file" | "content";
+    /** Number of leading `#` for headers; 0 for content lines. */
+    depth: number;
+    /** Resolved absolute path of the dir/file a header points at (when resolvable). */
+    headerPath?: string;
+    /** For content lines, the absolute path of the owning file (line hyperlinks). */
+    filePath?: string;
+    /** Header is an internal/url-like target the caller resolves itself. */
+    isUrl?: boolean;
+}
+/**
+ * Walk grouped output lines, tracking a directory stack keyed by header depth, so
+ * each header and body line can be linked back to its absolute filesystem path.
+ * Reconstruction is stack-based (not per-blank-group) so nested directory headers
+ * resolve correctly across the whole output.
+ *
+ * `headerBase` is the directory the displayed (folded) header paths are relative
+ * to — for grep/ast tools that is the session cwd, since display paths are
+ * formatted relative to cwd regardless of the (sub)directory the search was
+ * scoped to. `fileScope` is the initial owning file for body lines that appear
+ * before any header (single-file scopes have no `#` headers); it defaults to
+ * `headerBase` and should be passed the scoped file's absolute path.
+ */
+export declare function classifyGroupedLines(lines: readonly string[], headerBase: string | undefined, fileScope?: string | undefined): GroupedLineContext[];
+/**
+ * Split line indices into blank-line-separated groups, mirroring
+ * `splitGroupsByBlankLine`: when any blank line is present, break on runs of
+ * blanks; otherwise return a single group of the non-empty lines. Returning
+ * indices lets callers slice parallel arrays (raw lines, styled lines, contexts).
+ */
+export declare function groupLineIndicesByBlank(rawLines: readonly string[]): number[][];

package/dist/types/tools/image-gen.d.ts

@@ -1,5 +1,5 @@
 import { type Model } from "@prometheus-ai/ai";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { type ModelRegistry } from "../config/model-registry";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";

package/dist/types/tools/index.d.ts

@@ -1,9 +1,11 @@
 import type { AgentTelemetryConfig, AgentTool } from "@prometheus-ai/agent-core";
-import type { ToolChoice } from "@prometheus-ai/ai";
+import type { FetchImpl, Model, ToolChoice } from "@prometheus-ai/ai";
 import type { InMemorySnapshotStore } from "@prometheus-ai/hashline";
 import type { AsyncJobManager } from "../async/job-manager";
+import type { Rule } from "../capability/rule";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
+import type { ToolPathWithSource } from "../extensibility/custom-tools";
 import type { Skill } from "../extensibility/skills";
 import type { GoalModeState, GoalRuntime } from "../goals";
 import type { HindsightSessionState } from "../hindsight/state";
@@ -11,10 +13,11 @@ import type { LocalProtocolOptions } from "../internal-urls";
 import type { MCPManager } from "../mcp";
 import type { MnemopiSessionState } from "../mnemopi/state";
 import type { PlanModeState } from "../plan-mode/state";
-import { type AgentRegistry } from "../registry/agent-registry";
+import type { AgentRegistry } from "../registry/agent-registry";
 import type { ArtifactManager } from "../session/artifacts";
 import type { ClientBridge } from "../session/client-bridge";
 import type { CustomMessage } from "../session/messages";
+import type { UsageStatistics } from "../session/session-entries";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue";
 import type { AgentOutputManager } from "../task/output-manager";
 import type { DiscoverableTool, DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
@@ -23,8 +26,6 @@ import type { WorkspaceTree } from "../workspace-tree";
 import { type CheckpointState } from "./checkpoint";
 import { type TodoPhase } from "./todo";
 export * from "../edit";
-export * from "../exa";
-export type * from "../exa/types";
 export * from "../goals";
 export * from "../lsp";
 export * from "../session/streaming-output";
@@ -45,6 +46,8 @@ export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
 export * from "./job";
+export * from "./learn";
+export * from "./manage-skill";
 export * from "./memory-edit";
 export * from "./memory-recall";
 export * from "./memory-reflect";
@@ -69,12 +72,43 @@ export type ContextFileEntry = {
     depth?: number;
 };
 export type { DiscoverableTool, DiscoverableToolSearchIndex, DiscoverableToolSearchResult, DiscoverableToolSource, } from "../tool-discovery/tool-index";
+/**
+ * A late LSP diagnostics result that arrived after the edit/write tool already
+ * returned. Surfaced to the model and the transcript via
+ * {@link ToolSession.queueDeferredDiagnostics}, batched through the session
+ * yield queue like background-job results.
+ */
+export interface DeferredDiagnosticsEntry {
+    /** Absolute path the diagnostics belong to (the renderer shortens it). */
+    path: string;
+    /** One-line severity summary, e.g. "2 errors". */
+    summary: string;
+    /** Formatted, ready-to-display diagnostic lines. */
+    messages: string[];
+    /** True when any message is error severity. */
+    errored: boolean;
+    /**
+     * Evaluated at injection time (in the dispatcher's stale check): drop the entry
+     * when a newer mutation to the same file has superseded it, so the model never
+     * sees diagnostics for stale content.
+     */
+    isStale(): boolean;
+}
 /** Session context for tool factories */
 export interface ToolSession {
     /** Current working directory */
     cwd: string;
     /** Whether UI is available */
     hasUI: boolean;
+    /**
+     * Suppress the spawn specialization/coordination advisory appended to `task`
+     * results. Set by internal/programmatic callers (e.g. the commit agent's
+     * file-analysis fan-out) whose results are consumed by code — not by a model
+     * orchestrating further spawns — so the nudge would only be noise.
+     */
+    suppressSpawnAdvisory?: boolean;
+    /** Optional fetch implementation injected into the URL read pipeline (tests, proxies). Defaults to global fetch. */
+    fetch?: FetchImpl;
     /** Skip Python kernel availability check and warmup */
     skipPythonPreflight?: boolean;
     /** Pre-loaded context files (AGENTS.md, etc) */
@@ -85,6 +119,21 @@ export interface ToolSession {
     skills?: Skill[];
     /** Pre-loaded prompt templates */
     promptTemplates?: PromptTemplate[];
+    /** Pre-loaded rules (forwarded to subagents to skip re-discovery). */
+    rules?: Rule[];
+    /**
+     * Pre-discovered extension source paths. Forwarded to subagents so they
+     * skip the FS scan but still re-bind extensions to their own session-scoped
+     * `ExtensionAPI` (cwd, eventBus, runtime). Inline extension factories
+     * (`<inline-N>`) are NOT included — those are session-local.
+     */
+    extensionPaths?: string[];
+    /**
+     * Pre-discovered custom-tool source paths from `.prometheus/tools/`, `.claude/tools/`,
+     * plugins, etc. Forwarded to subagents so they skip the FS scan but still
+     * re-bind tools to their own session-scoped `CustomToolAPI`.
+     */
+    customToolPaths?: ToolPathWithSource[];
     /** Whether LSP integrations are enabled */
     enableLsp?: boolean;
     /** Whether an edit-capable tool is available in this session (controls hashline output) */
@@ -111,7 +160,7 @@ export interface ToolSession {
     getSessionId?: () => string | null;
     /** Get Hindsight runtime state for this agent session. */
     getHindsightSessionState?: () => HindsightSessionState | undefined;
-    /** Get Prometheus Memory runtime state for this agent session. */
+    /** Get Mnemopi runtime state for this agent session. */
     getMnemopiSessionState?: () => MnemopiSessionState | undefined;
     /** Agent identity used for IRC routing. Returns the registry id (e.g. "Main", "AuthLoader"). */
     getAgentId?: () => string | null;
@@ -134,6 +183,8 @@ export interface ToolSession {
     getModelString?: () => string | undefined;
     /** Get the current session model string, regardless of how it was chosen */
     getActiveModelString?: () => string | undefined;
+    /** Get the current session model object (provider/api capabilities), regardless of how it was chosen. */
+    getActiveModel?: () => Model | undefined;
     /** Auth storage for passing to subagents (avoids re-discovery) */
     authStorage?: import("../session/auth-storage").AuthStorage;
     /** Model registry for passing to subagents (avoids re-discovery) */
@@ -170,7 +221,7 @@ export interface ToolSession {
     /** Goal runtime for the active agent session. */
     getGoalRuntime?: () => GoalRuntime | undefined;
     /** Get cumulative session usage statistics (input/output tokens, cost). */
-    getUsageStatistics?: () => import("../session/session-manager").UsageStatistics;
+    getUsageStatistics?: () => UsageStatistics;
     /** Current per-turn token budget {total, spent, hard} for the eval `budget` helper. */
     getTurnBudget?: () => {
         total: number | null;
@@ -181,8 +232,6 @@ export interface ToolSession {
     recordEvalSubagentUsage?: (output: number) => void;
     /** Bridge to the connected client (e.g. ACP editor host). Tools should route fs/terminal/permission requests through this when available. */
     getClientBridge?: () => ClientBridge | undefined;
-    /** Get compact conversation context for subagents (excludes tool results, system prompts) */
-    getCompactContext?: () => string;
     /** Get cached todo phases for this session. */
     getTodoPhases?: () => TodoPhase[];
     /** Replace cached todo phases for this session. */
@@ -240,8 +289,23 @@ export interface ToolSession {
     /** Per-session ledger of post-edit LSP diagnostics already surfaced to the
      *  model for each file. Lazily initialized by `getDiagnosticsLedger`. */
     diagnosticsLedger?: import("../lsp/diagnostics-ledger").DiagnosticsLedger;
+    /** Per-session ledger of consecutive byte-identical no-op edits, keyed by
+     *  canonical file path. The hashline executor escalates a soft no-op hint
+     *  to a thrown error once the same payload no-ops `NOOP_HARD_LIMIT` times,
+     *  breaking subagent loops that ignore the textual hint (issue #2081).
+     *  Lazily initialized by `getNoopLoopGuard`. */
+    noopLoopGuard?: import("../edit/hashline/noop-loop-guard").NoopLoopGuard;
     /** Queue a hidden message to be injected at the next agent turn. */
     queueDeferredMessage?(message: CustomMessage): void;
+    /** Queue late LSP diagnostics (arrived after an edit/write returned) to be shown
+     *  in the transcript and delivered to the model at the next yield, like background
+     *  job results. */
+    queueDeferredDiagnostics?(entry: DeferredDiagnosticsEntry): void;
+    /** Bump and return the session-global mutation counter for `path`. Edit/write
+     *  tools call this on every file mutation so stale late-diagnostics can be dropped. */
+    bumpFileMutationVersion?(path: string): number;
+    /** Read the current session-global mutation counter for `path` (0 if never mutated). */
+    getFileMutationVersion?(path: string): number;
     /** Get the active OpenTelemetry config so subagent dispatch can forward
      *  the parent's tracer/hooks with the subagent's own identity stamped. */
     getTelemetry?: () => AgentTelemetryConfig | undefined;
@@ -256,6 +320,23 @@ export declare const DEFAULT_ESSENTIAL_TOOL_NAMES: readonly string[];
  * otherwise `DEFAULT_ESSENTIAL_TOOL_NAMES`.
  */
 export declare function computeEssentialBuiltinNames(settings: Settings): string[];
+/**
+ * Filter the initial active tool set when `tools.discoveryMode === "all"`.
+ *
+ * Non-essential discoverable built-ins are hidden — the model rediscovers them
+ * via `search_tool_bm25` and activates them on demand. A tool survives hiding
+ * when it is essential, explicitly requested, restored from a prior selection,
+ * or required by a forced tool_choice feature (`forceActive`). The last case is
+ * load-bearing: a named tool_choice (e.g. the eager `todo` prelude) must
+ * reference a tool present in the request, or the provider rejects it with 400.
+ */
+export declare function filterInitialToolsForDiscoveryAll(initialToolNames: string[], opts: {
+    loadModeOf: (name: string) => BuiltinToolLoadMode | undefined;
+    essentialNames: ReadonlySet<string>;
+    explicitlyRequested: ReadonlySet<string>;
+    restored: ReadonlySet<string>;
+    forceActive: ReadonlySet<string>;
+}): string[];
 /**
  * Public callable factory map. External callers may invoke `BUILTIN_TOOLS.read(session)` or
  * `BUILTIN_TOOLS[name](session)` to construct a tool directly.

package/dist/types/tools/inspect-image.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
 import { completeSimple } from "@prometheus-ai/ai";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from "./index";
 declare const inspectImageSchema: z.ZodObject<{
     path: z.ZodString;

package/dist/types/tools/irc.d.ts

@@ -1,58 +1,63 @@
 /**
- * IRC tool — agent-to-agent messaging.
+ * IRC tool — agent-to-agent messaging over the process-global IrcBus.
  *
- * Lets any live agent send a short prose message to any other live agent in
- * this process and (optionally) get a prose reply.
- *
- * Routing happens via the global AgentRegistry. Replies are produced by an
- * ephemeral side-channel call (`AgentSession.respondAsBackground`) that
- * mirrors `/btw`: the recipient's current model, system prompt, and message
- * history are used to compute a reply without persisting it through the
- * normal stream path. After the reply is generated, both the incoming
- * message and the auto-reply are queued for injection into the recipient's
- * persisted history (deferred until the recipient is idle), so the model
- * sees the exchange on its next turn.
- *
- * This avoids the deadlock that arises when the recipient is blocked on a
- * long-running tool call: the side-channel call does not depend on the
- * recipient's main agent loop being free.
+ * `send` is fire-and-forget: the bus routes the message to the recipient
+ * (waking idle agents with a real turn, reviving parked ones via the
+ * lifecycle manager, injecting a non-interrupting aside into busy ones) and
+ * returns delivery receipts immediately. Replies are real turns by the
+ * recipient, observed with `wait` (or the `await: true` send sugar). `inbox`
+ * drains pending messages; `list` shows every addressable peer.
  */
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
-import * as z from "zod/v4";
+import { type Component } from "@prometheus-ai/tui";
+import { z } from "zod/v4";
+import type { Settings } from "../config/settings";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type IrcDeliveryReceipt, type IrcMessage } from "../irc/bus";
+import type { Theme } from "../modes/theme/theme";
 import type { ToolSession } from ".";
+/**
+ * IRC availability: there must be someone to chat with. True for every
+ * subagent (it always has a parent, and possibly siblings) and for any
+ * session that can still spawn subagents through the task tool. Only a
+ * top-level session with task spawning unavailable has no peers — no irc.
+ */
+export declare function isIrcEnabled(settings: Settings, taskDepth: number): boolean;
 declare const ircSchema: z.ZodObject<{
     op: z.ZodEnum<{
+        inbox: "inbox";
         list: "list";
         send: "send";
+        wait: "wait";
     }>;
     to: z.ZodOptional<z.ZodString>;
     message: z.ZodOptional<z.ZodString>;
-    awaitReply: z.ZodOptional<z.ZodBoolean>;
+    replyTo: z.ZodOptional<z.ZodString>;
+    await: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    peek: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 type IrcParams = z.infer<typeof ircSchema>;
-interface IrcReply {
-    from: string;
-    text: string;
+interface IrcPeerInfo {
+    id: string;
+    displayName: string;
+    kind: string;
+    status: string;
+    parentId?: string;
+    unread: number;
+    lastActivity: number;
+    activity?: string;
 }
 export interface IrcDetails {
-    op: "send" | "list";
+    op: "send" | "wait" | "inbox" | "list";
     from?: string;
     to?: string;
-    delivered?: string[];
-    replies?: IrcReply[];
-    failed?: Array<{
-        id: string;
-        error: string;
-    }>;
-    notFound?: string[];
-    peers?: Array<{
-        id: string;
-        displayName: string;
-        kind: string;
-        status: string;
-        parentId?: string;
-    }>;
-    channels?: string[];
+    receipts?: IrcDeliveryReceipt[];
+    /** Message consumed by `wait` / `send await:true`; null when the wait timed out. */
+    waited?: IrcMessage | null;
+    inbox?: IrcMessage[];
+    peers?: IrcPeerInfo[];
 }
 export declare class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
     #private;
@@ -60,16 +65,22 @@ export declare class IrcTool implements AgentTool<typeof ircSchema, IrcDetails>
     readonly name = "irc";
     readonly approval: "read";
     readonly label = "IRC";
-    readonly summary = "Send and receive messages between agents over IRC-like channels";
+    readonly summary = "Send and receive messages between agents";
     readonly description: string;
     readonly parameters: z.ZodObject<{
         op: z.ZodEnum<{
+            inbox: "inbox";
             list: "list";
             send: "send";
+            wait: "wait";
         }>;
         to: z.ZodOptional<z.ZodString>;
         message: z.ZodOptional<z.ZodString>;
-        awaitReply: z.ZodOptional<z.ZodBoolean>;
+        replyTo: z.ZodOptional<z.ZodString>;
+        await: z.ZodOptional<z.ZodBoolean>;
+        from: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        peek: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     readonly strict = true;
     readonly loadMode = "discoverable";
@@ -77,4 +88,33 @@ export declare class IrcTool implements AgentTool<typeof ircSchema, IrcDetails>
     static createIf(session: ToolSession): IrcTool | null;
     execute(_toolCallId: string, params: IrcParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<IrcDetails>, _context?: AgentToolContext): Promise<AgentToolResult<IrcDetails>>;
 }
+type IrcRenderArgs = Partial<IrcParams>;
+/**
+ * Display-only transcript card for live IRC traffic: `irc:incoming` DMs
+ * delivered to this session, `irc:autoreply` side-channel replies sent on
+ * this session's behalf, and `irc:relay` observations of agent↔agent
+ * traffic. Shares the tool renderer's glyph + quote-border conventions so
+ * cards and `irc` tool output look identical in the transcript.
+ */
+export declare function createIrcMessageCard(card: {
+    kind: "incoming" | "autoreply" | "relay";
+    from?: string;
+    to?: string;
+    body?: string;
+    replyTo?: string;
+    timestamp?: number;
+}, getExpanded: () => boolean, uiTheme: Theme): Component;
+export declare const ircToolRenderer: {
+    inline: boolean;
+    mergeCallAndResult: boolean;
+    renderCall(args: IrcRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: IrcDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: IrcRenderArgs): Component;
+};
 export {};

package/dist/types/tools/job.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
 import type { Component } from "@prometheus-ai/tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import type { ToolSession } from "./index";
@@ -27,6 +27,13 @@ export interface JobToolDetails {
         status: CancelStatus;
     }[];
 }
+/**
+ * A poll snapshot where every watched job is still running and nothing was
+ * cancelled — pure "still waiting" noise once a newer poll exists. The TUI
+ * keeps such a block un-finalized (displaceable) so a follow-up `job` call
+ * replaces it instead of stacking another waiting frame in the transcript.
+ */
+export declare function isWaitingPollDetails(details: unknown): boolean;
 export declare class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
     #private;
     private readonly session;
@@ -43,7 +50,6 @@ export declare class JobTool implements AgentTool<typeof jobSchema, JobToolDetai
     readonly strict = true;
     readonly loadMode = "discoverable";
     constructor(session: ToolSession);
-    static createIf(session: ToolSession): JobTool | null;
     execute(_toolCallId: string, params: JobParams, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<JobToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<JobToolDetails>>;
 }
 interface JobRenderArgs {