@nanobpm/urban 0.49.0 → 0.49.1

package/dist/runtime/core/host.d.ts

@@ -187,6 +187,13 @@ export interface WorkerSubscription {
  * element-instance state set (which adds SKIPPED/CANCELED/FAILED for tokens).
  */
 export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
+/**
+ * A user task's lifecycle state, as the engine reports it on a `/v2/user-tasks/search`
+ * result. `CREATED` is the only *open* (answerable) state — a task in any other state has
+ * already been answered (`COMPLETED`), withdrawn (`CANCELED`), or errored (`FAILED`) and must
+ * never surface in the `taskInbox` as if it were actionable.
+ */
+export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
 /** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
 export interface ProcessInstanceSnapshot {
     readonly processInstanceKey: string;
@@ -253,12 +260,16 @@ export interface EngineClient {
         correlationKey?: string;
         variables?: Record<string, unknown>;
     }): Promise<void>;
-    /** Search open user tasks (optionally by process instance). Each result carries the
-     *  task's resolved form linkage (`formKey`/`externalFormReference`) when present. */
+    /** Search user tasks (optionally by process instance, assignee, or candidate group).
+     *  By default this is unfiltered by lifecycle state and may return tasks in any state
+     *  (e.g. completed/canceled); pass `state: "CREATED"` to constrain the search to open
+     *  (answerable) tasks. Each result carries the task's resolved form linkage
+     *  (`formKey`/`externalFormReference`) when present. */
     searchUserTasks(filter?: {
         processInstanceKey?: string;
         assignee?: string;
         candidateGroup?: string;
+        state?: UserTaskState;
     }): Promise<UserTaskSummary[]>;
     /**
      * Fetch a deployed form's form-js schema for the `taskInbox` surface. Resolve by

package/dist/runtime/core/modules/surfaces.js

@@ -201,7 +201,14 @@ export function mountSurfaces(ctx, app) {
             source: "surface:taskInbox",
             handler: async (req) => {
                 const pik = req.query.get("processInstanceKey") ?? undefined;
-                const tasks = await app.engine.searchUserTasks(pik ? { processInstanceKey: pik } : undefined);
+                // Constrain the inbox to open (answerable) tasks. Without a state filter the engine
+                // returns tasks in every state (CREATED/COMPLETED/CANCELED/...), so already-answered
+                // or withdrawn tasks would surface as if actionable — completing one then fails with
+                // "User task ... is not active". See nanobpm/nano-ide#248.
+                const tasks = await app.engine.searchUserTasks({
+                    state: "CREATED",
+                    ...(pik ? { processInstanceKey: pik } : {}),
+                });
                 return json(tasks);
             },
         });

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskSummary, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -140,6 +140,7 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKey?: string;
         assignee?: string;
         candidateGroup?: string;
+        state?: UserTaskState;
     }): Promise<UserTaskSummary[]>;
     getForm(input: {
         formKey?: string;

package/dist/runtime/engine/nanosdk.js

@@ -101,7 +101,13 @@ export class SdkEngineClient {
     async searchUserTasks(filter) {
         // User tasks are an eventually consistent read; ask for zero-wait consistency so
         // the search reflects what is currently visible without blocking.
-        const body = await this.client.searchUserTasks({ filter: { ...(filter ?? {}) } }, { consistency: { waitUpToMs: 0 } });
+        const body = await this.client.searchUserTasks(
+        // This method is contracted to return *open* tasks; constrain the read to
+        // CREATED so answered/canceled tasks never surface as answerable (e.g. a
+        // re-escalated instance whose prior escalation task is already COMPLETED).
+        // Spread caller filters first and pin `state` last so a caller can never
+        // override the open-only (CREATED) constraint this method contracts to.
+        { filter: { ...(filter ?? {}), state: "CREATED" } }, { consistency: { waitUpToMs: 0 } });
         const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
         return items.flatMap((it) => {
             const userTaskKey = it.userTaskKey ?? it.key;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.49.0",
+	"version": "0.49.1",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/core/host.ts

@@ -217,6 +217,14 @@ export interface WorkerSubscription {
  */
 export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
 
+/**
+ * A user task's lifecycle state, as the engine reports it on a `/v2/user-tasks/search`
+ * result. `CREATED` is the only *open* (answerable) state — a task in any other state has
+ * already been answered (`COMPLETED`), withdrawn (`CANCELED`), or errored (`FAILED`) and must
+ * never surface in the `taskInbox` as if it were actionable.
+ */
+export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
+
 /** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
 export interface ProcessInstanceSnapshot {
   readonly processInstanceKey: string;
@@ -277,12 +285,16 @@ export interface EngineClient {
     correlationKey?: string;
     variables?: Record<string, unknown>;
   }): Promise<void>;
-  /** Search open user tasks (optionally by process instance). Each result carries the
-   *  task's resolved form linkage (`formKey`/`externalFormReference`) when present. */
+  /** Search user tasks (optionally by process instance, assignee, or candidate group).
+   *  By default this is unfiltered by lifecycle state and may return tasks in any state
+   *  (e.g. completed/canceled); pass `state: "CREATED"` to constrain the search to open
+   *  (answerable) tasks. Each result carries the task's resolved form linkage
+   *  (`formKey`/`externalFormReference`) when present. */
   searchUserTasks(filter?: {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
+    state?: UserTaskState;
   }): Promise<UserTaskSummary[]>;
   /**
    * Fetch a deployed form's form-js schema for the `taskInbox` surface. Resolve by

package/src/runtime/core/modules/surfaces.test.ts

@@ -171,12 +171,28 @@ test("/api/tasks surfaces the resolved form linkage", async () => {
   };
   const { tasks } = inboxRoutes(engine);
   const res = await call(tasks, { query: "processInstanceKey=pi-9" });
-  assert.deepEqual(seenFilter, { processInstanceKey: "pi-9" });
+  assert.deepEqual(seenFilter, { state: "CREATED", processInstanceKey: "pi-9" });
   const parsed = JSON.parse(String(res.body));
   assert.equal(parsed[0].formKey, "form-123");
   assert.equal(parsed[1].formKey, undefined);
 });
 
+test("/api/tasks constrains the search to open (CREATED) tasks", async () => {
+  let seenFilter: unknown;
+  const engine: EngineClient = {
+    ...fakeEngine,
+    searchUserTasks: async (filter) => {
+      seenFilter = filter;
+      return [];
+    },
+  };
+  const { tasks } = inboxRoutes(engine);
+  await call(tasks);
+  // No processInstanceKey supplied, but the inbox must still pin state=CREATED so that
+  // already-answered/canceled tasks never surface as answerable (nanobpm/nano-ide#248).
+  assert.deepEqual(seenFilter, { state: "CREATED" });
+});
+
 test("/api/form resolves a linked form's schema", async () => {
   let seen: unknown;
   const schema = { type: "default", schemaVersion: 18, components: [{ type: "textfield", key: "name", label: "Name" }] };

package/src/runtime/core/modules/surfaces.ts

@@ -215,7 +215,14 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
       source: "surface:taskInbox",
       handler: async (req) => {
         const pik = req.query.get("processInstanceKey") ?? undefined;
-        const tasks = await app.engine.searchUserTasks(pik ? { processInstanceKey: pik } : undefined);
+        // Constrain the inbox to open (answerable) tasks. Without a state filter the engine
+        // returns tasks in every state (CREATED/COMPLETED/CANCELED/...), so already-answered
+        // or withdrawn tasks would surface as if actionable — completing one then fails with
+        // "User task ... is not active". See nanobpm/nano-ide#248.
+        const tasks = await app.engine.searchUserTasks({
+          state: "CREATED",
+          ...(pik ? { processInstanceKey: pik } : {}),
+        });
         return json(tasks);
       },
     });

package/src/runtime/engine/nanosdk.test.ts

@@ -177,8 +177,10 @@ test("publishMessage defaults correlationKey/variables", async () => {
 
 test("searchUserTasks passes zero-wait consistency and maps items", async () => {
   let consistency: unknown;
+  let input: { filter?: Record<string, unknown> } | undefined;
   const client = fakeSdkClient({
-    searchUserTasks: async (_input, c) => {
+    searchUserTasks: async (i, c) => {
+      input = i;
       consistency = c;
       return {
         items: [
@@ -192,6 +194,11 @@ test("searchUserTasks passes zero-wait consistency and maps items", async () =>
   const engine = new SdkEngineClient(client);
   const tasks = await engine.searchUserTasks({ processInstanceKey: "pi" });
   assert.deepEqual(consistency, { consistency: { waitUpToMs: 0 } });
+  // The search is constrained to open (CREATED) tasks so terminal tasks never
+  // surface as answerable, while caller filters (processInstanceKey) still apply.
+  // Assert individual fields so the check is independent of key insertion order.
+  assert.equal(input?.filter?.state, "CREATED");
+  assert.equal(input?.filter?.processInstanceKey, "pi");
   assert.deepEqual(tasks, [
     { userTaskKey: "7", elementId: "task_a", variables: { x: 1 } },
     { userTaskKey: "8", elementId: undefined, variables: undefined },

package/src/runtime/engine/nanosdk.ts

@@ -18,6 +18,7 @@ import type {
   JobHandler,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
+  UserTaskState,
   UserTaskSummary,
   WorkerSubscription,
 } from "../core/host.ts";
@@ -221,11 +222,17 @@ export class SdkEngineClient implements EngineClient {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
+    state?: UserTaskState;
   }): Promise<UserTaskSummary[]> {
     // User tasks are an eventually consistent read; ask for zero-wait consistency so
     // the search reflects what is currently visible without blocking.
     const body = await this.client.searchUserTasks(
-      { filter: { ...(filter ?? {}) } },
+      // This method is contracted to return *open* tasks; constrain the read to
+      // CREATED so answered/canceled tasks never surface as answerable (e.g. a
+      // re-escalated instance whose prior escalation task is already COMPLETED).
+      // Spread caller filters first and pin `state` last so a caller can never
+      // override the open-only (CREATED) constraint this method contracts to.
+      { filter: { ...(filter ?? {}), state: "CREATED" } },
       { consistency: { waitUpToMs: 0 } },
     );
     const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];