@pikku/core 0.12.80 → 0.12.82

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

@@ -0,0 +1,68 @@
+import { ForbiddenError } from '../../errors/errors.js'
+import { addError } from '../../errors/error-handler.js'
+import type { CoreUserSession } from '../../types/core.types.js'
+import type {
+  ApprovalDecider,
+  WorkflowApprovalPolicy,
+} from './dsl/workflow-dsl.types.js'
+
+export class WorkflowApprovalForbiddenError extends ForbiddenError {
+  public payload: { reason: string; detail: string }
+  constructor(reason: string, detail: string) {
+    super(detail)
+    this.payload = { reason, detail }
+  }
+}
+addError(WorkflowApprovalForbiddenError, {
+  status: 403,
+  message: 'Not authorized to answer this approval.',
+})
+
+export const approvalDeciderFrom = (
+  session: CoreUserSession | undefined
+): ApprovalDecider | undefined =>
+  session ? { userId: session.userId, scopes: session.scopes } : undefined
+
+/**
+ * Judge a decision against the gate's declared policy, returning the reason it
+ * is refused or `undefined` if it stands.
+ *
+ * Returns a message rather than throwing because the same judgement is needed
+ * in two places with different outcomes: refusing a live submission with a 403,
+ * and clearing an already-recorded decision on replay.
+ */
+export const approvalPolicyRefusal = (
+  policy: WorkflowApprovalPolicy,
+  owner: string | undefined,
+  decider: ApprovalDecider | undefined
+): string | undefined => {
+  if (
+    policy.approverScope &&
+    !decider?.scopes?.includes(policy.approverScope)
+  ) {
+    return `Answering this approval requires the '${policy.approverScope}' scope`
+  }
+
+  switch (policy.approvers ?? 'any') {
+    case 'owner':
+      if (!owner) {
+        return undefined
+      }
+      if (!decider?.userId || decider.userId !== owner) {
+        return 'Only the user who started this run may answer this approval'
+      }
+      return undefined
+
+    case 'not-initiator':
+      if (!decider?.userId) {
+        return 'Answering this approval requires a signed-in user'
+      }
+      if (owner && decider.userId === owner) {
+        return 'The user who started this run may not answer this approval'
+      }
+      return undefined
+
+    case 'any':
+      return undefined
+  }
+}

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

@@ -8,6 +8,14 @@ import type {
   StepState,
   WorkflowApprovalOptions,
 } from './workflow.types.js'
+import type {
+  ApprovalDecider,
+  WorkflowApprovalPolicy,
+} from './dsl/workflow-dsl.types.js'
+import {
+  approvalPolicyRefusal,
+  WorkflowApprovalForbiddenError,
+} from './workflow-approval-policy.js'
 
 /** The durable step name an approval point is recorded under. */
 export const approvalStepNameFor = (reason: string): string =>
@@ -28,6 +36,21 @@ export const approvalStateKey = (stepName: string): string => {
   return `__approval_${hex}`
 }
 
+/**
+ * An answer to an approval gate, as the audit trail sees it.
+ *
+ * `denied` covers both a submission refused at the door and a decision cleared
+ * on replay — from the trail's point of view they are the same event, someone
+ * tried to answer a gate they could not.
+ */
+export type ApprovalAuditEvent = {
+  runId: string
+  reason: string
+  outcome: 'success' | 'denied'
+  decidedBy?: ApprovalDecider
+  refusal?: string
+}
+
 /** What the approval gate needs from the workflow service. */
 export type ApprovalStore = {
   getStepState: (runId: string, stepName: string) => Promise<StepState>
@@ -45,6 +68,18 @@ export type ApprovalStore = {
   updateRunState: (runId: string, key: string, value: unknown) => Promise<void>
   resumeWorkflow: (runId: string) => Promise<void>
   scheduleRunWake: (runId: string, delay: number) => Promise<void>
+  getRunOwner: (runId: string) => Promise<string | undefined>
+  auditApproval: (event: ApprovalAuditEvent) => Promise<void>
+}
+
+/** What run state holds for an approval point between suspension and replay. */
+type ApprovalRecord = {
+  decision?: unknown
+  decidedAt?: string
+  decidedBy?: ApprovalDecider
+  policy?: WorkflowApprovalPolicy
+  expiresAt?: string
+  error?: unknown
 }
 
 /**
@@ -53,12 +88,19 @@ export type ApprovalStore = {
  * A decision arriving for an already-settled approval is refused rather than
  * overwriting it: the run has moved on, and a second answer would be recorded
  * against a gate nobody is waiting at.
+ *
+ * The decider is recorded rather than judged here, for the same reason the
+ * payload is: the gate's policy is a value on the workflow, and a decision can
+ * legitimately arrive before the run has ever reached the gate. Where the run
+ * has already published its policy, it is applied eagerly so a caller who
+ * cannot answer is told so rather than left waiting.
  */
 export const recordApprovalDecision = async (
   store: ApprovalStore,
   runId: string,
   reason: string,
-  decision: unknown
+  decision: unknown,
+  decidedBy?: ApprovalDecider
 ): Promise<void> => {
   const stepName = approvalStepNameFor(reason)
   const stateKey = approvalStateKey(stepName)
@@ -78,13 +120,34 @@ export const recordApprovalDecision = async (
   }
 
   const state = await store.getRunState(runId)
-  const record = (state[stateKey] ?? {}) as Record<string, unknown>
+  const record = (state[stateKey] ?? {}) as ApprovalRecord
+
+  if (record.policy) {
+    const refusal = approvalPolicyRefusal(
+      record.policy,
+      await store.getRunOwner(runId),
+      decidedBy
+    )
+    if (refusal) {
+      await store.auditApproval({
+        runId,
+        reason,
+        outcome: 'denied',
+        decidedBy,
+        refusal,
+      })
+      throw new WorkflowApprovalForbiddenError(reason, refusal)
+    }
+  }
+
   await store.updateRunState(runId, stateKey, {
     ...record,
     decision,
     decidedAt: new Date().toISOString(),
+    decidedBy,
     error: undefined,
-  })
+  } satisfies ApprovalRecord)
+  await store.auditApproval({ runId, reason, outcome: 'success', decidedBy })
   await store.resumeWorkflow(runId)
 }
 
@@ -95,6 +158,11 @@ export const recordApprovalDecision = async (
  * schema is a value on the workflow and only the workflow has it. A payload
  * that fails validation is cleared and the run suspends again, so a bad
  * submission cannot settle the gate.
+ *
+ * The decider is judged here for the same reason, and for one more: a decision
+ * can be recorded before the run has ever reached the gate, so submission time
+ * is not a point at which the policy is reliably knowable. Judging on replay is
+ * what makes the policy hold in every ordering.
  */
 export const evaluateApprovalStep = async (
   store: ApprovalStore,
@@ -109,7 +177,12 @@ export const evaluateApprovalStep = async (
       runId,
       approvalStepName,
       'pikkuWorkflowApproval',
-      { reason, expiry: options.expiry },
+      {
+        reason,
+        expiry: options.expiry,
+        approvers: options.approvers,
+        approverScope: options.approverScope,
+      },
       undefined,
       fromStepName
     )
@@ -129,15 +202,16 @@ export const evaluateApprovalStep = async (
   }
 
   const stateKey = approvalStateKey(approvalStepName)
-  let record = ((await store.getRunState(runId))[stateKey] ?? {}) as {
-    decision?: unknown
-    decidedAt?: string
-    expiresAt?: string
-    error?: unknown
+  let record = ((await store.getRunState(runId))[stateKey] ?? {}) as ApprovalRecord
+
+  const policy: WorkflowApprovalPolicy = {
+    approvers: options.approvers,
+    approverScope: options.approverScope,
   }
 
   if (stepState.status === 'pending') {
     await store.setStepRunning(stepState.stepId)
+    record = { ...record, policy }
     if (options.expiry !== undefined && !record.expiresAt) {
       const expiry = getDurationInMilliseconds(options.expiry)
       record = {
@@ -146,10 +220,35 @@ export const evaluateApprovalStep = async (
       }
       await store.updateRunState(runId, stateKey, record)
       await store.scheduleRunWake(runId, expiry)
+    } else {
+      await store.updateRunState(runId, stateKey, record)
     }
   }
 
   if (record.decision !== undefined) {
+    const refusal = approvalPolicyRefusal(
+      policy,
+      await store.getRunOwner(runId),
+      record.decidedBy
+    )
+    if (refusal) {
+      await store.updateRunState(runId, stateKey, {
+        ...record,
+        decision: undefined,
+        decidedAt: undefined,
+        decidedBy: undefined,
+        error: [{ message: refusal }],
+      } satisfies ApprovalRecord)
+      await store.auditApproval({
+        runId,
+        reason,
+        outcome: 'denied',
+        decidedBy: record.decidedBy,
+        refusal,
+      })
+      throw new WorkflowSuspendedException(runId, reason)
+    }
+
     const validation = await options.schema['~standard'].validate(
       record.decision
     )
@@ -158,6 +257,7 @@ export const evaluateApprovalStep = async (
         ...record,
         decision: undefined,
         decidedAt: undefined,
+        decidedBy: undefined,
         error: validation.issues.map((issue) => ({
           message: issue.message,
           path: issue.path?.map((segment) =>
@@ -167,9 +267,13 @@ export const evaluateApprovalStep = async (
       })
       throw new WorkflowSuspendedException(runId, reason)
     }
+    // Spread rather than assigned, so a gate answered without a session keeps
+    // the shape it had before there was anything to record.
     const outcome: ApprovalOutcome<unknown> = {
       status: 'decided',
       data: validation.value,
+      ...(record.decidedBy ? { decidedBy: record.decidedBy } : {}),
+      ...(record.decidedAt ? { decidedAt: record.decidedAt } : {}),
     }
     await store.setStepResult(stepState.stepId, outcome)
     return outcome

package/src/wirings/workflow/workflow-run-authority.test.ts

@@ -160,7 +160,7 @@ describe('workflow run ownership', () => {
     )
   })
 
-  test('approveStep refuses a caller who does not own the run', async () => {
+  test('approveStep does not impose ownership on a gate that did not ask for it', async () => {
     seedSingletons()
     const ws = new InMemoryWorkflowService()
     const runId = await ws.createRun('flow', {}, false, 'hash', {
@@ -168,23 +168,20 @@ describe('workflow run ownership', () => {
       pikkuUserId: 'owner',
     })
 
-    await assert.rejects(
-      ws.approveStep(
-        runId,
-        'release-funds',
-        { ok: true },
-        {
-          userId: 'attacker',
-        }
-      ),
-      ForbiddenError
+    await ws.approveStep(
+      runId,
+      'release-funds',
+      { ok: true },
+      {
+        userId: 'not-the-owner',
+      }
     )
 
     const state = await ws.getRunState(runId)
-    assert.deepEqual(
-      Object.keys(state),
-      [],
-      'no decision was recorded for the run'
+    assert.equal(
+      Object.keys(state).length,
+      1,
+      'the decision was recorded, to be judged against the gate on replay'
     )
   })
 

package/src/wirings/workflow/workflow-run-ownership.ts

@@ -15,7 +15,8 @@ addError(WorkflowRunForbiddenError, {
 
 /**
  * A run started through a session records that session's user as its owner, and
- * only that user may read it or answer its approval gates.
+ * only that user may read it. Who may *answer* a run's approval gates is the
+ * gate's own declaration — see `approvers` on `workflow.approval()`.
  *
  * A run with no recorded owner — started by a trigger, a scheduler, or a route
  * wired without auth — has nobody to compare a caller against, so ownership is

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

@@ -9,22 +9,13 @@ export type { WorkflowService } from '../../services/workflow-service.js'
 
 export type {
   WorkflowStepOptions,
-  WorkflowExpectEventuallyOptions,
-  WorkflowExpectErrorOptions,
-  WorkflowExpectServiceOptions,
   WorkflowWireDoRPC,
-  WorkflowWireDoInline,
-  WorkflowWireSleep,
-  WorkflowWireSuspend,
-  WorkflowWireApproval,
   WorkflowApprovalOptions,
   ApprovalOutcome,
   InputSource,
   OutputBinding,
   RpcStepMeta,
-  SimpleCondition,
   Condition,
-  BranchCase,
   BranchStepMeta,
   ParallelGroupStepMeta,
   FanoutStepMeta,

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

@@ -24,8 +24,12 @@ const ALLOWED: Record<string, string[]> = {
   // `remote` on a wire with no peer — one leaf module, not the channel runtime.
   http: ['channel'],
   cli: ['channel'],
-  // An agent streams over a channel and is invoked over rpc.
-  'ai-agent': ['channel', 'rpc'],
+  // 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'],
+  // 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'],
   // `wire.rpc.agent` — the facade lives with the agent runtime it delegates to.
   rpc: ['ai-agent'],
   gateway: ['http'],