@pikku/core 0.12.84 → 0.12.88

package/src/wirings/workflow/scenario-step.test.ts

@@ -8,7 +8,7 @@ import { addFunction } from '../../function/function-runner.js'
 import type { ScenarioPersona } from '../../services/personas-service.js'
 import type { PikkuWire } from '../../types/core.types.js'
 import type { ScenarioSurface } from './scenario-step.types.js'
-import { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
+import { requireScenarioEnv } from './scenario-step-guards.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
@@ -145,6 +145,7 @@ const registerStep = (
   config: {
     description?: string
     surfaces?: ScenarioSurface[]
+    requiresActor?: boolean
     func: (services: any, data: any, wire: PikkuWire) => Promise<unknown>
   }
 ) => {
@@ -215,7 +216,7 @@ describe('pikkuScenarioStep (scenario.given/when/then)', () => {
     let received: unknown
     registerStep('checksOut', {
       func: async (_services, _data, wire) => {
-        received = wire.scenarioStep!.actor
+        received = wire.actor
         return null
       },
     })
@@ -712,16 +713,17 @@ describe('the scenario environment reaches the step wire', () => {
   })
 })
 
-describe('requireActor / requireScenarioEnv', () => {
+describe('a step driven by a persona is given its actor', () => {
   beforeEach(() => resetPikkuState())
 
-  test('requireActor returns the actor a step was called with', async () => {
+  test('the actor is on the wire, not something the body unwraps', async () => {
     const { workflowService: ws, scenarioService } = createScenarioRunner()
     const shopper = fakeActor('shopper', async () => null)
     let resolved: unknown
     registerStep('needsAnActor', {
+      requiresActor: true,
       func: async (_services, _data, wire) => {
-        resolved = requireActor(wire.scenarioStep)
+        resolved = wire.actor
         return null
       },
     })
@@ -735,10 +737,15 @@ describe('requireActor / requireScenarioEnv', () => {
     assert.equal(resolved, shopper)
   })
 
-  test('requireActor names the step when it was called without one', async () => {
+  test('one dispatched without an actor is refused before its body runs', async () => {
     const { workflowService: ws, scenarioService } = createScenarioRunner()
+    let bodyRan = false
     registerStep('needsAnActor', {
-      func: async (_services, _data, wire) => requireActor(wire.scenarioStep),
+      requiresActor: true,
+      func: async () => {
+        bodyRan = true
+        return null
+      },
     })
 
     const runId = await setup(ws)
@@ -747,6 +754,24 @@ describe('requireActor / requireScenarioEnv', () => {
       wire.when('nobody acts', 'needsAnActor'),
       /needsAnActor.*actor/s
     )
+    assert.equal(bodyRan, false)
+  })
+
+  test('a step that declares no persona runs without one', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    let seen: unknown = 'unset'
+    registerStep('assertsSomething', {
+      func: async (_services, _data, wire) => {
+        seen = wire.actor
+        return null
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.then('it holds', 'assertsSomething')
+
+    assert.equal(seen, undefined)
   })
 
   test('requireScenarioEnv returns the environment, or says how to declare one', async () => {

package/src/wirings/workflow/scenario-step.types.ts

@@ -1,4 +1,4 @@
-import type { ScenarioPersona } from '../../services/personas-service.js'
+import type { ScenarioArtifact } from './scenario-run.types.js'
 
 /**
  * Scenario steps: named, typed units of scenario behaviour.
@@ -99,7 +99,10 @@ export type ScenarioSurfaceResolution =
  * default to no retries.
  */
 export interface ScenarioStepOptions {
-  /** The actor this step runs as. Required for steps declaring a `browser` binding. */
+  /**
+   * The actor this step runs as. Required for a step that declares `actor: true`
+   * or a `browser` binding; the runner refuses to dispatch one without it.
+   */
   actor?: unknown
   /** Overrides the step's own `description` for this call site only. */
   description?: string
@@ -122,11 +125,12 @@ export interface ScenarioEnvironment {
 /**
  * The `scenarioStep` wire, present on every scenario step invocation.
  *
- * `TActor` is the project's own actor type, so a step reaches only the RPCs its
- * actors can actually call. It defaults to the open `ScenarioPersona` for a
- * project that declares no registry.
+ * The persona a step runs as is not here: it arrives as `wire.actor`, injected
+ * by the runner and typed as present exactly on the bindings that declared they
+ * need one. Keeping it off this interface is what makes that possible — a wire
+ * member can be required per binding, a property of one cannot.
  */
-export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
+export interface PikkuScenarioStepWire {
   /** Registered step name (also its pikkuFuncId) */
   name: string
   /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
@@ -138,12 +142,6 @@ export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
    * per witness, so its body sees this change between invocations.
    */
   surface: ScenarioSurface
-  /**
-   * The actor this step runs as, when one was given. Call RPCs through it
-   * (`actor.invoke(...)`) so they run against the target environment as that
-   * persona.
-   */
-  actor?: TActor
   /**
    * The environment this run targets. A step runs in the CLI process, where
    * there is no `variables` service — this is how a raw-HTTP step learns the
@@ -237,11 +235,28 @@ export interface ScenarioBrowserProvider {
    * folder — findable only by timestamp.
    */
   beginScenario?(scenario: string): void
+  /**
+   * Report how the scenario that just ran finished.
+   *
+   * Called after each scenario, and separate from `reset()` because artifacts
+   * that only exist once a window closes — a video — are produced by the NEXT
+   * scenario's reset, long after the outcome that decides whether to keep them.
+   */
+  endScenario?(outcome: 'passed' | 'failed'): void
   /**
    * Snapshot every open window for a failed scenario. `label` identifies the
    * scenario in artifact filenames. Never throws: a failure to capture must
    * not replace the failure being captured.
    */
   captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>
+  /**
+   * Everything the run filed, each entry naming the scenario it belongs to.
+   *
+   * Reported by the driver rather than discovered by scanning the directory:
+   * only the driver knows which window produced a file and under what caption,
+   * and a video's final name is not settled until the run closes. Read after
+   * `close()`, which is the first moment the answer is complete.
+   */
+  artifacts?(): ScenarioArtifact[]
   close(): Promise<void>
 }

package/src/wirings/workflow/workflow-approval-policy.test.ts

@@ -166,9 +166,14 @@ describe('approval policy enforcement', () => {
     })
     await runToGate(ws, runId)
 
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'someone-else',
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'someone-else',
+      }
+    )
     await ws.runWorkflowJob(runId, {})
 
     assert.equal((await ws.getRun(runId))?.status, 'completed')
@@ -188,15 +193,25 @@ describe('approval policy enforcement', () => {
     await runToGate(ws, runId)
 
     await assert.rejects(
-      ws.approveStep(runId, 'Release funds', { ok: true }, {
-        userId: 'initiator',
-      }),
+      ws.approveStep(
+        runId,
+        'Release funds',
+        { ok: true },
+        {
+          userId: 'initiator',
+        }
+      ),
       WorkflowApprovalForbiddenError
     )
 
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'reviewer',
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'reviewer',
+      }
+    )
     await ws.runWorkflowJob(runId, {})
 
     assert.equal((await ws.getRun(runId))?.status, 'completed')
@@ -216,15 +231,25 @@ describe('approval policy enforcement', () => {
     await runToGate(ws, runId)
 
     await assert.rejects(
-      ws.approveStep(runId, 'Release funds', { ok: true }, {
-        userId: 'attacker',
-      }),
+      ws.approveStep(
+        runId,
+        'Release funds',
+        { ok: true },
+        {
+          userId: 'attacker',
+        }
+      ),
       WorkflowApprovalForbiddenError
     )
 
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'initiator',
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'initiator',
+      }
+    )
     await ws.runWorkflowJob(runId, {})
 
     assert.equal((await ws.getRun(runId))?.status, 'completed')
@@ -244,17 +269,27 @@ describe('approval policy enforcement', () => {
     await runToGate(ws, runId)
 
     await assert.rejects(
-      ws.approveStep(runId, 'Release funds', { ok: true }, {
-        userId: 'reviewer',
-        scopes: ['payments:read'],
-      }),
+      ws.approveStep(
+        runId,
+        'Release funds',
+        { ok: true },
+        {
+          userId: 'reviewer',
+          scopes: ['payments:read'],
+        }
+      ),
       WorkflowApprovalForbiddenError
     )
 
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'reviewer',
-      scopes: ['payments:approve'],
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'reviewer',
+        scopes: ['payments:approve'],
+      }
+    )
     await ws.runWorkflowJob(runId, {})
 
     assert.equal((await ws.getRun(runId))?.status, 'completed')
@@ -280,10 +315,15 @@ describe('approval policy enforcement', () => {
     })
     await runToGate(ws, runId)
 
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'reviewer',
-      scopes: ['payments:approve'],
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'reviewer',
+        scopes: ['payments:approve'],
+      }
+    )
     await ws.runWorkflowJob(runId, {})
 
     const step = await ws.getStepState(
@@ -343,9 +383,14 @@ describe('approval policy enforcement', () => {
 
     // The gate has not been reached, so no policy has been published and the
     // submission cannot be judged here — it is accepted and judged on replay.
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'initiator',
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'initiator',
+      }
+    )
 
     await runToGate(ws, runId)
 
@@ -392,10 +437,15 @@ describe('approval audit trail', () => {
       pikkuUserId: 'initiator',
     })
     await runToGate(ws, runId)
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'reviewer',
-      scopes: ['payments:approve'],
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'reviewer',
+        scopes: ['payments:approve'],
+      }
+    )
     await ws.runWorkflowJob(runId, {})
 
     assert.equal(events.length, 1)
@@ -428,9 +478,14 @@ describe('approval audit trail', () => {
     await runToGate(ws, runId)
 
     await assert.rejects(
-      ws.approveStep(runId, 'Release funds', { ok: true }, {
-        userId: 'initiator',
-      }),
+      ws.approveStep(
+        runId,
+        'Release funds',
+        { ok: true },
+        {
+          userId: 'initiator',
+        }
+      ),
       WorkflowApprovalForbiddenError
     )
 
@@ -462,9 +517,14 @@ describe('approval audit trail', () => {
 
     // Submitted before the gate published its policy, so it is accepted here
     // and only refused on replay.
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'initiator',
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'initiator',
+      }
+    )
     assert.equal(events[0].outcome, 'success')
 
     await runToGate(ws, runId)
@@ -495,9 +555,14 @@ describe('approval audit trail', () => {
       pikkuUserId: 'initiator',
     })
     await runToGate(ws, runId)
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'reviewer',
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'reviewer',
+      }
+    )
     await ws.runWorkflowJob(runId, {})
 
     assert.equal((await ws.getRun(runId))?.status, 'completed')
@@ -513,12 +578,17 @@ describe('approval audit trail', () => {
       pikkuUserId: 'initiator',
     })
     await runToGate(ws, runId)
-    await ws.approveStep(runId, 'Release funds', { ok: true }, {
-      userId: 'reviewer',
-    })
+    await ws.approveStep(
+      runId,
+      'Release funds',
+      { ok: true },
+      {
+        userId: 'reviewer',
+      }
+    )
     await ws.runWorkflowJob(runId, {})
 
     assert.equal((await ws.getRun(runId))?.status, 'completed')
     cleanup()
   })
-})
+})

package/src/wirings/workflow/workflow-approval.ts

@@ -202,7 +202,8 @@ export const evaluateApprovalStep = async (
   }
 
   const stateKey = approvalStateKey(approvalStepName)
-  let record = ((await store.getRunState(runId))[stateKey] ?? {}) as ApprovalRecord
+  let record = ((await store.getRunState(runId))[stateKey] ??
+    {}) as ApprovalRecord
 
   const policy: WorkflowApprovalPolicy = {
     approvers: options.approvers,

package/src/wirings/workflow/workflow-run-engine.types.ts

@@ -1,4 +1,5 @@
-import type { PikkuRawWire, SerializedError } from '../../types/core.types.js'
+import type { PikkuRawWire } from '../../types/core.types.js'
+import type { SerializedError } from '../../errors/serialized-error.js'
 import type {
   CoreWorkflow,
   PikkuWorkflowWire,

package/src/wirings/workflow/workflow-step-claim.ts

@@ -0,0 +1,46 @@
+import { WorkflowStepFunctionMismatchError } from './workflow-errors.js'
+import type { StepState } from './workflow.types.js'
+
+/** What claiming a step needs from the workflow service. */
+export type StepClaimStore = {
+  getStepState(runId: string, stepName: string): Promise<StepState>
+  setStepRunning(stepId: string): Promise<void>
+  createRetryAttempt(
+    failedStepId: string,
+    status: 'pending' | 'running'
+  ): Promise<StepState>
+}
+
+/**
+ * Decide whether this dispatch owns the step, by reading its state and then
+ * writing it — which only excludes a concurrent dispatch when the caller holds
+ * a lock that genuinely excludes one.
+ *
+ * A store that can express the whole decision as a single conditional write
+ * should do that instead of calling this.
+ */
+export const claimStepByReadThenWrite = async (
+  store: StepClaimStore,
+  runId: string,
+  stepName: string,
+  rpcName: string
+): Promise<StepState | null> => {
+  const stepState = await store.getStepState(runId, stepName)
+  // knowledge: decisions/security/a-step-runs-the-function-the-workflow-dispatched-it-with.md
+  if (
+    stepState.rpcName !== undefined &&
+    stepState.rpcName !== (rpcName ?? null)
+  ) {
+    throw new WorkflowStepFunctionMismatchError(runId, stepName)
+  }
+  if (stepState.status === 'succeeded' || stepState.status === 'running') {
+    return null
+  }
+  if (stepState.status === 'failed') {
+    return store.createRetryAttempt(stepState.stepId, 'running')
+  }
+  if (stepState.status === 'pending' || stepState.status === 'scheduled') {
+    await store.setStepRunning(stepState.stepId)
+  }
+  return stepState
+}

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

@@ -1,4 +1,5 @@
-import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
+import type { CommonWireMeta } from '../../types/core.types.js'
+import type { SerializedError } from '../../errors/serialized-error.js'
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js'
 
@@ -62,21 +63,12 @@ export interface WorkflowPlannedStep {
 }
 
 export type WorkflowStatus =
-  | 'running'
-  | 'suspended'
-  | 'completed'
-  | 'failed'
-  | 'cancelled'
+  'running' | 'suspended' | 'completed' | 'failed' | 'cancelled'
 
 export type WorkflowVersionStatus = 'draft' | 'active' | 'declined'
 
 export type StepStatus =
-  | 'pending'
-  | 'running'
-  | 'scheduled'
-  | 'succeeded'
-  | 'failed'
-  | 'suspended'
+  'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed' | 'suspended'
 
 export interface WorkflowRun {
   id: string

package/src/wirings-stay-decoupled.test.ts

@@ -25,13 +25,16 @@ const ALLOWED: Record<string, string[]> = {
   http: ['channel'],
   cli: ['channel'],
   // An agent streams over a channel and is invoked over rpc, and grades itself
-  // as the last thing a finished run does.
-  agent: ['channel', 'rpc', 'agent-scorer'],
+  // as the last thing a finished run does. Its own functions may come from an
+  // installed addon, so it builds that addon's services the same way rpc does.
+  agent: ['channel', 'rpc', 'agent-scorer', 'addon'],
   // A judge is a degenerate agent — it builds agent messages and runs them —
   // and a grade is dispatched to a queue.
   'agent-scorer': ['agent', 'queue'],
   // `wire.rpc.agent` — the facade lives with the agent runtime it delegates to.
-  rpc: ['agent'],
+  // An rpc call is how an installed addon's function is reached, so the runner
+  // resolves the addon instance that owns the namespace.
+  rpc: ['agent', 'addon'],
   gateway: ['http'],
   mcp: ['rpc'],
   trigger: ['rpc'],