Workflow API

A workflow is a TypeScript module that export defaults { schema, outputSchema?, settlement?, main }. Most of the API is global — no imports — while the typed authoring entry is importable from the virtual tide module. Type definitions live in runtime/src/tide.d.ts.

The workflow shape

const schema = S.object({ name: S.text() });

export default {
  schema,                                   // built with S — validates input
  outputSchema: S.object({ greeting: S.text() }),
  settlement: "promote_on_success",
  main: async (ctx: Infer<typeof schema>) => {
    return { greeting: `Hello ${ctx.name}` };
  },
};

defineWorkflow

defineWorkflow is typed sugar over the core export: it gives the body a discoverable core ctx. Plugin APIs are imported from generated modules. It returns the core export, so the module still export defaults its result.

import { defineWorkflow, S } from "tide";

export default defineWorkflow({
  input: S.object({ ... }),    // optional: defaults to S.object({})
  output: S.object({ ... }),   // validates and types the durable result
  settlement: "discard_on_success", // optional; default promotes
  async run(input, ctx) {      // input typed via Infer<typeof input>
    return { ... };
  },
});

When output/outputSchema is declared, the return value must be JSON and pass that schema. Tide canonicalizes it, refuses results above 1 MiB, and returns its sha256: digest. Returning a value without declaring an output schema is an error. Completed results are persisted by the runner and exposed by the control API; failed, running, and suspended invocations never expose a result.

settlement controls successful world-state writes:

Failure always discards. Suspension retains the run fork for resume.

The workflow context (ctx)

The same capabilities are available as globals in the core { schema, main } form.

step

step<T>(name: string, fn: () => Promise<T>, opts?: { retries?: number }): Promise<T>

Runs fn as an atomic, journaled transaction. On success its return value is recorded; on replay a completed step returns that value without re-running the body. On failure the step's buffered operations and VFS changes are rolled back. With { retries: n } the body is retried up to n times before the error propagates. Nested steps are not supported. See Steps.

const result = await step("charge", async () => {
  await writeFile("receipt.txt", "charged");
  return { ok: true };
}, { retries: 3 });

hitl

hitl.wait(request: HitlWaitRequest): Promise<HumanWaitOutcome>

Suspends the run for a human decision; resumes via tide resume. request requires a title; description, tags, priority, payload, classification, moduleName, and others are optional. The returned outcome carries action, payload, comment, resolvedBy, and resolvedAt. See Human-in-the-loop.

Virtual file system

All file operations run against an in-memory, sandboxed VFS — never the host filesystem. State is derived from journal replay.

Console and logging

log(...) and console.log(...) write to stdout; console.error(...) to stderr. Output is journaled and replayed deterministically — live logging during replay is suppressed to avoid duplicates. Changing log messages does not break determinism.

Time and sleep

sleep(ms: number): Promise<void>

sleep pauses on first run and is skipped on replay. Date.now() and new Date() return a frozen timestamp captured on first run and replayed thereafter; performance.now() returns 0. See Deterministic time.

AI capabilities

ai.llm.generate(model, prompt, options?) returns text, or a typed object when an outputSchema (built with S) is supplied. ai.agent(...) runs a stateful ReAct tool loop, ai.tool(...) declares a tool, and ai.code.* drives cloud coding agents. These require the host to be configured with the relevant credentials; in the disabled default posture they refuse deterministically. Full signatures are in runtime/src/tide.d.ts.

The tide module exports

Most APIs are global; the importable surface is:

Related

• Schema (S) reference — the input builder and Infer.
• Plugin architecture — namespaced host capabilities.
• Steps · Human-in-the-loop · Driving Argon.