Function maybeEmitCompletionWebhook

server/src/training-agent/webhooks.ts:161–202

(opts: {
  toolName: string;
  args: Record<string, unknown>;
  response: Record<string, unknown>;
  requestIdempotencyKey?: string;
  /** Caller-uniqueness key for webhook idempotency. Pass the same value the
   *  request-side idempotency store uses for this caller (legacy dispatch
   *  passes `scopedPrincipal(auth, accountScope)`; the framework path passes
   *  `auth` directly except for `static:public` where it scopes by account).
   *  Two distinct callers MUST produce distinct strings here, otherwise
   *  receivers that dedupe across tenants on `idempotency_key` may drop one
   *  caller's webhook as a duplicate of another's. Empty strings are rejected
   *  fail-fast — they would silently degrade scoping to "no partitioning". */
  principal: string;
})

 * adapter (`framework-server.ts`) so both paths emit byte-identical envelopes.
 */
export function maybeEmitCompletionWebhook(opts: {
  toolName: string;
  args: Record<string, unknown>;
  response: Record<string, unknown>;
  requestIdempotencyKey?: string;
  /** Caller-uniqueness key for webhook idempotency. Pass the same value the
   *  request-side idempotency store uses for this caller (legacy dispatch
   *  passes `scopedPrincipal(auth, accountScope)`; the framework path passes
   *  `auth` directly except for `static:public` where it scopes by account).
   *  Two distinct callers MUST produce distinct strings here, otherwise
   *  receivers that dedupe across tenants on `idempotency_key` may drop one
   *  caller's webhook as a duplicate of another's. Empty strings are rejected
   *  fail-fast — they would silently degrade scoping to "no partitioning". */
  principal: string;
}): void {
  if (!opts.principal) {
    throw new Error('maybeEmitCompletionWebhook: principal must be a non-empty string (callers must pass the same caller-uniqueness key used for the request-side idempotency cache)');
  }
  const webhookUrl = extractWebhookUrl(opts.args);
  if (!webhookUrl || !(opts.toolName in TOOL_TO_TASK_TYPE)) return;
  const tool = opts.toolName as WebhookEmittingTool;

  const emitter = getWebhookEmitter();
  const registeredOperationId = extractRegisteredOperationId(opts.args);
  const deliveryOperationId = registeredOperationId
    ? deriveRegisteredWebhookDeliveryOperationId(opts.toolName, registeredOperationId, opts.principal)
    : deriveWebhookOperationId(opts.toolName, opts.response, opts.requestIdempotencyKey, opts.principal);
  const payloadOperationId = registeredOperationId ?? deliveryOperationId;
  const webhookTaskId = (opts.response.task_id as string | undefined)
    ?? `tsk_${payloadOperationId.slice(0, 32).replace(/[^A-Za-z0-9_.:-]/g, '_')}`;
  const payload: Record<string, unknown> = {
    operation_id: payloadOperationId,
    task_id: webhookTaskId,
    task_type: TOOL_TO_TASK_TYPE[tool],
    protocol: TOOL_TO_PROTOCOL[tool],
    status: 'completed',
    timestamp: new Date().toISOString(),
    result: opts.response,
  };
  void emitter.emit({ url: webhookUrl, payload, operation_id: deliveryOperationId })
    .catch(err => logger.warn({ err, tool: opts.toolName, url: webhookUrl }, 'Webhook emission failed'));
}

const ENV_KEY = 'WEBHOOK_SIGNING_KEY_JWK';
const KMS_WEBHOOK_ENV = 'GCP_KMS_WEBHOOK_KEY_VERSION';