@rudderjs/ai 1.3.0 → 1.4.0

package/README.md

@@ -231,7 +231,7 @@ new Researcher().asTool({
 })
 ```
 
-The wrapped subagent runs via `prompt()` (non-streaming) regardless of how the parent was invoked. Token deltas from the subagent are not surfaced as `tool-update` chunks in the parent stream — if you need that, write the wrapping tool by hand and drive `agent.stream(...)` yourself.
+The wrapped subagent runs via `prompt()` (non-streaming) by default — to surface inner-agent progress as `tool-update` chunks in the parent stream, pass `streaming: true` (or a custom `(chunk) => SubAgentUpdate | null` projector). When the sub-agent's model emits a *client* tool call, opt into the suspend/resume protocol with `suspendable: { runStore }` — the parent loop halts with the inner agent's `pendingClientToolCalls`, the snapshot persists in the run store, and the host resumes via `Agent.resumeAsTool(subRunId, browserResults, { runStore, agent })`. See `docs/guide/ai.md` for the full flow. `InMemorySubAgentRunStore` works for tests; `CachedSubAgentRunStore` plugs into `@rudderjs/cache` for cross-process persistence. Suspend without streaming throws at builder time.
 
 ### Tool execution context
 
@@ -252,7 +252,7 @@ const myTool = toolDefinition({
 })
 ```
 
-The primary consumer is `@rudderjs/panels`'s `runAgentTool`, which uses
+The primary consumer is `@pilotiq-pro/ai`'s `runAgentTool`, which uses
 `ctx.toolCallId` to correlate sub-agent suspensions with the parent's
 `run_agent` call (see "Pausing the loop from a server tool" below).
 
@@ -604,6 +604,21 @@ const response = await agent('You are helpful.').prompt('Follow up question', {
 
 Works with both `.prompt()` and `.stream()`. History messages are prepended after the system prompt, before the current user message.
 
+### Auto-persist conversations
+
+Override `conversational()` on an agent class to auto-load and auto-save threads without threading user ids through every call site:
+
+```ts
+class ChatAgent extends Agent {
+  conversational() { return { user: Auth.user()?.id } }
+}
+
+await new ChatAgent().prompt('Hi')         // auto-loads + auto-saves
+await new ChatAgent().prompt('Continue?')  // resumes same thread (per user + class)
+```
+
+Returning `false` (the default) keeps the agent stateless. Async returns are awaited; an optional `historyLimit` caps loaded messages. Per-call escape hatches: `prompt(input, { conversation: false })` or `agent.forUser(id).prompt()` / `agent.continue(id).prompt()` — explicit always wins. See `docs/guide/ai.md` for the full precedence chain.
+
 ### Model Selection
 
 Configure available models for user selection (used by `@rudderjs/panels` chat UI):

package/boost/guidelines.md

@@ -91,7 +91,7 @@ class Planner extends Agent implements HasTools {
 }
 ```
 
-The subagent runs via `prompt()` (non-streaming); for `tool-update` chunks from a streaming subagent, write the wrapping tool by hand.
+By default the subagent runs via `prompt()` (non-streaming). Pass `streaming: true` to surface inner progress as `tool-update` chunks (default projection emits `agent_start` / `tool_call` / `agent_done`); pass `(chunk) => SubAgentUpdate | null` for a custom projector. To propagate inner client-tool calls upward through the parent loop, also pass `suspendable: { runStore }` (suspend without streaming throws at builder time) — the host's continuation calls `Agent.resumeAsTool(subRunId, results, { runStore, agent })` to resume the inner agent with the browser's results. `InMemorySubAgentRunStore` works for tests; `CachedSubAgentRunStore` plugs into `@rudderjs/cache` for multi-worker persistence.
 
 ### Middleware
 
@@ -135,6 +135,18 @@ const response = await myAgent.forUser('user-123').prompt('Hello')  // creates c
 const follow = await myAgent.continue(response.conversationId).prompt('Follow up')
 ```
 
+For chat agents that should always auto-persist for the active user, override `conversational()` on the class — `agent.prompt(input)` then auto-loads + auto-saves without each caller passing the user id:
+
+```ts
+class ChatAgent extends Agent {
+  conversational() { return { user: Auth.user()?.id } }   // null user → opt-out
+}
+await new ChatAgent().prompt('Hi')          // auto-loads thread
+await new ChatAgent().prompt('still you?')  // resumes per (user, class)
+```
+
+Returning `false` (default) keeps the agent stateless. Optional `historyLimit: N` caps loaded messages. Per-call `{ conversation: false }` opts out; `forUser`/`continue` always win.
+
 ### Streaming
 
 Use `.stream()` for real-time token delivery:

package/dist/agent.d.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import type { ServerToolBuilder } from './tool.js';
 import { QueuedPromptBuilder } from './queue-job.js';
-import type { AgentPromptOptions, AiMessage, AiMiddleware, AgentResponse, AgentStep, AgentStreamResponse, AnyTool, CacheableConfig, ConversationStore, HasMiddleware, HasTools, PrepareStepResult, StopCondition } from './types.js';
+import type { SubAgentRunStore } from './sub-agent-run-store.js';
+import type { AgentPromptOptions, AiMessage, AiMiddleware, AgentResponse, AgentStep, AgentStreamResponse, AnyTool, CacheableConfig, ConversationalSpec, ConversationStore, SubAgentUpdate, HasMiddleware, HasTools, PrepareStepResult, StopCondition, StreamChunk } from './types.js';
 /** Stop after N steps */
 export declare function stepCountIs(n: number): StopCondition;
 /** Stop when a specific tool is called in the latest step */
@@ -51,6 +52,34 @@ export declare abstract class Agent {
      * }
      */
     cacheable(): CacheableConfig | undefined;
+    /**
+     * Opt into auto-persisted conversation behavior. Override on a subclass
+     * to declare *which* user owns the thread and (optionally) which
+     * specific thread, and the framework will load history before each
+     * `prompt()`/`stream()` call and append the new turn after it — without
+     * any caller having to remember `forUser()` / `continue()`.
+     *
+     * Returning `false` (the default) disables auto-persist; the agent runs
+     * stateless. Returning a {@link ConversationalSpec} opts in:
+     *
+     * @example
+     * class ChatAgent extends Agent {
+     *   conversational() {
+     *     return { user: Auth.user()?.id }   // null user → falsy → opt-out
+     *   }
+     * }
+     *
+     * await new ChatAgent().prompt('Hi')          // auto-loads + auto-saves
+     *
+     * **Precedence (high → low):**
+     * 1. Explicit `agent.forUser(id).prompt()` / `agent.continue(id).prompt()`
+     * 2. Per-call `prompt(input, { conversation: false | {...} })`
+     * 3. This method's return value
+     *
+     * Async returns are supported — useful when the user identity is fetched
+     * from an async DI binding.
+     */
+    conversational(): false | ConversationalSpec | Promise<false | ConversationalSpec>;
     /**
      * Default for `AgentPromptOptions.parallelTools`. When `true` (default),
      * multiple tool calls within a single step run their `execute()` functions
@@ -102,15 +131,57 @@ export declare abstract class Agent {
         inputSchema: TInput;
         prompt: (input: z.infer<TInput>) => string;
         modelOutput?: (response: AgentResponse) => string | Promise<string>;
+        streaming?: AsToolStreamingOption;
+        suspendable?: AsToolSuspendableOption;
     }): ServerToolBuilder<z.infer<TInput>, AgentResponse>;
     asTool(options: {
         name: string;
         description: string;
         modelOutput?: (response: AgentResponse) => string | Promise<string>;
+        streaming?: AsToolStreamingOption;
+        suspendable?: AsToolSuspendableOption;
     }): ServerToolBuilder<{
         prompt: string;
     }, AgentResponse>;
+    /**
+     * Resume a sub-agent run that previously paused with
+     * `pauseForClientTools` (typically from {@link Agent.asTool} with
+     * `suspendable: { runStore }` set). Loads the snapshot, validates the
+     * incoming tool-result ids against the pending set, and re-runs the
+     * inner loop with those results appended.
+     *
+     * Returns either a `'completed'` result (the inner agent finished) or
+     * a `'paused'` continuation pointing at a fresh `subRunId` for the
+     * next round-trip.
+     *
+     * @example
+     * const r = await Agent.resumeAsTool(subRunId, browserResults, { runStore, agent: subAgent })
+     * if (r.kind === 'completed') {
+     *   feedToolResultBackToParent(r.response.text)
+     * } else {
+     *   emitPendingClientToolsSse(r.subRunId, r.pendingToolCallIds)
+     * }
+     */
+    static resumeAsTool(subRunId: string, clientToolResults: ReadonlyArray<{
+        toolCallId: string;
+        result: unknown;
+    }>, options: {
+        runStore: SubAgentRunStore;
+        agent: Agent;
+    }): Promise<{
+        kind: 'completed';
+        response: AgentResponse;
+    } | {
+        kind: 'paused';
+        subRunId: string;
+        pendingToolCallIds: string[];
+    }>;
 }
+type ChunkProjector = (chunk: StreamChunk) => SubAgentUpdate | null;
+type AsToolStreamingOption = boolean | ChunkProjector;
+type AsToolSuspendableOption = {
+    runStore: SubAgentRunStore;
+};
 /**
  * Wraps an Agent to add conversation memory.
  * Created via `agent.forUser(id)` or `agent.continue(id)`.
@@ -124,6 +195,13 @@ export declare class ConversableAgent {
     continue(conversationId: string): this;
     prompt(input: string, options?: AgentPromptOptions): Promise<AgentResponse>;
     stream(input: string, options?: AgentPromptOptions): AgentStreamResponse;
+    /**
+     * Translate the wrapper's explicit-form state (`forUser` / `continue`)
+     * into a {@link ConversationalSpec}. The explicit chain bypasses the
+     * agent's `conversational()` declaration entirely — `forUser` always
+     * wins over class defaults.
+     */
+    private toSpec;
 }
 /**
  * Create an anonymous agent inline.
@@ -160,4 +238,5 @@ export interface InvalidToolArgumentsError {
         message: string;
     }>;
 }
+export {};
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { AiRegistry } from './registry.js';
-import { isPauseForClientToolsChunk, toolDefinition, toolToSchema } from './tool.js';
+import { isPauseForClientToolsChunk, pauseForClientTools, toolDefinition, toolToSchema } from './tool.js';
 import { attachmentsToContentParts, getMessageText } from './attachment.js';
 import { QueuedPromptBuilder } from './queue-job.js';
+import { resolveAutoPersistSpec, runWithPersistence, runWithPersistenceStreaming, } from './conversation-persistence.js';
 import { runOnConfig, runOnChunk, runOnBeforeToolCall, runOnAfterToolCall, runSequential, runOnUsage, runOnAbort, runOnError, } from './middleware.js';
 // ─── AI Observer (lazy accessor) ─────────────────────────
 function _getAiObservers() {
@@ -79,6 +80,36 @@ export class Agent {
      * }
      */
     cacheable() { return undefined; }
+    /**
+     * Opt into auto-persisted conversation behavior. Override on a subclass
+     * to declare *which* user owns the thread and (optionally) which
+     * specific thread, and the framework will load history before each
+     * `prompt()`/`stream()` call and append the new turn after it — without
+     * any caller having to remember `forUser()` / `continue()`.
+     *
+     * Returning `false` (the default) disables auto-persist; the agent runs
+     * stateless. Returning a {@link ConversationalSpec} opts in:
+     *
+     * @example
+     * class ChatAgent extends Agent {
+     *   conversational() {
+     *     return { user: Auth.user()?.id }   // null user → falsy → opt-out
+     *   }
+     * }
+     *
+     * await new ChatAgent().prompt('Hi')          // auto-loads + auto-saves
+     *
+     * **Precedence (high → low):**
+     * 1. Explicit `agent.forUser(id).prompt()` / `agent.continue(id).prompt()`
+     * 2. Per-call `prompt(input, { conversation: false | {...} })`
+     * 3. This method's return value
+     *
+     * Async returns are supported — useful when the user identity is fetched
+     * from an async DI binding.
+     */
+    conversational() {
+        return false;
+    }
     /**
      * Default for `AgentPromptOptions.parallelTools`. When `true` (default),
      * multiple tool calls within a single step run their `execute()` functions
@@ -88,11 +119,15 @@ export class Agent {
     parallelTools() { return true; }
     /** Run the agent with a prompt (non-streaming) */
     async prompt(input, options) {
+        const spec = await resolveAutoPersistSpec(() => this.conversational(), options?.conversation);
+        if (spec) {
+            return runWithPersistence(spec, this.constructor.name, resolveConversationStore, input, options, (effOptions) => runAgentLoop(this, input, effOptions));
+        }
         return runAgentLoop(this, input, options);
     }
     /** Run the agent with a prompt (streaming) */
     stream(input, options) {
-        return runAgentLoopStreaming(this, input, options);
+        return runStreamWithMaybeAutoPersist(this, input, options);
     }
     /** Queue the prompt for background execution */
     queue(input, options) {
@@ -107,17 +142,201 @@ export class Agent {
         return new ConversableAgent(this).continue(conversationId);
     }
     asTool(options) {
+        if (options.suspendable && !options.streaming) {
+            throw new Error('[RudderJS AI] asTool: `suspendable` requires `streaming: true` (or a projector). Silent suspend would leave the parent UI with no progress signal between sub-agent invocations.');
+        }
         const schema = options.inputSchema ?? z.object({ prompt: z.string() });
         const promptOf = options.prompt ?? ((input) => input.prompt);
         const modelOutput = options.modelOutput ?? ((response) => response.text);
+        if (!options.streaming) {
+            // 1.2.0 zero-config path — single prompt() call, single AgentResponse out.
+            return toolDefinition({
+                name: options.name,
+                description: options.description,
+                inputSchema: schema,
+            })
+                .server((input) => this.prompt(promptOf(input)))
+                .modelOutput(modelOutput);
+        }
+        const project = options.streaming === true ? defaultSubAgentProjector : options.streaming;
+        const innerAgent = this; // eslint-disable-line @typescript-eslint/no-this-alias
+        const agentName = options.name;
+        const suspendable = options.suspendable;
+        const generatorExecute = async function* (input) {
+            const userPrompt = promptOf(input);
+            yield { kind: 'agent_start', agentName };
+            const streamOpts = suspendable
+                ? { toolCallStreamingMode: 'stop-on-client-tool' }
+                : undefined;
+            const { stream, response } = innerAgent.stream(userPrompt, streamOpts);
+            for await (const chunk of stream) {
+                const update = project(chunk);
+                if (update)
+                    yield update;
+            }
+            const result = await response;
+            if (suspendable &&
+                result.finishReason === 'client_tool_calls' &&
+                result.pendingClientToolCalls?.length) {
+                const subRunId = generateSubRunId();
+                const snapshot = {
+                    messages: buildSubAgentSnapshotMessages(userPrompt, result),
+                    pendingToolCallIds: result.pendingClientToolCalls.map((tc) => tc.id),
+                    stepsSoFar: result.steps.length,
+                    tokensSoFar: result.usage?.totalTokens ?? 0,
+                };
+                await suspendable.runStore.store(subRunId, snapshot);
+                yield { kind: 'subagent_paused', subRunId, pendingToolCallIds: snapshot.pendingToolCallIds };
+                yield pauseForClientTools(result.pendingClientToolCalls, subRunId);
+                // Unreachable — the parent loop halts iteration after the pause chunk.
+                return undefined;
+            }
+            yield {
+                kind: 'agent_done',
+                steps: result.steps.length,
+                tokens: result.usage?.totalTokens ?? 0,
+            };
+            return result;
+        };
         return toolDefinition({
             name: options.name,
             description: options.description,
             inputSchema: schema,
         })
-            .server((input) => this.prompt(promptOf(input)))
+            .server(generatorExecute)
             .modelOutput(modelOutput);
     }
+    /**
+     * Resume a sub-agent run that previously paused with
+     * `pauseForClientTools` (typically from {@link Agent.asTool} with
+     * `suspendable: { runStore }` set). Loads the snapshot, validates the
+     * incoming tool-result ids against the pending set, and re-runs the
+     * inner loop with those results appended.
+     *
+     * Returns either a `'completed'` result (the inner agent finished) or
+     * a `'paused'` continuation pointing at a fresh `subRunId` for the
+     * next round-trip.
+     *
+     * @example
+     * const r = await Agent.resumeAsTool(subRunId, browserResults, { runStore, agent: subAgent })
+     * if (r.kind === 'completed') {
+     *   feedToolResultBackToParent(r.response.text)
+     * } else {
+     *   emitPendingClientToolsSse(r.subRunId, r.pendingToolCallIds)
+     * }
+     */
+    static async resumeAsTool(subRunId, clientToolResults, options) {
+        const snapshot = await options.runStore.consume(subRunId);
+        if (!snapshot) {
+            throw new Error(`[RudderJS AI] resumeAsTool: subRunId "${subRunId}" expired or never existed.`);
+        }
+        // Forgery guard — every incoming tool-result id must be in the pending set.
+        const pending = new Set(snapshot.pendingToolCallIds);
+        const seen = new Set();
+        for (const r of clientToolResults) {
+            if (!pending.has(r.toolCallId)) {
+                throw new Error(`[RudderJS AI] resumeAsTool: toolCallId "${r.toolCallId}" was not in the pending set.`);
+            }
+            if (seen.has(r.toolCallId)) {
+                throw new Error(`[RudderJS AI] resumeAsTool: duplicate result for toolCallId "${r.toolCallId}".`);
+            }
+            seen.add(r.toolCallId);
+        }
+        // Append client tool-result messages to the snapshot, in incoming order.
+        const messages = [...snapshot.messages];
+        for (const r of clientToolResults) {
+            messages.push({
+                role: 'tool',
+                content: typeof r.result === 'string' ? r.result : JSON.stringify(r.result),
+                toolCallId: r.toolCallId,
+            });
+        }
+        const result = await options.agent.prompt('', {
+            messages,
+            toolCallStreamingMode: 'stop-on-client-tool',
+        });
+        if (result.finishReason === 'client_tool_calls' &&
+            result.pendingClientToolCalls?.length) {
+            const newSubRunId = generateSubRunId();
+            const newSnapshot = {
+                messages: buildResumeSnapshotMessages(messages, result),
+                pendingToolCallIds: result.pendingClientToolCalls.map((tc) => tc.id),
+                stepsSoFar: snapshot.stepsSoFar + result.steps.length,
+                tokensSoFar: snapshot.tokensSoFar + (result.usage?.totalTokens ?? 0),
+                ...(snapshot.meta !== undefined ? { meta: snapshot.meta } : {}),
+            };
+            await options.runStore.store(newSubRunId, newSnapshot);
+            return {
+                kind: 'paused',
+                subRunId: newSubRunId,
+                pendingToolCallIds: newSnapshot.pendingToolCallIds,
+            };
+        }
+        return { kind: 'completed', response: result };
+    }
+}
+/**
+ * Default projection from inner-agent stream chunks to {@link SubAgentUpdate}
+ * events. Emits one `tool_call` per inner `tool-call` chunk; everything
+ * else is suppressed (the wrapping execute emits the `agent_start` /
+ * `agent_done` bookends and the suspend path emits `subagent_paused`).
+ *
+ * Hosts wanting different cadence (e.g. surfacing `text-delta` previews
+ * or per-step usage) pass `streaming: chunk => …` and own the discriminator.
+ */
+function defaultSubAgentProjector(chunk) {
+    if (chunk.type === 'tool-call' && chunk.toolCall?.name) {
+        return {
+            kind: 'tool_call',
+            tool: chunk.toolCall.name,
+            ...(chunk.toolCall.arguments ? { args: chunk.toolCall.arguments } : {}),
+        };
+    }
+    return null;
+}
+/**
+ * Reconstruct the inner-agent message history at the point the loop
+ * paused, so a subsequent {@link Agent.resumeAsTool} can rerun the loop
+ * with the appended client tool results. The shape is `[user, …(message
+ * + serverToolResults)*]` — system messages are omitted because the
+ * `messages` mode of the agent loop prepends `system` itself.
+ *
+ * Each step's `message` includes ALL `toolCalls` (server + client).
+ * Server-side `toolResults` are interleaved; client-side calls remain
+ * unfulfilled until resume appends their results.
+ */
+function buildSubAgentSnapshotMessages(userPrompt, response) {
+    const out = [{ role: 'user', content: userPrompt }];
+    for (const step of response.steps) {
+        out.push(step.message);
+        for (const tr of step.toolResults) {
+            const resultStr = typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result);
+            out.push({ role: 'tool', content: resultStr, toolCallId: tr.toolCallId });
+        }
+    }
+    return out;
+}
+/**
+ * Snapshot reconstruction for a resume-time pause. The `priorMessages`
+ * already include the original user prompt + every step prior to the
+ * resume call. Append the freshly-completed steps' messages and any
+ * server-side tool results so the next resume sees the full history.
+ */
+function buildResumeSnapshotMessages(priorMessages, response) {
+    const out = [...priorMessages];
+    for (const step of response.steps) {
+        out.push(step.message);
+        for (const tr of step.toolResults) {
+            const resultStr = typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result);
+            out.push({ role: 'tool', content: resultStr, toolCallId: tr.toolCallId });
+        }
+    }
+    return out;
+}
+function generateSubRunId() {
+    if (typeof globalThis.crypto?.randomUUID === 'function')
+        return globalThis.crypto.randomUUID();
+    return `sub-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
 }
 // ─── Conversable Agent (conversation persistence) ───────
 /**
@@ -140,84 +359,35 @@ export class ConversableAgent {
         return this;
     }
     async prompt(input, options) {
-        const store = resolveConversationStore();
-        if (!store)
-            throw new Error('[RudderJS AI] No ConversationStore registered. Register one via the DI container with key "ai.conversations".');
-        // Load or create conversation
-        let history = options?.history ?? [];
-        if (this._conversationId) {
-            history = [...(await store.load(this._conversationId)), ...history];
-        }
-        else {
-            const meta = this._userId ? { userId: this._userId } : undefined;
-            this._conversationId = await store.create(undefined, meta);
-        }
-        const response = await runAgentLoop(this.agent, input, { ...options, history });
-        // Persist messages
-        const newMessages = [
-            { role: 'user', content: input },
-            ...response.steps.flatMap(s => {
-                const msgs = [s.message];
-                for (const tr of s.toolResults) {
-                    const resultStr = typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result);
-                    msgs.push({ role: 'tool', content: resultStr, toolCallId: tr.toolCallId });
-                }
-                return msgs;
-            }),
-        ];
-        await store.append(this._conversationId, newMessages);
-        return { text: response.text, steps: response.steps, usage: response.usage, conversationId: this._conversationId };
+        const spec = this.toSpec();
+        return runWithPersistence(spec, this.agent.constructor.name, resolveConversationStore, input, options, (effOptions) => runAgentLoop(this.agent, input, effOptions)).then((r) => {
+            // Track the resolved id back on the wrapper so a subsequent
+            // `wrapper.prompt()` call resumes the same thread.
+            if (r.conversationId)
+                this._conversationId = r.conversationId;
+            return r;
+        });
     }
     stream(input, options) {
-        const store = resolveConversationStore();
-        if (!store)
-            throw new Error('[RudderJS AI] No ConversationStore registered. Register one via the DI container with key "ai.conversations".');
-        // We need to handle async setup, so wrap the streaming
-        let resolveReady;
-        const ready = new Promise(r => { resolveReady = r; });
-        let loadedHistory = [];
-        let convId = this._conversationId;
-        // Kick off async setup
-        const setupPromise = (async () => {
-            if (convId) {
-                loadedHistory = await store.load(convId);
-            }
-            else {
-                const meta = this._userId ? { userId: this._userId } : undefined;
-                convId = await store.create(undefined, meta);
-                this._conversationId = convId;
-            }
-            resolveReady();
-        })();
-        let resolveResponse;
-        const responsePromise = new Promise(r => { resolveResponse = r; });
-        const self = this; // eslint-disable-line @typescript-eslint/no-this-alias
-        const storeRef = store;
-        async function* generateStream() {
-            await setupPromise;
-            const history = [...loadedHistory, ...(options?.history ?? [])];
-            const inner = runAgentLoopStreaming(self.agent, input, { ...options, history });
-            for await (const chunk of inner.stream) {
-                yield chunk;
-            }
-            const response = await inner.response;
-            // Persist messages
-            const newMessages = [
-                { role: 'user', content: input },
-                ...response.steps.flatMap(s => {
-                    const msgs = [s.message];
-                    for (const tr of s.toolResults) {
-                        const resultStr = typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result);
-                        msgs.push({ role: 'tool', content: resultStr, toolCallId: tr.toolCallId });
-                    }
-                    return msgs;
-                }),
-            ];
-            await storeRef.append(convId, newMessages);
-            const result = { text: response.text, steps: response.steps, usage: response.usage, conversationId: convId };
-            resolveResponse(result);
-        }
-        return { stream: generateStream(), response: responsePromise };
+        const spec = this.toSpec();
+        const persisted = runWithPersistenceStreaming(spec, this.agent.constructor.name, resolveConversationStore, input, options, (effOptions) => runAgentLoopStreaming(this.agent, input, effOptions));
+        // Update the wrapper's id once the run completes.
+        persisted.response.then((r) => { if (r.conversationId)
+            this._conversationId = r.conversationId; }, () => { });
+        return persisted;
+    }
+    /**
+     * Translate the wrapper's explicit-form state (`forUser` / `continue`)
+     * into a {@link ConversationalSpec}. The explicit chain bypasses the
+     * agent's `conversational()` declaration entirely — `forUser` always
+     * wins over class defaults.
+     */
+    toSpec() {
+        if (this._conversationId)
+            return { user: this._userId ?? '', id: this._conversationId };
+        if (this._userId)
+            return { user: this._userId };
+        throw new Error('[RudderJS AI] ConversableAgent requires forUser() or continue() to be called before prompt().');
     }
 }
 // ─── Anonymous Agent ─────────────────────────────────────
@@ -267,6 +437,76 @@ export function setConversationStore(store) {
 function resolveConversationStore() {
     return _conversationStore;
 }
+/**
+ * Streaming counterpart of `Agent.prompt`'s auto-persist branch. The spec
+ * resolution is async (since `conversational()` may return a Promise), so
+ * we defer the decision into the outer wrapper that handles the inner
+ * stream's setup the same way `runWithPersistenceStreaming` does for the
+ * persisted path.
+ */
+function runStreamWithMaybeAutoPersist(a, input, options) {
+    // Synchronous fast path — most agents don't override `conversational()`,
+    // so we'd pay an extra microtask boundary on every streaming call. Bail
+    // out cheaply when we can prove the call is stateless.
+    const declared = a.conversational();
+    const isFast = (options?.conversation === false ||
+        (declared === false && (options?.conversation === undefined)));
+    if (isFast) {
+        return runAgentLoopStreaming(a, input, options);
+    }
+    // Async path — resolve the spec, then dispatch to the persisted or plain stream.
+    let resolveResp;
+    let rejectResp;
+    const responsePromise = new Promise((res, rej) => { resolveResp = res; rejectResp = rej; });
+    async function* outer() {
+        let spec;
+        try {
+            spec = await resolveAutoPersistSpec(() => a.conversational(), options?.conversation);
+        }
+        catch (err) {
+            rejectResp(err);
+            throw err;
+        }
+        if (!spec) {
+            const inner = runAgentLoopStreaming(a, input, options);
+            try {
+                for await (const chunk of inner.stream)
+                    yield chunk;
+            }
+            catch (err) {
+                rejectResp(err);
+                throw err;
+            }
+            try {
+                const r = await inner.response;
+                resolveResp(r);
+            }
+            catch (err) {
+                rejectResp(err);
+                throw err;
+            }
+            return;
+        }
+        const persisted = runWithPersistenceStreaming(spec, a.constructor.name, resolveConversationStore, input, options, (effOptions) => runAgentLoopStreaming(a, input, effOptions));
+        try {
+            for await (const chunk of persisted.stream)
+                yield chunk;
+        }
+        catch (err) {
+            rejectResp(err);
+            throw err;
+        }
+        try {
+            const r = await persisted.response;
+            resolveResp(r);
+        }
+        catch (err) {
+            rejectResp(err);
+            throw err;
+        }
+    }
+    return { stream: outer(), response: responsePromise };
+}
 // ─── Helpers ─────────────────────────────────────────────
 function getTools(a) {
     return 'tools' in a && typeof a.tools === 'function'