<WaitForEvent> - Smithers

import { WaitForEvent } from "smithers-orchestrator";

type WaitForEventProps = {
  id: string;
  event: string;
  output: z.ZodObject | Table | string;
  correlationId?: string;
  outputSchema?: z.ZodObject;
  timeoutMs?: number;
  onTimeout?: "fail" | "skip" | "continue"; // default "fail"
  async?: boolean; // unrelated downstream may proceed while pending
  skipIf?: boolean;
  dependsOn?: string[];
  needs?: Record<string, string>;
  label?: string;
  meta?: Record<string, unknown>;
  key?: string;
};

<Workflow name="deploy-watcher">
  <Sequence>
    <WaitForEvent
      id="wait-deploy"
      event="deploy.completed"
      correlationId={ctx.input.deployId}
      output={outputs.deployEvent}
      outputSchema={deployPayload}
      timeoutMs={600_000}
      onTimeout="fail"
    />
    <Task id="notify" output={outputs.summary} agent={notifier}>
      The deploy finished. Summarize the result.
    </Task>
  </Sequence>
</Workflow>

Notes

Push-based; for poll-based checks use <Task> with a compute function.
External integration webhooks (the @smithers-orchestrator/integrations package) deliver these events. A source signals integration:<service>:<event> (for example integration:github:pull_request) with a correlationId that is owner/repo#number, owner/repo, or null depending on the payload, so set signalName and correlationId to match.
With async, dependents via dependsOn/needs still block until payload arrives.
Async waits are tracked by the smithers_external_wait_async_pending{kind="event"} gauge while pending (it rises on start, falls on completion).
A run suspended on <WaitForEvent> (status waiting-event) does not resume itself when the event is delivered out of process. A controller should deliver it with Gateway submitSignal, then call resumeRun. For ad-hoc CLI operation, deliver the event and resume with bunx smithers-orchestrator up workflow.tsx --run-id RUN_ID --resume true from the workspace root. Never locate or select the backing store yourself; discover the verified workspace Gateway with smithers gateway status --format json. See the keeper-loop pattern in the CLI overview.

​Notes

Notes