@pikku/core 0.12.83 → 0.12.86

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.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.
-  'ai-agent': ['channel', 'rpc', 'ai-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.
-  'ai-scorer': ['ai-agent', 'queue'],
+  'agent-scorer': ['agent', 'queue'],
   // `wire.rpc.agent` — the facade lives with the agent runtime it delegates to.
-  rpc: ['ai-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'],