agent-signal

Use defineSourceHandler from the runtime middleware, specifying the source type, a stable handler id, and an async function returning a dispatch result with signals. Register it in a policy via defineAgentSignalHandlers and wire the policy into the runtime factory.

A source is a normalized external fact like a user message, a signal is a reusable semantic interpretation derived from sources, and an action is a concrete side effect executed by the runtime. Keep interpretation in source and signal handlers and side effects in action handlers.

Use enqueueAgentSignalSourceEvent when the caller should return quickly and the work should run out-of-band via Upstash Workflow. Use emitAgentSignalSourceEvent when a server-owned producer should execute the pipeline immediately in the foreground.

Receipts are projected from the agent.execution.completed event, not the enqueue action. Verify the action stamped an Agent Signal operation marker, the completion payload carried selfIteration finalState, and buildSelfIterationReceipts recognized the mutation.

The runtime uses scopeKey-based dedupe windows, scope locks, and action idempotency checks in handlers. Keep dedupe keys and scope keys stable across retries and workflow handoff to avoid double execution.