Function formatPausedExecution

packages/core/execution/src/engine.ts:213–296

(
  paused: PausedExecution,
  options?: { readonly deadline?: PausedExecutionDeadline },
)

};

export const formatPausedExecution = (
  paused: PausedExecution,
  options?: { readonly deadline?: PausedExecutionDeadline },
): {
  text: string;
  structured: Record<string, unknown>;
} => {
  const req = paused.elicitationContext.request;
  const lines: string[] = [`Execution paused: ${req.message}`];
  const deadline = options?.deadline;
  const isUrlElicitation = Predicate.isTagged(req, "UrlElicitation");
  const isFormElicitation = Predicate.isTagged(req, "FormElicitation");
  const requestedSchema = isFormElicitation ? req.requestedSchema : undefined;
  const hasRequestedSchema =
    requestedSchema !== undefined && Object.keys(requestedSchema).length > 0;
  const baseInstructions = isUrlElicitation
    ? `The user needs to open this URL in a browser and complete the flow. After the user finishes, call the resume tool with executionId "${paused.id}" and action "accept".`
    : hasRequestedSchema
      ? `Ask the user for values matching requestedSchema. Then call the resume tool with executionId "${paused.id}", action "accept", and content matching requestedSchema. If the user declines, call resume with action "decline" or "cancel".`
      : `This is a model-side confirmation gate; there is no browser form to open. Ask the user whether to approve the paused tool call. If the user approves, call the resume tool with executionId "${paused.id}" and action "accept". If the user declines, call resume with action "decline" or "cancel".`;
  // When the upstream leaves the LIFETIME of an accept to the answer, the
  // caller has to know that a bare accept is a one-time approval — the same
  // prompt returns on the next call — and how to say otherwise.
  const meta = req.meta;
  const offered = offeredPersistence(meta);
  const persistInstructions =
    offered.length > 0
      ? ` To have an accepted approval remembered, also pass persist as one of ${offered
          .map((scope) => JSON.stringify(scope))
          .join(", ")}; without it the approval is for this call only.`
      : "";
  const deadlineInstructions = deadline
    ? ` Resume before ${deadline.expiresAt}; this approval window lasts ${formatTtlDuration(deadline.ttlMs)}.`
    : "";
  const instructions = `${baseInstructions}${persistInstructions}${deadlineInstructions}`;

  if (isUrlElicitation) {
    lines.push(`\nOpen this URL in a browser:\n${req.url}`);
    lines.push('\nAfter the browser flow, call the resume tool with action "accept".');
  } else if (hasRequestedSchema) {
    lines.push(
      "\nAsk the user for a response matching the requested schema, then call the resume tool.",
    );
    lines.push(`\nRequested schema:\n${JSON.stringify(requestedSchema, null, 2)}`);
  } else {
    lines.push(
      '\nThis is a model-side confirmation gate; no browser form is waiting. Ask the user whether to approve, then call the resume tool with action "accept", "decline", or "cancel".',
    );
  }

  // Terms the upstream attached to the approval. Stated plainly, because a
  // prompt whose schema is empty ("Allow X to access Y?") can still be
  // asking for a PERSISTENT grant, and the answer differs.
  if (meta !== undefined && Object.keys(meta).length > 0) {
    lines.push(`\nApproval terms:\n${JSON.stringify(meta, null, 2)}`);
  }

  lines.push(`\nexecutionId: ${paused.id}`);