@pikku/mongodb 0.12.19 → 0.12.20

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @pikku/mongodb
 
+## 0.12.20
+
+### Patch Changes
+
+- 3c0012c: Gate console agent-thread reads and deletes on thread ownership, claim MongoDB workflow steps atomically, and reach the deployment fallback from `rpcWithWire`
+
+  `getAgentThreadMessages` and `deleteAgentThread` in the console addon took a
+  caller-supplied `threadId` straight to storage, while their siblings
+  `getAgentThreads` and `getAgentThreadRuns` already filtered to what the session
+  owns. Both now carry an `isThreadOwner` permission: an admin reaches any thread,
+  everyone else only their own, and a missing thread is refused rather than 404'd
+  so it is indistinguishable from someone else's.
+
+  `MongoDBWorkflowService` claimed a step by reading its status and then writing
+  it, under a `withStepLock` that is a pass-through — so two dispatches racing for
+  the same step could both proceed and run a side-effecting step twice. The claim
+  is now a single status-guarded update, atomic on one document.
+
+  `rpcWithWire` threw `RPCNotFoundError` for any unresolved namespaced call
+  instead of falling through to the deployment service, so a namespaced RPC that
+  `rpc()` would have dispatched remotely failed when called with an explicit wire.
+
+- Updated dependencies [3c0012c]
+- Updated dependencies [05e47cf]
+- Updated dependencies [cfd364a]
+- Updated dependencies [05e47cf]
+- Updated dependencies [05e47cf]
+- Updated dependencies [05e47cf]
+  - @pikku/core@0.12.90
+
 ## 0.12.19
 
 ### Patch Changes

package/dist/src/mongodb-workflow-service.d.ts

@@ -44,7 +44,29 @@ export declare class MongoDBWorkflowService extends PikkuWorkflowService {
     protected setStepErrorImpl(stepId: string, error: Error): Promise<void>;
     protected createRetryAttemptImpl(stepId: string, status: 'pending' | 'running'): Promise<StepState>;
     withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * A pass-through: MongoDB has no advisory-lock primitive to build one on.
+     * The one decision that must exclude — claiming a step to execute it — is
+     * made by `claimStepForExecution` below as a single conditional write, which
+     * needs no lock to be exclusive.
+     */
     withStepLock<T>(_runId: string, _stepName: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Claim the step with a status-guarded update and read the modified count:
+     * a single-document update is atomic in MongoDB, so two dispatches racing for
+     * the same step cannot both proceed.
+     *
+     * This replaces the read-then-write the base engine does under
+     * `withStepLock`, which excludes nothing here — the lock above is a
+     * pass-through. The winner then goes through the ordinary transition methods,
+     * so history rows see exactly what they saw before.
+     */
+    protected claimStepForExecution(runId: string, stepName: string, rpcName: string): Promise<StepState | null>;
+    /**
+     * Move a step to `running` only if it is still in one of `from`, reporting
+     * whether this caller is the one that moved it.
+     */
+    private claimStepStatus;
     getCompletedGraphState(runId: string): Promise<{
         completedNodeIds: string[];
         failedNodeIds: string[];

package/dist/src/mongodb-workflow-service.js

@@ -1,4 +1,4 @@
-import { PikkuWorkflowService } from '@pikku/core/workflow';
+import { PikkuWorkflowService, WorkflowStepFunctionMismatchError, } from '@pikku/core/workflow';
 import { MongoDBWorkflowRunService } from './mongodb-workflow-run-service.js';
 export class MongoDBWorkflowService extends PikkuWorkflowService {
     initialized = false;
@@ -254,9 +254,61 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     async withRunLock(id, fn) {
         return fn();
     }
+    /**
+     * A pass-through: MongoDB has no advisory-lock primitive to build one on.
+     * The one decision that must exclude — claiming a step to execute it — is
+     * made by `claimStepForExecution` below as a single conditional write, which
+     * needs no lock to be exclusive.
+     */
     async withStepLock(_runId, _stepName, fn) {
         return fn();
     }
+    /**
+     * Claim the step with a status-guarded update and read the modified count:
+     * a single-document update is atomic in MongoDB, so two dispatches racing for
+     * the same step cannot both proceed.
+     *
+     * This replaces the read-then-write the base engine does under
+     * `withStepLock`, which excludes nothing here — the lock above is a
+     * pass-through. The winner then goes through the ordinary transition methods,
+     * so history rows see exactly what they saw before.
+     */
+    async claimStepForExecution(runId, stepName, rpcName) {
+        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') {
+            if (!(await this.claimStepStatus(stepState.stepId, ['failed']))) {
+                return null;
+            }
+            return this.createRetryAttempt(stepState.stepId, 'running');
+        }
+        if (stepState.status === 'pending' || stepState.status === 'scheduled') {
+            if (!(await this.claimStepStatus(stepState.stepId, [
+                'pending',
+                'scheduled',
+            ]))) {
+                return null;
+            }
+            await this.setStepRunning(stepState.stepId);
+            return { ...stepState, status: 'running' };
+        }
+        return stepState;
+    }
+    /**
+     * Move a step to `running` only if it is still in one of `from`, reporting
+     * whether this caller is the one that moved it.
+     */
+    async claimStepStatus(stepId, from) {
+        const claimed = await this.steps.updateOne({ _id: stepId, status: { $in: from } }, { $set: { status: 'running', updatedAt: new Date() } });
+        return claimed.modifiedCount > 0;
+    }
     async getCompletedGraphState(runId) {
         const results = await this.steps
             .find({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/mongodb",
-  "version": "0.12.19",
+  "version": "0.12.20",
   "description": "MongoDB services for Pikku — workflow state, agent runs, secrets and channel stores",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.85"
+    "@pikku/core": "^0.12.90"
   },
   "dependencies": {
     "mongodb": "^7.5.0"

package/src/mongodb-workflow-service.test.ts

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict'
 import { MongoClient, type Db } from 'mongodb'
 import { MongoMemoryServer } from 'mongodb-memory-server'
 
+import type { StepState } from '@pikku/core/workflow'
 import { MongoDBWorkflowService } from './mongodb-workflow-service.js'
 
 let mongod: MongoMemoryServer
@@ -119,3 +120,119 @@ describe('a step transition reaches the history', () => {
     assert.equal(state.attemptCount, 2)
   })
 })
+
+/**
+ * Dispatch is at-least-once — the relay re-dispatches a step it believes was
+ * dropped, and a queue can redeliver a job it already handed out — so the claim
+ * is the only thing standing between a duplicate dispatch and a second
+ * execution of a side-effecting step.
+ */
+describe('claiming a step for execution', () => {
+  const claim = (runId: string, stepName: string, rpcName = 'rpc.fn') =>
+    (ws as any).claimStepForExecution(
+      runId,
+      stepName,
+      rpcName
+    ) as Promise<StepState | null>
+
+  const seedRun = () =>
+    ws.createRun('flow', {}, false, 'hash', { type: 'test' } as any)
+
+  test('two dispatches racing for the same pending step: exactly one wins', async () => {
+    const runId = await seedRun()
+    await ws.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+
+    const claims = await Promise.all([claim(runId, 's1'), claim(runId, 's1')])
+    const winners = claims.filter((c) => c !== null)
+
+    assert.equal(
+      winners.length,
+      1,
+      `both dispatches claimed the step, so a side-effecting step would run twice: ${JSON.stringify(claims)}`
+    )
+    assert.equal((await ws.getStepState(runId, 's1')).status, 'running')
+  })
+
+  test('two dispatches racing to retry the same failed step: exactly one wins', async () => {
+    const runId = await seedRun()
+    const step = await ws.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+    await ws.setStepRunning(step.stepId)
+    await ws.setStepError(step.stepId, new Error('boom'))
+
+    const claims = await Promise.all([claim(runId, 's1'), claim(runId, 's1')])
+    const winners = claims.filter((c) => c !== null)
+
+    assert.equal(
+      winners.length,
+      1,
+      `both dispatches started a retry, so the failed step would be retried twice concurrently: ${JSON.stringify(claims)}`
+    )
+    assert.equal(
+      (await ws.getStepState(runId, 's1')).attemptCount,
+      2,
+      'the retry raced itself and burned more than one attempt'
+    )
+  })
+
+  test('two dispatches racing for the same scheduled step: exactly one wins', async () => {
+    const runId = await seedRun()
+    const step = await ws.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+    await ws.setStepScheduled(step.stepId)
+
+    const claims = await Promise.all([claim(runId, 's1'), claim(runId, 's1')])
+    const winners = claims.filter((c) => c !== null)
+
+    assert.equal(
+      winners.length,
+      1,
+      `both dispatches claimed the queued step, so a redelivered job would run it a second time: ${JSON.stringify(claims)}`
+    )
+    assert.equal((await ws.getStepState(runId, 's1')).status, 'running')
+  })
+
+  test('a step already claimed is not claimable again', async () => {
+    const runId = await seedRun()
+    await ws.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+
+    assert.notEqual(await claim(runId, 's1'), null)
+    assert.equal(
+      await claim(runId, 's1'),
+      null,
+      'a redelivered job re-claimed a step that is already running'
+    )
+  })
+
+  test('a succeeded step is not claimable', async () => {
+    const runId = await seedRun()
+    const step = await ws.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+    await ws.setStepRunning(step.stepId)
+    await ws.setStepResult(step.stepId, { ok: true })
+
+    assert.equal(await claim(runId, 's1'), null)
+  })
+
+  test('a claim that fails releases the step, so it is retryable', async () => {
+    const runId = await seedRun()
+    const step = await ws.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+
+    assert.notEqual(await claim(runId, 's1'), null)
+    await ws.setStepError(step.stepId, new Error('boom'))
+
+    const retry = await claim(runId, 's1')
+    assert.notEqual(
+      retry,
+      null,
+      'the failed step stayed claimed, so it can never be retried'
+    )
+    assert.equal(retry?.status, 'running')
+    assert.equal(retry?.attemptCount, 2)
+  })
+
+  test('a claim for a different function than the step was dispatched with is refused', async () => {
+    const runId = await seedRun()
+    await ws.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+
+    await assert.rejects(() => claim(runId, 's1', 'rpc.other'))
+    assert.equal((await ws.getStepState(runId, 's1')).status, 'pending')
+  })
+})

package/src/mongodb-workflow-service.ts

@@ -1,5 +1,8 @@
 import type { SerializedError } from '@pikku/core/errors'
-import { PikkuWorkflowService } from '@pikku/core/workflow'
+import {
+  PikkuWorkflowService,
+  WorkflowStepFunctionMismatchError,
+} from '@pikku/core/workflow'
 import type {
   WorkflowPlannedStep,
   WorkflowQueueOptions,
@@ -444,6 +447,12 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     return fn()
   }
 
+  /**
+   * A pass-through: MongoDB has no advisory-lock primitive to build one on.
+   * The one decision that must exclude — claiming a step to execute it — is
+   * made by `claimStepForExecution` below as a single conditional write, which
+   * needs no lock to be exclusive.
+   */
   async withStepLock<T>(
     _runId: string,
     _stepName: string,
@@ -452,6 +461,74 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     return fn()
   }
 
+  /**
+   * Claim the step with a status-guarded update and read the modified count:
+   * a single-document update is atomic in MongoDB, so two dispatches racing for
+   * the same step cannot both proceed.
+   *
+   * This replaces the read-then-write the base engine does under
+   * `withStepLock`, which excludes nothing here — the lock above is a
+   * pass-through. The winner then goes through the ordinary transition methods,
+   * so history rows see exactly what they saw before.
+   */
+  protected override async claimStepForExecution(
+    runId: string,
+    stepName: string,
+    rpcName: string
+  ): Promise<StepState | null> {
+    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') {
+      if (!(await this.claimStepStatus(stepState.stepId, ['failed']))) {
+        return null
+      }
+      return this.createRetryAttempt(stepState.stepId, 'running')
+    }
+
+    if (stepState.status === 'pending' || stepState.status === 'scheduled') {
+      if (
+        !(await this.claimStepStatus(stepState.stepId, [
+          'pending',
+          'scheduled',
+        ]))
+      ) {
+        return null
+      }
+      await this.setStepRunning(stepState.stepId)
+      return { ...stepState, status: 'running' }
+    }
+
+    return stepState
+  }
+
+  /**
+   * Move a step to `running` only if it is still in one of `from`, reporting
+   * whether this caller is the one that moved it.
+   */
+  private async claimStepStatus(
+    stepId: string,
+    from: StepStatus[]
+  ): Promise<boolean> {
+    const claimed = await this.steps.updateOne(
+      { _id: stepId, status: { $in: from } },
+      { $set: { status: 'running', updatedAt: new Date() } }
+    )
+
+    return claimed.modifiedCount > 0
+  }
+
   async getCompletedGraphState(runId: string): Promise<{
     completedNodeIds: string[]
     failedNodeIds: string[]