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

package/src/init-command.ts

@@ -1,21 +1,39 @@
 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" };
+import { messageOf } from "./errors";
+import help from "./help/init.txt" with { type: "text" };
+import type { Out } from "./run-commands";
 
-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 const initUsage = help.trimEnd();
 
 export type InitCommand = { dir: string; install: boolean };
 
+/** `awf init`: a folder set up for writing workflows. */
+export async function initCommand(
+  argv: readonly string[],
+  cwd: string,
+  io: Out & { install?: (dir: string) => Promise<number> },
+): Promise<number> {
+  let command: InitCommand | "help";
+  try {
+    command = parseInitCommand(argv, cwd);
+  } catch (error) {
+    io.stderr(`awf: ${messageOf(error)}\n\n${initUsage}`);
+    return 2;
+  }
+  if (command === "help") {
+    io.stdout(initUsage);
+    return 0;
+  }
+  try {
+    return await runInit(command, cwd, io, io.install);
+  } catch (error) {
+    io.stderr(`awf: ${messageOf(error)}`);
+    return 1;
+  }
+}
+
 export function parseInitCommand(argv: readonly string[], cwd: string): InitCommand | "help" {
   let dir: string | undefined;
   let install = true;

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

@@ -1,13 +1,13 @@
 # Workflows
 
-This folder holds [agents.wf](https://github.com/romanlv/agentswf) workflows: TypeScript files
+This folder holds [agents.wf](https://agents.wf) 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.
+  `defineWorkflow(…)` 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
+- The API, with every option and outcome, as Markdown:
+  https://agents.wf/reference/workflow-api.md. Every other page is in https://agents.wf/llms.txt.
 - `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

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

@@ -3,7 +3,7 @@ import { answer, reply, testWorkflow } from "agentswf/testing";
 import hello, { ANSWER } from "./workflow";
 
 test("returns the agent's answer", async () => {
-  const run = await testWorkflow(hello, {}, {
+  const run = await testWorkflow(hello, null, {
     agents: { hello: answer(ANSWER, { answer: 391 }) },
   });
   expect(run.value).toEqual({ answer: 391 });
@@ -11,7 +11,7 @@ test("returns the agent's answer", async () => {
 });
 
 test("an agent that never answers is nudged once, then the result says why", async () => {
-  const run = await testWorkflow(hello, {}, { agents: { hello: reply.silent() } });
+  const run = await testWorkflow(hello, null, { 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

@@ -1,26 +1,22 @@
-import { defineExecutableWorkflow, isAnswered } from "agentswf/workflow";
+import { defineWorkflow } 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 };
-    },
+export default defineWorkflow({
+  meta: { name: "hello", description: "Ask one agent a question with a known answer." },
+  async run(wf) {
+    // 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 wf.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 outcome.answered ? outcome.value : { unanswered: outcome.reason };
   },
-  // Turns the command line into args: `awf run hello/workflow.ts -- ...`.
-  prepare: () => ({}),
 });

package/src/keep-alive.ts

@@ -0,0 +1,40 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { EventAgentOpenSpec } from "@agentswf/contract/workflow";
+
+export type KeepAlive = NonNullable<EventAgentOpenSpec["keepAlive"]>;
+
+/** Claude's prompt cache lives an hour for the main conversation on a subscription. */
+export const DEFAULT_WINDOW_MS = 60 * 60_000;
+
+/**
+ * Set while an `onTimeout` handler runs: a turn begun in it opens no window, so a wrap-up can't keep
+ * its own agent live. A message turn opens one whatever the context: it is the peer's.
+ */
+const inHandler = new AsyncLocalStorage<boolean>();
+
+export function inTimeoutHandler(): boolean {
+  return inHandler.getStore() === true;
+}
+
+export function asTimeoutHandler<T>(fn: () => T): T {
+  return inHandler.run(true, fn);
+}
+
+/** `keepAlive` as an open gave it, checked: what a typed caller can't get wrong, a plain one can. */
+export function checkedKeepAlive(key: string, given: unknown): KeepAlive {
+  if (typeof given !== "object" || given === null)
+    throw new Error(`agent ${key}: keepAlive is { timeoutMs?, onTimeout? }`);
+  const { timeoutMs, onTimeout } = given as Record<string, unknown>;
+  if (
+    timeoutMs !== undefined &&
+    (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0)
+  )
+    throw new Error(`agent ${key}: keepAlive's timeoutMs is a positive number of milliseconds`);
+  if (onTimeout !== undefined && typeof onTimeout !== "function")
+    throw new Error(`agent ${key}: keepAlive's onTimeout is a function`);
+  // A copy: a later change to the caller's object would skip this check.
+  return {
+    ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    ...(onTimeout === undefined ? {} : { onTimeout: onTimeout as KeepAlive["onTimeout"] }),
+  } as KeepAlive;
+}

package/src/logs-command.ts

@@ -1,5 +1,9 @@
+import { homedir } from "node:os";
 import type { LogEventJson, LogsJson, RouteEnds, RunLogLine } from "@agentswf/contract/records";
+import type { JsonObject } from "@agentswf/contract/workflow";
+import { duration } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/logs.txt" with { type: "text" };
 import {
   clockTime,
   command,
@@ -28,24 +32,10 @@ import {
   readRun,
   timeOf,
 } from "./run-read";
-import { findRun, type RunStatus } from "./run-state";
-import { describeActivity, duration } from "./run-view";
+import { findRun, findRunByRef, type RunStatus } from "./run-state";
+import { describeActivity } from "./run-view";
 
-export const logsUsage = [
-  "usage: awf logs [<run>] [@<handle>] [--agent <key>] [--stage <name>] [--after <cursor>]",
-  "                [--limit <n>] [--wait <seconds> | --follow] [--full] [--cwd <directory>]",
-  "                [--run-root <directory>] [--json]",
-  "",
-  "What a run did and is doing: its events and what its agents did, read from their own session",
-  "files, merged by time. With no run, the newest here. Without --after, the last 40 events; with",
-  "it, what came after, oldest first. Every answer ends with the command that gets only what is",
-  "new. --wait: with nothing to show yet, wait for the first event, at most that many seconds, up",
-  "to 300; --follow prints each event as it comes until the run ends. @<handle> names one event,",
-  "and --full prints its text, with common credential shapes masked; --json carries it always.",
-  "",
-  "Exits 0 on any read that worked, 1 when there is no such run or the cursor or handle does not",
-  "fit it, 2 on a usage error, 3 when the run's files could not be read.",
-].join("\n");
+export const logsUsage = help.trimEnd();
 
 const DEFAULT_LIMIT = 40;
 /**
@@ -82,6 +72,7 @@ export async function logsCommand(
   shellCwd: string,
   out: Out,
   clock: LogsClock = REAL_CLOCK,
+  home: string = homedir(),
 ): Promise<number> {
   if (argv.includes("-h") || argv.includes("--help")) {
     out.stdout(logsUsage);
@@ -101,7 +92,10 @@ export async function logsCommand(
     return 2;
   }
   try {
-    const { status, alsoRunning } = await findRun(place.runRoot, options.ref);
+    const { status, alsoRunning } =
+      options.ref === undefined
+        ? await findRun(place.runRoot, undefined)
+        : { status: await findRunByRef(options.ref, place, home), alsoRunning: [] };
     const again = shellLine(command(place, "awf", "logs", status.ref));
     let after: Cursor | undefined;
     if (options.after !== undefined) {
@@ -200,20 +194,31 @@ class Reader {
     });
   }
 
-  async refresh(runRoot: string): Promise<RunStatus> {
-    this.status = (await findRun(runRoot, this.status.ref)).status;
+  /** The run read again where it was found, which may be another project's. */
+  async refresh(): Promise<RunStatus> {
+    this.status = (await findRun(this.status.run.root, this.status.ref)).status;
     return this.status;
   }
 }
 
 type Read = Awaited<ReturnType<Reader["next"]>>;
 
-/** Each operation's stage and agent, from the lines that name them. */
-type Places = { stage: Map<string, string>; agent: Map<string, string> };
+/** Where each operation ran, and each tool call's input, by its id, so its end shows it. */
+type Places = {
+  stage: Map<string, string>;
+  agent: Map<string, string>;
+  calls: Map<string, { input: JsonObject; ended: boolean }>;
+};
 
 function operationPlaces(lines: readonly { line: RunLogLine }[]): Places {
-  const places: Places = { stage: new Map(), agent: new Map() };
+  const places: Places = { stage: new Map(), agent: new Map(), calls: new Map() };
   for (const { line } of lines) {
+    if (line.kind === "tool-called")
+      places.calls.set(line.call, { input: line.input, ended: false });
+    if (line.kind === "tool-ended") {
+      const call = places.calls.get(line.call);
+      if (call) call.ended = true;
+    }
     if (!("operationId" in line) || !line.operationId) continue;
     if ("stage" in line && line.stage) places.stage.set(line.operationId, line.stage);
     if ("agent" in line && line.agent) places.agent.set(line.operationId, line.agent);
@@ -257,10 +262,17 @@ function sidesOf(event: ReadEvent): readonly string[] {
   }
 }
 
-function kept(read: Read, options: LogsOptions) {
+function kept(read: Read, options: LogsOptions, json = false) {
   const stages = operationPlaces(read.log.lines);
   const events = read.events.filter(
     (event) =>
+      // A call that has ended shows on its end's line, with its input; `--json` keeps both.
+      !(
+        !json &&
+        event.source !== "activity" &&
+        event.line.kind === "tool-called" &&
+        stages.calls.get(event.line.call)?.ended
+      ) &&
       (options.agent === undefined ||
         agentOf(event, stages) === options.agent ||
         sidesOf(event).includes(options.agent)) &&
@@ -290,7 +302,7 @@ async function page(
   clock: LogsClock,
 ): Promise<number> {
   let read = await reader.next();
-  let { events, stages } = kept(read, options);
+  let { events, stages } = kept(read, options, json);
   const deadline = clock.now() + options.waitSeconds * 1000;
   let waited = false;
   // Without a cursor, a wait reads on from its first read: nothing before it is kept.
@@ -305,14 +317,14 @@ async function page(
     waited = true;
     if (!reader.from) from = read.cursor;
     await clock.sleep(POLL_MS);
-    await reader.refresh(place.runRoot);
+    await reader.refresh();
     read = await reader.next(from);
-    ({ events, stages } = kept(read, options));
+    ({ events, stages } = kept(read, options, json));
     if (events.length > 0) {
       // A burst comes back as one page.
       await clock.sleep(SETTLE_MS);
       read = await reader.next(from);
-      ({ events, stages } = kept(read, options));
+      ({ events, stages } = kept(read, options, json));
     }
   }
   const status = reader.status;
@@ -417,7 +429,7 @@ async function follow(
       if (reader.status.state !== "running") break;
       await clock.sleep(POLL_MS);
     }
-    await reader.refresh(place.runRoot);
+    await reader.refresh();
     read = await reader.next(cursor);
   }
   out.stdout(trailer(reader.status, read, place, undefined, undefined, undefined));
@@ -532,11 +544,13 @@ function describeEvent(event: ReadEvent, stages: Places): string {
   const agent = agentOf(event, stages);
   const where = [stageOf(event, stages), agent && said(agent, 60)].filter(Boolean).join("  ");
   const what =
-    event.source === "activity" ? describeActivity(event.activity) : describeLine(event.line);
+    event.source === "activity"
+      ? describeActivity(event.activity)
+      : describeLine(event.line, stages);
   return `@${event.handle} ${clockTime(event.at)} ${where ? `${where}  ` : ""}${what}`;
 }
 
-function describeLine(line: RunLogLine): string {
+function describeLine(line: RunLogLine, places: Places): string {
   const operation = (of: "turn" | "compact") => (of === "compact" ? "compaction" : "turn");
   switch (line.kind) {
     case "attempt-started":
@@ -576,15 +590,21 @@ function describeLine(line: RunLogLine): string {
     case "decision-ended":
       return `decision ${line.decision} ${line.outcome}${line.error ? `  ${said(line.error)}` : ""}`;
     case "route-opened":
-      return `route ${routeEnds(line)} opened  "${said(line.purpose)}"  ${line.maxMessages} messages`;
+      return `route ${routeEnds(line)} opened  "${said(line.purpose)}"  ${line.maxMessages} messages${
+        line.timeoutMs === undefined ? "" : `, a question closes after ${duration(line.timeoutMs)}`
+      }`;
     case "route-closed":
       return `route ${routeEnds(line)} closed  ${line.reason}`;
     case "message-sent":
       return `message ${line.message} ${said(line.from, 60)} → ${said(line.to, 60)}  ${line.bytes} B${
-        line.replyTo === undefined ? "" : `, reply to ${line.replyTo}`
-      }${
+        line.via === undefined ? "" : ` via ${line.via}`
+      }${line.replyTo === undefined ? "" : `, reply to ${line.replyTo}`}${
         line.awaitsReply
-          ? `, reply owed  ${said(line.from, 60)} awaits it until ${clockTime(Date.parse(line.awaitsReply.until))}`
+          ? `, reply owed  ${said(line.from, 60)} awaits it${
+              line.awaitsReply.until
+                ? ` until ${clockTime(Date.parse(line.awaitsReply.until))}`
+                : ""
+            }`
           : ""
       }`;
     case "message-refused":
@@ -595,9 +615,60 @@ function describeLine(line: RunLogLine): string {
       return `message ${line.message} undelivered  ${line.reason}`;
     case "request-ended":
       return `request ${line.message} ${line.end}${line.reason ? `  ${said(line.reason)}` : ""}`;
+    case "participant-connected":
+      return `${said(line.participant, 60)} connected${line.to === "code" ? " to the code" : ""}`;
+    case "participant-post":
+      return `run → ${said(line.participant, 60)}  ${said(line.text)}`;
+    // A call is one line, its end's: what it was given, how it ended, and what it said back.
+    // Shown alone only while its end isn't in the log: still running, or cut short by a crash.
+    case "tool-called":
+      return toolLine(
+        line.tool,
+        line.input,
+        places.calls.get(line.call)?.ended ? "called" : "no end yet",
+      );
+    case "tool-ended": {
+      const answered =
+        line.outcome !== "ok"
+          ? line.error
+          : typeof line.result === "string"
+            ? `→ ${line.result}`
+            : line.result === undefined
+              ? undefined
+              : `→ ${JSON.stringify(line.result)}`;
+      return toolLine(
+        line.tool,
+        places.calls.get(line.call)?.input,
+        // Most calls take under a second; a duration says something only past one.
+        line.durationMs < 1000 ? line.outcome : `${line.outcome}  ${duration(line.durationMs)}`,
+        answered,
+      );
+    }
+    case "tool-refused":
+      return [
+        `tool call ${said(line.tool, 60)}`,
+        "refused",
+        line.code,
+        line.error && said(line.error),
+      ]
+        .filter(Boolean)
+        .join("  ");
   }
 }
 
+/** `tool call close_item {"id":"a1"}  ok  → Closed a1.`, apart from the harness's own tools. */
+function toolLine(
+  tool: string,
+  input: JsonObject | undefined,
+  how: string,
+  answered?: string,
+): string {
+  const given = input && Object.keys(input).length > 0 ? ` ${said(JSON.stringify(input), 80)}` : "";
+  return [`tool call ${said(tool, 60)}${given}`, how, answered && said(answered)]
+    .filter(Boolean)
+    .join("  ");
+}
+
 function routeEnds(line: RouteEnds): string {
   return line.between
     ? `${said(line.between[0], 60)} ↔ ${said(line.between[1], 60)}`

package/src/machine.ts

@@ -4,13 +4,15 @@ import type { RunRecord } from "@agentswf/contract/records";
 /**
  * What awf keeps per machine, under `~/.awf`, whatever a run's root: the marks of sessions runs
  * drive, each sandbox's homes, kept outside the project, whose run root a provider denies, and the
- * Herdr sessions it runs agents in: their config, and each run's mark on its workspace.
+ * Herdr sessions it runs agents in: their config, and each run's mark on its workspace; and the
+ * sockets holders reach live runs' coordinators through.
  */
 export function machinePaths(home: string): {
   root: string;
   callers: string;
   sandboxes: string;
   herdr: string;
+  coordinator: string;
 } {
   const root = join(home, ".awf");
   return {
@@ -18,6 +20,7 @@ export function machinePaths(home: string): {
     callers: join(root, "callers"),
     sandboxes: join(root, "sandboxes"),
     herdr: join(root, "herdr"),
+    coordinator: join(root, "coordinator"),
   };
 }
 
@@ -25,3 +28,11 @@ export function machinePaths(home: string): {
 export function sandboxesDirOf(home: string, run: Pick<RunRecord, "workflow" | "id">): string {
   return join(machinePaths(home).sandboxes, run.workflow, run.id);
 }
+
+/** Where live runs' coordinator sockets are: `AWF_COORDINATOR_DIR`, or `~/.awf/coordinator`. */
+export function coordinatorDir(
+  home: string,
+  environment: Readonly<Record<string, string | undefined>>,
+): string {
+  return environment.AWF_COORDINATOR_DIR || machinePaths(home).coordinator;
+}