@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/help/emit.txt

@@ -1,11 +1,12 @@
-usage: awf emit --target <file> --id <id> <event> [<json>] [--event-id <id>] [--json]
-       awf emit <run> <key>:reply '{"text": …, "author": …}' [--event-id <id>] [--cwd <directory>] [--run-root <directory>] [--json]
+usage: awf emit --target <file> --id <id> <event> [<json>] [--event-id <id>] [--source <name>] [--json]
+       awf emit <run> <key>:reply '{"text": …, "author": …}' [--event-id <id>] [--source <name>] [--cwd <directory>] [--run-root <directory>] [--json]
 
 Sends an event to the run of a workflow with events that --id names. That run starts if it has
 none and the event is one that starts one, and is woken if it has one: told while it runs,
 continued when it is parked or crashed. The run lives in the project of <file>, the nearest
 directory above it holding .awf/, whoever sends. --event-id names the occurrence: the same id
-again is a duplicate.
+again is a duplicate. --source names the integration that sent it, such as github, which the
+event a wait returns carries.
 
 The second form sends a participant's message to the code of a run that is there, <workflow>/<id>
 or an <id> only one workflow has, here or in a project awf knows: <key>:reply, which the workflow
@@ -15,7 +16,10 @@ arrive before the run connects the participant: it waits for the run's next wait
 takes only the workflow's own events.
 
 Prints what became of the event, and what was done to the run: accepted, duplicate or refused.
---json prints one document. Exits 0 for any of the three; 1 when <file> could not be loaded, or
-the run isn't found, and nothing is kept, or when the run's attempt could not be started (the
-event is kept, and the next event or awf tick tries again); 2 on a usage error, for a workflow
-with no events, or when the event is wrong for its target: its name, its data, or its id.
+--json prints one document: the result, or a refusal whose code says why it failed: usage,
+no-run, ambiguous, id, file, event, prepare, project, no-engine, other-engine, unreachable or
+internal-error. Exits 0 for any of the three; 1 when <file> could not be loaded, or the run
+isn't found or can't be read, and nothing is kept, or when the run's attempt could not be
+started (the event is kept, and the next event or awf tick tries again); 2 on a usage error, for
+a workflow with no events, or when the event is wrong for its target: its name, its data, or its
+id.

package/src/help/inbox.txt

@@ -4,9 +4,11 @@ usage: awf inbox [<run>] [--open] [--workflow <name>] [--as <key>] [--after <cur
 What agents said to a participant outside the run, and what it said back: routes, messages,
 answers, questions that closed unanswered, and each attempt's end, oldest first. Without a run,
 every run here that connected one; --workflow narrows that. A run is <workflow>/<id>, or an <id>
-only one workflow has. --after reads on from a cursor the last answer gave; --wait
-waits up to that long, at most 5m, when nothing is new. --open lists the questions
-still waiting for an answer, a snapshot. --json prints one item per line.
+only one workflow has. --after reads on from a cursor the last answer gave; --wait waits up to
+that long, at most 5m, when nothing is new. --open lists the questions still waiting for an
+answer, a snapshot. --json prints one item per line, and when it fails a refusal last whose code
+says why: usage, no-run, ambiguous, id, cursor, no-participant, unreachable, no-engine,
+other-engine or internal-error.
 
 Exits 0 on a read that worked, 1 when there is no such run, it has no participant, or the
 cursor is another's, 2 on a usage error, 3 when the run's files could not be read.

package/src/help/logs.txt

@@ -6,9 +6,11 @@ What a run did and is doing: its events and what its agents did, read from their
 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 long, up to 5m,
-such as 90s (a bare number, seconds, is deprecated); --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.
+such as 90s; --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.
+With --json, a failure prints a refusal whose code says why: usage, no-run, ambiguous, id,
+cursor, unreachable, no-engine, other-engine or internal-error. 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.

package/src/help/open.txt

@@ -0,0 +1,29 @@
+usage: awf open <run> <agent> [--no-fork] [--session <id>] [-p [<text>]]
+                [--cwd <directory>] [--run-root <directory>] [--json]
+
+A run is <workflow>/<id>, or an <id> only one workflow has, here or in a project awf knows.
+Without an agent, it prints the command that opens each of the run's agents.
+Opens a copy of an agent's latest session in its harness's own TUI, where the agent worked: its
+working directory, its home and skills, its sandbox, on the model and effort it ran on, with the
+harness's own permission prompts. The copy is made without asking the model, and is yours: the
+run and the agent's session are unchanged, and awf keeps no record of it.
+
+--no-fork opens the session itself: what you say stays with the agent, awf logs shows it, and the
+next attempt resumes it. It is refused while the run is live; while it is open, no attempt starts
+and an event waits, and once the harness exits a run with events is woken for it.
+--session opens another session in the agent's place: a copy an earlier awf open made, as it is;
+or one of the agent's earlier sessions, as its latest would be.
+-p asks one question headless and prints the answer; the text is its argument, or stdin without
+one. It runs as the agent's turns ran, without prompts, in its sandbox when it had one; on
+claude, billed per token headless, it is refused unless the agent ran metered.
+As the harness exits, awf prints the command that opens the same session again.
+
+With --json, -p prints {"v": 1, "session", "forkedFrom"?, "reply", "again"}, or a refusal whose
+code says why: usage, no-run, ambiguous, id, no-session, live, opened, unreachable, no-engine,
+other-engine or internal-error. no-session is an agent with no session or operation to open;
+live, --no-fork, or a sandboxed agent, on a running run, or a --no-fork whose session changed as
+it held the run; opened, a run another awf open --no-fork holds, or a sandbox another awf open
+has open; internal-error, a copy or a -p question that failed. A TUI has no JSON: --json without
+-p is a usage error. Exits with the TUI's exit code, or 0 once -p printed its answer; 1 when
+refused or failed; 2 on a usage error, or a -p or a TUI the agent's harness can't give; 3 when
+the run or the agent's place could not be read, or awf itself failed.

package/src/help/reply.txt

@@ -1,6 +1,5 @@
 usage: awf reply <run> <agent> [--to <id>] [--as <participant>] [<text>]
        awf send <run> <agent> [--as <participant>] [<text>]
-       awf send <run> --as <participant> --event-id <id> [--author <name>] [<text>]
 each takes [--cwd <directory>] [--run-root <directory>] [--json]
 
 A run is <workflow>/<id>, or an <id> only one workflow has, here or in a project awf knows.
@@ -8,11 +7,10 @@ Answers a question an agent asked a participant outside the run, or messages an
 over a route the workflow allowed. The text is the argument, or stdin without one. --to names
 the question, as awf inbox prints it; it may be left out when the agent has one open. --as
 names the participant when the workflow connects more than one. Neither waits for an answer:
-it comes back in awf inbox. send --event-id is deprecated: awf emit <run> <participant>:reply
-'{"text":…,"author":…}' --event-id <id> replaces it, and it forwards there. It still sends a
-message on a participant to the run's code, the id the message's own, and prints as awf emit
-does; it exits 0 for whatever the run did with it (accepted, duplicate, or refused by a run that
-returned); 1 when the run or participant isn't found, or its attempt didn't start.
+it comes back in awf inbox. A message on a participant to the run's code is sent with awf emit
+<run> <participant>:reply '{"text":…,"author":…}' --event-id <id>.
 
-Exits 0 when delivered, 1 when refused (the code says why), 2 on a usage error, 3 when the run
-could not be reached.
+With --json, each prints {"v": 3, "id": …} when delivered, or a refusal whose code says why: the
+participant's, or usage, no-run, ambiguous, id, unreachable, no-engine, other-engine or
+internal-error. Exits 0 when delivered, 1 when refused (the code says why), 2 on a usage error,
+3 when the run could not be reached.

package/src/help/run.txt

@@ -13,14 +13,20 @@ A new run with --from-stage starts there. A stage before it with no record to re
 value from --values, a JSON object by stage name, checked by its result; one that returns
 nothing is passed. Without one the attempt stops, naming the stage and its schema.
 A run is kept in .awf/runs/<workflow>/<id> under --cwd, unless --run-root names another folder
-for .awf/runs.
+for .awf/runs. A workflow that gives file: import.meta.path keeps its runs in its file's project
+unless --run-root names another folder: the nearest directory at or above the file holding .awf/,
+else the file's own, so --continue finds a run a program started there from anywhere.
 A run has no deadline unless --timeout gives it one, per attempt: a duration, a decimal and s, m,
 h or d, such as 20m or 1d.
 A workflow that knows how to present its result prints that; --json prints the full result instead.
-Either way the full result is kept as output.json in the run's folder, beside report.md
+Either way the full result is kept as out.json in the run's folder, beside report.md
 when the workflow writes one. A run that fails or is cancelled once its agents have started keeps
-output.json too, with what it spent and why it ended; --json prints it. A second Ctrl-C stops
-awf at once, without it.
+out.json too, with what it spent and why it ended; --json prints it. When no run comes of it,
+--json prints a refusal whose code says why: usage, file, prepare, no-id, id, no-run,
+other-args, not-started, unreachable, project, no-engine, other-engine or internal-error;
+--here takes no --json, nor does opening a run of a workflow with events, which prints no
+document. A second Ctrl-C stops awf at once, without it; a continue then reads
+what its agents spent.
 --cwd sets the directory the workflow and its agents work in; it defaults to the current one.
 --sandbox puts every agent of the run in one sandbox, working in --cwd; the file is a JSON spec
 such as {"read": ["/data/request.md"], "srt": {}}, naming srt or docker, whose relative paths are
@@ -31,10 +37,9 @@ panes; --no-watch leaves it out, and awf still prints the command that shows the
 default); origin, the one awf run was typed in; or any other word, the workspace with that label,
 found or made. --keep-panes says whether an agent's pane stays once it is done: never (the
 default), on-failure, when its last turn wasn't answered, or always. A kept pane's harness is left
-running, and yours. Both are kept with the run for every attempt, a woken one too, and win over a
-workflow's deprecated layout and keepPane. A run an event started has neither, and takes the
-defaults. A continue may give either again with the run's value, or its default where the run had
-none, and no other.
+running, and yours. Both are kept with the run for every attempt, a woken one too. A run an event
+started has neither, and takes the defaults. A continue may give either again with the run's
+value, or its default where the run had none, and no other.
 --here, run by an agent in a Herdr pane, starts the run in a new tab and has it take that agent's
 session over as one of its agents, from its next turn until the run ends. It prints a line for
 the agent to end its turn with, which is how the run finds the session.

package/src/help/runs.txt

@@ -7,5 +7,7 @@ number. A run is <workflow>/<id>, or an <id> only one
 workflow has. Runs are listed under --cwd's .awf/runs, or --run-root, as awf run keeps them; a
 run named is found there first, then in each project awf has started a run with events in.
 
---json prints one document, the interface for scripts. Exits 0 on any read that worked, 1 when
-there is no such run, 2 on a usage error, 3 when the run's files could not be read.
+--json prints one document, the interface for scripts: when it fails, a refusal whose code says
+why: usage, no-run, ambiguous, id, unreachable, no-engine, other-engine or internal-error. Exits
+0 on any read that worked, 1 when there is no such run, 2 on a usage error, 3 when the run's
+files could not be read.

package/src/help/tick.txt

@@ -5,8 +5,13 @@ Wakes every run of a workflow with events under --cwd's .awf/runs, or --run-root
 runs lists there, as an event would: continues a parked run whose wait's timer is due, and a
 crashed or failed one until it has failed three times in a row. Runs of other workflows are left
 as they are. --all wakes them in every project awf has started one in, as ~/.awf/projects lists
-them. Run it on any schedule; a run is continued once however many wakers come at once.
+them. A project's runs are woken by its own agentswf: one at another version than this awf runs
+its own awf tick for them. Run it on any schedule; a run is continued once however many wakers
+come at once.
 
-Prints a line for each run it woke, and nothing when it woke none. --json prints one document.
-Exits 0; 1 when a project is gone or a run could not be woken, the others still woken; 2 on a
-usage error.
+Prints a line for each run it woke, and nothing when it woke none, and one line on stderr
+counting runs with events it can't read, which it doesn't wake; --json prints one document,
+those runs under unreadable, on exit 1 too, or a refusal whose code says why it failed: usage or
+internal-error. Exits 0; 1 when a project is gone, declares agentswf without installing it, or
+its own agentswf failed, or a run could not be woken, the others still woken; 2 on a usage
+error.

package/src/herdr-placement.ts

@@ -2,46 +2,16 @@ import { createHash } from "node:crypto";
 import { mkdir, rename, rmdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { HERDR_VERSION, type RunProcess } from "@agentswf/harness";
-import { messageOf } from "./errors";
-import { ensureRunSession, parseSessions, type RunSessionDeps } from "./herdr-run-session";
+import { isCode } from "./files";
+import { parseSessions } from "./herdr-run-session";
 import { machinePaths } from "./machine";
 
-/** Where a layout may open a session awf does not otherwise use: one named `awf-…` it starts. */
-const OWN_SESSION = /^awf(-|$)/;
 const LOCK_POLL_MS = 100;
 /** Held inside a session's queue: a short wait, then made anyway. */
 const LOCK_WAIT_MS = 5_000;
 /** A lock older than this was left by a run that died holding it. */
 const LOCK_STALE_MS = 30_000;
 
-/**
- * Whether a session a layout names can be used: undefined when it can, else why not. One named
- * `awf-…` is started, swept and restarted as the run session is; any other must be running. Either
- * must answer, on the Herdr the adapter drives.
- */
-export async function namedSession(
-  name: string,
-  deps: RunSessionDeps,
-): Promise<string | undefined> {
-  if (OWN_SESSION.test(name)) {
-    try {
-      await ensureRunSession(name, deps);
-    } catch (error) {
-      return messageOf(error);
-    }
-  } else {
-    const listed = await deps.run({
-      argv: ["herdr", "session", "list", "--json"],
-      timeoutMs: 10_000,
-    });
-    const found = parseSessions(listed.stdout).find((session) => session.name === name);
-    if (!found?.running) {
-      return "it is not running, and awf starts only sessions named awf-…";
-    }
-  }
-  return wrongVersion(name, deps.run);
-}
-
 /** Why the session's server is not the Herdr the adapter drives; undefined when it is. */
 async function wrongVersion(session: string, run: RunProcess): Promise<string | undefined> {
   const status = await run({
@@ -154,7 +124,7 @@ export function workspaceLock(home: string) {
         await mkdir(lock);
         return () => rmdir(lock).catch(() => undefined);
       } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        if (!isCode(error, "EEXIST")) throw error;
       }
       const made = await stat(lock).then(
         (found) => found.mtimeMs,

package/src/herdr-run-session.ts

@@ -1,9 +1,9 @@
 import { spawn } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { link, mkdir, unlink, writeFile } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { RunProcess } from "@agentswf/harness";
 import { messageOf } from "./errors";
+import { linkNewText } from "./files";
 import {
   liveness,
   type MarkedPane,
@@ -53,7 +53,7 @@ const READY_POLL_MS = 200;
 const READY_WITHIN_MS = 10_000;
 
 /** Starts a server that outlives this process; settles once it has started, or could not. */
-export type StartServer = (
+type StartServer = (
   argv: readonly string[],
   options: { cwd: string; env: Record<string, string> },
 ) => Promise<void>;
@@ -87,7 +87,7 @@ export type RunSession = {
   kept?: KeptPane[];
 };
 
-export type KeptPane = { run: string; session: string; paneId: string };
+type KeptPane = { run: string; session: string; paneId: string };
 
 /** `AWF_HERDR_SESSION`, else `awf`; refused when Herdr could not use it as a session name. */
 export function runSessionName(environment: Readonly<Record<string, string | undefined>>): string {
@@ -431,15 +431,7 @@ export function serverEnvironment(
 async function quietConfig(home: string): Promise<string> {
   const file = join(machinePaths(home).herdr, "config.toml");
   await mkdir(dirname(file), { recursive: true });
-  const temporary = `${file}.${randomBytes(4).toString("hex")}.tmp`;
-  try {
-    await writeFile(temporary, QUIET_CONFIG, { flag: "wx" });
-    await link(temporary, file);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-  } finally {
-    await unlink(temporary).catch(() => undefined);
-  }
+  await linkNewText(file, QUIET_CONFIG);
   return file;
 }
 

package/src/herdr-workspace-marks.ts

@@ -1,10 +1,11 @@
 import { randomBytes } from "node:crypto";
-import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
+import { isCode, writeJson } from "./files";
 import { machinePaths } from "./machine";
 import { type ProcessProbe, processStart, sameProcess } from "./runs";
 
-export const WORKSPACE_MARK_VERSION = 2;
+const WORKSPACE_MARK_VERSION = 2;
 
 /**
  * A run's claim on its workspace in a shared Herdr session: the run's process, and when that
@@ -73,7 +74,7 @@ export async function markWorkspace(
   };
   try {
     await mkdir(dir, { recursive: true });
-    await writeWhole(file, mark);
+    await writeJson(file, mark);
   } catch {
     return unmarked;
   }
@@ -85,7 +86,7 @@ export async function markWorkspace(
   const write = (next: WorkspaceMark) => {
     if (released) return writing;
     current = next;
-    writing = writing.then(() => writeWhole(file, current).catch(() => undefined));
+    writing = writing.then(() => writeJson(file, current).catch(() => undefined));
     return writing;
   };
   return {
@@ -110,17 +111,6 @@ export async function markWorkspace(
   };
 }
 
-/** Renamed into place, so a reader never sees half a mark and skips a live run. */
-async function writeWhole(file: string, mark: WorkspaceMark): Promise<void> {
-  const temporary = `${file}.${randomBytes(4).toString("hex")}.tmp`;
-  try {
-    await writeFile(temporary, JSON.stringify(mark));
-    await rename(temporary, file);
-  } finally {
-    await rm(temporary, { force: true }).catch(() => undefined);
-  }
-}
-
 export async function readMarks(
   home: string,
   session: string,
@@ -163,7 +153,7 @@ export async function readAllMarks(
 
 /** Rewrites a mark read from `file`, as one sweep leaves it. */
 export function rewriteMark(file: string, mark: WorkspaceMark): Promise<void> {
-  return writeWhole(file, mark).catch(() => undefined);
+  return writeJson(file, mark).catch(() => undefined);
 }
 
 export function removeMark(file: string): Promise<void> {
@@ -189,6 +179,6 @@ function processExists(pid: number): boolean {
     process.kill(pid, 0);
     return true;
   } catch (error) {
-    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+    return !isCode(error, "ESRCH");
   }
 }