agentswf 0.1.0-beta.4 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the agents.wf authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,107 @@
 # agentswf
 
-agents.wf is an engine that runs workflows made of coding agents. This package gives you the
-`awf` command and `agentswf/workflow`, the module a workflow imports.
+**Write workflows for coding agents in TypeScript.** Hand work to the coding agents you already
+use, run them side by side, have one check another, loop until a reviewer is happy, and get typed
+answers back. `awf` runs the workflow and handles the parts that make agent scripts fragile:
+agents that never answer, answer in prose, hang, or quietly run up a bill.
 
-> **Beta.** Interfaces will change between versions.
+```ts
+const reviewer = await wf.agents.open({ key: "reviewer", runtime: { harness: "codex", model: "gpt-6-luna" } });
+const { outcome } = await reviewer.run({ prompt: "Review `git diff main`.", schema: FINDINGS });
+if (outcome.answered) console.log(outcome.value.findings); // validated against FINDINGS, or a reason why not
+```
+
+> **Shaped by use.** agents.wf is in its evaluation phase, and what people build with it decides
+> where the design goes next. Found a bug, missing a use case, or have an idea?
+> [Open an issue](https://github.com/romanlv/agentswf/issues).
+
+## How it works
+
+1. Your code calls `agent.run({ prompt, schema })`.
+2. awf hands the prompt to a coding agent, in a [Herdr](https://herdr.dev) pane you can watch or
+   headless.
+3. The agent works in your repo with its own tools and skills, then answers by running
+   `wfa result`.
+4. awf checks the answer against your schema. A wrong shape goes back to the agent to fix; a quiet
+   agent gets a nudge.
+5. `await` returns a typed value, and your code decides what happens next.
+
+It drives the agent CLIs you already use, logged in as you already are: claude, codex, pi or
+cursor. Control flow is plain TypeScript: `for`, `if`, `Promise.all`.
+
+## What you get
+
+- **Typed answers, checked.** A turn ends `answered`, with JSON that fits its schema, or with a
+  reason: `unanswered`, `blocked`, `timed-out`, `failed` or `cancelled`.
+- **Mix harnesses and models.** A codex reviewer checks a claude implementer; a cheap model
+  triages before an expensive one works.
+- **Long-lived sessions.** An agent keeps its context from turn to turn; `compact` and `fork` it.
+- **Stages you can continue.** A run that stops part-way goes on from the stage that stopped.
+- **Cost on every run.** Time, tokens and an estimated cost per agent, stage and model.
+- **Sandboxes, messaging, events.** docker or srt limits what agents reach, agents message each
+  other on routes you grant, and a run can wait for an event for weeks without a process running.
+- **Free tests.** `agentswf/testing` runs a workflow on scripted agents; no agent starts.
+
+## Install
+
+You need [Bun](https://bun.sh) 1.4 or later, git, and at least one agent CLI you're logged in to.
 
 ```sh
-bun add -g agentswf@beta
-awf run ./review.ts
+bun add -g agentswf   # puts awf in ~/.bun/bin
+awf --version
 ```
 
-It runs on Bun only. The README in the repository says what to install first and how to write a
-workflow: [github.com/romanlv/agentswf](https://github.com/romanlv/agentswf).
+## Your first workflow
+
+```sh
+mkdir ~/workflows && cd ~/workflows
+awf init                    # a hello workflow, its test, and the config files
+awf test                    # its test, on scripted agents
+awf run hello/workflow.ts   # one real agent
+```
+
+```ts
+// hello/workflow.ts
+import { typed } from "agentswf/typebox";
+import { defineWorkflow } from "agentswf/workflow";
+import Type from "typebox";
+
+export const ANSWER = typed(Type.Object({ answer: Type.Integer() }, { additionalProperties: false }));
+
+export default defineWorkflow({
+  meta: { name: "hello", description: "Ask one agent a question with a known answer." },
+  async run(wf) {
+    const agent = await wf.agents.open({
+      key: "hello",
+      runtime: { harness: "codex", model: "gpt-6-luna", placement: "headless" },
+    });
+    const { outcome } = await agent.run({
+      prompt: "What is 17 multiplied by 23? Work it out yourself; do not run any code.",
+      schema: ANSWER,
+      timeout: "3m",
+    });
+    return outcome.answered ? outcome.value : { unanswered: outcome.reason };
+  },
+});
+```
+
+`awf run` prints a line on time, tokens and estimated cost, then the run's record as JSON, its
+`value` `{ "answer": 391 }`; a workflow's `present` prints something shorter instead. The record
+stays in `.awf/runs/hello/{id}`; `awf runs` and `awf logs` show what it did.
+
+## What this package gives you
+
+| Entry | For |
+| --- | --- |
+| `awf` | the command: run, test, follow and continue workflows |
+| `agentswf/workflow` | what a workflow imports: `defineWorkflow`, the `wf` context |
+| `agentswf/typebox` | `typed`, to turn a TypeBox schema into an answer schema |
+| `agentswf/testing` | run a workflow on scripted agents in its tests |
+| `agentswf/client` | drive runs from your own program |
+
+## Learn more
+
+- [Guide](https://agents.wf/guide/) and [quick start](https://agents.wf/guide/quick-start)
+- [Workflow API](https://agents.wf/reference/workflow-api), every call on one page
+- [Patterns](https://agents.wf/patterns/review-loop): review loops, plan and implement
+- [Examples and design](https://github.com/romanlv/agentswf), in the repository

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentswf",
-  "version": "0.1.0-beta.4",
-  "description": "agents.wf: an engine that runs workflows made of coding agents. Gives you awf, agentswf/workflow and agentswf/testing",
+  "version": "0.1.0",
+  "description": "agents.wf: an engine that runs workflows made of coding agents. Gives you awf, agentswf/workflow, agentswf/typebox, agentswf/testing and agentswf/client",
   "license": "MIT",
   "homepage": "https://agents.wf",
   "repository": {
@@ -18,15 +18,23 @@
   },
   "exports": {
     "./workflow": "./src/workflow.ts",
-    "./testing": "./src/testing.ts"
+    "./testing": "./src/testing.ts",
+    "./typebox": "./src/typebox.ts",
+    "./client": "./src/client.ts"
   },
   "files": [
     "src",
-    "README.md"
+    "!src/**/*.test.ts",
+    "!src/**/*.eval.ts",
+    "!src/**/*.typecheck.ts",
+    "!src/**/*.fixture.ts",
+    "!src/**/fixtures",
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
-    "@agentswf/contract": "0.1.0-beta.4",
-    "@agentswf/engine": "0.1.0-beta.4"
+    "@agentswf/contract": "0.1.0",
+    "@agentswf/engine": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/awf.ts

@@ -1,4 +1,9 @@
 #!/usr/bin/env -S bun --no-env-file
-import { main } from "@agentswf/engine/cli";
+import { dirname } from "node:path";
+import { handOver } from "@agentswf/engine/hand-over";
+import manifest from "../package.json" with { type: "json" };
 
+// Before the engine loads: a project at another version runs on its own (ADR 0015).
+await handOver({ dir: dirname(import.meta.dir), version: manifest.version });
+const { main } = await import("@agentswf/engine/cli");
 await main();

package/src/client.ts

@@ -0,0 +1,2 @@
+// A program's way to a workflow's runs: the types live in the contract, `client` in the engine.
+export * from "@agentswf/engine/client";

package/src/testing.ts

@@ -1 +1,2 @@
+// The curated list is the engine's workflow-testing/index.ts, which `awf test` serves too.
 export * from "@agentswf/engine/workflow-testing";

package/src/typebox.ts

@@ -0,0 +1 @@
+export * from "@agentswf/engine/typebox";

package/src/workflow.ts

@@ -1 +1,2 @@
-export * from "@agentswf/contract/workflow";
+// The list lives in the contract, which the engine also serves it from to the workflows it loads.
+export * from "@agentswf/contract/author";