<WaitForEvent>

import { WaitForEvent } from "smthrs";

type WaitForEventProps = {
  id: string;
  event: string;
  output: z.ZodObject | Table | string;
  correlationId?: string;
  outputSchema?: z.ZodObject;
  timeoutMs?: number;
  onTimeout?: "fail" | "skip" | "continue"; // default "fail"
  tagged?: boolean; // opt into { kind: "signal" | "timeout", payload? }
  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.
• tagged is an explicit migration opt-in: signal completion then stores { kind: "signal", payload } and timeout continuation stores { kind: "timeout" }. A schema that merely contains kind and payload isn’t treated as tagged. onTimeout="continue" without tagged fails clearly instead of persisting an ambiguous null row.
• External integration webhooks (@smthrs/integrations) deliver these events. A source signals integration:<service>:<event> (e.g. integration:github:pull_request) with a correlationId of owner/repo#number, owner/repo, or null depending on payload, so set signalName/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) doesn’t 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 smthrs 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.