@pikku/core 0.12.86 → 0.12.88

package/src/wirings/agent/agent.types.ts

@@ -6,6 +6,7 @@ import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
 } from '../../middleware/middleware.types.js'
+import type { CoreSingletonServices } from '../../types/core.types.js'
 import type { PermissionMetadata } from '../../function/function-meta.types.js'
 import type { AIProviderOptions } from '../../services/agent-runner-service.js'
 import type { PikkuChannel } from '../channel/channel.types.js'
@@ -180,10 +181,10 @@ export interface AgentToolDef extends Partial<ApprovalPolicy> {
 
 export interface PikkuAgentMiddlewareHooks<
   State extends Record<string, unknown> = Record<string, unknown>,
-  Services = any,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
 > {
   modifyInput?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       messages: AgentMessage[]
       instructions: string
@@ -210,7 +211,7 @@ export interface PikkuAgentMiddlewareHooks<
     | { messages: AgentMessage[]; instructions: string }
 
   modifyOutputStream?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       event: AgentStreamEvent
       allEvents: readonly AgentStreamEvent[]
@@ -262,7 +263,7 @@ export interface PikkuAgentMiddlewareHooks<
    * leaves them untouched.
    */
   modifyOutput?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       text: string
       messages: AgentMessage[]
@@ -282,7 +283,7 @@ export interface PikkuAgentMiddlewareHooks<
       }
 
   beforeToolCall?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       toolName: string
       toolCallId: string
@@ -294,7 +295,7 @@ export interface PikkuAgentMiddlewareHooks<
     | void
 
   afterToolCall?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       toolName: string
       toolCallId: string
@@ -305,7 +306,7 @@ export interface PikkuAgentMiddlewareHooks<
   ) => Promise<{ result: unknown } | void> | { result: unknown } | void
 
   afterStep?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       stepNumber: number
       text: string
@@ -323,7 +324,7 @@ export interface PikkuAgentMiddlewareHooks<
   ) => Promise<void> | void
 
   onError?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       error: Error
       stepNumber: number

package/src/wirings/variable/validate-variable-definitions.test.ts

@@ -89,26 +89,27 @@ describe('validateAndBuildVariableDefinitionsMeta', () => {
     assert.deepStrictEqual(result, {})
   })
 
-  test('carries required into the meta so only the opted-in ones block a deploy', () => {
+  test('carries optional into the meta so only the opted-out ones skip the gate', () => {
     const result = validateAndBuildVariableDefinitionsMeta(
       [
-        {
-          name: 'consoleUrl',
-          displayName: 'Console URL',
-          variableId: 'CONSOLE_URL',
-          required: true,
-          sourceFile: 'a.ts',
-        },
         {
           name: 'corsOrigins',
           displayName: 'Allowed Browser Origins',
           variableId: 'CORS_ORIGINS',
+          optional: true,
+          sourceFile: 'a.ts',
+        },
+        {
+          name: 'consoleUrl',
+          displayName: 'Console URL',
+          variableId: 'CONSOLE_URL',
           sourceFile: 'a.ts',
         },
       ] as any,
       new Map()
     )
-    assert.strictEqual(result['consoleUrl']!.required, true)
-    assert.strictEqual(result['corsOrigins']!.required, undefined)
+    assert.strictEqual(result['corsOrigins']!.optional, true)
+    // Undeclared means required, which is what makes the gate ask by default.
+    assert.strictEqual(result['consoleUrl']!.optional, undefined)
   })
 })

package/src/wirings/variable/validate-variable-definitions.ts

@@ -43,7 +43,7 @@ export function validateAndBuildVariableDefinitionsMeta(
           description: def.description,
           variableId: def.variableId,
           schema: def.schema,
-          required: def.required,
+          optional: def.optional,
           docsUrl: def.docsUrl,
           sourceFile: def.sourceFile,
         }
@@ -60,7 +60,7 @@ export function validateAndBuildVariableDefinitionsMeta(
         description: def.description,
         variableId: def.variableId,
         schema: def.schema,
-        required: def.required,
+        optional: def.optional,
         docsUrl: def.docsUrl,
         sourceFile: def.sourceFile,
       }

package/src/wirings/variable/variable.types.ts

@@ -5,13 +5,19 @@ export type CoreVariable<T = unknown> = {
   variableId: string
   schema: T
   /**
-   * A variable is OPTIONAL by default because `variables.get` returns
-   * `T | undefined` and never throws — every caller already handles absence, so
-   * a deploy gate that blocks on one contradicts the API. Mark a variable
-   * `required` for the few whose absence genuinely breaks the app; only those
-   * block a deploy.
+   * A variable is REQUIRED by default, and marking it `optional` is how a
+   * declaration says its absence is a supported state. Same flag, same
+   * polarity and same meaning as `CoreSecret.optional` — one word to learn
+   * rather than two with opposite senses.
+   *
+   * Defaulting to required rather than following `variables.get`'s
+   * `T | undefined` return is deliberate. That signature describes what a
+   * caller must HANDLE, not whether a deployment is correct without the value:
+   * an undefined feature flag is fine, an undefined API base URL is an outage
+   * that the type system cannot tell apart. Declaring the difference is the
+   * point of the flag, and the safe default for an undeclared one is to ask.
    */
-  required?: boolean
+  optional?: boolean
   docsUrl?: string
 }
 
@@ -21,7 +27,7 @@ export type VariableDefinitionMeta = {
   description?: string
   variableId: string
   schema?: Record<string, unknown> | string
-  required?: boolean
+  optional?: boolean
   docsUrl?: string
   sourceFile?: string
 }

package/src/wirings/workflow/pikku-scenario-service.ts

@@ -59,8 +59,34 @@ const assertionStep = <T extends WorkflowStepOptions>(
   ({ ...options, retries: options?.retries ?? 0 }) as T & { retries: number }
 
 export { addFeature, resolveFeatureScenarios } from './feature.js'
-export type * from './scenario.types.js'
-export type * from './scenario-run.types.js'
+export type {
+  CoreFeature,
+  CoreFeatureScenario,
+  FeatureMeta,
+  FeaturesMeta,
+  PikkuBrowserWire,
+  PikkuScenarioWire,
+  ScenarioBrowserFailure,
+  ScenarioBrowserProvider,
+  ScenarioEnvironment,
+  ScenarioStepKind,
+  ScenarioStepMeta,
+  ScenarioStepOptions,
+  ScenarioStepPhase,
+  ScenarioSurface,
+  TestIdSelector,
+} from './scenario.types.js'
+export type {
+  ScenarioArtifact,
+  ScenarioFailureDetail,
+  ScenarioResult,
+  ScenarioRunRecord,
+  ScenarioRunReport,
+  ScenarioRunStatus,
+  ScenarioRunStore,
+  ScenarioRunSummary,
+  ScenarioStepRow,
+} from './scenario-run.types.js'
 export { SCENARIO_SURFACES } from './scenario-step.types.js'
 
 // Which of a step's bindings run: one for an action, every witness for a `then`
@@ -979,10 +1005,7 @@ export class PikkuScenarioService implements WorkflowRunExtension {
    * Whether a step is driven by a persona, and so must be given one. Stamped by
    * the definer from a `browser` binding or an explicit `actor: true`.
    */
-  private requiresActor(
-    packageName: string | null,
-    stepFunc: string
-  ): boolean {
+  private requiresActor(packageName: string | null, stepFunc: string): boolean {
     return (
       this.scenarioStepConfig(packageName, stepFunc)?.requiresActor === true
     )

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -68,7 +68,6 @@ import {
   WorkflowRunCancelledError,
   WorkflowRunFailedError,
   WorkflowRunNotFoundError,
-  WorkflowStepFunctionMismatchError,
   WorkflowStepNameNotString,
   WorkflowSuspendedException,
 } from './workflow-errors.js'
@@ -95,6 +94,7 @@ import {
 } from './workflow-approval.js'
 import { auditApprovalDecision } from './workflow-approval-audit.js'
 import { recordSuspension, suspendStepNameFor } from './workflow-suspend.js'
+import { claimStepByReadThenWrite } from './workflow-step-claim.js'
 import {
   RedispatchBackoff,
   sweepStalledRuns,
@@ -639,12 +639,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    *
    * Returns nothing by default so a store that cannot express the query keeps
    * working unchanged — and, because it does not opt in, gains no re-dispatches
-   * either. A store must have an atomic `withStepLock` before overriding this,
-   * or no concurrency for one to exclude: the relay makes duplicate dispatch
-   * routine, and the claim in `executeWorkflowStepInner` is what keeps a
-   * duplicate from becoming a second execution. `kysely-postgres` and
-   * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
-   * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+   * either. A store must have an atomic `claimStepForExecution` before
+   * overriding this, or no concurrency for one to exclude: the relay makes
+   * duplicate dispatch routine, and the claim is what keeps a duplicate from
+   * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
+   * status-guarded claim, `in-memory` on being inline and single-process;
+   * `mongodb` still qualifies on neither.
    */
   protected async findUndispatchedSteps(
     _before: Date,
@@ -1300,6 +1300,29 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
   }
 
+  /**
+   * Take sole ownership of a step before it runs, returning the state to run
+   * under — or `null` when another dispatch already owns it.
+   *
+   * Dispatch is at-least-once by design: the relay re-dispatches steps it
+   * believes were dropped, and a queue can redeliver a job it already handed
+   * out. This is the one place that keeps a duplicate dispatch from becoming a
+   * second execution of a side-effecting step, so it is only as strong as the
+   * exclusion it is built on — and `withStepLock` excludes nothing unless the
+   * store backs it with a real primitive. A store able to express the decision
+   * as one conditional write should override this rather than reach for a lock,
+   * which is what `@pikku/kysely` does with a status-guarded `UPDATE`.
+   */
+  protected async claimStepForExecution(
+    runId: string,
+    stepName: string,
+    rpcName: string
+  ): Promise<StepState | null> {
+    return this.withStepLock(runId, stepName, () =>
+      claimStepByReadThenWrite(this, runId, stepName, rpcName)
+    )
+  }
+
   private async executeWorkflowStepInner(
     runId: string,
     stepName: string,
@@ -1307,26 +1330,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     data: any,
     rpcService: PikkuRPC
   ): Promise<void> {
-    const claimed = await this.withStepLock(runId, stepName, async () => {
-      const stepState = await this.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 this.createRetryAttempt(stepState.stepId, 'running')
-      }
-      if (stepState.status === 'pending' || stepState.status === 'scheduled') {
-        await this.setStepRunning(stepState.stepId)
-      }
-      return stepState
-    })
+    const claimed = await this.claimStepForExecution(runId, stepName, rpcName)
 
     if (!claimed) {
       return

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
+}