import { workflow } from "@bastani/atomic/workflows";
import { Type } from "typebox";

export default workflow({
  name: "explain-file",
  description: "Explain a file with tracked workflow stages.",
  inputs: {
    path: Type.String({ description: "File path to explain." }),
  },
  outputs: {
    explanation: Type.String({
      description: "Explanation of the file's purpose, risks, and key symbols.",
    }),
  },
  run: async (ctx) => {
    const explanation = await ctx.task("explain", {
      prompt: `Read ${String(ctx.inputs.path)} and explain purpose, risks, and key symbols.`,
      context: "fresh",
    });

    return { explanation: explanation.text };
  },
});

/workflow list
/workflow inputs explain-file
/workflow explain-file path="src/index.ts"

const result = await ctx.task("analyze", {
  model: "auto",
  prompt: `Analyze ${String(ctx.inputs.path)} against the supplied requirements.`,
  modelConstraints: { minContextWindow: 32000, maxInputCost: 5 },
});

const prompt = [
  keepContext("Review only. Do not edit files. Report findings as JSON."),
  `Reference material:\n${ctx.inputs.issueBody}`,
  `Task: review the change for issue #${ctx.inputs.issue} and report defects.`,
].join("\n\n");

import { workflow } from "@bastani/atomic/workflows";
import { Type } from "typebox";

export default workflow({
  name: "my-workflow",
  description: "Short description shown in workflow listings.",
  inputs: {
    prompt: Type.String({ description: "Task or question for the workflow." }),
  },
  outputs: {
    summary: Type.String({ description: "Synthesized findings and recommended next steps." }),
    reviewer_count: Type.Number({ description: "Number of parallel reviewers that ran." }),
  },
  run: async (ctx) => {
    const prompt = String(ctx.inputs.prompt);

    const scoutPath = ".atomic/workflows/runs/my-workflow/scout.md";
    const reviewPaths = {
      quality: ".atomic/workflows/runs/my-workflow/quality.md",
      runtime: ".atomic/workflows/runs/my-workflow/runtime.md",
    } as const;

    await ctx.task("scout", {
      prompt: `Map the relevant context for: ${prompt}`,
      context: "fresh",
      output: scoutPath,
      outputMode: "file-only",
    });

    const reviews = await ctx.parallel(
      [
        {
          name: "quality",
          prompt: `Scout artifact: ${scoutPath}\nRead the file at ${scoutPath} and inspect only sections needed for this quality review.`,
          reads: [scoutPath],
          output: reviewPaths.quality,
          outputMode: "file-only",
        },
        {
          name: "runtime",
          prompt: `Scout artifact: ${scoutPath}\nRead the file at ${scoutPath} and inspect only sections needed for this runtime review.`,
          reads: [scoutPath],
          output: reviewPaths.runtime,
          outputMode: "file-only",
        },
      ],
      { concurrency: 2 },
    );

    const final = await ctx.task("synthesis", {
      prompt: [
        `Quality review: ${reviewPaths.quality}`,
        `Runtime review: ${reviewPaths.runtime}`,
        "Read the files at the paths above incrementally, then synthesize findings and recommend next steps.",
      ].join("\n"),
      reads: Object.values(reviewPaths),
    });

    return { summary: final.text, reviewer_count: reviews.length };
  },
});

.atomic/workflows/code-review.ts
.atomic/workflows/code-review/prompts.ts
.atomic/workflows/code-review/schemas.ts
.atomic/workflows/code-review/model-policy.ts

Implement → Review → Validate
    ▲                    │
    └────── Repair ──────┘

Implement
   ↓
Review 1
   ↓
Validate 1
   ↓
Repair 1
   ↓
Review 2
   ↓
Validate 2

Implement ✓
  activity: processing follow-up

export default workflow({
  name: "review-with-summary",
  description: "Review with returned artifacts.",
  inputs: {},
  outputs: {
    research_artifact: Type.String(),
    review: Type.String(),
  },
  run: async (ctx) => {
    const researchPath = ".atomic/workflows/runs/review-with-summary/research.md";
    await ctx.task("research", {
      prompt: "Research the target.",
      output: researchPath,
      outputMode: "file-only",
    });
    const review = await ctx.task("review", {
      prompt: `Research artifact: ${researchPath}\nRead the file at ${researchPath} incrementally and summarize risks.`,
      reads: [researchPath],
    });

    return {
      research_artifact: researchPath,
      review: review.text,
    };
  },
});

// ❌ Loose: child.outputs.report is `unknown`; nothing checks the shape at runtime.
outputs: {
  report: Type.Unknown(),
}

// ✅ Precise: child.outputs.report is `{ topic: string; score: number; tags: string[] }`,
//    and TypeBox rejects a returned value missing `score` or with a non-number `score`.
outputs: {
  report: Type.Object({
    topic: Type.String(),
    score: Type.Number(),
    tags: Type.Array(Type.String()),
  }),
}

import { workflow } from "@bastani/atomic/workflows";
import { Type } from "typebox";

type ResearchPacket = {
  readonly topic: string;
  readonly score: number;
  readonly sections: readonly { readonly heading: string; readonly body: string }[];
};

export default workflow({
  name: "research-packet",
  description: "",
  inputs: {
    topic: Type.String(),
  },
  outputs: {
    packet: Type.Unsafe<ResearchPacket>(Type.Object({}, { additionalProperties: true })),
  },
  run: async (ctx) => {
    const packet: ResearchPacket = {
      topic: ctx.inputs.topic,
      score: 1,
      sections: [{ heading: "overview", body: "…" }],
    };
    return { packet }; // statically checked against ResearchPacket
  },
});

const gate = ctx.stage("review-gate", {
  schema: Type.Object({ approved: Type.Boolean() }, { additionalProperties: false }),
});
const decision = await gate.prompt("Review the implementation and call structured_output.");
if (!decision.approved) {
  await gate.sendUserMessage("Explain the highest-priority changes needed before approval.");
}

interface StageSessionRuntime {
  readonly queuedMessagesPaused?: boolean;
  pauseQueuedMessages?(): void;
  resumeQueuedMessages?(): boolean | Promise<boolean>;
}

interface StageSessionRuntime {
  getSteeringMessages?(): readonly string[];
  getFollowUpMessages?(): readonly string[];
}

export default workflow({
  name: "guarded-import",
  description: "",
  inputs: {},
  outputs: {
    scanned: Type.Number(),
  },
  run: async (ctx) => {
    const files = await findCandidateFiles(ctx.cwd);
    if (files.length === 0) {
      return ctx.exit({
        status: "skipped",
        reason: "No matching files",
        outputs: { scanned: 0 },
      });
    }

    const review = await ctx.task("review", { prompt: `Review ${files.join(", ")}` });
    return { scanned: files.length };
  },
});

// Reads {"daemon":true|false,"artifactsDir":"..."} from argv[2]; prints one JSON result line.
// Replace the app name, window title, element labels, and postcondition with ones you control.
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import {
  ActionTarget, ClickButton, ClickInput, ClickPosition, CuaDriver,
  GetWindowStateInput, InputDeliveryMode, ListAppsInput, ListWindowsInput,
} from "@trycua/cua-driver";

const { daemon, artifactsDir } = JSON.parse(process.argv[2]);
mkdirSync(artifactsDir, { recursive: true });
const unique = (items, what) => {
  if (items.length !== 1) throw new Error(`Expected one ${what}, found ${items.length}`);
  return items[0];
};
const finish = (result, detail) => {
  process.stdout.write(`${JSON.stringify({ result, detail })}\n`);
  process.exitCode = result === "verified" ? 0 : 1;
};

// The wrapper already set CUA_DRIVER_RS_TELEMETRY_ENABLED=false in this process's environment
// before the driver was constructed; the SDK is one of the faces that reports telemetry by default.
const driver = daemon ? CuaDriver.connect(undefined) : CuaDriver.create(undefined);
try {
  const apps = await driver.listApps(ListAppsInput.new({}));
  const app = unique(apps.apps.filter((a) => a.name === "Window Demo" && a.running), "app");
  const windows = await driver.listWindows(ListWindowsInput.new({ pid: app.pid, onScreenOnly: true }));
  const window = unique(windows.windows.filter((w) => w.title === "Counter"), "window");
  const target = new ActionTarget.Window({ pid: app.pid, windowId: window.windowId });
  const snapshot = async (label) => {
    const state = await driver.getWindowState(
      GetWindowStateInput.new({
        pid: app.pid, windowId: window.windowId,
        includeAccessibilityTree: true, includeScreenshot: true,
        screenshotOutFile: join(artifactsDir, `${label}.png`),
      }),
    );
    if (state.degraded || state.truncated) throw new Error(`${label} snapshot is degraded or truncated`);
    // Keep the whole result (snapshot id, screenshot reference, degraded/truncated flags), not just
    // the elements, so the retained tree is provably from a complete snapshot. Ids are bigint.
    const json = JSON.stringify(state, (_key, value) => (typeof value === "bigint" ? value.toString() : value), 2);
    writeFileSync(join(artifactsDir, `${label}.json`), json);
    return state;
  };

  const before = await snapshot("before");
  const button = unique((before.elements ?? []).filter((e) => e.label === "Increment"), "button");
  const counter = unique((before.elements ?? []).filter((e) => e.label === "Count"), "counter");
  if (!button.elementToken || counter.value === undefined) throw new Error("Snapshot lacks the button token or counter value");

  let clicked = false;
  try {
    await driver.click(ClickInput.new({
      target,
      position: new ClickPosition.Element({ elementToken: button.elementToken }),
      deliveryMode: InputDeliveryMode.Background,
      button: ClickButton.Left, count: 1,
    }));
    clicked = true;
  } catch (error) {
    // A timeout or interrupted action before its response is "unknown": the postcondition below
    // decides, and the click is never replayed.
    if (!/timed out|ActionInterrupted/u.test(String(error))) throw error;
  }

  // Bounded poll on fresh snapshots; never a fixed sleep, never a second click.
  const deadline = Date.now() + 10_000;
  let after = await snapshot("after");
  let updated = unique((after.elements ?? []).filter((e) => e.label === "Count"), "counter");
  while (updated.value === counter.value && Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, 250));
    after = await snapshot("after");
    updated = unique((after.elements ?? []).filter((e) => e.label === "Count"), "counter");
  }
  if (updated.value !== undefined && updated.value !== counter.value) {
    finish("verified", `Count ${counter.value} -> ${updated.value}`);
  } else {
    finish(clicked ? "refuted" : "unknown", `Count stayed ${counter.value}`);
  }
} catch (error) {
  finish("unknown", String(error));
} finally {
  try {
    await driver.shutdown();
  } finally {
    if ("uniffiDestroy" in driver && typeof driver.uniffiDestroy === "function") driver.uniffiDestroy();
  }
}

import { spawn } from "node:child_process";
import { homedir } from "node:os";
import { join } from "node:path";
import { workflow } from "@bastani/atomic/workflows";
import { Type } from "typebox";

const sdkDir = join(homedir(), ".cache", "atomic-cua");
const cuaEnv = { ...process.env, CUA_DRIVER_RS_TELEMETRY_ENABLED: "false" };

function run(command: string, args: string[], signal: AbortSignal, cwd?: string) {
  return new Promise<{ code: number | null; stdout: string; stderr: string }>((resolve) => {
    const child = spawn(command, args, { cwd, env: cuaEnv, signal, stdio: ["ignore", "pipe", "pipe"] });
    let stdout = "";
    let stderr = "";
    child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
    child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
    // A missing executable (ENOENT) or an abort arrives here rather than on "close"; treat it as a
    // failed command so the preflight can return its remediation instead of throwing.
    child.on("error", (error) => resolve({ code: null, stdout, stderr: `${stderr}${error.message}` }));
    child.on("close", (code) => resolve({ code, stdout, stderr }));
  });
}

export default workflow({
  name: "verify-counter",
  description: "Prove the Increment button changes the Count field in the Counter window.",
  inputs: { artifactsDir: Type.String({ description: "Directory for before/after state JSON and screenshots" }) },
  outputs: { result: Type.String(), detail: Type.String() },
  run: async (ctx) => {
    const preflight = await ctx.tool(
      "cua-preflight",
      { platform: process.platform },
      async ({ signal }) => {
        const version = await run("cua-driver", ["--version"], signal);
        if (version.code !== 0) {
          return { ready: false, reason: "cua-driver is not installed; run /bin/bash -c \"$(curl -fsSL https://cua.ai/driver/install.sh)\" (Windows: irm https://cua.ai/driver/install.ps1 | iex), then cua-driver telemetry disable" };
        }
        const status = await run("cua-driver", ["status"], signal);
        const daemon = status.code === 0;
        if (process.platform === "darwin" && daemon) {
          const permissions = await run("cua-driver", ["permissions", "status", "--json"], signal);
          const grants = permissions.code === 0
            ? (JSON.parse(permissions.stdout) as { accessibility?: boolean; screen_recording?: boolean })
            : {};
          if (grants.accessibility !== true || grants.screen_recording !== true) {
            return { ready: false, reason: "Missing macOS grant: run `cua-driver permissions grant`, toggle CuaDriver on under System Settings → Privacy & Security → Accessibility and Screen & System Audio Recording, then relaunch the daemon with `open -n -g -a CuaDriver --args serve`" };
          }
        }
        const apps = await run("cua-driver", ["call", "list_apps"], signal);
        if (apps.code !== 0) {
          return { ready: false, reason: `cua-driver call list_apps failed; start the daemon (macOS: open -n -g -a CuaDriver --args serve; Windows: cua-driver serve in the interactive session; Linux: cua-driver serve inside the graphical session): ${apps.stderr.trim()}` };
        }
        return { ready: true, daemon };
      },
      { timeoutMs: 60_000 },
    );
    if (!preflight.ready) {
      return ctx.exit({ status: "blocked", reason: preflight.reason });
    }

    const scenario = await ctx.tool(
      "verify-counter-scenario",
      { artifactsDir: ctx.inputs.artifactsDir, daemon: preflight.daemon },
      async ({ signal }) => {
        const args = JSON.stringify({ daemon: preflight.daemon, artifactsDir: ctx.inputs.artifactsDir });
        const child = await run("node", ["verify-counter.mjs", args], signal, sdkDir);
        const line = child.stdout.trim().split("\n").at(-1) ?? "";
        const parsed = line.startsWith("{") ? (JSON.parse(line) as { result: string; detail: string }) : undefined;
        const result = parsed?.result ?? "unknown";
        if (result !== "verified") {
          throw new Error(`desktop verification ${result}: ${parsed?.detail ?? child.stderr.trim()}`);
        }
        return { result, detail: parsed?.detail ?? "" };
      },
      { timeoutMs: 5 * 60_000 },
    );

    return scenario;
  },
});

npm install --save-dev @bastani/atomic@"$(atomic --version)" @bastani/pi-ai@"$(atomic --version)"

import { AuthStorage } from "@bastani/atomic";
import { workflow } from "@bastani/atomic/workflows";
import { builtinModels } from "@bastani/pi-ai/providers/all";
import { Type } from "typebox";

export default workflow({
  name: "triage",
  description: "Route a support request to a suitable handler.",
  inputs: { request: Type.String() },
  outputs: { handler: Type.String() },
  run: async (ctx) => {
    const request = ctx.inputs.request;
    const decision = await ctx.tool("classify-intent", { request }, async ({ signal }) => {
      const models = builtinModels({ credentials: AuthStorage.create() });
      const model = models.getModelOfType("classifier", "typesafe", "jev-latest");
      if (!model) throw new Error("TypeSafe classifier is unavailable");
      const result = await models.classify(model, {
        state: { request },
        questions: {
          intent: {
            type: "choice",
            instructions: "Which support handler should review this request?",
            criteria: {
              account: "Questions about an existing account",
              product: "Questions about product behavior",
              other: "Neither account nor product",
            },
          },
        },
      }, { signal });
      if (result.stopReason !== "stop") throw new Error(result.errorMessage ?? "Classification failed");
      const intent = result.answers.intent;
      if (intent?.type !== "choice") throw new Error("Missing intent answer");
      return { choice: intent.choice, confidence: intent.confidence };
    }, { timeoutMs: 60_000 });

    // Only workflow code chooses the next action; uncertain requests go to a person.
    if (decision.confidence < 0.7 || decision.choice === "other") {
      return { handler: "human review required" };
    }
    await ctx.task(`${decision.choice}-review`, {
      prompt: `Review this ${decision.choice} request and propose a response: ${request}`,
    });
    return { handler: decision.choice };
  },
});

import { mkdir, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { AuthStorage } from "@bastani/atomic";
import { workflow } from "@bastani/atomic/workflows";
import { builtinModels } from "@bastani/pi-ai/providers/all";
import { Type } from "typebox";

export default workflow({
  name: "preview-asset",
  description: "Generate a draft visual asset for review.",
  inputs: { brief: Type.String() },
  outputs: { imagePath: Type.String() },
  run: async (ctx) => {
    const brief = ctx.inputs.brief;
    const outputDir = join(ctx.cwd ?? process.cwd(), ".atomic", "workflow-assets", ctx.runId ?? "local");
    const generated = await ctx.tool("generate-preview", { brief, outputDir }, async ({ signal }) => {
      const models = builtinModels({ credentials: AuthStorage.create() });
      const model = models.getModelOfType("image", "openrouter", "google/gemini-2.5-flash-image");
      if (!model) throw new Error("OpenRouter image model is unavailable");
      const result = await models.generateImages(model, {
        input: [{ type: "text", text: `Draft visual asset: ${brief}` }],
      }, { signal });
      if (result.stopReason !== "stop") throw new Error(result.errorMessage ?? "Image generation failed");
      const image = result.output.find((block) => block.type === "image");
      if (!image) throw new Error("The response contained no image");
      const extension = image.mimeType === "image/jpeg" ? "jpg" : image.mimeType === "image/webp" ? "webp" : "png";
      const imagePath = join(outputDir, `preview.${extension}`);
      await mkdir(dirname(imagePath), { recursive: true });
      await writeFile(imagePath, Buffer.from(image.data, "base64"));
      return { imagePath };
    }, { timeoutMs: 120_000 });
    return { imagePath: generated.imagePath };
  },
});

// .atomic/workflows/shared-research.ts
import { workflow } from "@bastani/atomic/workflows";
import { Type } from "typebox";

export default workflow({
  name: "shared-research",
  description: "",
  inputs: {
    topic: Type.String(),
  },
  outputs: {
    summary: Type.String({ description: "Research summary markdown." }),
    sources: Type.Optional(Type.Array(Type.String(), { description: "Source URLs and file references." })),
  },
  run: async (ctx) => {
    const result = await ctx.task("research", { prompt: `Research ${String(ctx.inputs.topic)}` });
    return { summary: result.text, sources: [] };
  },
});

// .atomic/workflows/research-and-synthesize.ts
import { workflow } from "@bastani/atomic/workflows";
import { Type } from "typebox";
import sharedResearch from "./shared-research.js";

export default workflow({
  name: "research-and-synthesize",
  description: "Run shared research and synthesize it.",
  inputs: {
    topic: Type.String(),
  },
  outputs: {
    final: Type.String({ description: "Synthesis built from the child research summary." }),
    child_run_id: Type.String({ description: "Run id of the nested shared-research child." }),
  },
  run: async (ctx) => {
    const child = await ctx.workflow(sharedResearch, {
      inputs: { topic: ctx.inputs.topic },
      stageName: "run shared research",
    });
    if (child.exited === true) {
      return ctx.exit({ status: child.status, reason: child.exitReason ?? "shared research stopped early" });
    }

    const final = await ctx.task("synthesize", {
      prompt: `Synthesize:\n\n${String(child.outputs.summary)}`,
    });
    return { final: final.text, child_run_id: child.runId };
  },
});

import {
  adversarialVerification,
  classifyAndAct,
  fanOutAndSynthesize,
  generateAndFilter,
  goal,
  loopUntilDone,
  openClaudeDesign,
  ralph,
  tournament,
} from "@bastani/atomic/workflows/builtin";

import goal from "@bastani/atomic/workflows/builtin/goal";
import ralph from "@bastani/atomic/workflows/builtin/ralph";

import { workflow } from "@bastani/atomic/workflows";
import { Type } from "typebox";
import { adversarialVerification, fanOutAndSynthesize } from "@bastani/atomic/workflows/builtin";

export default workflow({
  name: "research-and-verify",
  description: "Map repository slices, synthesize evidence, and verify the report.",
  inputs: { topic: Type.String() },
  outputs: {
    report_path: Type.String(),
    approved: Type.Boolean(),
  },
  run: async (ctx) => {
    const research = await ctx.workflow(fanOutAndSynthesize, {
      inputs: {
        prompt: `Partition repository research for: ${ctx.inputs.topic}. Save cited findings per slice and synthesize conflicts.`,
        max_branches: 6,
      },
      stageName: "repository research",
    });
    if (research.exited === true) {
      return ctx.exit({ status: research.status, reason: research.exitReason ?? "research stopped early" });
    }

    const verification = await ctx.workflow(adversarialVerification, {
      inputs: { task: `Verify the cited report at ${research.outputs.synthesis_path}` },
      stageName: "verify research report",
    });
    if (verification.exited === true) {
      return ctx.exit({ status: verification.status, reason: verification.exitReason ?? "verification stopped early" });
    }

    return {
      report_path: research.outputs.synthesis_path,
      approved: verification.outputs.approved,
    };
  },
});

const child = await ctx.workflow(sharedResearch);
if (child.exited === true) {
  child.outputs.summary; // string | undefined: ctx.exit({ outputs }) may be partial
} else {
  child.outputs.summary; // string: normal completion returned the full declared contract
  child.outputs.sources; // string[] | undefined: optional output declared by sharedResearch
}