@prometheus-ai/agent 0.5.3 → 0.5.8

package/dist/types/plan-mode/approved-plan.d.ts

@@ -1,9 +1,10 @@
 /** Shape forwarded from the plan-mode resolve handler to InteractiveMode's
  *  approval popup. Populated by the standing handler that the resolve tool
- *  dispatches to when the agent submits `resolve { action: "apply" }`. */
+ *  dispatches to when the agent submits `resolve { action: "apply" }`.
+ *  `planFilePath` is the agent-chosen `local://<slug>-plan.md` artifact — it is
+ *  never renamed on approval, so links to it stay valid for the session. */
 export interface PlanApprovalDetails {
     planFilePath: string;
-    finalPlanFilePath: string;
     title: string;
     planExists: boolean;
 }
@@ -39,11 +40,29 @@ export declare function resolvePlanTitle(input: {
  *  Replaces `-`/`_` separators with spaces and capitalizes the first letter.
  *  Returns an empty string when the input collapses to whitespace. */
 export declare function humanizePlanTitle(title: string): string;
-interface RenameApprovedPlanFileOptions {
+/** The `local://` URL a plan slug maps to. The agent writes the plan here and
+ *  passes the slug to `resolve`; the file is never renamed, so this URL — and
+ *  any hyperlink to it — stays valid for the life of the session. */
+export declare function planFileUrlForSlug(slug: string): string;
+export interface ResolveApprovedPlanInput {
+    /** The agent's `extra.title` from the `resolve` call, if any. */
+    suppliedTitle?: unknown;
+    /** The plan path recorded in plan-mode state (the entry default or a prior plan). */
+    statePlanFilePath: string;
+    /** Read a plan `local://` URL, returning null when the file does not exist. */
+    readPlan: (planUrl: string) => Promise<string | null>;
+    /** Optional fallback: list candidate plan `local://` URLs (newest first) so a
+     *  plan whose name can't be reconstructed (e.g. a dropped `extra.title`) is
+     *  still found. */
+    listPlanFiles?: () => Promise<string[]>;
+}
+export interface ResolvedApprovedPlan {
     planFilePath: string;
-    finalPlanFilePath: string;
-    getArtifactsDir: () => string | null;
-    getSessionId: () => string | null;
+    planContent: string;
+    title: string;
 }
-export declare function renameApprovedPlanFile(options: RenameApprovedPlanFileOptions): Promise<void>;
-export {};
+/** Locate the plan file the agent wrote and finalize its title — without
+ *  renaming anything. Tries, in order: the slug derived from `extra.title`
+ *  (`local://<slug>-plan.md`), the plan path from plan-mode state, then a scan
+ *  of recent plan files. Throws a `ToolError` guiding the agent when none exist. */
+export declare function resolveApprovedPlan(input: ResolveApprovedPlanInput): Promise<ResolvedApprovedPlan>;

package/dist/types/plan-mode/plan-protection.d.ts

@@ -3,10 +3,10 @@ import { type ProtectedToolContext } from "@prometheus-ai/agent-core/compaction/
  * Build a compaction protection matcher that keeps `read` results for the active
  * plan file intact through prune/shake — the plan analog of skill-read
  * protection. Matches both the canonical `local://PLAN.md` alias and the
- * session's current plan reference path (e.g. a titled `local://<title>.md`), so
- * the plan survives compaction whether the agent reads it by alias or by title.
+ * session's current plan reference path (the agent-chosen `local://<slug>-plan.md`),
+ * so the plan survives compaction whether the agent reads it by alias or by name.
  *
- * `getPlanReferencePath` is evaluated at match time so a mid-session retitle
- * (plan approval renames `PLAN.md` → `<title>.md`) is honored immediately.
+ * `getPlanReferencePath` is evaluated at match time so the plan path set on
+ * approval is honored immediately.
  */
 export declare function createPlanReadMatcher(getPlanReferencePath: () => string): (context: ProtectedToolContext) => boolean;

package/dist/types/registry/agent-lifecycle.d.ts

@@ -0,0 +1,51 @@
+/**
+ * AgentLifecycleManager - Owns the idle → parked → revived lifecycle of
+ * adopted subagents.
+ *
+ * The task executor hands a finished agent over via {@link AgentLifecycleManager.adopt};
+ * from then on the manager arms a TTL timer whenever the agent goes `idle`,
+ * parks it on expiry (disposes the live session, keeps the AgentRef +
+ * sessionFile), and revives it on demand through
+ * {@link AgentLifecycleManager.ensureLive}. Only this manager flips
+ * `parked` ↔ `idle`.
+ */
+import type { AgentSession } from "../session/agent-session";
+import { AgentRegistry } from "./agent-registry";
+export type AgentReviver = () => Promise<AgentSession>;
+export interface AdoptOptions {
+    /** TTL before an idle agent is parked. <= 0 disables parking. */
+    idleTtlMs: number;
+    /** Recreates a live AgentSession from the ref's sessionFile. Absent => not resumable after park (e.g. isolated runs). */
+    revive?: AgentReviver;
+}
+export declare class AgentLifecycleManager {
+    #private;
+    static global(): AgentLifecycleManager;
+    /** Reset the global manager. Test-only. */
+    static resetGlobalForTests(): void;
+    constructor(registry?: AgentRegistry);
+    /**
+     * Take ownership of a finished subagent. Caller has already set registry
+     * status to "idle". Arms the TTL timer (idleTtlMs <= 0 adopts without one).
+     */
+    adopt(id: string, opts: AdoptOptions): void;
+    /** True if the id is adopted (parked or live). */
+    has(id: string): boolean;
+    /** True while {@link park} is disposing this agent's session (lets dispose hooks distinguish park from teardown). */
+    isParking(id: string): boolean;
+    /**
+     * Dispose the live session, detach it from the registry, and mark the
+     * agent `parked`. No-op unless the id is adopted and live.
+     */
+    park(id: string): Promise<void>;
+    /**
+     * Return the live session, reviving from the sessionFile if parked.
+     * Throws a plain Error if the id is unknown or parked without a reviver.
+     * Concurrent calls share one in-flight revive.
+     */
+    ensureLive(id: string): Promise<AgentSession>;
+    /** Hard removal: dispose if live, unregister from registry, drop timers. */
+    release(id: string): Promise<void>;
+    /** Teardown everything (process exit / main session dispose). */
+    dispose(): Promise<void>;
+}

package/dist/types/registry/agent-registry.d.ts

@@ -1,13 +1,23 @@
 /**
- * AgentRegistry - Process-global registry of live AgentSession instances.
+ * AgentRegistry - Process-global registry of agents (the main session plus
+ * every subagent), keyed by stable id.
  *
- * Tracks every alive agent (the main session plus every subagent) so the
- * `irc` tool can address peers by id. Sessions are registered explicitly at
- * creation and removed when the owner releases them.
+ * Tracks each agent's status and (when live) its AgentSession so peers can be
+ * addressed by id (`irc`, `task resume`, `history://`). Sessions are
+ * registered explicitly at creation; finished agents stay registered as
+ * `idle` (live) or `parked` (session disposed, ref + sessionFile retained for
+ * revival) and are only removed on explicit release/teardown.
  */
 import type { AgentSession } from "../session/agent-session";
 export declare const MAIN_AGENT_ID = "Main";
-export type AgentStatus = "running" | "idle" | "completed" | "aborted";
+/**
+ * - `running`: a turn is in flight.
+ * - `idle`: live AgentSession in memory, awaiting work. Finished agents are
+ *   `idle`, not removed.
+ * - `parked`: session disposed; AgentRef + sessionFile retained, revivable.
+ * - `aborted`: hard-killed, terminal.
+ */
+export type AgentStatus = "running" | "idle" | "parked" | "aborted";
 export type AgentKind = "main" | "sub";
 export interface AgentRef {
     id: string;
@@ -15,10 +25,13 @@ export interface AgentRef {
     kind: AgentKind;
     parentId?: string;
     status: AgentStatus;
+    /** Null exactly when parked/aborted. */
     session: AgentSession | null;
     sessionFile: string | null;
     createdAt: number;
     lastActivity: number;
+    /** Short gist of what the agent is currently doing (latest intent or tool), for the work-aware roster. Display-only. */
+    activity?: string;
 }
 export type RegistryEvent = {
     type: "registered";
@@ -47,6 +60,21 @@ export declare class AgentRegistry {
     static resetGlobalForTests(): void;
     register(input: RegisterInput): AgentRef;
     setStatus(id: string, status: AgentStatus): void;
+    /**
+     * Record a short activity gist for the work-aware roster. Display-only and
+     * read on demand (`irc list`, peer roster), so it emits no event — keeping
+     * the per-tool-call update rate off the registry listener path (same as
+     * `attachSession`, which also bumps `lastActivity` without emitting). Only a
+     * `running` agent has current work: a heartbeat for any other status is
+     * dropped, so a late progress flush can't resurrect activity on a ref that
+     * `setStatus` just cleared. Every running heartbeat refreshes `lastActivity`
+     * — even when the gist text is unchanged — so the roster's "active … ago" and
+     * recency sort track real work, not just the last status change.
+     * The gist is normalized to one bounded line (`oneLineLabel`) so model-derived
+     * intent text can neither break the roster nor smuggle terminal escapes —
+     * every caller is safe without sanitizing at its own call site.
+     */
+    setActivity(id: string, activity: string): void;
     attachSession(id: string, session: AgentSession, sessionFile?: string | null): void;
     detachSession(id: string): void;
     unregister(id: string): void;

package/dist/types/sdk.d.ts

@@ -6,6 +6,7 @@ import { type PromptTemplate } from "./config/prompt-templates";
 import { Settings, type SkillsSettings } from "./config/settings";
 import "./discovery";
 import { type CustomCommandsLoadResult } from "./extensibility/custom-commands";
+import { type ToolPathWithSource } from "./extensibility/custom-tools";
 import type { CustomTool } from "./extensibility/custom-tools/types";
 import { type ExtensionFactory, type ExtensionUIContext, type LoadExtensionsResult, type ToolDefinition } from "./extensibility/extensions";
 import { type Skill, type SkillWarning } from "./extensibility/skills";
@@ -13,7 +14,7 @@ import { type FileSlashCommand } from "./extensibility/slash-commands";
 import type { HindsightSessionState } from "./hindsight/state";
 import { type LocalProtocolOptions } from "./internal-urls";
 import { MCPManager, type MCPToolsLoadResult } from "./mcp";
-import { type MnemopiSessionState } from "./mnemopi/state";
+import type { MnemopiSessionState } from "./mnemopi/state";
 import { AgentRegistry } from "./registry/agent-registry";
 import { AgentSession } from "./session/agent-session";
 import { AuthStorage } from "./session/auth-storage";
@@ -47,10 +48,12 @@ export interface CreateAgentSessionOptions {
         thinkingLevel?: ThinkingLevel;
     }>;
     /** System prompt blocks. Array replaces default, function receives default blocks and returns final blocks. */
-    systemPrompt?: string[] | ((defaultPrompt: string[]) => string[]);
+    systemPrompt?: string | string[] | ((defaultPrompt: string[]) => string | string[]);
     /** Optional provider-facing session identifier for prompt caches and sticky auth selection.
      * Keeps persisted session files isolated while reusing provider-side caches. */
     providerSessionId?: string;
+    /** Optional provider-facing prompt cache key, distinct from request lineage. */
+    providerPromptCacheKey?: string;
     /** Custom tools to register (in addition to built-in tools). Accepts both CustomTool and ToolDefinition. */
     customTools?: (CustomTool | ToolDefinition)[];
     /** Inline extensions (merged with discovery). */
@@ -60,10 +63,41 @@ export interface CreateAgentSessionOptions {
     /** Disable extension discovery (explicit paths still load). */
     disableExtensionDiscovery?: boolean;
     /**
-     * Pre-loaded extensions (skips file discovery).
-     * @internal Used by CLI when extensions are loaded early to parse custom flags.
+     * Pre-loaded extensions (skips file discovery and the per-session factory
+     * call). Used by the CLI when extensions are loaded early to parse custom
+     * flags — the same process owns the returned instances, so reusing them is
+     * safe.
+     *
+     * NEVER pass this across session boundaries (e.g. parent → subagent).
+     * `Extension` instances close over a parent-bound `ExtensionAPI` (cwd,
+     * eventBus, runtime), and reusing them would route tools/handlers/commands
+     * back through the parent. For subagents, forward
+     * {@link preloadedExtensionPaths} instead.
+     *
+     * @internal
      */
     preloadedExtensions?: LoadExtensionsResult;
+    /**
+     * Pre-discovered extension source paths. When provided, the filesystem-scan
+     * inside `discoverExtensionPaths()` is skipped — the session still calls
+     * `loadExtensions()` itself so each `Extension` is bound to THIS session's
+     * `ExtensionAPI` (cwd, eventBus, runtime).
+     *
+     * This is the safe pass-through for parent → subagent forwarding.
+     */
+    preloadedExtensionPaths?: string[];
+    /**
+     * Pre-discovered custom-tool source paths from `.prometheus/tools/`, `.claude/tools/`,
+     * plugins, etc. When provided, the filesystem-scan inside
+     * `discoverCustomToolPaths()` is skipped — subagents inherit the parent's
+     * scan result and call `loadCustomTools()` themselves so each session binds
+     * tools to its OWN `CustomToolAPI` (cwd, exec, pushPendingAction, UI).
+     *
+     * Forwarding the loaded `LoadedCustomTool[]` instances directly would reuse
+     * the parent's session-bound API and route tool execution back through the
+     * parent — wrong for isolated tasks and for pending-action routing.
+     */
+    preloadedCustomToolPaths?: ToolPathWithSource[];
     /** Shared event bus for tool/extension communication. Default: creates new bus. */
     eventBus?: EventBus;
     /** Skills. Default: discovered from multiple locations */
@@ -176,6 +210,14 @@ export declare function discoverAuthStorage(agentDir?: string): Promise<AuthStor
  * Discover extensions from cwd.
  */
 export declare function discoverExtensions(cwd?: string): Promise<LoadExtensionsResult>;
+/**
+ * Path-only counterpart of {@link loadSessionExtensions}: the FS-heavy scan
+ * without the per-session module load. Subagents reuse the parent's path list
+ * (cached on {@link ToolSession.extensionPaths}) and rebuild Extension
+ * instances themselves so each session's `ExtensionAPI` (cwd, eventBus,
+ * runtime) is its own.
+ */
+export declare function discoverSessionExtensionPaths(options: Pick<CreateAgentSessionOptions, "disableExtensionDiscovery" | "additionalExtensionPaths">, cwd: string, settings: Settings): Promise<string[]>;
 /**
  * Load the discovered/configured extensions for a session — everything {@link
  * createAgentSession} would load except the inline factory extensions it appends

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

@@ -1,5 +1,5 @@
 import type { SecretEntry } from "./obfuscator";
-export { deobfuscateSessionContext, obfuscateMessages, type SecretEntry, SecretObfuscator } from "./obfuscator";
+export { deobfuscateSessionContext, obfuscateMessages, obfuscateProviderContext, obfuscateProviderTools, type SecretEntry, SecretObfuscator, } from "./obfuscator";
 /**
  * Load secrets from project-local and global secrets.yml files.
  * Project-local entries override global entries with matching content.

package/dist/types/secrets/obfuscator.d.ts

@@ -1,5 +1,5 @@
-import type { Message } from "@prometheus-ai/ai";
-import type { SessionContext } from "../session/session-manager";
+import type { Context, Message, Tool } from "@prometheus-ai/ai";
+import type { SessionContext } from "../session/session-context";
 export interface SecretEntry {
     type: "plain" | "regex";
     content: string;
@@ -17,7 +17,13 @@ export declare class SecretObfuscator {
     deobfuscate(text: string): string;
     /** Deep-walk an object, deobfuscating all string values. */
     deobfuscateObject<T>(obj: T): T;
+    /** Deep-walk an object, obfuscating all string values. */
+    obfuscateObject<T>(obj: T): T;
 }
 export declare function deobfuscateSessionContext(sessionContext: SessionContext, obfuscator: SecretObfuscator | undefined): SessionContext;
-/** Obfuscate all text content in LLM messages (for outbound interception). */
+/** Obfuscate all string content in LLM messages (for outbound interception). */
 export declare function obfuscateMessages(obfuscator: SecretObfuscator, messages: Message[]): Message[];
+/** Obfuscate provider request context without walking live tool schema instances. */
+export declare function obfuscateProviderContext(obfuscator: SecretObfuscator | undefined, context: Context): Context;
+/** Convert tool schemas to wire JSON Schema before obfuscating provider-visible strings. */
+export declare function obfuscateProviderTools(obfuscator: SecretObfuscator | undefined, tools: Tool[] | undefined): Tool[] | undefined;