@pikku/core 0.12.51 → 0.12.53

package/dist/wirings/actor-flow/run-conversation.js

@@ -0,0 +1,181 @@
+/** One turn the persona takes: the message to send and whether it's finished. */
+const PERSONA_TURN_SCHEMA = {
+    type: 'object',
+    properties: {
+        message: { type: 'string' },
+        done: { type: 'boolean' },
+    },
+    required: ['message', 'done'],
+};
+/** The persona's approve/deny decision for each pending tool request. */
+const APPROVAL_DECISION_SCHEMA = {
+    type: 'object',
+    properties: {
+        decisions: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    toolCallId: { type: 'string' },
+                    approved: { type: 'boolean' },
+                    reason: { type: 'string' },
+                },
+                required: ['toolCallId', 'approved'],
+            },
+        },
+    },
+    required: ['decisions'],
+};
+/** The persona's final verdict on whether the task was accomplished. */
+const EVALUATION_SCHEMA = {
+    type: 'object',
+    properties: {
+        passed: { type: 'boolean' },
+        reasoning: { type: 'string' },
+    },
+    required: ['passed', 'reasoning'],
+};
+const DEFAULT_MAX_TURNS = 12;
+const DEFAULT_MAX_APPROVAL_ROUNDS = 16;
+function msg(role, content) {
+    return {
+        id: globalThis.crypto.randomUUID(),
+        role,
+        content,
+        createdAt: new Date(),
+    };
+}
+/** Read a structured `run` result, falling back to parsing JSON from text. */
+function readObject(result) {
+    if (result.object && typeof result.object === 'object') {
+        return result.object;
+    }
+    if (result.text) {
+        try {
+            return JSON.parse(result.text);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function personaInstructions(persona, task) {
+    return [
+        `You are role-playing a real user interacting with an AI assistant. Stay in character at all times — you are the user, not the assistant.`,
+        persona.name ? `Your name is ${persona.name}.` : '',
+        persona.jobTitle ? `Your role: ${persona.jobTitle}.` : '',
+        persona.personality
+            ? `Your personality and communication style: ${persona.personality}. Match this tone, vocabulary, and level of detail exactly.`
+            : '',
+        `Your goal in this conversation: ${task}.`,
+        `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+/** Route the target agent's pending tool approvals through the persona. */
+async function decideApprovals(params, instructions, pending) {
+    const policy = params.approvals ?? 'in-persona';
+    if (policy === 'always') {
+        return pending.map((p) => ({ toolCallId: p.toolCallId, approved: true }));
+    }
+    if (policy === 'never') {
+        return pending.map((p) => ({ toolCallId: p.toolCallId, approved: false }));
+    }
+    const summary = pending
+        .map((p) => `- toolCallId "${p.toolCallId}": ${p.toolName}(${JSON.stringify(p.args)})${p.reason ? ` — ${p.reason}` : ''}`)
+        .join('\n');
+    const result = await params.llm({
+        model: params.model,
+        instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this persona, would allow each one.`,
+        messages: [
+            msg('user', `The assistant wants to run these tools:\n${summary}\nApprove or deny each toolCallId.`),
+        ],
+        tools: [],
+        maxSteps: 1,
+        toolChoice: 'none',
+        outputSchema: APPROVAL_DECISION_SCHEMA,
+    });
+    const decided = readObject(result)?.decisions ?? [];
+    // Every pending call must get a decision; a missing one defaults to denied.
+    return pending.map((p) => {
+        const match = decided.find((d) => d.toolCallId === p.toolCallId);
+        return { toolCallId: p.toolCallId, approved: match?.approved ?? false };
+    });
+}
+/** Drive the target to a non-suspended reply, routing approvals to the persona. */
+async function converseWithTarget(params, instructions, message) {
+    const maxRounds = params.maxApprovalRounds ?? DEFAULT_MAX_APPROVAL_ROUNDS;
+    let reply = await params.target.run(message);
+    let rounds = 0;
+    while (reply.status === 'suspended' &&
+        reply.pendingApprovals &&
+        reply.pendingApprovals.length > 0) {
+        if (rounds >= maxRounds) {
+            throw new Error(`Target agent "${params.agentName}" stayed suspended after ${maxRounds} approval rounds (runId ${reply.runId}); aborting to avoid an unbounded approve loop.`);
+        }
+        rounds++;
+        const decisions = await decideApprovals(params, instructions, reply.pendingApprovals);
+        reply = await params.target.approve(reply.runId, decisions);
+    }
+    return reply;
+}
+/**
+ * Run a conversation: an LLM-driven persona holds a real multi-turn exchange
+ * with a target agent (driven via the injected transport), answers the target's
+ * tool-approval requests in-persona, then evaluates whether the task was met.
+ * Deterministic checks are the caller's responsibility.
+ */
+export async function runConversation(params) {
+    const maxTurns = params.maxTurns ?? DEFAULT_MAX_TURNS;
+    const instructions = personaInstructions(params.persona, params.task);
+    // Seed a kickoff so the very first persona turn has a non-empty message list
+    // (providers reject an empty prompt). It's an instruction TO the persona, so
+    // it never appears in the transcript.
+    const personaMessages = [
+        msg('user', 'Begin the conversation now — send your first message to the assistant to work towards your goal.'),
+    ];
+    const transcript = [];
+    for (let turn = 0; turn < maxTurns; turn++) {
+        const personaResult = await params.llm({
+            model: params.model,
+            instructions,
+            messages: personaMessages,
+            tools: [],
+            maxSteps: 1,
+            toolChoice: 'none',
+            outputSchema: PERSONA_TURN_SCHEMA,
+        });
+        const turnData = readObject(personaResult);
+        const personaMessage = turnData?.message?.trim();
+        if (!personaMessage) {
+            break;
+        }
+        personaMessages.push(msg('assistant', personaMessage));
+        transcript.push(`${params.personaName}: ${personaMessage}`);
+        const reply = await converseWithTarget(params, instructions, personaMessage);
+        personaMessages.push(msg('user', reply.text ?? ''));
+        transcript.push(`${params.agentName}: ${reply.text ?? ''}`);
+        if (turnData?.done) {
+            break;
+        }
+    }
+    const evalResult = await params.llm({
+        model: params.model,
+        instructions: `${instructions}\nThe conversation has ended. Judge honestly whether your goal was accomplished.`,
+        messages: [
+            msg('user', `Here is the full conversation:\n\n${transcript.join('\n')}\n\nSuccess criterion: ${params.evaluate}\n\nWas it met?`),
+        ],
+        tools: [],
+        maxSteps: 1,
+        toolChoice: 'none',
+        outputSchema: EVALUATION_SCHEMA,
+    });
+    const verdict = readObject(evalResult);
+    return {
+        passed: verdict?.passed ?? false,
+        reasoning: verdict?.reasoning ?? 'No evaluation produced.',
+        transcript,
+    };
+}

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -3,7 +3,7 @@
  * These types define the step-based workflow format extracted by the inspector
  */
 import type { WorkflowRun } from '../workflow.types.js';
-import type { UserFlowActor } from '../../../services/user-flow-actors-service.js';
+import type { ScenarioActor } from '../../../services/scenario-actors-service.js';
 /**
  * Workflow step options
  */
@@ -15,16 +15,16 @@ export interface WorkflowStepOptions {
     /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
     retryDelay?: string | number;
     /**
-     * Run this step as an actor (user flows). The RPC is sent through the
+     * Run this step as an actor (scenarios). The RPC is sent through the
      * actor's authenticated client over the REAL transport — never dispatched
      * internally — so auth middleware and permissions are exercised end-to-end.
      * The step is recorded durably like any RPC step.
      */
-    actor?: UserFlowActor;
+    actor?: ScenarioActor;
 }
 /**
  * Options for workflow.expectEventually() — a durable polling step used by
- * user flows to await async effects (a notification landing, a job finishing).
+ * scenarios to await async effects (a notification landing, a job finishing).
  */
 export interface WorkflowExpectEventuallyOptions extends WorkflowStepOptions {
     /** Give up after this long (e.g. '30s'). Default '30s'. */
@@ -32,6 +32,18 @@ export interface WorkflowExpectEventuallyOptions extends WorkflowStepOptions {
     /** Poll interval (e.g. '1s'). Default '1s'. */
     interval?: string | number;
 }
+/** Options for workflow.expectError() */
+export interface WorkflowExpectErrorOptions extends WorkflowStepOptions {
+    /** Assert the error message matches (string = substring match). */
+    matches?: string | RegExp;
+}
+/** Options for workflow.expectService() */
+export interface WorkflowExpectServiceOptions extends WorkflowStepOptions {
+    /** Assert a recorded call's first argument deep-equals this value. */
+    calledWith?: unknown;
+    /** Assert the exact number of matching calls. Default: at least one. */
+    times?: number;
+}
 /**
  * Type signature for workflow.do() RPC form - used by inspector
  */
@@ -110,7 +122,7 @@ export interface RpcStepMeta {
     inputs?: Record<string, InputSource> | 'passthrough';
     /** Step options */
     options?: WorkflowStepOptions;
-    /** User-flow actor name this step runs as ({ actor: actors.x }) */
+    /** Scenario actor name this step runs as ({ actor: actors.x }) */
     actor?: string;
     /** True for workflow.expectEventually polling steps */
     expectEventually?: boolean;
@@ -340,10 +352,14 @@ export interface PikkuWorkflowWire {
     /** Execute a workflow step (overloaded - RPC or inline form) */
     do: WorkflowWireDoRPC & WorkflowWireDoInline;
     /**
-     * Durable polling step (user flows): invoke `rpcName` (as an actor when
+     * Durable polling step (scenarios): invoke `rpcName` (as an actor when
      * `options.as` is set) until `predicate` passes or `options.within` elapses.
      */
     expectEventually: <TOutput = any, TInput = any>(stepName: string, rpcName: string, data: TInput, predicate: (output: TOutput) => boolean, options?: WorkflowExpectEventuallyOptions) => Promise<TOutput>;
+    /** Error-path step (scenarios): succeeds only when the RPC throws; returns the message */
+    expectError: <TInput = any>(stepName: string, rpcName: string, data: TInput, options?: WorkflowExpectErrorOptions) => Promise<string>;
+    /** Stub-assertion step (scenarios): asserts `service.method` was called on the target server */
+    expectService: (stepName: string, serviceMethod: string, options?: WorkflowExpectServiceOptions) => Promise<void>;
     /** Sleep for a duration */
     sleep: WorkflowWireSleep;
     /** Suspend workflow until explicitly resumed */

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,7 +1,7 @@
 import type { SerializedError } from '../../types/core.types.js';
 import type { PikkuWorkflowWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
-import type { UserFlowActors } from '../../services/user-flow-actors-service.js';
+import type { ScenarioActors } from '../../services/scenario-actors-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
 import type { JobOptions } from '../queue/queue.types.js';
@@ -366,6 +366,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      *   false to fall through to inline `setTimeout` behavior.
      */
     protected scheduleSleep(runId: string, stepId: string, duration: number | string): Promise<boolean>;
+    /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
+    private resolveScenarioActors;
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -375,7 +377,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
         inline?: boolean;
         startNode?: string;
-        actors?: UserFlowActors;
+        actors?: ScenarioActors;
     }): Promise<{
         runId: string;
     }>;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -3,6 +3,7 @@ import { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSl
 import { wireQueueWorker } from '../queue/queue-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
+import { createHttpScenarioActors } from '../../services/http-scenario-actors.js';
 const resolveWorkflowMeta = (name) => {
     const rootMeta = pikkuState(null, 'workflows', 'meta');
     if (rootMeta[name]) {
@@ -601,6 +602,35 @@ export class PikkuWorkflowService {
         await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, { runId, stepId });
         return true;
     }
+    /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
+    async resolveScenarioActors() {
+        const services = getSingletonServices();
+        const variables = services?.variables;
+        const metaService = services?.metaService;
+        if (!variables || !metaService) {
+            return undefined;
+        }
+        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
+        const apiUrl = await variables.get('API_URL');
+        if (!secret || !apiUrl) {
+            services?.logger?.warn('A scenario was started without actors but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without actors.');
+            return undefined;
+        }
+        const actorsConfig = await metaService.getScenarioActorsMeta();
+        if (!actorsConfig || Object.keys(actorsConfig).length === 0) {
+            return undefined;
+        }
+        const signInPath = (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
+            '/api/auth/sign-in/actor';
+        const rpcPath = (await variables.get('SCENARIO_RPC_PATH')) ?? '/rpc';
+        return createHttpScenarioActors({
+            apiUrl,
+            secret,
+            actors: actorsConfig,
+            signInPath,
+            rpcPath,
+        });
+    }
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -641,8 +671,12 @@ export class PikkuWorkflowService {
             deterministic: workflowMeta.deterministic,
             plannedSteps: workflowMeta.plannedSteps,
         });
-        if (options?.actors) {
-            this.runActors.set(runId, options.actors);
+        const actors = options?.actors ??
+            (workflowMeta.source === 'scenario'
+                ? await this.resolveScenarioActors()
+                : undefined);
+        if (actors) {
+            this.runActors.set(runId, actors);
         }
         if (shouldInline) {
             this.inlineRuns.add(runId);
@@ -1387,6 +1421,62 @@ export class PikkuWorkflowService {
                     }
                 }, options);
             },
+            expectError: async (stepName, rpcName, data, options) => {
+                this.verifyStepName(stepName);
+                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
+                    ? `${addonNamespace}:${rpcName}`
+                    : rpcName;
+                return await this.inlineStep(runId, stepName, async () => {
+                    let result;
+                    try {
+                        result = options?.actor
+                            ? await options.actor.invoke(resolvedRpcName, data)
+                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
+                    }
+                    catch (e) {
+                        const message = e?.message ?? String(e);
+                        if (options?.matches) {
+                            const matched = typeof options.matches === 'string'
+                                ? message.includes(options.matches)
+                                : options.matches.test(message);
+                            if (!matched) {
+                                throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') threw, but the message did not match ${options.matches}: ${message}`);
+                            }
+                        }
+                        return message;
+                    }
+                    throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`);
+                }, options);
+            },
+            expectService: async (stepName, serviceMethod, options) => {
+                this.verifyStepName(stepName);
+                const [service, method] = serviceMethod.split('.');
+                if (!service || !method) {
+                    throw new Error(`[workflow] expectService '${stepName}' needs 'service.method', got '${serviceMethod}'`);
+                }
+                await this.inlineStep(runId, stepName, async () => {
+                    const rpcName = 'console:getStubCalls';
+                    const calls = options?.actor
+                        ? await options.actor.invoke(rpcName, { service })
+                        : await rpcService.rpcWithWire(rpcName, { service }, {});
+                    const matching = (calls ?? []).filter((c) => c.service === service &&
+                        c.method === method &&
+                        (options?.calledWith === undefined ||
+                            JSON.stringify(c.args?.[0]) ===
+                                JSON.stringify(options.calledWith)));
+                    const expected = options?.times;
+                    const ok = expected === undefined
+                        ? matching.length > 0
+                        : matching.length === expected;
+                    if (!ok) {
+                        const seen = (calls ?? [])
+                            .map((c) => `${c.service}.${c.method}(${JSON.stringify(c.args?.[0])?.slice(0, 120) ?? ''})`)
+                            .join('\n  ') || '(none)';
+                        throw new Error(`[workflow] expectService '${stepName}' expected ${expected ?? 'at least one'} call(s) to '${serviceMethod}'` +
+                            `${options?.calledWith !== undefined ? ` with ${JSON.stringify(options.calledWith)}` : ''}, found ${matching.length}. Recorded:\n  ${seen}`);
+                    }
+                }, options);
+            },
             // Implement workflow.sleep()
             sleep: async (stepName, duration) => {
                 this.verifyStepName(stepName);

package/dist/wirings/workflow/workflow.types.d.ts

@@ -1,7 +1,7 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -236,9 +236,9 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     context?: WorkflowContext;
     dsl?: boolean;
     expose?: boolean;
-    /** True for pikkuUserFlow workflows (complex + actor steps). */
-    userFlow?: boolean;
-    /** Actor names a user flow declares (personas it runs steps as). */
+    /** True for pikkuScenario workflows (complex + actor steps). */
+    scenario?: boolean;
+    /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[];
 }>;
 /**
@@ -251,13 +251,13 @@ export interface WorkflowRuntimeMeta {
     name: string;
     /** Pikku function name (for execution) */
     pikkuFuncId: string;
-    /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph', 'user-flow' (complex + actor steps) */
-    source: 'dsl' | 'complex' | 'graph' | 'dynamic-workflow' | 'user-flow';
+    /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph', 'scenario' (complex + actor steps) */
+    source: 'dsl' | 'complex' | 'graph' | 'dynamic-workflow' | 'scenario';
     /** Optional description */
     description?: string;
     /** Tags for organization */
     tags?: string[];
-    /** Actor names a user flow declares (personas it runs steps as). */
+    /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[];
     /** Serialized nodes */
     nodes?: Record<string, any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.51",
+  "version": "0.12.53",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -24,6 +24,7 @@
     "./workflow": "./dist/wirings/workflow/index.js",
     "./workflow/timeline": "./dist/wirings/workflow/run-timeline.js",
     "./workflow/types": "./dist/wirings/workflow/workflow.types.js",
+    "./actor-flow": "./dist/wirings/actor-flow/index.js",
     "./channel/local": "./dist/wirings/channel/local/index.js",
     "./channel/serverless": "./dist/wirings/channel/serverless/index.js",
     "./http": "./dist/wirings/http/index.js",

package/src/services/http-scenario-actors-converse.test.ts

@@ -0,0 +1,222 @@
+import { describe, test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer, type Server } from 'node:http'
+
+import { createHttpScenarioActors } from './http-scenario-actors.js'
+import { pikkuState, resetPikkuState } from '../pikku-state.js'
+import type { AIAgentStepResult } from './ai-agent-runner-service.js'
+
+/**
+ * Minimal target app exposing the agent HTTP surface: actor sign-in, the agent
+ * run route (suspends once for approval, then completes), and the batch approve
+ * route (records the decisions). `authRequired` toggles whether the agent
+ * routes reject unauthenticated calls with 401 (to exercise lazy sign-in).
+ */
+const startAgentTarget = async () => {
+  let agentRuns = 0
+  let logins = 0
+  let authRequired = false
+  let approvalsSeen: unknown[] = []
+  const server: Server = createServer((req, res) => {
+    const chunks: Buffer[] = []
+    req.on('data', (c) => chunks.push(c))
+    req.on('end', () => {
+      const body = chunks.length
+        ? JSON.parse(Buffer.concat(chunks).toString())
+        : {}
+      const json = (obj: unknown) =>
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(JSON.stringify(obj))
+
+      if (req.url === '/api/auth/sign-in/actor') {
+        logins++
+        res.setHeader('set-cookie', ['session=s1; Path=/; HttpOnly'])
+        json({ ok: true })
+        return
+      }
+
+      const isAgentRoute = req.url?.startsWith('/api/rpc/agent/')
+      if (
+        isAgentRoute &&
+        authRequired &&
+        !(req.headers.cookie ?? '').includes('session=')
+      ) {
+        res.writeHead(401).end()
+        return
+      }
+
+      if (req.url === '/api/rpc/agent/todoBot/approve') {
+        approvalsSeen.push(body.approvals)
+        json({ runId: body.runId, text: 'Created it.', status: 'completed' })
+        return
+      }
+      if (req.url === '/api/rpc/agent/todoBot') {
+        agentRuns++
+        if (agentRuns === 1) {
+          json({
+            runId: 'run-1',
+            text: 'Let me do that.',
+            status: 'suspended',
+            pendingApprovals: [
+              {
+                toolCallId: 'tc1',
+                toolName: 'createTodo',
+                args: { title: 'x' },
+              },
+            ],
+          })
+          return
+        }
+        json({
+          runId: `run-${agentRuns}`,
+          text: 'All set.',
+          status: 'completed',
+        })
+        return
+      }
+      res.writeHead(404).end()
+    })
+  })
+  await new Promise<void>((resolve) => server.listen(0, resolve))
+  const { port } = server.address() as { port: number }
+  return {
+    server,
+    apiUrl: `http://127.0.0.1:${port}/api`,
+    loginCount: () => logins,
+    approvalsSeen: () => approvalsSeen,
+    reset: (opts?: { authRequired?: boolean }) => {
+      agentRuns = 0
+      logins = 0
+      approvalsSeen = []
+      authRequired = opts?.authRequired ?? false
+    },
+  }
+}
+
+/** Persona LLM scripted by the outputSchema it's asked for. */
+const scriptedRunner = () => {
+  let turn = 0
+  const turns = [
+    { message: 'please make a todo', done: false },
+    { message: 'thanks', done: true },
+  ]
+  return {
+    run: async (params: {
+      outputSchema?: unknown
+    }): Promise<AIAgentStepResult> => {
+      const props =
+        (params.outputSchema as { properties?: Record<string, unknown> })
+          ?.properties ?? {}
+      const object =
+        'message' in props
+          ? (turns[turn++] ?? turns[turns.length - 1])
+          : 'decisions' in props
+            ? { decisions: [{ toolCallId: 'tc1', approved: true }] }
+            : { passed: true, reasoning: 'a todo was created' }
+      return {
+        text: '',
+        object,
+        toolCalls: [],
+        toolResults: [],
+        usage: { inputTokens: 0, outputTokens: 0 },
+        finishReason: 'stop',
+      }
+    },
+  }
+}
+
+const wireRunner = () => {
+  resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+    aiAgentRunner: scriptedRunner(),
+  } as any)
+}
+
+describe('HttpScenarioActor.converse', async () => {
+  const target = await startAgentTarget()
+  after(() => {
+    target.server.close()
+    resetPikkuState()
+  })
+
+  test('converses over HTTP, approves in-persona, returns a verdict', async () => {
+    wireRunner()
+    target.reset()
+
+    const actors = createHttpScenarioActors({
+      apiUrl: target.apiUrl,
+      secret: 'impersonation-secret',
+      model: 'test/test-model',
+      actors: {
+        pm: { email: 'pm@actors.local', name: 'Priya', personality: 'concise' },
+      },
+    })
+
+    const verdict = await actors.pm!.converse({
+      agent: 'todoBot',
+      task: 'Get a todo created for the launch',
+      evaluate: 'A todo about the launch now exists',
+    })
+
+    assert.equal(verdict.passed, true)
+    assert.match(verdict.reasoning, /todo/i)
+    // The target's approval was answered in-persona (approved) over HTTP.
+    assert.deepEqual(target.approvalsSeen(), [
+      [{ toolCallId: 'tc1', approved: true }],
+    ])
+    // No-auth agent → converse never signs in (lazy login).
+    assert.equal(target.loginCount(), 0)
+  })
+
+  test('signs in lazily and retries once when an agent route returns 401', async () => {
+    wireRunner()
+    target.reset({ authRequired: true })
+
+    const actors = createHttpScenarioActors({
+      apiUrl: target.apiUrl,
+      secret: 'impersonation-secret',
+      model: 'test/test-model',
+      actors: { pm: { email: 'pm@actors.local' } },
+    })
+
+    const verdict = await actors.pm!.converse({
+      agent: 'todoBot',
+      task: 'make a todo',
+      evaluate: 'a todo exists',
+    })
+
+    assert.equal(verdict.passed, true)
+    // 401 on the first (unauthenticated) call → one sign-in, then cached.
+    assert.equal(target.loginCount(), 1)
+  })
+
+  test('throws when no AI provider is configured', async () => {
+    resetPikkuState()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+    } as any)
+
+    const actors = createHttpScenarioActors({
+      apiUrl: target.apiUrl,
+      secret: 'impersonation-secret',
+      model: 'test/test-model',
+      actors: { pm: { email: 'pm@actors.local' } },
+    })
+
+    await assert.rejects(
+      actors.pm!.converse({ agent: 'todoBot', task: 't', evaluate: 'e' })
+    )
+  })
+})