All jobs

Add Signals and Queries to a Temporal Workflow

Yes. An agent adds an approval signal and a status query to your Temporal workflow, wires the client to send them, covers both with tests and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the repository into its own cloud sandbox and reads the workflow before it changes anything. In a project like temporalio/money-transfer-project-template-ts, src/workflows.ts holds one workflow, moneyTransfer, which proxies three activities (withdraw, deposit, refund) with a retry policy of initialInterval: '1 second', maximumInterval: '1 minute', backoffCoefficient: 2, maximumAttempts: 500 and two non-retryable error types, InvalidAccountError and InsufficientFundsError, under a startToCloseTimeout of one minute. It withdraws, then deposits, and on a failed deposit calls refund before failing the workflow with an ApplicationFailure. src/client.ts starts it with client.workflow.start on the money-transfer task queue from src/shared.ts, a fixed workflowId of pay-invoice-801, and then blocks on handle.result(). The worker in src/worker.ts registers workflowsPath and the activities module. The SDK packages are all pinned to ~1.14.1, .nvmrc says Node 18, and npm test runs Mocha over src/mocha/*.test.ts.

The agent then adds the two handlers in src/workflows.ts. It declares approveSignal with defineSignal<[string]>('approve'), carrying the approver's name, and statusQuery with defineQuery<TransferStatus>('status'), where TransferStatus is a small union type the agent adds to src/shared.ts (awaiting-approval, withdrawing, depositing, refunding, complete, failed). Inside moneyTransfer it keeps a status variable and an approved flag, registers both handlers with setHandler before any activity runs, and waits with condition(() => approved, approvalTimeout) ahead of the withdrawal, where the timeout is a duration string the agent reads from the prompt. When the condition times out the workflow fails with an ApplicationFailure that says no approval arrived, so the money never leaves the source account. Every step that already exists updates status, including the refund branch, so a query answers the same during a retry storm as it does on the happy path.

On the client side it changes src/client.ts so the start is followed by handle.query(statusQuery), a log line, handle.signal(approveSignal, 'ops@your-org') and then handle.result(), and it adds a second script, src/approve.ts, that takes a workflow id from process.argv, calls client.workflow.getHandle(id) and sends the signal, with an npm run approve entry in package.json next to client and worker. The pull request also notes the equivalent temporal workflow signal --workflow-id pay-invoice-801 --name approve command for people who approve from the CLI. Nothing in the activities or the banking client changes.

Tests follow the shape already in src/mocha/workflows.test.ts: a TestWorkflowEnvironment, a Worker created on the test environment's nativeConnection with the activities mocked to return fixed transaction ids, and worker.runUntil. The agent adds one test that starts the workflow with client.workflow.start, asserts handle.query(statusQuery) returns awaiting-approval, sends the signal and asserts the same Transfer complete string the existing test expects. A second test uses TestWorkflowEnvironment.createTimeSkipping() so the approval timeout elapses without waiting, and asserts the workflow fails with a WorkflowFailedError. It runs npm run lint, npm run build and npm test in the sandbox, which downloads the Temporal test server the testing package uses, and fixes anything the TypeScript 4.9 compiler or the ESLint rules in .eslintrc.js reject.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Signals and Queries to the Temporal workflow in this repository. Read src/workflows.ts, src/client.ts, src/worker.ts, src/shared.ts and the Mocha tests first. Add an `approve` Signal that the workflow waits for before the first activity, with a timeout of 24 hours after which the workflow fails without moving money, and a `status` Query that reports which step the transfer is in, including the refund path. Update the client to query the status and send the approval, add a small script that sends the approval to a workflow id given on the command line, and keep the existing activity code unchanged. Add tests for the approved path and for the timeout using the time-skipping test environment. Run lint, build and the tests, and open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that changes src/workflows.ts, src/shared.ts, src/client.ts, package.json and src/mocha/workflows.test.ts, and adds src/approve.ts. The description names the Signal and Query, quotes the workflow code where the handlers are registered and where the condition waits, and pastes the Mocha output from the sandbox for the existing four tests and the two new ones.

The run's record keeps every command with its output: the install, the lint, the build and the test run with the test server download, so a reviewer can see the tests passed on the SDK version the lockfile pins rather than take the description's word for it.

Before merging, a reviewer decides the real approval timeout, whether the approver's name belongs in the workflow result or in a search attribute, and who may send the signal in production, since any client with access to the namespace can. A workflow already running on the old code picks up the new handlers only on a fresh execution, which the pull request says in plain words.

Run it on every workflow that needs a human step

The setup is one POST /o/{org}/sessions with this body and the repository in resources, started from a terminal; the run continues in its sandbox after you close the window, and a follow-up through POST /o/{org}/sessions/{id}/messages can change the timeout or add a reject Signal without starting over. To cover several workflow files at once, a script sends one request per repository with its own prompt, each with a fresh UUID as request_id so a retry returns the run already started.

Set a webhook URL on the API key and Rush posts run.completed or run.failed when a run's turn finishes, with session_url so your server can read the pull request link and the result text.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Signal and a Query look like a few lines, but the places they can go wrong are the ones that only show up when the code runs: a handler registered after the first await, a condition that never clears because the flag is set in the wrong scope, a timeout that the deterministic replay disagrees with. The agent runs the worker and the test server in its sandbox and the Mocha suite tells it, and then the reviewer, whether the approval path and the timeout path both behave.

The sandbox is its own computer with Node 18 from .nvmrc, the Temporal test server the testing package downloads, and the full record of every command kept with the run. Several services that each have a workflow to change can be done at the same time in separate sandboxes, each ending in its own pull request.

Frequently asked questions

Will running workflows break when the new code deploys?

Executions already in flight replay against the new code on their next workflow task, and a workflow that is past the point where the new condition sits would see a history that no longer matches. The pull request says so and suggests either draining in-flight transfers first or wrapping the new wait in patched('approval') so old histories skip it.

Who can send the approval signal?

Any client connected to the namespace with the workflow id, which in this template is the fixed pay-invoice-801. The pull request leaves authorization to the caller and names where to add a check, for example in the service that calls the new approve script, rather than inventing one inside the workflow.

Why wait before the withdrawal and not before the deposit?

Because the withdrawal is the step that moves money, and the template already compensates a failed deposit with a refund. Waiting before withdraw means a timed-out approval leaves both accounts untouched and no refund path is needed.

Does the query work while an activity is retrying?

Yes. A Query handler reads workflow state without touching history, so it answers while deposit is in its retry loop, and the status it reports is whatever the workflow last set, for example depositing. The agent sets the status before each activity call for that reason.

More Temporal jobs

More jobs like this: Hand off a long task

Keep reading