@agentswf/engine 0.1.0-beta.0 → 0.1.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentswf/engine",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.2",
   "description": "agents.wf: the engine that runs workflows made of coding agents",
   "license": "MIT",
   "homepage": "https://github.com/romanlv/agentswf",
@@ -29,10 +29,10 @@
     "!src/**/fixtures"
   ],
   "dependencies": {
-    "@agentswf/wf": "0.1.0-beta.0",
-    "@agentswf/contract": "0.1.0-beta.0",
-    "@agentswf/harness": "0.1.0-beta.0",
-    "@agentswf/sandbox": "0.1.0-beta.0",
+    "@agentswf/wf": "0.1.0-beta.2",
+    "@agentswf/contract": "0.1.0-beta.2",
+    "@agentswf/harness": "0.1.0-beta.2",
+    "@agentswf/sandbox": "0.1.0-beta.2",
     "typebox": "^1.3.34"
   },
   "publishConfig": {

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/operator-cli.ts

@@ -27,6 +27,7 @@ import { type Kept, keepRecords } from "./attempt-output";
 import { continueCommand, printEnding, toldOf } from "./attempt-view";
 import { messageOf } from "./errors";
 import { type Caller, showOwnTab, startHere, takeCaller } from "./here";
+import { type InitCommand, initUsage, parseInitCommand, runInit } from "./init-command";
 import { logsCommand } from "./logs-command";
 import { machinePaths, sandboxesDirOf } from "./machine";
 import {
@@ -79,6 +80,8 @@ export type OperatorEnvironment = {
   callerSearchMs?: number;
   signal?: AbortSignal;
   now?: () => number;
+  /** What `awf init` runs to install, in the folder it set up. */
+  install?: (dir: string) => Promise<number>;
   /** How `awf allowance` reads a harness's plan. */
   readAllowance?: (harness: Harness) => Promise<HarnessAllowance>;
   /**
@@ -126,6 +129,7 @@ export async function runOperatorCli(
     return 0;
   }
   if (argv[0] === "test") return testCommand(argv.slice(1), environment, stdout, stderr);
+  if (argv[0] === "init") return initCommand(argv.slice(1), environment, stdout, stderr);
   if (argv[0] === "logs") {
     return logsCommand(argv.slice(1), environment.cwd ?? process.cwd(), { stdout, stderr });
   }
@@ -453,6 +457,33 @@ async function allowanceCommand(
   return 0;
 }
 
+/** `awf init`: a folder set up for writing workflows. */
+async function initCommand(
+  argv: readonly string[],
+  environment: OperatorEnvironment,
+  stdout: (text: string) => void,
+  stderr: (text: string) => void,
+): Promise<number> {
+  const cwd = environment.cwd ?? process.cwd();
+  let command: InitCommand | "help";
+  try {
+    command = parseInitCommand(argv, cwd);
+  } catch (error) {
+    stderr(`awf: ${messageOf(error)}\n\n${initUsage}`);
+    return 2;
+  }
+  if (command === "help") {
+    stdout(initUsage);
+    return 0;
+  }
+  try {
+    return await runInit(command, cwd, { stdout, stderr }, environment.install);
+  } catch (error) {
+    stderr(`awf: ${messageOf(error)}`);
+    return 1;
+  }
+}
+
 /** `awf test`: the workflow tests under the given paths, with Bun's test runner. */
 async function testCommand(
   argv: readonly string[],

package/src/run-command.ts

@@ -11,6 +11,7 @@ const DEFAULT_TIMEOUT = "1h";
 export const usage = [
   "usage: awf run [options] <workflow-file> [options] [-- workflow arguments...]",
   "       awf run [options] <workflow-file> --continue <id>",
+  "       awf init [dir] [--no-install]",
   "       awf test [paths...] [-t <pattern>] [--watch] [--timeout <duration>]",
   "       awf allowance [harness...] [--json]",
   "       awf runs [<run>] [--json]          (awf runs -h)",

package/src/sandboxes.ts

@@ -75,6 +75,8 @@ export type Seat = {
 
 export type SeatedAgent = {
   occupant: Occupant;
+  /** Its sandbox keeps the harness's model-side web tools. */
+  webSearch?: true;
   /** Hands a refreshed credential back to the operator; after each operation and at release. */
   writeBack(): Promise<void>;
   /** Writes back, then releases the occupant; once, however often it is called. */
@@ -299,6 +301,8 @@ export class RunSandboxes {
           read: [...resolved.read],
           write: [...resolved.write],
           network: [...resolved.network],
+          ...(resolved.sockets.length > 0 ? { sockets: [...resolved.sockets] } : {}),
+          ...(resolved.webSearch ? { webSearch: true } : {}),
           [provider]: resolved.environment,
         },
         directory,
@@ -441,6 +445,7 @@ export class RunSandboxes {
       let released: Promise<void> | undefined;
       const seated: SeatedAgent = {
         occupant: this.#logged(sandbox, occupant, who),
+        ...(sandbox.resolved.webSearch ? { webSearch: true as const } : {}),
         writeBack: () => seeded.writeBack(),
         release: () => {
           released ??= seeded

package/src/workflow-runner.ts

@@ -79,7 +79,6 @@ import type {
   SessionCopy,
   SessionSettings,
 } from "@agentswf/harness/adapter";
-import type { Occupant } from "@agentswf/sandbox";
 import { PUBLISHED_PRICES } from "./accounting/prices";
 import { summarizeRun } from "./accounting/summary";
 import { buildAgentBundle, installAgentLauncher, installSandboxedDoor } from "./agent-launcher";
@@ -687,10 +686,10 @@ type AgentOpening = {
   ledger: AgentLedger;
   /** Its skills' sources, resolved when it opens; absent when it has the operator's. */
   skills?: SkillSource[];
-  /** The host's activation for the agent, working in `cwd`, inside `occupant` if sandboxed. */
+  /** The host's activation for the agent, working in `cwd`, inside its seat's occupant if sandboxed. */
   activation(
     cwd: string,
-    occupant?: Occupant,
+    seated?: Pick<SeatedAgent, "occupant" | "webSearch">,
     skills?: AgentSkills,
     /** Its harness home: a sandbox's, or its own on the host. */
     home?: string,
@@ -1227,14 +1226,15 @@ class WorkflowOwner {
       sessions,
       ledger: this.options.ledger.agent(accounted),
       ...(identity.skills ? { skills: identity.skills } : {}),
-      activation: (cwd, occupant, skills, home) => ({
+      activation: (cwd, seated, skills, home) => ({
         key: spec.key,
         deadline: effectiveDeadline,
         cwd,
         execution,
         ...(spec.instructions === undefined ? {} : { instructions: spec.instructions }),
         ...(spec.labels === undefined ? {} : { labels: spec.labels }),
-        ...(occupant ? { occupant } : {}),
+        ...(seated ? { occupant: seated.occupant } : {}),
+        ...(seated?.webSearch ? { webSearch: true } : {}),
         ...(skills ? { skills } : {}),
         ...(home ? { home } : {}),
         ...paneOptions(identity),
@@ -1624,7 +1624,7 @@ class WorkflowOwner {
       let session: HarnessSession;
       try {
         session = await this.options.host.openAgent(
-          activation(seat.cwd, seated.occupant, seat.skills, seat.home),
+          activation(seat.cwd, seated, seat.skills, seat.home),
         );
       } catch (error) {
         await seated.release().catch(() => undefined);
@@ -1827,14 +1827,15 @@ class WorkflowOwner {
       ledger: this.options.ledger.agent(accounted),
       ...(sources ? { skills: sources } : {}),
       ...(sandboxed && copy ? { carried: { parent: parentKey, forked, copy } } : {}),
-      activation: (cwd, occupant, given, home) => ({
+      activation: (cwd, seated, given, home) => ({
         key: spec.key,
         deadline,
         cwd,
         execution,
         ...(forkSpec.instructions === undefined ? {} : { instructions: forkSpec.instructions }),
         ...(forkSpec.labels === undefined ? {} : { labels: forkSpec.labels }),
-        ...(occupant ? { occupant } : {}),
+        ...(seated ? { occupant: seated.occupant } : {}),
+        ...(seated?.webSearch ? { webSearch: true } : {}),
         ...(given ? { skills: given } : {}),
         ...(home ? { home } : {}),
         ...(continues ? { continues } : {}),