@pikku/core 0.12.69 → 0.12.70

package/src/wirings/actor-flow/run-conversation.ts

@@ -11,8 +11,8 @@ import type {
   AIAgentStepResult,
 } from '../../services/ai-agent-runner-service.js'
 
-/** One turn the persona takes: the message to send and whether it's finished. */
-const PERSONA_TURN_SCHEMA = {
+/** One turn the actor takes: the message to send and whether it's finished. */
+const ACTOR_TURN_SCHEMA = {
   type: 'object',
   properties: {
     message: { type: 'string' },
@@ -21,7 +21,7 @@ const PERSONA_TURN_SCHEMA = {
   required: ['message', 'done'],
 } as const
 
-/** The persona's approve/deny decision for each pending tool request. */
+/** The actor's approve/deny decision for each pending tool request. */
 const APPROVAL_DECISION_SCHEMA = {
   type: 'object',
   properties: {
@@ -41,7 +41,7 @@ const APPROVAL_DECISION_SCHEMA = {
   required: ['decisions'],
 } as const
 
-/** The persona's final verdict on whether the task was accomplished. */
+/** The actor's final verdict on whether the task was accomplished. */
 const EVALUATION_SCHEMA = {
   type: 'object',
   properties: {
@@ -55,23 +55,23 @@ const DEFAULT_MAX_TURNS = 12
 
 const DEFAULT_MAX_APPROVAL_ROUNDS = 16
 
-/** The LLM call the persona uses for its own turns/decisions/evaluation. */
-export type PersonaLLM = (
+/** The LLM call the actor uses for its own turns/decisions/evaluation. */
+export type ActorLLM = (
   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
+  /** The actor's own config (personality/jobTitle/name), which shapes how it talks. */
+  actor: ScenarioActorConfig
+  /** Stable actor name (for transcript labelling). */
+  actorName: 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 the actor uses for its own turns/decisions. */
   model: string
   /** Hard cap on conversation turns. Default 12. */
   maxTurns?: number
@@ -79,8 +79,8 @@ export interface RunConversationParams {
   maxApprovalRounds?: number
   /** Transport that drives the target agent (HTTP in production). */
   target: TargetAgentDriver
-  /** The persona's own LLM. */
-  llm: PersonaLLM
+  /** The actor's own LLM. */
+  llm: ActorLLM
   /** Display name of the target agent (transcript labelling). */
   agentName: string
 }
@@ -109,16 +109,13 @@ function readObject<T>(result: { object?: unknown; text?: string }): T | null {
   return null
 }
 
-function personaInstructions(
-  persona: ScenarioActorConfig,
-  task: string
-): string {
+function actorInstructions(actor: ScenarioActorConfig, task: string): string {
   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.`
+    actor.name ? `Your name is ${actor.name}.` : '',
+    actor.jobTitle ? `Your role: ${actor.jobTitle}.` : '',
+    actor.personality
+      ? `Your personality and communication style: ${actor.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.`,
@@ -127,7 +124,7 @@ function personaInstructions(
     .join('\n')
 }
 
-/** Route the target agent's pending tool approvals through the persona. */
+/** Route the target agent's pending tool approvals through the actor. */
 async function decideApprovals(
   params: RunConversationParams,
   instructions: string,
@@ -150,7 +147,7 @@ async function decideApprovals(
 
   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.`,
+    instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this actor, would allow each one.`,
     messages: [
       msg(
         'user',
@@ -178,7 +175,7 @@ async function decideApprovals(
   })
 }
 
-/** Drive the target to a non-suspended reply, routing approvals to the persona. */
+/** Drive the target to a non-suspended reply, routing approvals to the actor. */
 async function converseWithTarget(
   params: RunConversationParams,
   instructions: string,
@@ -209,7 +206,7 @@ async function converseWithTarget(
 }
 
 /**
- * Run a conversation: an LLM-driven persona holds a real multi-turn exchange
+ * Run a conversation: an LLM-driven actor 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.
@@ -218,11 +215,11 @@ export async function runConversation(
   params: RunConversationParams
 ): Promise<ActorFlowVerdict> {
   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
+  const instructions = actorInstructions(params.actor, params.task)
+  // Seed a kickoff so the very first actor turn has a non-empty message list
+  // (providers reject an empty prompt). It's an instruction TO the actor, so
   // it never appears in the transcript.
-  const personaMessages: AIMessage[] = [
+  const actorMessages: AIMessage[] = [
     msg(
       'user',
       'Begin the conversation now — send your first message to the assistant to work towards your goal.'
@@ -231,29 +228,27 @@ export async function runConversation(
   const transcript: string[] = []
 
   for (let turn = 0; turn < maxTurns; turn++) {
-    const personaResult = await params.llm({
+    const actorResult = await params.llm({
       model: params.model,
       instructions,
-      messages: personaMessages,
+      messages: actorMessages,
       tools: [],
       maxSteps: 1,
       toolChoice: 'none',
-      outputSchema: PERSONA_TURN_SCHEMA as unknown as Record<string, unknown>,
+      outputSchema: ACTOR_TURN_SCHEMA as unknown as Record<string, unknown>,
     })
 
-    const turnData = readObject<{ message: string; done: boolean }>(
-      personaResult
-    )
-    const personaMessage = turnData?.message?.trim()
-    if (!personaMessage) {
+    const turnData = readObject<{ message: string; done: boolean }>(actorResult)
+    const actorMessage = turnData?.message?.trim()
+    if (!actorMessage) {
       break
     }
 
-    personaMessages.push(msg('assistant', personaMessage))
-    transcript.push(`${params.personaName}: ${personaMessage}`)
+    actorMessages.push(msg('assistant', actorMessage))
+    transcript.push(`${params.actorName}: ${actorMessage}`)
 
-    const reply = await converseWithTarget(params, instructions, personaMessage)
-    personaMessages.push(msg('user', reply.text ?? ''))
+    const reply = await converseWithTarget(params, instructions, actorMessage)
+    actorMessages.push(msg('user', reply.text ?? ''))
     transcript.push(`${params.agentName}: ${reply.text ?? ''}`)
 
     if (turnData?.done) {

package/src/wirings/cli/command-parser.test.ts

@@ -74,6 +74,20 @@ const testMeta: CLIMeta = {
           positionals: [{ name: 'name', required: false }],
           options: {},
         },
+        serve: {
+          pikkuFuncId: 'serveFunc',
+          positionals: [],
+          options: {
+            browser: {
+              description: 'Open a browser',
+              default: true,
+            },
+            port: {
+              description: 'Port to listen on',
+              default: 8080,
+            },
+          },
+        },
       },
     },
   },
@@ -103,6 +117,52 @@ describe('Command Parser', () => {
       assert.strictEqual(result.errors.length, 0)
     })
 
+    test('should turn a boolean option off with --no-<flag>', () => {
+      const result = parseCLIArguments(
+        ['serve', '--no-browser'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.strictEqual(result.options.browser, false)
+      assert.strictEqual(result.errors.length, 0)
+      assert.deepStrictEqual(
+        result.warnings ?? [],
+        [],
+        '--no-browser is the negation of a known option, not an unknown one'
+      )
+    })
+
+    test('should leave a boolean option at its default when not negated', () => {
+      const result = parseCLIArguments(['serve'], 'test-cli', testMeta)
+
+      assert.strictEqual(result.options.browser, true)
+    })
+
+    test('should not consume the next argument when negating', () => {
+      const result = parseCLIArguments(
+        ['serve', '--no-browser', '--port', '4077'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.strictEqual(result.options.browser, false)
+      assert.strictEqual(result.options.port, 4077)
+    })
+
+    test('should still warn about an unknown --no-<flag>', () => {
+      const result = parseCLIArguments(
+        ['serve', '--no-telemetry'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.ok(
+        (result.warnings ?? []).length > 0,
+        'negating an option that does not exist is a typo, not a feature'
+      )
+    })
+
     test('should parse command with short flag', () => {
       const result = parseCLIArguments(
         ['greet', 'Alice', '-l'],

package/src/wirings/cli/command-parser.ts

@@ -210,8 +210,19 @@ export function parseCLIArguments(
 
     if (arg.startsWith('--')) {
       // Long option (--from-plan → fromPlan)
+      const negatedKey = arg.startsWith('--no-')
+        ? toCamelCase(arg.slice(5))
+        : undefined
       const equalIndex = arg.indexOf('=')
-      if (equalIndex > 0) {
+      if (
+        negatedKey &&
+        typeof availableOptions[negatedKey]?.default === 'boolean'
+      ) {
+        // --no-<flag> turns a boolean option off. Only options that declare a
+        // boolean default can be negated, so a literal `--no-something` option
+        // name still parses as itself.
+        optionArgs[negatedKey] = false
+      } else if (equalIndex > 0) {
         // --option=value format
         const key = toCamelCase(arg.slice(2, equalIndex))
         const optionDef = availableOptions[key]

package/src/wirings/rpc/rpc-runner.test.ts

@@ -29,11 +29,13 @@ const registerFunction = (
     expose,
     pikkuFuncId,
     tags,
+    scenarioStep,
   }: {
     packageName?: string | null
     expose?: boolean
     pikkuFuncId?: string
     tags?: string[]
+    scenarioStep?: boolean
   } = {}
 ) => {
   addFunction(funcName, { func } as never, packageName)
@@ -44,6 +46,7 @@ const registerFunction = (
     permissions: [],
     expose,
     tags,
+    scenarioStep,
   } as never
 }
 
@@ -312,6 +315,27 @@ describe('ContextAwareRPCService.rpcExposed', () => {
     )
   })
 
+  test('a scenario step is not callable over the network, even if marked exposed', async () => {
+    // A step may drive a browser or assert against fixtures, so it is a step
+    // RPC — dispatched by name inside a run, never reachable from outside it.
+    pikkuState(null, 'rpc', 'meta').seesAddonCard = 'seesAddonCard'
+    registerFunction('seesAddonCard', async () => ({ visible: true }), {
+      expose: true,
+      scenarioStep: true,
+    })
+
+    const service = new ContextAwareRPCService(
+      createServices(),
+      {} as never,
+      {}
+    )
+
+    await assert.rejects(
+      () => service.rpcExposed('seesAddonCard', {}),
+      RPCNotFoundError
+    )
+  })
+
   test('runs exposed addon functions', async () => {
     pikkuState(null, 'addons', 'packages').set('addon', {
       package: '@addon/pkg',
@@ -669,7 +693,9 @@ describe('wireRemoteAddon dispatch', () => {
         {}
       )
 
-      const result = await service.rpc('registry:getOpenApi', { name: 'stripe' })
+      const result = await service.rpc('registry:getOpenApi', {
+        name: 'stripe',
+      })
 
       assert.deepEqual(result, { echoed: 42 })
       assert.equal(calls.length, 1)
@@ -713,10 +739,7 @@ describe('wireRemoteAddon dispatch', () => {
       )
 
       await service.rpc('registry:getOpenApi', {})
-      assert.equal(
-        calls[0]!.init.headers.authorization,
-        'Bearer user-token-9'
-      )
+      assert.equal(calls[0]!.init.headers.authorization, 'Bearer user-token-9')
     } finally {
       restoreFetch()
     }

package/src/wirings/rpc/rpc-runner.ts

@@ -165,7 +165,7 @@ export class ContextAwareRPCService {
     if (!functionMeta) {
       throw new RPCNotFoundError(funcName)
     }
-    if (!functionMeta.expose) {
+    if (!functionMeta.expose || functionMeta.scenarioStep) {
       throw new RPCNotFoundError(funcName)
     }
     return await this.rpc(funcName, data)

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -7,6 +7,10 @@ import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 import type { WorkflowRun } from '../workflow.types.js'
 import type { ScenarioActor } from '../../../services/scenario-actors-service.js'
+import type {
+  ScenarioStepOptions,
+  ScenarioStepPhase,
+} from '../scenario-step.types.js'
 
 /**
  * Workflow step options
@@ -79,6 +83,19 @@ export type WorkflowWireDoInline = <T>(
   options?: WorkflowStepOptions
 ) => Promise<T>
 
+/**
+ * Type signature for scenario.step/given/when/then - used by inspector.
+ *
+ * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
+ * an imported symbol, so the extractor reads it as a literal.
+ */
+export type ScenarioStepInvocation = <TOutput = any, TInput = any>(
+  stepName: string,
+  stepFunc: string,
+  data?: TInput,
+  options?: ScenarioStepOptions
+) => Promise<TOutput>
+
 /**
  * Type signature for workflow.sleep() - used by inspector
  */
@@ -180,6 +197,34 @@ export interface RpcStepMeta {
   expectEventually?: boolean
 }
 
+/**
+ * Scenario step metadata — a call to `scenario.step/given/when/then`.
+ *
+ * Distinct from RpcStepMeta on purpose: a step runs locally through
+ * runPikkuFunc and must never be treated as dispatchable on the queue/replay
+ * path, nor registered as a callable RPC (a browser-driving step must not be
+ * network-invocable).
+ */
+export interface ScenarioStepMeta {
+  type: 'scenarioStep'
+  /** Cache key (first argument), ordinal-suffixed by the engine when repeated */
+  stepName: string
+  /** Registered name of the step function being run */
+  stepFunc: string
+  /** Which keyword the reporter prefixes — given/when/then, or none for `step` */
+  phase: ScenarioStepPhase
+  /** Output variable name (if assigned) */
+  outputVar?: string
+  /** Input source mappings, or 'passthrough' when entire data is passed */
+  inputs?: Record<string, InputSource> | 'passthrough'
+  /** Step options */
+  options?: WorkflowStepOptions
+  /** Scenario actor name this step runs as ({ actor: actors.x }) */
+  actor?: string
+  /** Mirrors the step function's `browser: true` declaration */
+  browser?: boolean
+}
+
 /**
  * Simple condition expression (leaf node)
  */
@@ -223,7 +268,7 @@ export interface BranchStepMeta {
 export interface ParallelGroupStepMeta {
   type: 'parallel'
   /** Child steps to execute in parallel */
-  children: RpcStepMeta[]
+  children: Array<RpcStepMeta | ScenarioStepMeta>
 }
 
 /**
@@ -244,7 +289,7 @@ export interface FanoutStepMeta {
   /** Execution mode */
   mode: 'parallel' | 'sequential'
   /** Steps to execute inline per iteration, in order */
-  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>
+  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta | ScenarioStepMeta>
   /** Time between iterations (sequential mode only) */
   timeBetween?: string
 }
@@ -409,6 +454,7 @@ export interface ArrayPredicateStepMeta {
  */
 export type WorkflowStepMeta =
   | RpcStepMeta
+  | ScenarioStepMeta
   | BranchStepMeta
   | ParallelGroupStepMeta
   | FanoutStepMeta
@@ -509,5 +555,43 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     options?: WorkflowExpectServiceOptions
   ) => Promise<void>
 
+  /**
+   * Run a registered scenario step. Shaped exactly like `do`'s RPC form —
+   * `(stepName, target, data, options)` — so the inspector reads the target as
+   * a string literal rather than resolving an imported symbol.
+   *
+   * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
+   */
+  step(
+    stepName: string,
+    stepFunc: string,
+    data?: any,
+    options?: ScenarioStepOptions
+  ): Promise<any>
+
+  /** `step` with a "Given" prefix in the rendered prose */
+  given(
+    stepName: string,
+    stepFunc: string,
+    data?: any,
+    options?: ScenarioStepOptions
+  ): Promise<any>
+
+  /** `step` with a "When" prefix in the rendered prose */
+  when(
+    stepName: string,
+    stepFunc: string,
+    data?: any,
+    options?: ScenarioStepOptions
+  ): Promise<any>
+
+  /** `step` with a "Then" prefix in the rendered prose */
+  then(
+    stepName: string,
+    stepFunc: string,
+    data?: any,
+    options?: ScenarioStepOptions
+  ): Promise<any>
+
   runScheduledTask: (name: string) => Promise<unknown>
 }

package/src/wirings/workflow/feature.test.ts

@@ -0,0 +1,131 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveFeatureScenarios } from './feature.js'
+import type { CoreFeature, CoreWorkflow } from './workflow.types.js'
+
+const scenario = (tags: string[] = []) =>
+  ({ tags, func: async () => ({}) }) as any
+
+const registered = (entries: Array<[string, any]>): Map<string, CoreWorkflow> =>
+  new Map(entries.map(([name, func]) => [name, { name, func }]))
+
+describe('resolveFeatureScenarios', () => {
+  test('resolves imported identifiers to the names they are registered under', () => {
+    const lazyLoad = scenario()
+    const roundTrip = scenario()
+    const features = new Map<string, CoreFeature>([
+      [
+        'credentialFeature',
+        {
+          name: 'Credential API',
+          scenarios: [lazyLoad, roundTrip],
+        },
+      ],
+    ])
+
+    const { entries, unresolved } = resolveFeatureScenarios(
+      features,
+      registered([
+        ['credentialLazyLoadScenario', lazyLoad],
+        ['credentialRoundTripScenario', roundTrip],
+      ])
+    )
+
+    assert.deepEqual(unresolved, [])
+    assert.deepEqual(
+      entries.map((e) => e.scenarioName),
+      ['credentialLazyLoadScenario', 'credentialRoundTripScenario']
+    )
+    assert.equal(entries[0]!.featureName, 'Credential API')
+    assert.equal(entries[0]!.featureId, 'credentialFeature')
+  })
+
+  test('keeps declaration order, including repeats of the same scenario', () => {
+    const roundTrip = scenario()
+    const features = new Map<string, CoreFeature>([
+      [
+        'credentialFeature',
+        {
+          name: 'Credential API',
+          scenarios: ['stripe', 'google', 'hmac-key'].map((name) => ({
+            scenario: roundTrip,
+            data: { name },
+          })),
+        },
+      ],
+    ])
+
+    const { entries } = resolveFeatureScenarios(
+      features,
+      registered([['credentialRoundTripScenario', roundTrip]])
+    )
+
+    assert.equal(entries.length, 3, 'a mapped loop is three separate runs')
+    assert.deepEqual(
+      entries.map((e) => e.data),
+      [{ name: 'stripe' }, { name: 'google' }, { name: 'hmac-key' }]
+    )
+    assert.ok(
+      entries.every((e) => e.scenarioName === 'credentialRoundTripScenario')
+    )
+  })
+
+  test('a bare reference carries no data', () => {
+    const lazyLoad = scenario()
+    const { entries } = resolveFeatureScenarios(
+      new Map([['f', { name: 'F', scenarios: [lazyLoad] } as CoreFeature]]),
+      registered([['lazyLoadScenario', lazyLoad]])
+    )
+    assert.equal(entries[0]!.data, undefined)
+  })
+
+  test("a scenario's effective tags union its own with the feature's", () => {
+    const lazyLoad = scenario(['scenario', 'credential'])
+    const { entries } = resolveFeatureScenarios(
+      new Map([
+        [
+          'f',
+          {
+            name: 'F',
+            tags: ['nightly', 'credential'],
+            scenarios: [lazyLoad],
+          } as CoreFeature,
+        ],
+      ]),
+      registered([['lazyLoadScenario', lazyLoad]])
+    )
+    assert.deepEqual(entries[0]!.tags, ['scenario', 'credential', 'nightly'])
+  })
+
+  test('an unregistered scenario is reported, never silently matched by shape', () => {
+    const registeredScenario = scenario()
+    const lookalike = scenario()
+    const { entries, unresolved } = resolveFeatureScenarios(
+      new Map([
+        [
+          'f',
+          {
+            name: 'F',
+            scenarios: [registeredScenario, lookalike],
+          } as CoreFeature,
+        ],
+      ]),
+      registered([['realScenario', registeredScenario]])
+    )
+    assert.deepEqual(
+      entries.map((e) => e.scenarioName),
+      ['realScenario']
+    )
+    assert.deepEqual(unresolved, [{ featureId: 'f', index: 1 }])
+  })
+
+  test('a feature with no scenarios contributes nothing', () => {
+    const { entries, unresolved } = resolveFeatureScenarios(
+      new Map([['f', { name: 'F', scenarios: [] } as CoreFeature]]),
+      registered([])
+    )
+    assert.deepEqual(entries, [])
+    assert.deepEqual(unresolved, [])
+  })
+})