Function defineAction

packages/core/src/action.ts:146–216

(options: any)

  TReturn,
>(options: DefineActionWithParams<TParams, TReturn>): any;
export function defineAction(options: any) {
  const hasSchema = options.schema && "~standard" in options.schema;

  // Build tool definition for the Claude API
  let toolParameters: ActionTool["parameters"];
  if (hasSchema) {
    // Convert Standard Schema to JSON Schema for Claude
    toolParameters = schemaToJsonSchema(options.schema, options.description);
  } else if (options.parameters) {
    toolParameters = {
      type: "object" as const,
      properties: options.parameters,
    };
  }

  // Wrap run() with validation when schema is provided.
  // Pass toolParameters so the validation error can echo the expected signature
  // (required vs optional fields) and help the caller self-correct.
  const run = hasSchema
    ? wrapWithValidation(options.schema, options.run, toolParameters)
    : options.run;

  // Auto-infer readOnly from http.method === "GET" unless explicitly set.
  // GET actions are idempotent reads; their completion should NOT trigger a
  // screen refresh. Everything else is assumed to mutate — the dispatcher
  // emits a poll event on success so the UI auto-refetches its queries.
  const httpConfig = options.http as ActionHttpConfig | false | undefined;
  const inferredReadOnly =
    httpConfig !== false &&
    httpConfig !== undefined &&
    httpConfig.method === "GET";
  // Explicit `readOnly` (true OR false) wins. Otherwise infer from http.method.
  // We store the resolved boolean so downstream checks can trust entry.readOnly
  // without re-running method inference — including when a caller explicitly
  // passes readOnly:false to override a GET (rare but valid).
  const readOnly: boolean | undefined =
    typeof options.readOnly === "boolean"
      ? options.readOnly
      : inferredReadOnly
        ? true
        : undefined;

  // toolCallable: thread through whatever the caller declared. We DO NOT
  // default to `true` here — the absence of an explicit field is meaningful
  // to the tools bridge: it lets us emit a one-shot warning when an action
  // without a declared `toolCallable` flag is invoked from a tool, so the
  // ecosystem can migrate over time. The bridge treats `undefined` as
  // "implicit allow with a deprecation warning"; only an explicit `false`
  // refuses the call. See `tools/routes.ts` and audit H5.
  const toolCallable: boolean | undefined =
    typeof options.toolCallable === "boolean"
      ? options.toolCallable
      : undefined;
  const parallelSafe: boolean | undefined =
    typeof options.parallelSafe === "boolean"
      ? options.parallelSafe
      : undefined;