@agentswf/engine 0.0.0-stage → 0.1.0-beta.1

package/src/init-command.ts

@@ -0,0 +1,240 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import manifest from "../package.json" with { type: "json" };
+
+export const initUsage = [
+  "usage: awf init [dir] [--no-install]",
+  "",
+  "Sets up the current directory, or dir, for writing workflows: hello/workflow.ts, a workflow",
+  "with one agent, and hello/workflow.test.ts, its test; package.json, tsconfig.json, .gitignore",
+  "and AGENTS.md. Then runs bun install, unless --no-install, for editor types: awf runs a",
+  "workflow against its own copies either way.",
+  "",
+  "Never overwrites. A file that exists is skipped, except that package.json gains the",
+  "devDependencies and scripts it lacks and .gitignore the lines it lacks.",
+].join("\n");
+
+export type InitCommand = { dir: string; install: boolean };
+
+export function parseInitCommand(argv: readonly string[], cwd: string): InitCommand | "help" {
+  let dir: string | undefined;
+  let install = true;
+  for (const option of argv) {
+    if (option === "-h" || option === "--help") return "help";
+    if (option === "--no-install") install = false;
+    else if (option.startsWith("-")) throw new Error(`unknown option: ${option}`);
+    else if (dir !== undefined) throw new Error(`one directory only, not ${dir} and ${option}`);
+    else dir = option;
+  }
+  const path = resolve(cwd, dir ?? ".");
+  if (existsSync(path) && !statSync(path).isDirectory()) {
+    throw new Error(`not a directory: ${dir}`);
+  }
+  return { dir: path, install };
+}
+
+const TEMPLATES = join(import.meta.dir, "init-template");
+
+/** Copied as they are, each only where nothing is yet. */
+const COPIED = ["hello/workflow.ts", "hello/workflow.test.ts", "tsconfig.json", "AGENTS.md"];
+
+const SCRIPTS = { test: "awf test", check: "tsc --noEmit" };
+
+// The versions this repository builds with; the root's catalog holds the same.
+export const DEV_DEPENDENCIES = {
+  "@types/bun": "^1.3.4",
+  // agentswf is released at the engine's version; it can't be imported here, it imports the engine.
+  agentswf: `^${manifest.version}`,
+  typebox: manifest.dependencies.typebox,
+  typescript: "^5.9.3",
+};
+
+const IGNORED = ["node_modules/", ".awf/"];
+
+type Change = { path: string; change: "created" | "updated" | "skipped"; detail?: string };
+
+/** A target init may write: absent, a file it reads or skips, or a symlink it never follows. */
+type Target = "missing" | "file" | "symlink";
+
+function targetOf(dir: string, path: string): Target {
+  const stat = lstatSync(join(dir, path), { throwIfNoEntry: false });
+  if (stat === undefined) return "missing";
+  if (stat.isSymbolicLink()) return "symlink";
+  if (!stat.isFile()) throw new Error(`${path} exists and is not a file`);
+  return "file";
+}
+
+/**
+ * Writes what `awf init` writes into `dir`, and says what it did to each file. Everything that
+ * would stop it, such as a package.json that isn't a JSON object, is found before it writes.
+ */
+export function initFolder(dir: string): Change[] {
+  for (const parent of new Set(COPIED.map(dirname))) {
+    const stat = lstatSync(join(dir, parent), { throwIfNoEntry: false });
+    if (stat !== undefined && !stat.isDirectory()) {
+      throw new Error(`${parent} exists and is not a directory`);
+    }
+  }
+  const targets = new Map(
+    ["package.json", ".gitignore", ...COPIED].map((path) => [path, targetOf(dir, path)]),
+  );
+  const pkg = targets.get("package.json") === "file" ? readPackageJson(dir) : undefined;
+
+  const changes: Change[] = [packageJson(dir, targets.get("package.json")!, pkg)];
+  for (const path of COPIED) {
+    const target = targets.get(path)!;
+    if (target !== "missing") {
+      changes.push({ path, change: "skipped", detail: skippedBecause(target) });
+      continue;
+    }
+    mkdirSync(join(dir, dirname(path)), { recursive: true });
+    const template = readFileSync(join(TEMPLATES, `${path}.template`));
+    writeFileSync(join(dir, path), template, { flag: "wx" });
+    changes.push({ path, change: "created" });
+  }
+  changes.push(gitignore(dir, targets.get(".gitignore")!));
+  return changes;
+}
+
+const skippedBecause = (target: Target) => (target === "symlink" ? "a symlink" : "exists");
+
+function readPackageJson(dir: string): { text: string; value: Record<string, unknown> } {
+  const text = readFileSync(join(dir, "package.json"), "utf8");
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`package.json is not JSON: ${(error as Error).message}`);
+  }
+  if (!isRecord(value)) throw new Error("package.json is not a JSON object");
+  return { text, value };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+function packageJson(
+  dir: string,
+  target: Target,
+  pkg: { text: string; value: Record<string, unknown> } | undefined,
+): Change {
+  const path = join(dir, "package.json");
+  if (target === "symlink") return { path: "package.json", change: "skipped", detail: "a symlink" };
+  if (pkg === undefined) {
+    const created = {
+      name: packageName(dir),
+      private: true,
+      type: "module",
+      scripts: SCRIPTS,
+      devDependencies: DEV_DEPENDENCIES,
+    };
+    writeFileSync(path, `${JSON.stringify(created, null, 2)}\n`, { flag: "wx" });
+    return { path: "package.json", change: "created" };
+  }
+  const { text, value: existing } = pkg;
+  const record = (key: string): Record<string, unknown> => {
+    const value = existing[key];
+    return isRecord(value) ? value : {};
+  };
+  const scripts = record("scripts");
+  const declared = {
+    ...record("dependencies"),
+    ...record("devDependencies"),
+    ...record("peerDependencies"),
+    ...record("optionalDependencies"),
+  };
+  const addedScripts = Object.entries(SCRIPTS).filter(([name]) => !(name in scripts));
+  const addedDependencies = Object.entries(DEV_DEPENDENCIES).filter(
+    ([name]) => !(name in declared),
+  );
+  if (addedScripts.length === 0 && addedDependencies.length === 0) {
+    return { path: "package.json", change: "skipped", detail: "has what init adds" };
+  }
+  const updated = {
+    ...existing,
+    scripts: { ...scripts, ...Object.fromEntries(addedScripts) },
+    devDependencies: { ...record("devDependencies"), ...Object.fromEntries(addedDependencies) },
+  };
+  const json = `${JSON.stringify(updated, null, indentOf(text))}\n`;
+  writeFileSync(path, text.includes("\r\n") ? json.replaceAll("\n", "\r\n") : json);
+  const added = [
+    ...addedDependencies.map(([name]) => name),
+    ...addedScripts.map(([name]) => `the ${name} script`),
+  ];
+  return { path: "package.json", change: "updated", detail: `added ${added.join(", ")}` };
+}
+
+function gitignore(dir: string, target: Target): Change {
+  const path = join(dir, ".gitignore");
+  if (target === "symlink") return { path: ".gitignore", change: "skipped", detail: "a symlink" };
+  if (target === "missing") {
+    writeFileSync(path, `${IGNORED.join("\n")}\n`, { flag: "wx" });
+    return { path: ".gitignore", change: "created" };
+  }
+  const text = readFileSync(path, "utf8");
+  const lines = new Set(text.split("\n").map((line) => line.trim().replace(/^\/|\/$/g, "")));
+  const missing = IGNORED.filter((line) => !lines.has(line.replace(/\/$/, "")));
+  if (missing.length === 0) return { path: ".gitignore", change: "skipped", detail: "has both" };
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const separator = text === "" || text.endsWith("\n") ? "" : newline;
+  writeFileSync(path, `${text}${separator}${missing.join(newline)}${newline}`);
+  return { path: ".gitignore", change: "updated", detail: `added ${missing.join(", ")}` };
+}
+
+/** A valid npm name from the folder's, which is all a private package's name has to be. */
+function packageName(dir: string): string {
+  const name = basename(dir)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .slice(0, 214)
+    .replace(/^[._-]+|-+$/g, "");
+  return name || "workflows";
+}
+
+function indentOf(text: string): string | number {
+  return /^\{\s*\r?\n([ \t]+)"/.exec(text)?.[1] ?? 2;
+}
+
+/** As a shell reads it: bare when that's safe, otherwise single-quoted. */
+function shellWord(word: string): string {
+  return /^[\w./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+}
+
+/** `awf init`: writes the folder, installs unless told not to, and says what to run next. */
+export async function runInit(
+  command: InitCommand,
+  cwd: string,
+  output: { stdout(text: string): void; stderr(text: string): void },
+  install: (dir: string) => Promise<number> = bunInstall,
+): Promise<number> {
+  mkdirSync(command.dir, { recursive: true });
+  const changes = initFolder(command.dir);
+  const installed = command.install ? (await install(command.dir)) === 0 : undefined;
+  const width = Math.max(...changes.map(({ change }) => change.length));
+  const lines = changes.map(
+    ({ path, change, detail }) =>
+      `${change.padEnd(width)}  ${path}${detail === undefined ? "" : ` (${detail})`}`,
+  );
+  const into = relative(cwd, command.dir);
+  const next = [
+    ...(into === "" ? [] : [`cd ${shellWord(into)}`]),
+    ...(installed ? [] : ["bun install"]),
+    "awf test                     # scripted agents: free, no agent starts",
+    "awf run hello/workflow.ts    # one real codex agent",
+  ];
+  output.stdout([...lines, "", "next:", ...next.map((line) => `  ${line}`)].join("\n"));
+  if (installed === false) {
+    output.stderr("awf: bun install failed; the files are written, run it again there");
+    return 1;
+  }
+  return 0;
+}
+
+async function bunInstall(dir: string): Promise<number> {
+  const child = Bun.spawn([process.execPath, "install"], {
+    cwd: dir,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  return child.exited;
+}

package/src/init-template/AGENTS.md.template

@@ -0,0 +1,16 @@
+# Workflows
+
+This folder holds [agents.wf](https://github.com/romanlv/agentswf) workflows: TypeScript files
+that run coding agents, started with `awf`.
+
+- A workflow is a folder with a `workflow.ts`, which default-exports
+  `defineExecutableWorkflow(…)` from `agentswf/workflow`, and a `workflow.test.ts` beside it.
+  `hello/` is the smallest one; copy it to start another.
+- The API, with every option and outcome:
+  https://github.com/romanlv/agentswf/blob/main/docs/workflow-api.md
+- `awf test` runs the tests with each agent replaced by scripted answers: no agent starts, and it
+  costs nothing. After a change, run it and `bun run check`, which typechecks.
+- `awf run hello/workflow.ts` starts real agents, on the operator's accounts. Don't run a workflow
+  unless asked.
+- Each run is kept in `.awf/runs/{workflow}/{id}`. `awf runs` lists them; `awf logs {run}` shows
+  what one did.

package/src/init-template/hello/workflow.test.ts.template

@@ -0,0 +1,17 @@
+import { expect, test } from "bun:test";
+import { answer, reply, testWorkflow } from "agentswf/testing";
+import hello, { ANSWER } from "./workflow";
+
+test("returns the agent's answer", async () => {
+  const run = await testWorkflow(hello, {}, {
+    agents: { hello: answer(ANSWER, { answer: 391 }) },
+  });
+  expect(run.value).toEqual({ answer: 391 });
+  expect(run.turnsOf("hello")[0]?.prompt).toContain("17 multiplied by 23");
+});
+
+test("an agent that never answers is nudged once, then the result says why", async () => {
+  const run = await testWorkflow(hello, {}, { agents: { hello: reply.silent() } });
+  expect(run.value).toHaveProperty("unanswered");
+  expect(run.turnsOf("hello").map((turn) => turn.nudge)).toEqual([false, true]);
+});

package/src/init-template/hello/workflow.ts.template

@@ -0,0 +1,26 @@
+import { defineExecutableWorkflow, isAnswered } from "agentswf/workflow";
+import Type from "typebox";
+
+export const ANSWER = Type.Object({ answer: Type.Integer() }, { additionalProperties: false });
+
+export default defineExecutableWorkflow({
+  definition: {
+    meta: { name: "hello", description: "Ask one agent a question with a known answer." },
+    async run(workflow) {
+      // A headless agent needs neither Herdr nor a sandbox. Swap in any harness and model your
+      // account has: "claude" in a pane, the default placement, runs on a subscription.
+      const agent = await workflow.agents.open({
+        key: "hello",
+        runtime: { harness: "codex", model: "gpt-6-luna", placement: "headless" },
+      });
+      const { outcome } = await agent.run<Type.Static<typeof ANSWER>>({
+        prompt: "What is 17 multiplied by 23? Work it out yourself; do not run any code.",
+        schema: ANSWER,
+        timeoutMs: 3 * 60_000,
+      });
+      return isAnswered(outcome) ? outcome.value : { unanswered: outcome.reason };
+    },
+  },
+  // Turns the command line into args: `awf run hello/workflow.ts -- ...`.
+  prepare: () => ({}),
+});

package/src/init-template/tsconfig.json.template

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "noEmit": true,
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "target": "ESNext",
+    "types": ["bun"]
+  },
+  "exclude": ["node_modules", ".awf"]
+}

package/src/jsonl.ts

@@ -0,0 +1,74 @@
+import { open, readFile } from "node:fs/promises";
+import { isCode } from "./files";
+
+const appendQueues = new Map<string, Promise<void>>();
+
+export async function appendLine(path: string, line: string): Promise<void> {
+  const previous = appendQueues.get(path) ?? Promise.resolve();
+  const current = previous.catch(() => undefined).then(() => appendCompleteLine(path, line));
+  appendQueues.set(path, current);
+  try {
+    await current;
+  } finally {
+    if (appendQueues.get(path) === current) appendQueues.delete(path);
+  }
+}
+
+async function appendCompleteLine(path: string, line: string): Promise<void> {
+  const handle = await open(path, "a");
+  try {
+    await writeAll(handle, new TextEncoder().encode(`${line}\n`));
+  } finally {
+    await handle.close();
+  }
+}
+
+type AppendWriter = {
+  write(bytes: Uint8Array, offset: number, length: number): Promise<{ bytesWritten: number }>;
+};
+
+export async function writeAll(handle: AppendWriter, bytes: Uint8Array): Promise<void> {
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const { bytesWritten } = await handle.write(bytes, offset, bytes.byteLength - offset);
+    if (bytesWritten === 0) throw new Error("append made no progress");
+    offset += bytesWritten;
+  }
+}
+
+/**
+ * Each line that parses as a JSON object, in order. One that doesn't is skipped wherever it is: a
+ * crash can tear the last, and a later writer appends after it.
+ */
+export async function readLines<T extends object>(path: string): Promise<T[]> {
+  const text = await readFile(path, "utf8").catch((error) => {
+    if (isCode(error, "ENOENT")) return "";
+    throw error;
+  });
+  return text.split("\n").flatMap((line) => {
+    try {
+      const value: unknown = JSON.parse(line);
+      return typeof value === "object" && value !== null ? [value as T] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+/** Ends a line a crash left torn, so the next line appended starts a line of its own. */
+export async function endTornLine(path: string): Promise<void> {
+  const handle = await open(path, "r").catch((error) => {
+    if (isCode(error, "ENOENT")) return undefined;
+    throw error;
+  });
+  if (!handle) return;
+  let torn: boolean;
+  try {
+    const { size } = await handle.stat();
+    const last = Buffer.alloc(1);
+    torn = size > 0 && (await handle.read(last, 0, 1, size - 1)).bytesRead === 1 && last[0] !== 10;
+  } finally {
+    await handle.close();
+  }
+  if (torn) await appendLine(path, "");
+}