@pikku/core 0.12.51 → 0.12.52

package/dist/types/core.types.d.ts

@@ -19,7 +19,7 @@ import type { SchedulerService } from '../services/scheduler-service.js';
 import type { DeploymentService } from '../services/deployment-service.js';
 import type { AIStorageService } from '../services/ai-storage-service.js';
 import type { ContentService } from '../services/content-service.js';
-import type { UserFlowActors } from '../services/user-flow-actors-service.js';
+import type { ScenarioActors } from '../services/scenario-actors-service.js';
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js';
 import type { AIRunStateService } from '../services/ai-run-state-service.js';
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
@@ -186,7 +186,7 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
 export interface CoreUserSession {
     userId?: string;
     orgId?: string;
-    /** True when the session belongs to a synthetic user-flow actor — lets audits/analytics address synthetic traffic */
+    /** True when the session belongs to a synthetic scenario actor — lets audits/analytics address synthetic traffic */
     actor?: boolean;
 }
 /**
@@ -266,8 +266,8 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     queue: PikkuQueue;
     cli: PikkuCLI;
     workflow: TypedWorkflow;
-    /** User-flow actor registry (user-flow runs only) — pass into workflow.do as `{ actor: actors.x }` */
-    actors: UserFlowActors;
+    /** Scenario actor registry (scenario runs only) — pass into workflow.do as `{ actor: actors.x }` */
+    actors: ScenarioActors;
     workflowStep: WorkflowStepWire;
     graph: PikkuGraphWire;
     trigger: PikkuTrigger<TriggerOutput>;

package/dist/wirings/actor-flow/actor-flow.types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * How an actor agent answers the target agent's tool-approval requests during
+ * a conversation.
+ * - `'in-persona'` — the actor agent decides as the persona would (default).
+ * - `'always'` — approve every request (stress the happy path).
+ * - `'never'` — deny every request (exercise refusal handling).
+ */
+export type ActorFlowApprovalPolicy = 'in-persona' | 'always' | 'never';
+/**
+ * Options for `actor.converse(...)` — a dynamic conversation an actor holds
+ * with a target Pikku AI agent, in the actor's own persona. `TAgentName` is
+ * bound to the generated union of agent names in a typed project.
+ */
+export interface ConverseOptions<TAgentName extends string = string> {
+    /** Target Pikku AI agent name to converse with. */
+    agent: TAgentName;
+    /** What the actor is trying to get the agent to accomplish. */
+    task: string;
+    /** Natural-language success criterion the actor evaluates at the end. */
+    evaluate: string;
+    /** How the actor answers the agent's tool-approval requests. Default `'in-persona'`. */
+    approvals?: ActorFlowApprovalPolicy;
+    /** Model the persona uses for its own turns/decisions. Falls back to the actor service default. */
+    model?: string;
+    /** Hard cap on conversation turns before forcing evaluation. Default 12. */
+    maxTurns?: number;
+}
+/**
+ * The verdict a conversation produces: the persona's LLM self-evaluation of
+ * whether the task was met. Deterministic checks are the caller's job — they
+ * already hold the actor and can `actor.invoke(...)` afterwards.
+ */
+export interface ActorFlowVerdict {
+    /** Whether the actor judged the task accomplished. */
+    passed: boolean;
+    /** The actor's reasoning for its verdict. */
+    reasoning: string;
+    /** The conversation transcript, for debugging/reporting. */
+    transcript: string[];
+}
+/** A pending tool-approval request surfaced by the target agent. */
+export interface TargetPendingApproval {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    reason?: string;
+}
+/** A normalized reply from the target agent, independent of transport. */
+export interface TargetAgentReply {
+    text: string;
+    runId: string;
+    status?: 'completed' | 'suspended';
+    pendingApprovals?: TargetPendingApproval[];
+}
+/**
+ * Drives the target agent. In production this is HTTP-backed (the actor's
+ * `agentRun` / `agentApprove` calls as the signed-in actor); the conversation
+ * engine only sees this transport-agnostic contract.
+ */
+export interface TargetAgentDriver {
+    /** Send a message, starting or continuing the target agent's run. */
+    run(message: string): Promise<TargetAgentReply>;
+    /** Answer the target agent's pending approvals and continue its run. */
+    approve(runId: string, decisions: {
+        toolCallId: string;
+        approved: boolean;
+    }[]): Promise<TargetAgentReply>;
+}

package/dist/wirings/actor-flow/actor-flow.types.js

@@ -0,0 +1 @@
+export {};

package/dist/wirings/actor-flow/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Actor flow module exports.
+ *
+ * An actor holds a dynamic conversation with a target Pikku AI agent via
+ * `actor.converse(...)` — playing its own persona, approving the agent's tool
+ * requests in-persona, and evaluating whether the task was accomplished. The
+ * conversation engine here is transport-agnostic; the actor drives the target
+ * over HTTP.
+ */
+export type { ActorFlowApprovalPolicy, ActorFlowVerdict, ConverseOptions, TargetAgentReply, TargetPendingApproval, TargetAgentDriver, } from './actor-flow.types.js';
+export { runConversation, type RunConversationParams, type PersonaLLM, } from './run-conversation.js';

package/dist/wirings/actor-flow/index.js

@@ -0,0 +1 @@
+export { runConversation, } from './run-conversation.js';

package/dist/wirings/actor-flow/run-conversation.d.ts

@@ -0,0 +1,36 @@
+import type { ActorFlowApprovalPolicy, ActorFlowVerdict, TargetAgentDriver } from './actor-flow.types.js';
+import type { ScenarioActorConfig } from '../../services/scenario-actors-service.js';
+import type { AIAgentRunnerParams, AIAgentStepResult } from '../../services/ai-agent-runner-service.js';
+/** The LLM call the persona uses for its own turns/decisions/evaluation. */
+export type PersonaLLM = (params: AIAgentRunnerParams) => Promise<AIAgentStepResult>;
+export interface RunConversationParams {
+    /** Persona config (personality/jobTitle/name) that shapes how the actor talks. */
+    persona: ScenarioActorConfig;
+    /** Stable persona name (for transcript labelling). */
+    personaName: string;
+    /** What the actor is trying to get the target agent to accomplish. */
+    task: string;
+    /** Natural-language success criterion the actor evaluates at the end. */
+    evaluate: string;
+    /** How the actor answers the target agent's tool-approval requests. */
+    approvals?: ActorFlowApprovalPolicy;
+    /** Model the persona uses for its own turns/decisions. */
+    model: string;
+    /** Hard cap on conversation turns. Default 12. */
+    maxTurns?: number;
+    /** Hard cap on tool-approval rounds within a single target turn. Default 16. */
+    maxApprovalRounds?: number;
+    /** Transport that drives the target agent (HTTP in production). */
+    target: TargetAgentDriver;
+    /** The persona's own LLM. */
+    llm: PersonaLLM;
+    /** Display name of the target agent (transcript labelling). */
+    agentName: string;
+}
+/**
+ * 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 declare function runConversation(params: RunConversationParams): Promise<ActorFlowVerdict>;

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'. */
@@ -110,7 +110,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,7 +340,7 @@ 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>;

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,14 @@ 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
+     * @param options.inline - If true, execute workflow directly without queue service
+     * @param options.startNode - Starting node ID for graph workflows (from wire config)
+     */
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -375,7 +383,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,41 @@ 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
+     * @param options.inline - If true, execute workflow directly without queue service
+     * @param options.startNode - Starting node ID for graph workflows (from wire config)
+     */
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -641,8 +677,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);

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

@@ -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.52",
   "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",