@opencraw/azure-durable 0.0.24 → 0.0.26

package/README.md

@@ -53,6 +53,7 @@ Everything that is code or a secret stays in the host: hooks, captcha solvers, a
 | `hooks`, `captchaSolvers`, `access`, `accessPlugins`, `browser` | As in `createCrawler`. `captchaSolvers` is a factory: each crawler gets its own set. |
 | `pools` | `windows` (the default policy), `maxWindows` (the cap per pool, default 8), `idleTtlMs` (a pool with no item this long closes, default 10 minutes). |
 | `authLevel`, `routePrefix` | Default `function` (a function key) and no prefix. |
+| `callouts` | Lets a hook that answers `pending` post its result back, `POST /callouts/{token}/resolve`, instead of being asked again: `{ signingKeyEnv, publicUrl?, waitMs? }`. See [the guide](https://github.com/Open-Craw/OpenCraw/blob/main/docs/recipes/azure-durable.md#8-hooks-that-take-a-while). Off by default. |
 
 ## Call it
 

package/dist/index.esm.js

@@ -1,7 +1,8 @@
 import { app } from '@azure/functions';
-import { activityTask, any, resultOf, startOrchestration, callActivity, defineOrchestration, defineActivity } from '@mnci/az-durable';
+import { any, resultOf, eventTask, defineEvent, timerTask, activityTask, startOrchestration, callActivity, defineOrchestration, defineActivity } from '@mnci/az-durable';
 import * as df from 'durable-functions';
-import { memorySink, createCrawler, loadRecipes, createWorkInbox } from '@opencraw/core';
+import { timingSafeEqual, createHmac, createHash } from 'node:crypto';
+import { calloutResolutionSchema, memorySink, createCrawler, loadRecipes, withCalloutWaiter, createWorkInbox } from '@opencraw/core';
 import { BlobServiceClient, BlobSASPermissions, RestError } from '@azure/storage-blob';
 import { z } from 'zod';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
@@ -9,46 +10,317 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { setTimeout } from 'node:timers/promises';
 import { probeUrl } from '@opencraw/cli';
 import { validateTool } from '@opencraw/mcp';
-import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+const SEPARATOR = '.';
+function signature(secret, payload) {
+  return createHmac('sha256', secret).update(payload).digest('base64url');
+}
+/**
+ * The token a handler posts its result back with. It is the ticket and an HMAC of it, so the host holds no
+ * state for it: any instance of the Function App can check it.
+ *
+ * @param secret - The host's signing key.
+ * @param ticket - What the token lets its holder do.
+ * @returns A URL-safe token.
+ */
+function signCalloutTicket(secret, ticket) {
+  const payload = Buffer.from(JSON.stringify(ticket), 'utf8').toString('base64url');
+  return `${payload}${SEPARATOR}${signature(secret, payload)}`;
+}
+/**
+ * Checks a token and reads the ticket in it.
+ *
+ * @param secret - The host's signing key.
+ * @param token - What was posted to.
+ * @param now - The current time, epoch milliseconds.
+ * @returns The ticket, or why the token is not good.
+ */
+function readCalloutTicket(secret, token, now) {
+  const [payload, given, ...rest] = token.split(SEPARATOR);
+  if (payload === undefined || given === undefined || rest.length > 0) return {
+    ok: false,
+    reason: 'malformed'
+  };
+  const expected = Buffer.from(signature(secret, payload));
+  const actual = Buffer.from(given);
+  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return {
+    ok: false,
+    reason: 'signature'
+  };
+  let ticket;
+  try {
+    ticket = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+  } catch {
+    return {
+      ok: false,
+      reason: 'malformed'
+    };
+  }
+  if (typeof ticket.instanceId !== 'string' || typeof ticket.key !== 'string' || typeof ticket.index !== 'number' || typeof ticket.expiresAt !== 'number') return {
+    ok: false,
+    reason: 'malformed'
+  };
+  if (ticket.expiresAt < now) return {
+    ok: false,
+    reason: 'expired'
+  };
+  return {
+    ok: true,
+    ticket
+  };
+}
+
+/**
+ * The name of the external event a posted-back result is raised as. The call's idempotency key is the
+ * same for the same call anywhere in the job, so the recipe's index keeps two recipes that make an
+ * identical call apart.
+ *
+ * @param index - The input recipe of the job.
+ * @param key - The call's idempotency key.
+ * @returns The event name.
+ */
+function calloutEventName(index, key) {
+  return `opencraw-callout:${String(index)}:${key}`;
+}
+/**
+ * Where a handler posts a result, given the URL the job was started at.
+ *
+ * `publicUrl` wins when the host sets it (behind a proxy or a custom domain the request does not show);
+ * otherwise it is the start URL without its last path segment, which is where `/crawl` and
+ * `/callouts/{token}/resolve` are siblings.
+ *
+ * @param startUrl - The URL of the `/crawl` request.
+ * @param settings - The host settings.
+ * @returns The base all callback URLs start with, without a trailing slash.
+ */
+function callbackBaseOf(startUrl, settings) {
+  const configured = settings.callouts?.publicUrl;
+  if (configured !== undefined) return configured.replace(/\/+$/, '');
+  const url = new URL(startUrl);
+  return `${url.origin}${url.pathname.replace(/\/[^/]*\/?$/, '')}`;
+}
+/**
+ * @param base - What `callbackBaseOf` returned.
+ * @param token - The signed ticket.
+ * @returns The URL a handler posts its `CalloutResolution` to.
+ */
+function callbackUrl(base, token) {
+  return `${base}/callouts/${token}/resolve`;
+}
+
+/**
+ * @param status - The HTTP status.
+ * @param body - A JSON body.
+ * @returns The response.
+ */
+function reply(status, body) {
+  return {
+    status,
+    jsonBody: body
+  };
+}
+/**
+ * An error the caller can act on: what went wrong, and the issues a recipe
+ * error lists (each with its JSON path).
+ *
+ * @param status - The HTTP status.
+ * @param error - What went wrong.
+ * @returns The response.
+ */
+function problem(status, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const issues = typeof error === 'object' && error !== null && 'issues' in error ? error.issues : undefined;
+  return reply(status, {
+    error: message,
+    ...(issues !== undefined && {
+      issues
+    })
+  });
+}
+/**
+ * The request body as JSON.
+ *
+ * @param request - The request.
+ * @returns The body, or `undefined` when it is not JSON.
+ */
+async function readJson(request) {
+  try {
+    return await request.json();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `POST /callouts/{token}/resolve`: a handler that answered `pending` posts the result of the call here.
+ * The token in the path is the credential (it is a signed ticket for that one call), so the route does
+ * not ask for a function key. The result is raised to the waiting job as an external event; a second post
+ * for a call that was already settled finds nobody waiting and is refused.
+ *
+ * @param request - The request.
+ * @param client - The Durable client.
+ * @param settings - The host settings.
+ * @param now - The current time, epoch milliseconds.
+ * @returns 202 when the result was handed to the job, or the problem.
+ */
+async function resolveCallout(request, client, settings, now = Date.now()) {
+  const callouts = settings.callouts;
+  if (callouts === undefined) return problem(404, 'this host does not take posted-back results');
+  const secret = process.env[callouts.signingKeyEnv];
+  if (secret === undefined || secret === '') return problem(500, 'the host has no signing key for posted-back results');
+  const reading = readCalloutTicket(secret, request.params.token ?? '', now);
+  if (!reading.ok) return problem(reading.reason === 'expired' ? 410 : 401, `the token is ${reading.reason === 'expired' ? 'expired' : 'not valid'}`);
+  const parsed = calloutResolutionSchema.safeParse(await readJson(request));
+  if (!parsed.success) return problem(400, `the body must be {"status":"ok","output":…} or {"status":"error","error":"…"}: ${parsed.error.message}`);
+  const {
+    instanceId,
+    index,
+    key
+  } = reading.ticket;
+  const status = await client.getStatus(instanceId);
+  if (status === undefined || status.runtimeStatus !== 'Running') return problem(410, 'the job this result is for is no longer waiting for it');
+  await client.raiseEvent(instanceId, calloutEventName(index, key), parsed.data);
+  return reply(202, {
+    status: 'accepted'
+  });
+}
+
+/** A recipe is run again at most this many times for parked calls, so a hook whose key changes every run cannot loop for ever. */
+const MAX_RESUMES = 25;
+const DEFAULT_WAIT_MS = 60 * 60 * 1000;
 /**
  * The `/crawl` orchestration: one activity per input recipe, all at once;
  * the custom status counts recipes and records as each one finishes.
  *
+ * A recipe whose hooks answered `pending` and will post their results back stops its activity with
+ * `parked` calls. The orchestration then waits for one external event per call (and a timer, so a
+ * handler that never answers fails the recipe, not the job) and runs the recipe again with the results
+ * so far: calls that have a result return it without being made again.
+ *
  * @param runRecipe - The activity that runs one recipe.
+ * @param options - How long to wait for posted-back results.
  * @returns The orchestrator body.
  */
-function crawlOrchestrator(runRecipe) {
+function crawlOrchestrator(runRecipe, options = {}) {
+  const waitMs = options.waitMs ?? DEFAULT_WAIT_MS;
   return function* crawl(context, job) {
-    const tasks = job.inputs.map((input, index) => activityTask(context, runRecipe, {
-      allowedHosts: job.allowedHosts,
-      output: job.output,
-      input,
-      resultName: `${context.df.instanceId}/${index}.jsonl`,
-      ...(job.dedupe !== undefined && {
-        dedupe: job.dedupe
-      })
+    const slots = job.inputs.map(() => ({
+      resolutions: {},
+      waiting: new Set(),
+      events: [],
+      resumes: 0,
+      handlers: []
     }));
-    const finished = new Map();
+    const owners = new Map();
+    const outcomes = new Map();
     const progress = {
-      recipes: tasks.length,
+      recipes: job.inputs.length,
       recipesDone: 0,
       records: 0
     };
+    let running = [];
+    let waitingRecipes = 0;
+    const start = index => {
+      const slot = slots[index];
+      const task = activityTask(context, runRecipe, {
+        allowedHosts: job.allowedHosts,
+        output: job.output,
+        input: job.inputs[index],
+        resultName: `${context.df.instanceId}/${String(index)}.jsonl`,
+        instanceId: context.df.instanceId,
+        index,
+        ...(job.dedupe !== undefined && {
+          dedupe: job.dedupe
+        }),
+        ...(job.callbackBase !== undefined && {
+          callbackBase: job.callbackBase
+        }),
+        ...(Object.keys(slot.resolutions).length > 0 && {
+          resolutions: {
+            ...slot.resolutions
+          }
+        })
+      });
+      owners.set(task, {
+        kind: 'recipe',
+        index
+      });
+      running.push(task);
+    };
+    const finish = (index, result) => {
+      outcomes.set(index, result);
+      progress.recipesDone += 1;
+      progress.records += result.reports.reduce((sum, report) => sum + report.emitted, 0);
+      context.df.setCustomStatus(progress);
+    };
+    const stopWaiting = slot => {
+      if (slot.timer !== undefined && !slot.timer.isCompleted()) slot.timer.cancel();
+      const stopped = new Set([...slot.events, ...(slot.timer === undefined ? [] : [slot.timer])]);
+      running = running.filter(task => !stopped.has(task));
+      slot.events = [];
+      slot.timer = undefined;
+      waitingRecipes -= 1;
+      progress.recipesWaiting = waitingRecipes;
+    };
     context.df.setCustomStatus(progress);
-    let running = tasks;
+    for (let index = 0; index < job.inputs.length; index += 1) start(index);
     while (running.length > 0) {
       const winner = yield* any(context, running);
-      const result = resultOf(winner);
-      finished.set(winner, result);
       running = running.filter(task => task !== winner);
-      progress.recipesDone += 1;
-      progress.records += result.reports.reduce((sum, report) => sum + report.emitted, 0);
-      context.df.setCustomStatus(progress);
+      const owner = owners.get(winner);
+      if (owner === undefined) continue;
+      const slot = slots[owner.index];
+      if (owner.kind === 'recipe') {
+        const result = resultOf(winner);
+        const parked = result.parked ?? [];
+        if (parked.length === 0) {
+          finish(owner.index, result);
+        } else if (slot.resumes >= MAX_RESUMES) {
+          finish(owner.index, {
+            reports: [failedReport(job.inputs[owner.index], owner.index, `still waiting for posted-back results after ${String(MAX_RESUMES)} runs: the keys of its calls keep changing`)]
+          });
+        } else {
+          slot.resumes += 1;
+          slot.waiting = new Set(parked.map(call => call.idempotencyKey));
+          slot.handlers = parked.map(call => call.handler);
+          for (const call of parked) {
+            const event = eventTask(context, defineEvent(calloutEventName(owner.index, call.idempotencyKey)));
+            owners.set(event, {
+              kind: 'event',
+              index: owner.index,
+              key: call.idempotencyKey
+            });
+            slot.events.push(event);
+            running.push(event);
+          }
+          slot.timer = timerTask(context, waitMs);
+          owners.set(slot.timer, {
+            kind: 'timer',
+            index: owner.index
+          });
+          running.push(slot.timer);
+          waitingRecipes += 1;
+          progress.recipesWaiting = waitingRecipes;
+          context.df.setCustomStatus(progress);
+        }
+      } else if (owner.kind === 'event') {
+        slot.resolutions[owner.key] = resultOf(winner);
+        slot.waiting.delete(owner.key);
+        if (slot.waiting.size === 0) {
+          stopWaiting(slot);
+          context.df.setCustomStatus(progress);
+          start(owner.index);
+        }
+      } else {
+        stopWaiting(slot);
+        finish(owner.index, {
+          reports: [failedReport(job.inputs[owner.index], owner.index, `no result was posted back within ${String(waitMs)} ms by ${slot.handlers.join(', ')}`)]
+        });
+      }
     }
-    const results = tasks.map(task => finished.get(task)).filter(result => result !== undefined);
+    const results = job.inputs.flatMap((_, index) => outcomes.get(index) ?? []);
     return {
       recipes: results.flatMap(result => result.reports),
       records: results.flatMap(result => result.records ?? []),
@@ -56,9 +328,26 @@ function crawlOrchestrator(runRecipe) {
     };
   };
 }
+/** The report of a recipe the orchestration gave up on: it never finished a run, so there is nothing from the engine. */
+function failedReport(input, index, error) {
+  const id = typeof input === 'object' && input !== null && 'id' in input && typeof input.id === 'string' ? input.id : `input-${String(index)}`;
+  return {
+    recipeId: id,
+    mode: 'api',
+    emitted: 0,
+    rejected: 0,
+    duplicates: 0,
+    skipped: 0,
+    stepsSkipped: 0,
+    pages: 0,
+    durationMs: 0,
+    error
+  };
+}
 
 const KIB = 1024;
-const MINUTE_MS = 60_000;
+const MINUTE_MS$1 = 60_000;
+const HOUR_MS = 60 * MINUTE_MS$1;
 /**
  * @param options - As given.
  * @returns The options with their defaults.
@@ -69,13 +358,15 @@ function resolveHostOptions(options) {
   const authLevel = options.authLevel ?? 'function';
   const mcp = options.mcp === undefined || options.mcp === false ? undefined : {
     sampleRecords: 20,
-    sampleMs: MINUTE_MS,
+    sampleMs: MINUTE_MS$1,
     ...(options.mcp !== true && options.mcp)
   };
   if (mcp !== undefined && authLevel === 'anonymous' && options.identify === undefined) throw new Error('the MCP endpoint needs authentication: keep authLevel "function", or put the app behind App Service authentication and set identify');
+  const callouts = options.callouts === undefined ? undefined : calloutSettings(options.callouts);
   const {
     mcp: _mcp,
     canPromote,
+    callouts: _callouts,
     ...rest
   } = options;
   return {
@@ -83,12 +374,15 @@ function resolveHostOptions(options) {
     ...(mcp !== undefined && {
       mcp
     }),
+    ...(callouts !== undefined && {
+      callouts
+    }),
     canPromote: canPromote ?? (() => false),
     inlineLimitBytes: options.inlineLimitBytes ?? 256 * KIB,
     routePrefix: (options.routePrefix ?? '').replaceAll(/^\/+|\/+$/g, ''),
     authLevel,
     pools: {
-      idleTtlMs: options.pools?.idleTtlMs ?? 10 * MINUTE_MS,
+      idleTtlMs: options.pools?.idleTtlMs ?? 10 * MINUTE_MS$1,
       windows: options.pools?.windows ?? {
         min: 1,
         max: 4,
@@ -96,13 +390,24 @@ function resolveHostOptions(options) {
           after: 5
         },
         idle: {
-          afterMs: MINUTE_MS
+          afterMs: MINUTE_MS$1
         }
       },
       maxWindows: options.pools?.maxWindows ?? 8
     }
   };
 }
+function calloutSettings(options) {
+  const key = process.env[options.signingKeyEnv];
+  if (key === undefined || key === '') throw new Error(`callouts.signingKeyEnv names ${options.signingKeyEnv}, which is not set: it must hold the key that signs resume tokens`);
+  return {
+    signingKeyEnv: options.signingKeyEnv,
+    waitMs: options.waitMs ?? HOUR_MS,
+    ...(options.publicUrl !== undefined && {
+      publicUrl: options.publicUrl
+    })
+  };
+}
 /**
  * What a crawler for one caller is created with: the host's code and
  * secrets, and the caller's hosts.
@@ -170,30 +475,45 @@ async function packRecords(records, options) {
   };
 }
 
+const MINUTE_MS = 60_000;
 /**
  * The `/crawl` activity: one input recipe, on a crawler of its own, limited
  * to the caller's hosts. A recipe that fails is reported, not thrown: the
  * orchestration still gathers the others.
  *
+ * When the host takes posted-back results, a hook that answers `pending` parks its call instead of
+ * being polled: the run stops and the result says which calls it is waiting for (`parked`), with no
+ * reports, because the orchestration runs the recipe again once they have arrived.
+ *
  * @param settings - The host settings.
  * @param task - The recipe and where its records go.
- * @returns Its reports (one per matrix variant) and records (or their link).
+ * @param now - The current time, epoch milliseconds (for the token expiry).
+ * @returns Its reports (one per matrix variant) and records (or their link), or what it waits for.
  */
-async function runRecipeTask(settings, task) {
+async function runRecipeTask(settings, task, now = Date.now()) {
   const sink = memorySink();
   const crawler = createCrawler({
     ...crawlOptionsFor(settings, task.allowedHosts),
     sink,
     dedupe: task.dedupe ?? 'recipe'
   });
+  const parked = [];
+  const waiter = calloutWaiter(settings, task, parked, now);
   let reports;
   try {
     const set = await loadRecipes([task.output, task.input]);
-    const result = await crawler.run(set);
-    reports = result.recipes;
+    const run = async () => {
+      const result = await crawler.run(set);
+      return result.recipes;
+    };
+    reports = waiter === undefined ? await run() : await withCalloutWaiter(waiter, run);
   } finally {
     await crawler.close();
   }
+  if (parked.length > 0) return {
+    reports: [],
+    parked
+  };
   const packed = await packRecords(sink.records, {
     store: settings.results,
     inlineLimitBytes: settings.inlineLimitBytes,
@@ -204,6 +524,26 @@ async function runRecipeTask(settings, task) {
     ...packed
   };
 }
+/** The waiter of a run, when the host takes posted-back results and the job knows where they go. */
+function calloutWaiter(settings, task, parked, now) {
+  const callouts = settings.callouts;
+  if (callouts === undefined || task.callbackBase === undefined) return undefined;
+  const secret = process.env[callouts.signingKeyEnv] ?? '';
+  const base = task.callbackBase;
+  const expiresAt = now + callouts.waitMs + MINUTE_MS;
+  return {
+    resolutions: task.resolutions ?? {},
+    callbackFor: key => ({
+      url: callbackUrl(base, signCalloutTicket(secret, {
+        instanceId: task.instanceId,
+        index: task.index,
+        key,
+        expiresAt
+      }))
+    }),
+    parked
+  };
+}
 
 /**
  * Resolves the caller of a request and the hosts its recipes may reach.
@@ -234,49 +574,6 @@ function poolKey(access, crawlId) {
   return `${access.caller ?? ''}\u{0}${crawlId}`;
 }
 
-/**
- * @param status - The HTTP status.
- * @param body - A JSON body.
- * @returns The response.
- */
-function reply(status, body) {
-  return {
-    status,
-    jsonBody: body
-  };
-}
-/**
- * An error the caller can act on: what went wrong, and the issues a recipe
- * error lists (each with its JSON path).
- *
- * @param status - The HTTP status.
- * @param error - What went wrong.
- * @returns The response.
- */
-function problem(status, error) {
-  const message = error instanceof Error ? error.message : String(error);
-  const issues = typeof error === 'object' && error !== null && 'issues' in error ? error.issues : undefined;
-  return reply(status, {
-    error: message,
-    ...(issues !== undefined && {
-      issues
-    })
-  });
-}
-/**
- * The request body as JSON.
- *
- * @param request - The request.
- * @returns The body, or `undefined` when it is not JSON.
- */
-async function readJson(request) {
-  try {
-    return await request.json();
-  } catch {
-    return undefined;
-  }
-}
-
 /** A version that does not exist, or a write to one that does. */
 class RecipeStoreError extends Error {
   status;
@@ -502,6 +799,9 @@ async function startCrawl(request, client, settings, orchestration) {
     inputs: recipes.filter(recipe => recipe !== output),
     ...(parsed.data.options?.dedupe !== undefined && {
       dedupe: parsed.data.options.dedupe
+    }),
+    ...(settings.callouts !== undefined && {
+      callbackBase: callbackBaseOf(request.url, settings)
     })
   };
   const instanceId = await startOrchestration(client, orchestration, job);
@@ -516,7 +816,8 @@ const crawlJobSchema = z.object({
   allowedHosts: z.array(z.string()).min(1),
   output: z.unknown(),
   inputs: z.array(z.unknown()).min(1),
-  dedupe: z.enum(['recipe', 'off']).optional()
+  dedupe: z.enum(['recipe', 'off']).optional(),
+  callbackBase: z.string().optional()
 });
 /**
  * Checks a `/crawl` orchestration's input as it comes back out of the task
@@ -1369,7 +1670,8 @@ function hostJsonWarnings(maxWindows, directory = process.cwd()) {
  * model): `POST /crawl` runs recipes once, `POST /jobs/{crawlId}/items`
  * sends one item to the caller's warm pool, `GET` and `DELETE
  * /jobs/{crawlId}` read and close it, `POST /recipes/{name}/{version}/promote`
- * makes a draft runnable, and with `mcp` on, `/mcp` serves the authoring
+ * makes a draft runnable, with `callouts` set `POST /callouts/{token}/resolve`
+ * takes the results of hooks that answered `pending`, and with `mcp` on, `/mcp` serves the authoring
  * tools. Call it once, from the app's entry module; nothing is registered by
  * importing the package.
  *
@@ -1383,7 +1685,9 @@ function registerOpenCraw(options) {
   for (const warning of hostJsonWarnings(settings.pools.maxWindows)) console.warn(`[opencraw] ${warning}`);
   const runRecipe = async task => await runRecipeTask(settings, task);
   const runItem = async job => await pools.run(job);
-  const crawl = defineOrchestration('OpenCrawCrawl', crawlOrchestrator(defineActivity('OpenCrawRunRecipe', runRecipe)), {
+  const crawl = defineOrchestration('OpenCrawCrawl', crawlOrchestrator(defineActivity('OpenCrawRunRecipe', runRecipe), {
+    waitMs: settings.callouts?.waitMs
+  }), {
     parse: parseCrawlJob
   });
   const item = defineOrchestration('OpenCrawItem', itemOrchestrator(defineActivity('OpenCrawRunItem', runItem)), {
@@ -1391,6 +1695,7 @@ function registerOpenCraw(options) {
   });
   const http = {
     startCrawl: async (request, client) => await startCrawl(request, client, settings, crawl),
+    resolveCallout: async (request, client) => await resolveCallout(request, client, settings),
     submitItem: async (request, client) => await submitItem(request, client, settings, pools, item),
     job: async request => await jobRequest(request, settings, pools),
     mcp: async (request, client) => await mcpEndpoint(request, client, settings, crawl),
@@ -1421,6 +1726,13 @@ function registerOpenCraw(options) {
     authLevel: settings.authLevel,
     handler: http.promote
   });
+  // The token in the path is the credential: the services that post results back hold no function key.
+  if (settings.callouts !== undefined) df.app.client.http('OpenCrawResolveCallout', {
+    route: route('callouts/{token}/resolve'),
+    methods: ['POST'],
+    authLevel: 'anonymous',
+    handler: http.resolveCallout
+  });
   if (settings.mcp !== undefined) df.app.client.http('OpenCrawMcp', {
     route: route('mcp'),
     methods: ['GET', 'POST', 'DELETE'],

package/dist/src/callout-resume/callout-event.mapper.d.ts

@@ -0,0 +1,30 @@
+import type { HostSettings } from '../host-options/index.js';
+/**
+ * The name of the external event a posted-back result is raised as. The call's idempotency key is the
+ * same for the same call anywhere in the job, so the recipe's index keeps two recipes that make an
+ * identical call apart.
+ *
+ * @param index - The input recipe of the job.
+ * @param key - The call's idempotency key.
+ * @returns The event name.
+ */
+export declare function calloutEventName(index: number, key: string): string;
+/**
+ * Where a handler posts a result, given the URL the job was started at.
+ *
+ * `publicUrl` wins when the host sets it (behind a proxy or a custom domain the request does not show);
+ * otherwise it is the start URL without its last path segment, which is where `/crawl` and
+ * `/callouts/{token}/resolve` are siblings.
+ *
+ * @param startUrl - The URL of the `/crawl` request.
+ * @param settings - The host settings.
+ * @returns The base all callback URLs start with, without a trailing slash.
+ */
+export declare function callbackBaseOf(startUrl: string, settings: Pick<HostSettings, 'callouts'>): string;
+/**
+ * @param base - What `callbackBaseOf` returned.
+ * @param token - The signed ticket.
+ * @returns The URL a handler posts its `CalloutResolution` to.
+ */
+export declare function callbackUrl(base: string, token: string): string;
+//# sourceMappingURL=callout-event.mapper.d.ts.map

package/dist/src/callout-resume/callout-ticket.algorithm.d.ts

@@ -0,0 +1,36 @@
+/** What a resume token says: which call of which recipe of which job it may settle, and until when. */
+export interface CalloutTicket {
+    instanceId: string;
+    /** The input recipe of the job the call belongs to. */
+    index: number;
+    /** The call's idempotency key. */
+    key: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+export type TicketReading = {
+    ok: true;
+    ticket: CalloutTicket;
+} | {
+    ok: false;
+    reason: 'malformed' | 'signature' | 'expired';
+};
+/**
+ * The token a handler posts its result back with. It is the ticket and an HMAC of it, so the host holds no
+ * state for it: any instance of the Function App can check it.
+ *
+ * @param secret - The host's signing key.
+ * @param ticket - What the token lets its holder do.
+ * @returns A URL-safe token.
+ */
+export declare function signCalloutTicket(secret: string, ticket: CalloutTicket): string;
+/**
+ * Checks a token and reads the ticket in it.
+ *
+ * @param secret - The host's signing key.
+ * @param token - What was posted to.
+ * @param now - The current time, epoch milliseconds.
+ * @returns The ticket, or why the token is not good.
+ */
+export declare function readCalloutTicket(secret: string, token: string, now: number): TicketReading;
+//# sourceMappingURL=callout-ticket.algorithm.d.ts.map

package/dist/src/callout-resume/index.d.ts

@@ -0,0 +1,5 @@
+export { signCalloutTicket, readCalloutTicket } from './callout-ticket.algorithm.js';
+export type { CalloutTicket, TicketReading } from './callout-ticket.algorithm.js';
+export { calloutEventName, callbackBaseOf, callbackUrl } from './callout-event.mapper.js';
+export { resolveCallout } from './resolve-callout.handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/callout-resume/resolve-callout.handler.d.ts

@@ -0,0 +1,17 @@
+import type { HttpRequest, HttpResponseInit } from '@azure/functions';
+import type { DurableClient } from 'durable-functions';
+import type { HostSettings } from '../host-options/index.js';
+/**
+ * `POST /callouts/{token}/resolve`: a handler that answered `pending` posts the result of the call here.
+ * The token in the path is the credential (it is a signed ticket for that one call), so the route does
+ * not ask for a function key. The result is raised to the waiting job as an external event; a second post
+ * for a call that was already settled finds nobody waiting and is refused.
+ *
+ * @param request - The request.
+ * @param client - The Durable client.
+ * @param settings - The host settings.
+ * @param now - The current time, epoch milliseconds.
+ * @returns 202 when the result was handed to the job, or the problem.
+ */
+export declare function resolveCallout(request: HttpRequest, client: DurableClient, settings: HostSettings, now?: number): Promise<HttpResponseInit>;
+//# sourceMappingURL=resolve-callout.handler.d.ts.map

package/dist/src/crawl-run/crawl-job.model.d.ts

@@ -1,4 +1,4 @@
-import type { OutputRecord, RecipeReport } from '@opencraw/core';
+import type { CalloutResolution, OutputRecord, ParkedCallout, RecipeReport } from '@opencraw/core';
 /** What a `/crawl` orchestration runs: written by the starter, never by the caller. */
 export interface CrawlJob {
     caller?: string;
@@ -6,6 +6,8 @@ export interface CrawlJob {
     output: unknown;
     inputs: unknown[];
     dedupe?: 'recipe' | 'off';
+    /** Where handlers post results back (`https://app/api`): set by the starter when the host takes posted-back results. */
+    callbackBase?: string;
 }
 /** One input recipe of a job, run by one activity. */
 export interface RecipeTask {
@@ -15,12 +17,20 @@ export interface RecipeTask {
     dedupe?: 'recipe' | 'off';
     /** Where its records go when too large to return: `<instance>/<index>.jsonl`. */
     resultName: string;
+    /** The job's instance and this recipe's index in it: what a resume token names. */
+    instanceId: string;
+    index: number;
+    callbackBase?: string;
+    /** Results of calls that parked on an earlier run of this recipe, by idempotency key. */
+    resolutions?: Record<string, CalloutResolution>;
 }
 export interface RecipeTaskResult {
     /** One per run: a recipe with a `matrix` runs once per variant. */
     reports: RecipeReport[];
     records?: OutputRecord[];
     resultUrl?: string;
+    /** Set when calls are waiting for their results to be posted back: the run stopped, and this is what it waits for. */
+    parked?: ParkedCallout[];
 }
 /** What a `/crawl` orchestration returns. */
 export interface CrawlResult {
@@ -36,5 +46,7 @@ export interface CrawlProgress {
     recipes: number;
     recipesDone: number;
     records: number;
+    /** Recipes waiting for a posted-back result. Present only when the host takes them. */
+    recipesWaiting?: number;
 }
 //# sourceMappingURL=crawl-job.model.d.ts.map

package/dist/src/crawl-run/crawl-orchestration.use-case.d.ts

@@ -1,12 +1,22 @@
 import type { TypedActivity } from '@mnci/az-durable';
 import type { OrchestrationContext, Task } from 'durable-functions';
 import type { CrawlJob, CrawlResult, RecipeTask, RecipeTaskResult } from './crawl-job.model.js';
+export interface CrawlOrchestratorOptions {
+    /** How long a recipe waits for the results of parked calls before it fails. Only used when a call parks. */
+    waitMs?: number;
+}
 /**
  * The `/crawl` orchestration: one activity per input recipe, all at once;
  * the custom status counts recipes and records as each one finishes.
  *
+ * A recipe whose hooks answered `pending` and will post their results back stops its activity with
+ * `parked` calls. The orchestration then waits for one external event per call (and a timer, so a
+ * handler that never answers fails the recipe, not the job) and runs the recipe again with the results
+ * so far: calls that have a result return it without being made again.
+ *
  * @param runRecipe - The activity that runs one recipe.
+ * @param options - How long to wait for posted-back results.
  * @returns The orchestrator body.
  */
-export declare function crawlOrchestrator(runRecipe: TypedActivity<RecipeTask, RecipeTaskResult>): (context: OrchestrationContext, job: CrawlJob) => Generator<Task, CrawlResult, unknown>;
+export declare function crawlOrchestrator(runRecipe: TypedActivity<RecipeTask, RecipeTaskResult>, options?: CrawlOrchestratorOptions): (context: OrchestrationContext, job: CrawlJob) => Generator<Task, CrawlResult, unknown>;
 //# sourceMappingURL=crawl-orchestration.use-case.d.ts.map

package/dist/src/crawl-run/run-recipe.use-case.d.ts

@@ -5,9 +5,14 @@ import type { RecipeTask, RecipeTaskResult } from './crawl-job.model.js';
  * to the caller's hosts. A recipe that fails is reported, not thrown: the
  * orchestration still gathers the others.
  *
+ * When the host takes posted-back results, a hook that answers `pending` parks its call instead of
+ * being polled: the run stops and the result says which calls it is waiting for (`parked`), with no
+ * reports, because the orchestration runs the recipe again once they have arrived.
+ *
  * @param settings - The host settings.
  * @param task - The recipe and where its records go.
- * @returns Its reports (one per matrix variant) and records (or their link).
+ * @param now - The current time, epoch milliseconds (for the token expiry).
+ * @returns Its reports (one per matrix variant) and records (or their link), or what it waits for.
  */
-export declare function runRecipeTask(settings: HostSettings, task: RecipeTask): Promise<RecipeTaskResult>;
+export declare function runRecipeTask(settings: HostSettings, task: RecipeTask, now?: number): Promise<RecipeTaskResult>;
 //# sourceMappingURL=run-recipe.use-case.d.ts.map

package/dist/src/host-options/host-options.config.d.ts

@@ -42,6 +42,19 @@ export interface OpenCrawHostOptions {
     authLevel?: 'anonymous' | 'function' | 'admin';
     /** Prepended to every route: `'opencraw'` gives `/api/opencraw/crawl`. Default none. */
     routePrefix?: string;
+    /**
+     * Lets a hook that answers `pending` post its result back (`POST /callouts/{token}/resolve`) instead of
+     * being asked again. Off by default: a pending hook is then polled inside the activity.
+     */
+    callouts?: CalloutSettings;
+}
+export interface CalloutSettings {
+    /** The name of the environment variable holding the key that signs resume tokens. A secret: never in code or a recipe. */
+    signingKeyEnv: string;
+    /** The base URL handlers post to (`https://app.example.com/api`), when the request URL is not it (a proxy, a custom domain). Default: derived from the request that started the job. */
+    publicUrl?: string;
+    /** How long a job waits for a posted-back result before the recipe fails. Default 1 hour. */
+    waitMs?: number;
 }
 export interface McpSettings {
     /** A sample run (`run` without `full`) stops after this many records per input recipe. Default 20. */
@@ -58,7 +71,7 @@ export interface PoolSettings {
     maxWindows?: number;
 }
 /** The options with their defaults. */
-export interface HostSettings extends Omit<OpenCrawHostOptions, 'pools' | 'inlineLimitBytes' | 'routePrefix' | 'authLevel' | 'mcp' | 'canPromote'> {
+export interface HostSettings extends Omit<OpenCrawHostOptions, 'pools' | 'inlineLimitBytes' | 'routePrefix' | 'authLevel' | 'mcp' | 'canPromote' | 'callouts'> {
     inlineLimitBytes: number;
     routePrefix: string;
     authLevel: 'anonymous' | 'function' | 'admin';
@@ -66,6 +79,8 @@ export interface HostSettings extends Omit<OpenCrawHostOptions, 'pools' | 'inlin
     /** `undefined` when the endpoint is off. */
     mcp?: Required<McpSettings>;
     canPromote: (caller: string | undefined) => boolean;
+    /** `undefined` when posted-back results are off. */
+    callouts?: Required<Pick<CalloutSettings, 'signingKeyEnv' | 'waitMs'>> & Pick<CalloutSettings, 'publicUrl'>;
 }
 /**
  * @param options - As given.

package/dist/src/host-options/index.d.ts

@@ -1,3 +1,3 @@
 export { resolveHostOptions, crawlOptionsFor } from './host-options.config.js';
-export type { OpenCrawHostOptions, PoolSettings, McpSettings, HostSettings } from './host-options.config.js';
+export type { OpenCrawHostOptions, PoolSettings, McpSettings, CalloutSettings, HostSettings } from './host-options.config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts

@@ -1,6 +1,6 @@
 export { registerOpenCraw, hostJsonWarnings } from './open-craw-host/index.js';
 export type { OpenCrawHost } from './open-craw-host/index.js';
-export type { OpenCrawHostOptions, PoolSettings, McpSettings, HostSettings } from './host-options/index.js';
+export type { OpenCrawHostOptions, PoolSettings, McpSettings, CalloutSettings, HostSettings } from './host-options/index.js';
 export { memoryRecipes, blobRecipes, RecipeStoreError } from './recipe-store/index.js';
 export type { RecipeStore, StoredRecipes, BlobRecipesOptions } from './recipe-store/index.js';
 export { blobResults } from './result-store/index.js';

package/dist/src/open-craw-host/register-open-craw.use-case.d.ts

@@ -19,6 +19,8 @@ export interface OpenCrawHost {
     };
     http: {
         startCrawl: (request: HttpRequest, client: DurableClient) => Promise<HttpResponse | HttpResponseInit>;
+        /** `POST /callouts/{token}/resolve`; registered only when `callouts` is set. */
+        resolveCallout: (request: HttpRequest, client: DurableClient) => Promise<HttpResponseInit>;
         submitItem: (request: HttpRequest, client: DurableClient) => Promise<HttpResponse | HttpResponseInit>;
         job: (request: HttpRequest) => Promise<HttpResponseInit>;
         /** The authoring MCP endpoint; registered only when `mcp` is on. */
@@ -33,7 +35,8 @@ export interface OpenCrawHost {
  * model): `POST /crawl` runs recipes once, `POST /jobs/{crawlId}/items`
  * sends one item to the caller's warm pool, `GET` and `DELETE
  * /jobs/{crawlId}` read and close it, `POST /recipes/{name}/{version}/promote`
- * makes a draft runnable, and with `mcp` on, `/mcp` serves the authoring
+ * makes a draft runnable, with `callouts` set `POST /callouts/{token}/resolve`
+ * takes the results of hooks that answered `pending`, and with `mcp` on, `/mcp` serves the authoring
  * tools. Call it once, from the app's entry module; nothing is registered by
  * importing the package.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/azure-durable",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "type": "module",
   "main": "./dist/index.esm.js",
   "module": "./dist/index.esm.js",
@@ -24,9 +24,9 @@
     "@azure/storage-blob": "^12.34.0",
     "@mnci/az-durable": "^0.1.12",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@opencraw/cli": "^0.1.31",
-    "@opencraw/core": "^0.1.30",
-    "@opencraw/mcp": "^0.1.31",
+    "@opencraw/cli": "^0.1.32",
+    "@opencraw/core": "^0.1.31",
+    "@opencraw/mcp": "^0.1.32",
     "durable-functions": ">=3.0.0 <4",
     "zod": "^4.6.5"
   },