@nanobpm/nano-workforce 0.57.0 → 0.58.0

package/e2e/user-task-spine.e2e.ts

@@ -0,0 +1,155 @@
+// End-to-end proof for the user-task + form spine (epic #156, slice U0 — the keystone).
+//
+// Boots this whole Urban app in-process against the WASM engine and a virtual clock via
+// `bootTestApp`, deploys the throwaway `spine-demo` process (a native `userTask` linked to
+// `spine-demo.form`, whose completion drives a data-based decision gateway), and proves the
+// round-trip every later escalation slice builds on:
+//
+//   start instance → the task is listed via the `taskInbox` surface route
+//   (GET /tasks/api/tasks) → complete it with the typed form field via POST /tasks/api/complete
+//   → the process resumes, and the TYPED variable routes the decision gateway before the instance
+//   COMPLETES.
+//
+// The gateway is deliberate: a bare "the token advanced" assertion cannot tell a real typed
+// submission apart from an empty one (the WASM engine folds a completed instance's variables away,
+// so they are not observable post-completion). Routing the resume through a FEEL condition on the
+// form's `decision` field makes "resumes WITH those variables" falsifiable — an empty/wrong value
+// would take the gateway's default (reject) flow instead of the approve flow this test asserts. This
+// mirrors the answer/abandon gateway the escalation slices (U2/U3) build on the same spine.
+//
+// Network isolation mirrors the sibling convergence e2e: the app's GitHub transport is forced to
+// `token` mode with no token, so any best-effort GitHub read short-circuits instead of reaching out.
+//
+// Run with `npm run e2e` (a dedicated node:test invocation, kept out of the fast unit `npm test`).
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+
+// The app root is this repo's root (one level up from `e2e/`) — where nano.app.json + the
+// resources/processes + resources/forms it deploys live.
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Provision the app's SQLite in a throwaway temp dir so the test never touches (or leaks into) the
+// repo's real ./app.db, and every run starts from a freshly-migrated, empty schema.
+const DB_DIR = mkdtempSync(join(tmpdir(), "nwf-u0-"));
+
+// Force the app fully offline (github.ts reads process.env directly, not the harness env overlay):
+// `token` mode with no GITHUB_TOKEN means every best-effort GitHub read short-circuits to null.
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+const savedEnv = new Map<string, string | undefined>();
+
+// The harness `env` overlay drives the runtime's `${NANO_APP_DB_URL}` resolution.
+const HARNESS_ENV = {
+  NANO_APP_DB_URL: `file:${join(DB_DIR, "app.db")}`,
+} as const;
+
+interface InboxTask {
+  userTaskKey: string;
+  elementId?: string;
+  variables?: Record<string, unknown>;
+}
+
+interface TakenFlow {
+  from: string;
+  to: string;
+}
+
+/** The engine snapshot's cumulative taken sequence flows, as `from->to` strings. With a single
+ *  instance in play this is exactly that instance's routing history. */
+function takenFlows(app: TestApp): string[] {
+  const snapshot = app.snapshot();
+  const flows = Array.isArray(snapshot.takenSequenceFlows) ? snapshot.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+describe("nano-workforce user-task spine (U0 keystone)", () => {
+  let app: TestApp;
+
+  before(async () => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    app = await bootTestApp(APP_ROOT, { env: HARNESS_ENV });
+  });
+
+  after(async () => {
+    await app?.stop();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    rmSync(DB_DIR, { recursive: true, force: true });
+  });
+
+  test("a userTask bearing a linked .form round-trips list → complete → resume with typed vars", async () => {
+    // Boot deploys every model under `models` — including the throwaway spine-demo.bpmn and its
+    // linked spine-demo.form. Start one instance of the spine process.
+    const created = await app.engine.createInstance({ processDefinitionId: "spine-demo" });
+    const processInstanceKey = created.processInstanceKey;
+    assert.ok(processInstanceKey, "starting spine-demo returns a process instance key");
+
+    // The instance parks on the native userTask. It is visible through the `taskInbox` surface's
+    // JSON route (GET /tasks/api/tasks) — the manifest-enabled surface this slice lands.
+    const listed = await app.callRoute<InboxTask[]>({
+      method: "GET",
+      path: "/tasks/api/tasks",
+      query: { processInstanceKey },
+    });
+    assert.equal(listed.status, 200, "the taskInbox surface serves the task list");
+    assert.equal(listed.body.length, 1, "exactly the one spine userTask is open");
+    const task = listed.body[0];
+    assert.equal(task.elementId, "decide", "the open task is the spine's `decide` userTask");
+    assert.ok(task.userTaskKey, "the task carries a completable userTaskKey");
+
+    // Complete it through the surface's completion route (POST /tasks/api/complete) with exactly the
+    // typed field the linked .form declares (`decision`). This is the list → render → complete path
+    // an operator drives through the inbox.
+    const completed = await app.callRoute<{ ok: boolean }>({
+      method: "POST",
+      path: "/tasks/api/complete",
+      body: JSON.stringify({ userTaskKey: task.userTaskKey, variables: { decision: "approve" } }),
+    });
+    assert.equal(completed.status, 200, "the completion route accepts the typed form submission");
+    assert.equal(completed.body.ok, true, "the userTask was completed");
+
+    // The typed variable resumed the token through the decision gateway: `decision = "approve"`
+    // satisfied the FEEL condition, so the token took the approve flow (NOT the default reject flow).
+    // This is the falsifiable core of "resumes WITH those variables" — an empty/wrong value would
+    // have fallen through to `end-rejected`.
+    const flows = takenFlows(app);
+    assert.ok(
+      flows.includes("gw-decision->end-approved"),
+      `the typed decision routed to the approve end (flows: ${flows.join(", ")})`,
+    );
+    assert.ok(
+      !flows.includes("gw-decision->end-rejected"),
+      `the default reject flow was NOT taken (flows: ${flows.join(", ")})`,
+    );
+
+    // The token advanced start → userTask → gateway → end: the process resumes and reaches COMPLETED,
+    // with no open task left behind.
+    const instances = await app.engine.searchProcessInstances({
+      processInstanceKeys: [processInstanceKey],
+    });
+    assert.equal(instances.length, 1, "the spine instance is still resolvable");
+    assert.equal(instances[0].state, "COMPLETED", "the process resumed and completed");
+
+    const remaining = await app.callRoute<InboxTask[]>({
+      method: "GET",
+      path: "/tasks/api/tasks",
+      query: { processInstanceKey },
+    });
+    assert.equal(remaining.body.length, 0, "the completed task is no longer open");
+  });
+});

package/nano.app.json

@@ -8,6 +8,9 @@
     "processes": [
       "resources/processes/*.bpmn"
     ],
+    "forms": [
+      "resources/forms/*.form"
+    ],
     "templates": [
       "prompts/*.md"
     ]
@@ -39,9 +42,7 @@
       ],
       "onTerminated": {
         "set": {
-          "status": "abandoned",
-          "open_escalation_id": null,
-          "open_escalation_question": null
+          "status": "abandoned"
         }
       },
       "pollMs": 5000
@@ -60,6 +61,20 @@
         }
       },
       "pollMs": 5000
+    },
+    {
+      "table": "feature_runs",
+      "keyField": "process_key",
+      "statusField": "status",
+      "activeStatuses": [
+        "running"
+      ],
+      "onTerminated": {
+        "set": {
+          "status": "abandoned"
+        }
+      },
+      "pollMs": 5000
     }
   ],
   "workers": [
@@ -75,6 +90,10 @@
       "taskType": "pr.persist-escalation",
       "handler": "workers/persist-escalation/worker.ts"
     },
+    {
+      "taskType": "pr.answer-escalation",
+      "handler": "workers/answer-escalation/worker.ts"
+    },
     {
       "taskType": "pr.finalize",
       "handler": "workers/finalize/worker.ts"
@@ -112,20 +131,24 @@
       "handler": "workers/record-wave/worker.ts"
     },
     {
-      "taskType": "pr.record-trial-merge",
-      "handler": "workers/record-trial-merge/worker.ts"
+      "taskType": "pr.record-feature",
+      "handler": "workers/record-feature/worker.ts"
     },
     {
-      "taskType": "pr.record-results",
-      "handler": "workers/record-results/worker.ts"
+      "taskType": "pr.converge-feature",
+      "handler": "workers/converge-feature/worker.ts"
     },
     {
-      "taskType": "pr.persist-task-escalation",
-      "handler": "workers/persist-task-escalation/worker.ts"
+      "taskType": "pr.record-trial-merge",
+      "handler": "workers/record-trial-merge/worker.ts"
+    },
+    {
+      "taskType": "pr.resolve-trial-attention",
+      "handler": "workers/resolve-trial-attention/worker.ts"
     },
     {
-      "taskType": "pr.persist-plan-escalation",
-      "handler": "workers/persist-plan-escalation/worker.ts"
+      "taskType": "pr.record-results",
+      "handler": "workers/record-results/worker.ts"
     },
     {
       "taskType": "pr.retro-gather",
@@ -147,6 +170,9 @@
     "senior:retro"
   ],
   "surfaces": {
+    "taskInbox": {
+      "enabled": true
+    },
     "pages": {
       "enabled": true,
       "pagesDir": "pages",

package/openapi.yaml

@@ -306,6 +306,19 @@ components:
         alreadyRunning:
           type: boolean
           description: True when a non-terminal plan for this issue already exists; no new instance was started.
+    StartFeatureResult:
+      type: object
+      required:
+        - featureKey
+      properties:
+        featureKey:
+          type: string
+        processKey:
+          type: string
+          nullable: true
+        alreadyRunning:
+          type: boolean
+          description: True when a non-terminal feature run for this issue already exists; no new instance was started.
     ConvergenceStart:
       description: The start-convergence request body. Names the target PR by EXACTLY ONE of `pr`
         (an `owner/repo#123` reference) or `url` (a bare PR URL) — never both, never neither — with
@@ -444,78 +457,144 @@ components:
             Accepted by the schema today but currently has no runtime effect. When implemented it
             will be the required acknowledgement when `baseBranch` names the repository default
             branch. See `PlanStartByIssue.confirmDefaultBase`.
-    MessageResult:
+    FeatureStart:
+      description: The start-feature request body — a SINGLE-issue feature run. Names the target issue
+        by EXACTLY ONE of `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a
+        REQUIRED `baseBranch` (ADR 0003, same admission as the epic path), and the two optional
+        follow-on knobs `converge` / `autoMerge`. Modeled as `oneOf` named variants (Camunda REST v2
+        pattern) so an ambiguous or empty target is a 400 at the edge.
+      oneOf:
+        - $ref: "#/components/schemas/FeatureStartByIssue"
+        - $ref: "#/components/schemas/FeatureStartByUrl"
+    FeatureStartByIssue:
       type: object
-      description: The result of publishing a message / answering an escalation. Shape varies by message
-        name; `ok` is always present.
-      additionalProperties: true
+      additionalProperties: false
       required:
-        - ok
+        - issue
+        - baseBranch
       properties:
-        ok:
+        issue:
+          type: string
+          description: "Issue reference: owner/repo#123."
+        baseBranch:
+          type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: >-
+            REQUIRED target branch the agent branches off and opens its PR against. Admitted through
+            the same ADR 0003 policy as the epic path (`admitPlan`): a missing `epic/*` base is
+            auto-created off default HEAD; a non-`epic/*` base must already exist; naming the default
+            branch requires `confirmDefaultBase`.
+        converge:
           type: boolean
-    FeatureAnswerRequest:
-      description: "Answer an implementation-phase task escalation (issue #25). Supply the target by
-        EXACTLY ONE of `corrKey`, or the `plan`+`task` pair the delegate derives it from; `answer`
-        is always required. Modeled as `oneOf` named variants (Camunda REST v2 pattern) so a body
-        that supplies neither addressing form — or mixes them — is a 400 at the edge that names the
-        allowed shapes, instead of the delegate re-deriving the precedence by hand."
-      oneOf:
-        - $ref: "#/components/schemas/FeatureAnswerByCorrKey"
-        - $ref: "#/components/schemas/FeatureAnswerByPlanTask"
-    FeatureAnswerByCorrKey:
+          description: >-
+            When true, hand the opened PR to the convergence loop (review rounds) as a follow-on step.
+            When false (default) the run ends at "PR raised, not reviewed".
+        autoMerge:
+          type: boolean
+          description: >-
+            When true (and `converge` is true), drive the merge-loop after convergence — mirrors
+            `convergeOnly`/`NANO_PR_AUTO_MERGE` inverted. When false the run stops at `converged`.
+            Moot when `converge` is false.
+        confirmDefaultBase:
+          type: boolean
+          description: >-
+            Acknowledge that `baseBranch` is the repository default branch (the PR would target it
+            directly). See `PlanStartByIssue.confirmDefaultBase`.
+        allowSharedBase:
+          type: boolean
+          description: >-
+            Opt in to sharing a custom integration base branch with another already-active epic. See
+            `PlanStartByIssue.allowSharedBase`.
+    FeatureStartByUrl:
       type: object
       additionalProperties: false
       required:
-        - corrKey
-        - answer
+        - url
+        - baseBranch
       properties:
-        corrKey:
+        url:
           type: string
-          description: The task correlation key, `<plan_key>:<task_id>` (e.g. owner/repo#12:task-3).
-        answer:
+          description: A bare issue URL, when no `owner/repo#123` reference is supplied.
+        baseBranch:
           type: string
           minLength: 1
-          description: The operator's answer that resumes the parked implementation agent.
-    FeatureAnswerByPlanTask:
+          maxLength: 255
+          pattern: '\S'
+          description: >-
+            REQUIRED target branch the agent branches off and opens its PR against. See
+            `FeatureStartByIssue.baseBranch`.
+        converge:
+          type: boolean
+          description: When true, hand the opened PR to the convergence loop. See `FeatureStartByIssue.converge`.
+        autoMerge:
+          type: boolean
+          description: When true (with `converge`), drive the merge-loop. See `FeatureStartByIssue.autoMerge`.
+        confirmDefaultBase:
+          type: boolean
+          description: Acknowledge landing on the default branch. See `PlanStartByIssue.confirmDefaultBase`.
+        allowSharedBase:
+          type: boolean
+          description: Share a custom integration base with another active epic. See `PlanStartByIssue.allowSharedBase`.
+    MessageResult:
+      type: object
+      description: The result of publishing a message / answering an escalation. Shape varies by message
+        name; `ok` is always present.
+      additionalProperties: true
+      required:
+        - ok
+      properties:
+        ok:
+          type: boolean
+    AgentCompleteRequest:
       type: object
       additionalProperties: false
+      description: >-
+        Complete an escalation user task AS AN AGENT (epic #156 / ADR 0046). The agent submits the
+        SAME typed form variables a human would through the task inbox; the host routes them through
+        the one canonical attributed completer, records the agent's identity for the audit trail, and
+        resumes the process. Only the migrated escalation user tasks may be completed this way.
       required:
-        - plan
-        - task
-        - answer
+        - userTaskKey
+        - agentId
+        - variables
       properties:
-        plan:
-          type: string
-          description: Plan reference (owner/repo#N); combined with `task` to derive the corrKey.
-        task:
+        userTaskKey:
           type: string
-          description: Task id within the plan; combined with `plan` to derive the corrKey.
-        answer:
+          minLength: 1
+          description: The engine user-task key of the parked escalation task (from GET /tasks/api/tasks).
+        agentId:
           type: string
           minLength: 1
-          description: The operator's answer that resumes the parked implementation agent.
-    PlanAnswerRequest:
+          description: The completing agent's identity (ADR 0046), recorded for attribution.
+        variables:
+          type: object
+          additionalProperties: true
+          description: >-
+            The typed form completion variables — the SAME shape a human submits (e.g.
+            `{ resolution, answer }`, `{ directive, notes }`, `{ action, notes }`, or `{ answer }`).
+    RevertCompletionRequest:
       type: object
       additionalProperties: false
+      description: >-
+        Revert/override an agent escalation completion (the reversibility guarantee of ADR 0046). A
+        human marks a reversible agent completion reverted so the agent's answer is no longer treated
+        as authoritative; the reverter's identity + timestamp are recorded.
       required:
-        - plan
-        - directive
+        - completionId
+        - reverterId
       properties:
-        plan:
-          type: string
-          description: Plan reference (owner/repo#N), also the message correlation key.
-        directive:
+        completionId:
+          type: integer
+          description: The `task_completions` id returned when the agent completion was recorded.
+        reverterId:
           type: string
-          description: >-
-            One of `proceed` or `revise` (case-insensitive; normalized to lowercase and trimmed
-            server-side, see `parsePlanEscalationDirective`).
-            `proceed` dispatches the current unapproved plan as an explicit human override;
-            `revise` loops back to the planner with the note folded into planFindings and a fresh
-            review budget.
+          minLength: 1
+          description: The human identity overriding the agent completion, recorded for the audit trail.
         note:
           type: string
-          description: Human guidance for the planner (used for `revise`; optional for `proceed`).
+          description: Optional corrective guidance from the human that overrides the agent's answer.
     BlackboardEntry:
       type: object
       additionalProperties: false
@@ -767,12 +846,43 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/start/feature:
+    post:
+      operationId: startFeature
+      summary: Register/refresh a feature-run aggregate (idempotent on featureKey) and start the single-issue run.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FeatureStart"
+      responses:
+        "202":
+          description: The feature run was started (or was already running).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StartFeatureResult"
+        "400":
+          description: The issue reference could not be parsed, or the base branch was rejected.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "409":
+          description: The base branch is already in use by another active epic.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/message:
     post:
       operationId: postMessage
-      summary: Publish a message / answer an escalation. For escalation-answered,
-        feature-escalation-answered, and plan-escalation-answered names, runs the corresponding
-        answer flow; otherwise a plain publishMessage.
+      summary: "Publish a message / answer an escalation. For the merge-loop `escalation-answered`
+        name, runs the merge-loop escalation answer flow; otherwise a plain publishMessage. The
+        epic #156 escalation
+        kinds (task, plan-review, trial-merge, PR review-loop) are native user tasks answered via
+        the task inbox (POST /tasks/api/complete), not this route."
       requestBody:
         required: true
         content:
@@ -795,13 +905,7 @@ paths:
                   properties:
                     answer:
                       type: string
-                    directive:
-                      type: string
-                      description: >-
-                        One of `proceed` or `revise` (case-insensitive; normalized to lowercase and
-                        trimmed server-side, see `parsePlanEscalationDirective`).
-                    note:
-                      type: string
+                      description: The operator's answer that resumes a parked merge-loop escalation.
       responses:
         "200":
           description: The message was published (or the escalation answered).
@@ -821,11 +925,13 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
-  /hooks/feature-answer:
+  /hooks/agent-complete:
     post:
-      operationId: answerFeatureEscalation
-      summary: "Answer an implementation-phase task escalation out of band (issue #25). Optional
-        shared-secret guard (x-hook-secret), enforced only when NANO_PR_WEBHOOK_SECRET is set."
+      operationId: agentCompleteEscalation
+      summary: "Complete an escalation user task as an agent assignee (ADR 0046). Reuses the same
+        `.form` contract + engine resume path a human uses; records the agent identity for
+        attribution. Optional shared-secret guard (x-hook-secret), enforced only when
+        NANO_PR_WEBHOOK_SECRET is set."
       security:
         - hookSecret: []
         - {}
@@ -834,16 +940,16 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/FeatureAnswerRequest"
+              $ref: "#/components/schemas/AgentCompleteRequest"
       responses:
         "200":
-          description: The escalation was answered and the parked agent resumed.
+          description: The agent completed the escalation task and the process resumed.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
         "400":
-          description: A required field was missing (answer, or a resolvable correlation key).
+          description: A required field was missing (userTaskKey, agentId, variables), or the target is not an escalation task.
           content:
             application/json:
               schema:
@@ -855,16 +961,18 @@ paths:
               schema:
                 $ref: "#/components/schemas/MessageResult"
         "404":
-          description: No matching open task escalation for the correlation key.
+          description: No open escalation user task matches the userTaskKey.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
-  /hooks/plan-answer:
+  /hooks/revert-completion:
     post:
-      operationId: answerPlanEscalation
-      summary: "Answer a plan-review cap escalation out of band. Optional shared-secret guard
-        (x-hook-secret), enforced only when NANO_PR_WEBHOOK_SECRET is set."
+      operationId: revertEscalationCompletion
+      summary: "Revert/override an agent escalation completion (ADR 0046 reversibility). A human marks
+        a reversible agent completion reverted so the agent's answer is no longer authoritative.
+        Optional shared-secret guard (x-hook-secret), enforced only when NANO_PR_WEBHOOK_SECRET is
+        set."
       security:
         - hookSecret: []
         - {}
@@ -873,16 +981,16 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/PlanAnswerRequest"
+              $ref: "#/components/schemas/RevertCompletionRequest"
       responses:
         "200":
-          description: The escalation was answered and the parked plan resumed.
+          description: The agent completion was reverted.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
         "400":
-          description: A required field was missing (plan or directive).
+          description: A required field was missing, or the completion is not reversible / already reverted.
           content:
             application/json:
               schema:
@@ -894,7 +1002,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/MessageResult"
         "404":
-          description: No matching open plan escalation for the plan key.
+          description: No completion matches the completionId.
           content:
             application/json:
               schema:

package/operations/agentCompleteEscalation.ts

@@ -0,0 +1,53 @@
+// POST /app/api/hooks/agent-complete → operationId `agentCompleteEscalation` (epic #156, slice U6;
+// ADR 0046). Lets an AGENT assignee complete an escalation user task by submitting the SAME typed
+// form variables a human would through the task inbox. The completion routes through the one
+// canonical attributed completer (`completeEscalationAsAgent` → `completeUserTaskAttributed`), which
+// records the agent's identity in the `task_completions` ledger (for attribution) and then resumes
+// the process via `engine.completeUserTask` — the exact same resume path a human drives, no parallel
+// lane. Optional shared-secret guard (x-hook-secret), enforced only when NANO_PR_WEBHOOK_SECRET is
+// set, mirroring the other operator/webhook control surfaces.
+//
+// The runtime validates the body against openapi.yaml (`userTaskKey`, `agentId`, `variables` all
+// required); this delegate narrows the validated shape and applies the shared-secret guard.
+
+import { completeEscalationAsAgent } from "../app/agentCompletion.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const WEBHOOK_SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("agentCompleteEscalation", async ({ req, body }, app) => {
+  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
+    app.log.warn("agent-complete rejected: missing/invalid shared secret");
+    return { status: 401, body: { ok: false, error: "unauthorized" } };
+  }
+  if (!body || typeof body !== "object") {
+    app.log.warn("agent-complete rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "userTaskKey, agentId and variables are required" } };
+  }
+
+  const userTaskKey = str(body.userTaskKey);
+  const agentId = str(body.agentId);
+  const variables = body.variables;
+  if (!userTaskKey) return { status: 400, body: { ok: false, error: "userTaskKey is required" } };
+  if (!agentId) return { status: 400, body: { ok: false, error: "agentId is required" } };
+  if (!variables || typeof variables !== "object" || Array.isArray(variables)) {
+    return { status: 400, body: { ok: false, error: "variables must be an object" } };
+  }
+
+  const r = await completeEscalationAsAgent(app.data, app.engine, {
+    userTaskKey,
+    agentId,
+    variables,
+  });
+  if (r.ok) {
+    app.log.info("agent completed escalation", { userTaskKey, agentId, elementId: r.elementId });
+    return { status: 200, body: { ok: true, completionId: r.completionId, elementId: r.elementId } };
+  }
+  // A non-escalation / missing-target is a client error; an unknown key is a 404.
+  const status = r.reason === "no open escalation task" ? 404 : 400;
+  app.log.warn("agent-complete: not completed", { userTaskKey, reason: r.reason });
+  return { status, body: { ok: false, error: r.reason } };
+});