@pikku/core 0.12.51 → 0.12.53

package/dist/services/scenario-actors-service.d.ts

@@ -0,0 +1,21 @@
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
+/** A synthetic user (a user row flagged `actor`) that workflow steps run as over the real transport */
+export interface ScenarioActor<TAgentName extends string = string> {
+    /** Stable actor name (the key in pikku.config.json's actor registry). */
+    readonly name: string;
+    /** The actor's user email — flows use it for invites/lookups. */
+    readonly email: string;
+    /** Invoke an exposed RPC as this actor over the real transport. */
+    invoke(rpcName: string, data: unknown): Promise<unknown>;
+    /** Converse with a Pikku AI agent in this actor's persona and return its verdict */
+    converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>;
+}
+/** Display/config metadata for an actor (from pikku.config.json) */
+export interface ScenarioActorConfig {
+    email: string;
+    name?: string;
+    jobTitle?: string;
+    personality?: string;
+}
+/** The injected `actors` service: actor name → actor. */
+export type ScenarioActors = Record<string, ScenarioActor>;

package/dist/services/scenario-actors-service.js

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

package/dist/services/stub-tracker.d.ts

@@ -0,0 +1,43 @@
+export type StubCall = {
+    service: string;
+    method: string;
+    args: unknown[];
+};
+/**
+ * Tracks calls made to stubbed services and enforces strict mode:
+ * once a scenario asserts any call on a service, every recorded call on that
+ * service must be verified by end of scenario — otherwise the After hook fails.
+ * Services never touched by an assertion stay lenient.
+ */
+export declare class StubTracker {
+    private readonly calls;
+    private readonly touched;
+    record(service: string, method: string, args: unknown[]): void;
+    getCalls(service?: string): StubCall[];
+    reset(): void;
+    stub<T>(service: string): T;
+    assert(service: string, method: string): void;
+    assertCall(service: string, method: string, predicate: (args: unknown[]) => boolean, description: string): void;
+    assertNoCalls(service: string, method?: string, predicate?: (args: unknown[]) => boolean, description?: string): void;
+    verify(): void;
+}
+/**
+ * Creates a Proxy suitable for passing as `existingServices` to
+ * `createSingletonServices`. Every property returns `tracker.stub(prop)`
+ * EXCEPT `schema`, which returns `undefined` so the service factory creates
+ * a real schema service. Stubbing the schema makes validation a no-op —
+ * required fields pass silently and tests validate nothing.
+ */
+export declare function createStubProxy(tracker: StubTracker): Record<string, unknown>;
+/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+export declare const getStubTracker: () => StubTracker;
+/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+export declare const isTestRun: () => boolean;
+/**
+ * Creates a recording fake for a service. Methods present on `impl` run and
+ * their result is returned; missing methods resolve `undefined`. Every call
+ * is recorded so scenarios can assert via workflow.expectService().
+ */
+export declare function stub<T = any>(service: string, impl?: Partial<T>): T;
+/** Wraps a real service so every method call is recorded and passed through */
+export declare function spy<T extends object>(service: string, real: T): T;

package/dist/services/stub-tracker.js

@@ -0,0 +1,146 @@
+/**
+ * Tracks calls made to stubbed services and enforces strict mode:
+ * once a scenario asserts any call on a service, every recorded call on that
+ * service must be verified by end of scenario — otherwise the After hook fails.
+ * Services never touched by an assertion stay lenient.
+ */
+export class StubTracker {
+    calls = new Map();
+    touched = new Set();
+    record(service, method, args) {
+        const list = this.calls.get(service) ?? [];
+        list.push({ method, args, verified: false });
+        this.calls.set(service, list);
+    }
+    getCalls(service) {
+        const result = [];
+        for (const [name, list] of this.calls) {
+            if (service && name !== service)
+                continue;
+            for (const call of list) {
+                result.push({ service: name, method: call.method, args: call.args });
+            }
+        }
+        return result;
+    }
+    reset() {
+        this.calls.clear();
+        this.touched.clear();
+    }
+    stub(service) {
+        const self = this;
+        return new Proxy(Object.create(null), {
+            get(_, method) {
+                return (...args) => {
+                    self.record(service, method, args);
+                    return Promise.resolve();
+                };
+            },
+        });
+    }
+    assert(service, method) {
+        this.touched.add(service);
+        const list = this.calls.get(service) ?? [];
+        const idx = list.findIndex((c) => c.method === method && !c.verified);
+        if (idx === -1) {
+            const seen = list.map((c) => c.method).join(', ') || '(none)';
+            throw new Error(`Expected "${service}.${method}" to have been called. Recorded: ${seen}`);
+        }
+        list[idx].verified = true;
+    }
+    assertCall(service, method, predicate, description) {
+        this.touched.add(service);
+        const list = this.calls.get(service) ?? [];
+        const idx = list.findIndex((c) => c.method === method && !c.verified && predicate(c.args));
+        if (idx === -1) {
+            const seen = list
+                .filter((c) => c.method === method)
+                .map((c) => JSON.stringify(c.args[0]))
+                .join('\n  ') || '(none)';
+            throw new Error(`Expected ${description} but found:\n  ${seen}`);
+        }
+        list[idx].verified = true;
+    }
+    assertNoCalls(service, method, predicate, description) {
+        this.touched.add(service);
+        const list = this.calls.get(service) ?? [];
+        const relevant = (method ? list.filter((c) => c.method === method) : list).filter((c) => !predicate || predicate(c.args));
+        if (relevant.length > 0) {
+            const calls = relevant
+                .map((c) => `${c.method}(${c.args.map((a) => JSON.stringify(a)).join(', ')})`)
+                .join('\n  ');
+            const what = description ?? `"${service}${method ? '.' + method : ''}"`;
+            throw new Error(`Expected no ${what} calls but got:\n  ${calls}`);
+        }
+    }
+    verify() {
+        const errors = [];
+        for (const service of this.touched) {
+            const unverified = (this.calls.get(service) ?? []).filter((c) => !c.verified);
+            for (const c of unverified) {
+                const argStr = c.args.map((a) => JSON.stringify(a)).join(', ');
+                errors.push(`  ${service}.${c.method}(${argStr})`);
+            }
+        }
+        if (errors.length) {
+            throw new Error(`Unexpected stub calls — assert them in the scenario or remove the side effect:\n${errors.join('\n')}`);
+        }
+    }
+}
+/**
+ * Creates a Proxy suitable for passing as `existingServices` to
+ * `createSingletonServices`. Every property returns `tracker.stub(prop)`
+ * EXCEPT `schema`, which returns `undefined` so the service factory creates
+ * a real schema service. Stubbing the schema makes validation a no-op —
+ * required fields pass silently and tests validate nothing.
+ */
+export function createStubProxy(tracker) {
+    return new Proxy({}, {
+        get(_, prop) {
+            if (prop === 'schema')
+                return undefined;
+            return tracker.stub(prop);
+        },
+    });
+}
+const defaultStubTracker = new StubTracker();
+/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+export const getStubTracker = () => defaultStubTracker;
+/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+export const isTestRun = () => globalThis
+    .process?.env?.PIKKU_TEST_RUN === 'true';
+/**
+ * Creates a recording fake for a service. Methods present on `impl` run and
+ * their result is returned; missing methods resolve `undefined`. Every call
+ * is recorded so scenarios can assert via workflow.expectService().
+ */
+export function stub(service, impl) {
+    return new Proxy((impl ?? {}), {
+        get(target, method) {
+            if (typeof method === 'symbol')
+                return target[method];
+            const real = target[method];
+            if (typeof real !== 'function' && real !== undefined)
+                return real;
+            return (...args) => {
+                defaultStubTracker.record(service, method, args);
+                return real ? real.apply(target, args) : Promise.resolve(undefined);
+            };
+        },
+    });
+}
+/** Wraps a real service so every method call is recorded and passed through */
+export function spy(service, real) {
+    return new Proxy(real, {
+        get(target, method) {
+            const value = target[method];
+            if (typeof method === 'symbol' || typeof value !== 'function') {
+                return value;
+            }
+            return (...args) => {
+                defaultStubTracker.record(service, method, args);
+                return value.apply(target, args);
+            };
+        },
+    });
+}

package/dist/services/user-flow-actors-service.d.ts

@@ -1,3 +1,4 @@
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
 /**
  * A user-flow actor: a synthetic user (a normal user row flagged `actor`) that
  * workflow steps can run as. Passed to `workflow.do(step, rpc, data, { actor })`
@@ -6,13 +7,22 @@
  * never through internal dispatch. Login is lazy: the first `invoke` signs the
  * actor in and the session is cached for the actor's lifetime.
  */
-export interface UserFlowActor {
+export interface UserFlowActor<TAgentName extends string = string> {
     /** Stable actor name (the key in pikku.config.json's actor registry). */
     readonly name: string;
     /** The actor's user email — flows use it for invites/lookups. */
     readonly email: string;
     /** Invoke an exposed RPC as this actor over the real transport. */
     invoke(rpcName: string, data: unknown): Promise<unknown>;
+    /**
+     * Hold a dynamic conversation with a target Pikku AI agent, in THIS actor's
+     * persona (personality/jobTitle). Drives the target over the real transport
+     * as the signed-in actor, answers its tool-approval requests in-persona, and
+     * returns the actor's verdict on whether the task was met. Deterministic
+     * checks are the caller's job — use `invoke` afterwards. In a typed project
+     * `agent` is constrained to the generated union of agent names.
+     */
+    converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>;
 }
 /**
  * Display/config metadata for an actor (from pikku.config.json). The email

package/dist/services/v8-coverage-service.d.ts

@@ -0,0 +1,41 @@
+export interface CoverageRange {
+    startOffset: number;
+    endOffset: number;
+    count: number;
+}
+export interface FunctionCoverage {
+    functionName: string;
+    isBlockCoverage: boolean;
+    ranges: CoverageRange[];
+}
+export interface ScriptCoverage {
+    scriptId: string;
+    url: string;
+    functions: FunctionCoverage[];
+}
+export type LineHits = Map<string, Map<number, number>>;
+export type CoverageSnapshot = {
+    kind: 'v8-scripts';
+    scripts: ScriptCoverage[];
+    getScriptSource: (scriptId: string) => Promise<string>;
+} | {
+    kind: 'line-hits';
+    lineHits: LineHits;
+};
+export interface CoverageService {
+    start(): Promise<void>;
+    takeCoverage(): Promise<CoverageSnapshot>;
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare class V8CoverageService implements CoverageService {
+    private session;
+    private startPromise;
+    private post;
+    start(): Promise<void>;
+    private doStart;
+    takeCoverage(): Promise<CoverageSnapshot>;
+    getScriptSource(scriptId: string): Promise<string>;
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/services/v8-coverage-service.js

@@ -0,0 +1,63 @@
+// node:inspector is imported lazily inside start() so this module stays
+// loadable on runtimes without it (e.g. Cloudflare Workers).
+export class V8CoverageService {
+    session = null;
+    startPromise = null;
+    post(method, params) {
+        const session = this.session;
+        if (!session) {
+            throw new Error('V8CoverageService not started — call start() first');
+        }
+        return new Promise((resolve, reject) => {
+            session.post(method, params, (err, result) => err ? reject(err) : resolve(result));
+        });
+    }
+    start() {
+        this.startPromise ??= this.doStart();
+        return this.startPromise;
+    }
+    async doStart() {
+        const inspector = await import('node:inspector');
+        this.session = new inspector.Session();
+        this.session.connect();
+        await this.post('Profiler.enable');
+        await this.post('Debugger.enable');
+        await this.post('Profiler.startPreciseCoverage', {
+            callCount: true,
+            detailed: true,
+        });
+    }
+    async takeCoverage() {
+        const { result } = await this.post('Profiler.takePreciseCoverage');
+        return {
+            kind: 'v8-scripts',
+            scripts: result.filter((script) => script.url.startsWith('file://')),
+            getScriptSource: (scriptId) => this.getScriptSource(scriptId),
+        };
+    }
+    async getScriptSource(scriptId) {
+        const { scriptSource } = await this.post('Debugger.getScriptSource', { scriptId });
+        return scriptSource;
+    }
+    async reset() {
+        await this.post('Profiler.stopPreciseCoverage');
+        await this.post('Profiler.startPreciseCoverage', {
+            callCount: true,
+            detailed: true,
+        });
+    }
+    async stop() {
+        if (!this.session)
+            return;
+        try {
+            await this.post('Profiler.stopPreciseCoverage');
+            await this.post('Profiler.disable');
+            await this.post('Debugger.disable');
+        }
+        finally {
+            this.session.disconnect();
+            this.session = null;
+            this.startPromise = null;
+        }
+    }
+}

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';
@@ -28,6 +28,7 @@ import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
 import type { CredentialService } from '../services/credential-service.js';
 import type { EmailService } from '../services/email-service.js';
 import type { MetaService } from '../services/meta-service.js';
+import type { CoverageService } from '../services/v8-coverage-service.js';
 import type { SessionStore } from '../services/session-store.js';
 import type { AuditDurability, AuditLog, AuditService } from '../services/audit-service.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
@@ -110,6 +111,12 @@ export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     isDirectFunction: boolean;
     sourceFile: string;
     exportedName: string;
+    /** File containing the handler body when it differs from sourceFile (imported handlers) */
+    bodySourceFile?: string;
+    /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
+    bodyStart: number;
+    /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
+    bodyEnd: number;
 } & CommonWireMeta>;
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>;
 export type FunctionsMeta = Record<string, FunctionMeta>;
@@ -186,7 +193,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;
 }
 /**
@@ -233,6 +240,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     emailService?: EmailService;
     /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
     metaService?: MetaService;
+    /** V8 precise-coverage collector (`pikku dev --coverage` only) */
+    coverageService?: CoverageService;
     /** Audit service for durable or staged audit event capture */
     audit?: AuditService;
     /**
@@ -266,8 +275,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>;