@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/decisions/directory.ts

@@ -1,7 +1,11 @@
 import { createHash } from "node:crypto";
-import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import type { DecisionArtifact, Money, SettledDecision } from "@agentswf/contract/records";
+import {
+  type DecisionArtifact,
+  type Money,
+  OP_FILE_VERSIONS,
+  type SettledDecision,
+} from "@agentswf/contract/records";
 import {
   type AbsoluteDeadline,
   type Answers,
@@ -16,6 +20,8 @@ import {
 import { canonical } from "../canonical-json";
 import { abortableSleep, assertDeadline, boundedDeadline, scheduleAt } from "../deadlines";
 import { messageOf } from "../errors";
+import { writeJson } from "../files";
+import { decisionArtifact, type OpIds } from "../ops";
 import type { RunEventBody } from "../run-event-log";
 import {
   type DecisionInstallation,
@@ -35,8 +41,6 @@ export type DecisionScope = {
   add?(cancel: (reason: string) => Promise<unknown>): () => void;
   /** The workflow stage it is asked in. */
   stage?: string;
-  /** The spec gave a deprecated form of `timeout`. */
-  deprecated?(name: "timeout-ms" | "deadline-option", call: string): void;
 };
 
 type PreparedCall = {
@@ -66,6 +70,8 @@ export class RunDecisions {
     private readonly options: {
       installation?: DecisionInstallation;
       runDir: string;
+      /** Numbers each asking, `{key}.{n}`, and keeps the keys apart from agents'. */
+      ops: OpIds;
       sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
       /** Writes the run's event log. */
       event?(body: RunEventBody): void;
@@ -129,24 +135,12 @@ export class RunDecisions {
       ? installed.providers[resolved.provider]
       : undefined;
     if (!provider) throw new Error(`decision provider "${resolved.provider}" is not installed`);
-    const deadline = boundedDeadline(
-      { timeout: spec.timeout, deadline: spec.deadline },
-      scope.deadline,
-      (name, call) => scope.deprecated?.(name, call),
-      "on decide",
-    );
+    const deadline = boundedDeadline(spec.timeout, scope.deadline);
     assertDeadline(deadline);
+    // Last: a decision refused for anything else holds no key.
+    this.options.ops.claim(spec.key, "decision");
     const slot = this.#slots.length;
     this.#slots.push(undefined);
-    this.options.event?.({
-      kind: "decision-asked",
-      decision: slot + 1,
-      ...(scope.stage === undefined ? {} : { stage: scope.stage }),
-      key: spec.key,
-      alias: spec.model,
-      provider: resolved.provider,
-      model: resolved.model,
-    });
     return { spec, ids, resolved, provider, deadline, slot };
   }
 
@@ -155,6 +149,12 @@ export class RunDecisions {
     scope: DecisionScope,
   ): Promise<{ answers: Record<string, unknown>; record: DecisionRecord }> {
     const { spec, ids, resolved, provider, deadline, slot } = call;
+    const { runDir, ops } = this.options;
+    // Its folder and op.json are written as its id is drawn, before any line names it.
+    const { id: operation, lost: opLost } = ops.draw(spec.key, {
+      kind: "decision",
+      ...(scope.stage === undefined ? {} : { stage: scope.stage }),
+    });
     const startedAt = new Date().toISOString();
     const controller = new AbortController();
     let ending: Ending | undefined;
@@ -168,17 +168,27 @@ export class RunDecisions {
       : () => undefined;
     this.#cancellers.add(cancel);
     const removeFromScope = scope.add?.(async (reason) => cancel(reason));
+    this.options.event?.({
+      kind: "decision-asked",
+      decision: slot + 1,
+      operation,
+      ...(scope.stage === undefined ? {} : { stage: scope.stage }),
+      key: spec.key,
+      alias: spec.model,
+      provider: resolved.provider,
+      model: resolved.model,
+    });
 
     let attempts = 0;
     let tokens: { input: number; output: number } | undefined;
-    let charged: Money[] = [];
+    let reportedCosts: Money[] = [];
     let requestId: string | undefined;
     let response: ProviderResponse | undefined;
     let answers: Record<string, unknown> | undefined;
     let error: string | undefined;
     const count = (spent: {
       tokens?: ProviderResponse["tokens"];
-      charged?: Money;
+      reportedCost?: Money;
       requestId?: string;
     }) => {
       if (spent.tokens) {
@@ -187,7 +197,7 @@ export class RunDecisions {
           output: (tokens?.output ?? 0) + spent.tokens.output,
         };
       }
-      if (spent.charged) charged = [...charged, spent.charged];
+      if (spent.reportedCost) reportedCosts = [...reportedCosts, spent.reportedCost];
       if (spent.requestId) requestId = spent.requestId;
     };
     const request = {
@@ -230,7 +240,7 @@ export class RunDecisions {
       this.#cancellers.delete(cancel);
     }
 
-    const artifact = join("decisions", `${slot + 1}.json`);
+    const artifact = decisionArtifact(operation);
     const outcome: DecisionRecord["outcome"] = ending
       ? ending.outcome
       : answers
@@ -261,19 +271,21 @@ export class RunDecisions {
       ...(requestId ? { requestId } : {}),
       artifact,
     };
-    const total = sumMoney(charged);
-    let settled: SettledDecision = { ...record, ...(total ? { charged: total } : {}) };
+    const total = sumMoney(reportedCosts);
+    let settled: SettledDecision = { ...record, ...(total ? { reportedCost: total } : {}) };
     const written: DecisionArtifact = {
+      version: OP_FILE_VERSIONS.decision,
       record: settled,
       request: { state: spec.state, questions: spec.questions },
       ...(answers ? { answers: answers as JsonObject } : {}),
     };
-    try {
-      await mkdir(join(this.options.runDir, "decisions"), { recursive: true });
-      await writeFile(join(this.options.runDir, artifact), `${JSON.stringify(written, null, 2)}\n`);
-    } catch (thrown) {
-      const lost = `artifact not written: ${messageOf(thrown)}`;
-      // Without its artifact an answer cannot be fitted again, so it does not count as one; any
+    const artifactLost = await writeJson(join(runDir, artifact), written).then(
+      () => undefined,
+      (thrown: unknown) => `artifact not written: ${messageOf(thrown)}`,
+    );
+    if (opLost !== undefined || artifactLost !== undefined) {
+      const lost = [opLost, artifactLost].filter((each) => each !== undefined).join("; ");
+      // Without its records an answer cannot be fitted again, so it does not count as one; any
       // other outcome stands.
       settled =
         settled.outcome === "answered"
@@ -284,11 +296,12 @@ export class RunDecisions {
     this.options.event?.({
       kind: "decision-ended",
       decision: slot + 1,
+      operation,
       ...(settled.stage === undefined ? {} : { stage: settled.stage }),
       outcome: settled.outcome,
       ...(settled.error === undefined ? {} : { error: settled.error }),
     });
-    const { charged: _charged, ...returned } = settled;
+    const { reportedCost: _reportedCost, ...returned } = settled;
 
     if (returned.outcome === "answered") return { answers: answers!, record: returned };
     if (returned.outcome === "timed-out") throw new DeadlineExceededError(deadline!);
@@ -406,11 +419,11 @@ function isProbability(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
 }
 
-/** Charges in more than one currency cannot be added without converting, so their sum is unknown. */
-function sumMoney(charges: readonly Money[]): Money | undefined {
-  const currency = charges[0]?.currency;
-  if (!currency || charges.some((charge) => charge.currency !== currency)) return undefined;
-  return { amount: charges.reduce((sum, charge) => sum + charge.amount, 0), currency };
+/** Costs in more than one currency cannot be added without converting, so their sum is unknown. */
+function sumMoney(costs: readonly Money[]): Money | undefined {
+  const currency = costs[0]?.currency;
+  if (!currency || costs.some((cost) => cost.currency !== currency)) return undefined;
+  return { amount: costs.reduce((sum, cost) => sum + cost.amount, 0), currency };
 }
 
 function untilAborted<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {

package/src/decisions/fake.ts

@@ -36,7 +36,7 @@ export function confidentResponse(request: ProviderRequest): ProviderResponse {
     snapshot: `${request.model}-20260926`,
     answers,
     tokens: { input: 1_000, output: 10 },
-    charged: { amount: 0.000042, currency: "USD" },
+    reportedCost: { amount: 0.000042, currency: "USD" },
     requestId: `request-${Object.keys(request.questions).join("-")}`,
   };
 }

package/src/decisions/openrouter.ts

@@ -130,7 +130,7 @@ function levelsOf(question: Question, probabilities: Record<string, unknown>): n
 }
 
 /** What a body says was spent, as far as it says: tokens only when both counts are reported. */
-function spendOf(body: unknown): Pick<ProviderResponse, "tokens" | "charged" | "requestId"> {
+function spendOf(body: unknown): Pick<ProviderResponse, "tokens" | "reportedCost" | "requestId"> {
   if (!isRecord(body)) return {};
   const usage = isRecord(body.usage) ? body.usage : {};
   const counted = typeof usage.input_tokens === "number" && typeof usage.output_tokens === "number";
@@ -138,7 +138,9 @@ function spendOf(body: unknown): Pick<ProviderResponse, "tokens" | "charged" | "
     ...(counted
       ? { tokens: { input: usage.input_tokens as number, output: usage.output_tokens as number } }
       : {}),
-    ...(typeof usage.cost === "number" ? { charged: { amount: usage.cost, currency: "USD" } } : {}),
+    ...(typeof usage.cost === "number"
+      ? { reportedCost: { amount: usage.cost, currency: "USD" } }
+      : {}),
     ...(typeof body.id === "string" ? { requestId: body.id } : {}),
   };
 }

package/src/decisions/seam.ts

@@ -24,7 +24,7 @@ export type ProviderResponse = {
   answers: Record<string, ProviderAnswer>;
   /** Absent when the provider did not report them: unknown, not zero. */
   tokens?: { input: number; output: number };
-  charged?: Money;
+  reportedCost?: Money;
   requestId?: string;
 };
 
@@ -40,7 +40,7 @@ export interface DecisionProvider {
 export class DecisionProviderError extends Error {
   readonly retryable: boolean;
   readonly tokens?: { input: number; output: number };
-  readonly charged?: Money;
+  readonly reportedCost?: Money;
   readonly requestId?: string;
 
   constructor(
@@ -48,7 +48,7 @@ export class DecisionProviderError extends Error {
     options: {
       retryable: boolean;
       tokens?: { input: number; output: number };
-      charged?: Money;
+      reportedCost?: Money;
       requestId?: string;
     },
   ) {
@@ -56,7 +56,7 @@ export class DecisionProviderError extends Error {
     this.name = "DecisionProviderError";
     this.retryable = options.retryable;
     if (options.tokens) this.tokens = options.tokens;
-    if (options.charged) this.charged = options.charged;
+    if (options.reportedCost) this.reportedCost = options.reportedCost;
     if (options.requestId) this.requestId = options.requestId;
   }
 }

package/src/display-path.ts

@@ -1,4 +1,5 @@
-import { isAbsolute, relative, resolve } from "node:path";
+import { relative, resolve } from "node:path";
+import { isInside } from "./files";
 
 /**
  * `path` as typed from `cwd`: relative under it, absolute elsewhere, so it works from anywhere; with
@@ -7,8 +8,7 @@ import { isAbsolute, relative, resolve } from "node:path";
  */
 export function pathFrom(cwd: string, path: string, options: { home?: string } = {}): string {
   const absolute = resolve(cwd, path);
-  const inside = relative(cwd, absolute);
-  if (inside && !inside.startsWith("..") && !isAbsolute(inside)) return inside;
+  if (isInside(cwd, absolute)) return relative(cwd, absolute);
   const { home } = options;
   return home !== undefined && absolute.startsWith(`${home}/`)
     ? `~${absolute.slice(home.length)}`

package/src/duration.ts

@@ -1,55 +1,41 @@
-import { durationMilliseconds, positiveDurationMilliseconds } from "@agentswf/contract/workflow";
-import { deprecationLine } from "./deprecations";
+import {
+  durationMilliseconds,
+  positiveDurationMilliseconds,
+  secondsForMilliseconds,
+} from "@agentswf/contract/workflow";
 import { messageOf } from "./errors";
 
 /**
  * A flag's duration in milliseconds, longer than none: the one grammar, `"90s"`, `"1.5h"`, `"1d"`.
- * A whole number of `ms`, which the CLI took before, is read until 0.1.0 and `deprecated` told.
+ * A number of `ms`, which the CLI took before 0.1.0-beta.6, is refused with its replacement.
  */
-export function parseDuration(
-  value: string,
-  flag: string,
-  deprecated: (line: string) => void,
-): number {
-  const ms = /^(\d+)ms$/.exec(value);
-  if (!ms) return positiveDurationMilliseconds(value, flag);
-  const milliseconds = Number(ms[1]);
-  if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0)
-    throw new Error(`${flag} is a positive duration: not ${value}`);
-  deprecated(deprecationLine("duration-ms", value));
-  return milliseconds;
+export function parseDuration(value: string, flag: string): number {
+  const seconds = secondsForMilliseconds(value);
+  if (seconds === undefined) return positiveDurationMilliseconds(value, flag);
+  throw new Error(
+    `${flag} is a duration, a decimal and s, m, h or d: give ${seconds}, not ${value}`,
+  );
 }
 
 /**
  * `--wait`, in seconds from none to `maxSeconds`: a duration, `"90s"`. A bare number of seconds,
- * which it took before, is read until 0.1.0 and `deprecated` told.
+ * which it took before 0.1.0-beta.6, is refused with its replacement.
  */
-export function parseWait(
-  value: string,
-  maxSeconds: number,
-  deprecated: (line: string) => void,
-): number {
-  const bare = /^\d+(\.\d+)?$/.test(value);
+export function parseWait(value: string, maxSeconds: number): number {
+  if (/^\d+(\.\d+)?$/.test(value))
+    throw new Error(
+      `--wait takes a duration up to ${maxSeconds}s: give --wait ${Math.min(Number(value), maxSeconds)}s`,
+    );
   let seconds: number;
   try {
-    seconds = bare ? Number(value) : durationMilliseconds(value) / 1000;
+    seconds = durationMilliseconds(value) / 1000;
   } catch (error) {
     throw new Error(`--wait takes a duration up to ${maxSeconds}s: ${messageOf(error)}`);
   }
   if (seconds > maxSeconds) throw new Error(`--wait takes a duration up to ${maxSeconds}s`);
-  if (bare) deprecated(deprecationLine("wait-seconds", value));
   return seconds;
 }
 
-/** `45s`, `6m40s`, `1h02m`. */
-export function formatDuration(milliseconds: number): string {
-  const seconds = Math.max(0, Math.round(milliseconds / 1000));
-  if (seconds < 60) return `${seconds}s`;
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
-  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
-}
-
 /**
  * When a timer given `when` is due, epoch ms, from `now`, and `when` as its record keeps it: a
  * `Duration` as given, or a `Date` as an ISO time. A workflow's grammar, apart from the CLI's

package/src/emit-command.ts

@@ -1,16 +1,20 @@
 import type { EmitResultJson } from "@agentswf/contract/records";
 import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
+import { type Out, parsePlace, type ReadPlace } from "./command-line";
 import { EmitError, emitEvent, emitToRun } from "./emit";
 import { messageOf } from "./errors";
 import help from "./help/emit.txt" with { type: "text" };
-import { type Out, parsePlace, type ReadPlace } from "./run-commands";
+import { asksJson, printRefusal, readFailureCode } from "./refusals";
 import { findRunByRef } from "./run-state";
-import type { Launch } from "./wake";
+import type { Launch, Woken } from "./wake";
 import { loadWorkflowFile } from "./workflow-loader";
 
+/** `awf emit --json`'s `"v"`, which its refusals carry too. */
+export const EMIT_V = 1 satisfies EmitResultJson["v"];
+
 export const emitUsage = help.trimEnd();
 
-type Event = { name: string; data: JsonValue; id?: string };
+type Event = { name: string; data: JsonValue; id?: string; source?: string };
 
 /** `--target {file} --id {id}`, which may start the run; or a run that is there, by its ref. */
 type Parsed = Event & { json: boolean } & (
@@ -28,21 +32,19 @@ export async function emitCommand(
     launch?: Launch;
   },
 ): Promise<number> {
-  if (argv.includes("-h") || argv.includes("--help")) {
-    out.stdout(emitUsage);
-    return 0;
-  }
   let parsed: Parsed;
   try {
     parsed = parse(argv, shellCwd);
   } catch (error) {
-    out.stderr(`awf: ${messageOf(error)}\n\n${emitUsage}`);
+    printRefusal(out, { json: asksJson(argv), v: EMIT_V }, error, "usage", emitUsage);
     return 2;
   }
+  const json = { json: parsed.json, v: EMIT_V };
   const event = {
     name: parsed.name,
     data: parsed.data,
     ...(parsed.id === undefined ? {} : { id: parsed.id }),
+    ...(parsed.source === undefined ? {} : { source: parsed.source }),
   };
   let result: EmitResultJson;
   try {
@@ -50,9 +52,9 @@ export async function emitCommand(
       const status = await findRunByRef(parsed.ref, parsed.place, context.home);
       result = await emitToRun(status, event, context);
     } else {
-      const loaded = await loadWorkflowFile(parsed.target, shellCwd);
+      const loaded = await loadWorkflowFile(parsed.target, shellCwd, context.home);
       if (!isEventWorkflow(loaded.workflow)) {
-        out.stderr(`awf: ${loaded.file} declares no events; awf run starts it`);
+        printRefusal(out, json, `${loaded.file} declares no events; awf run starts it`, "event");
         return 2;
       }
       result = await emitEvent(
@@ -62,24 +64,29 @@ export async function emitCommand(
       );
     }
   } catch (error) {
-    out.stderr(`awf: ${messageOf(error)}`);
+    printRefusal(out, json, error, readFailureCode(error));
     return error instanceof EmitError ? 2 : 1;
   }
   return printEmit(result, parsed.json, out);
 }
 
-/** Prints an emit's result, as `awf emit` and `awf send` do: 1 when the run's attempt didn't start. */
-export function printEmit(result: EmitResultJson, json: boolean, out: Out): number {
-  out.stdout(json ? JSON.stringify(result) : emitLine(result));
-  if (result.why !== "launch-failed") return 0;
-  out.stderr(`awf: the run's attempt did not start: ${result.error}`);
-  return 1;
+/** Prints an emit's result, `accepted dd-case/kombo: started`: 1 when the run's attempt didn't start. */
+function printEmit(result: EmitResultJson, json: boolean, out: Out): number {
+  out.stdout(json ? JSON.stringify(result) : `${result.outcome} ${result.ref}${didOf(result)}`);
+  return launchExit(result, out);
 }
 
-/** `accepted dd-case/kombo: started`. */
-function emitLine(result: EmitResultJson): string {
-  const did = result.did === "none" ? result.why : result.did;
-  return `${result.outcome} ${result.ref}${did === undefined ? "" : `: ${did}`}`;
+/** What waking a run did, `: started`, or why it did nothing; empty when neither is said. */
+export function didOf(woken: Pick<Woken, "did" | "why">): string {
+  const did = woken.did === "none" ? woken.why : woken.did;
+  return did === undefined ? "" : `: ${did}`;
+}
+
+/** 0; or 1, said on stderr, when the run's attempt did not start. */
+export function launchExit(woken: Pick<Woken, "why" | "error">, out: Out): number {
+  if (woken.why !== "launch-failed") return 0;
+  out.stderr(`awf: the run's attempt did not start: ${woken.error}`);
+  return 1;
 }
 
 function parse(argv: readonly string[], shellCwd: string): Parsed {
@@ -87,6 +94,7 @@ function parse(argv: readonly string[], shellCwd: string): Parsed {
   let target: string | undefined;
   let run: string | undefined;
   let id: string | undefined;
+  let source: string | undefined;
   const words: string[] = [];
   for (let i = 0; i < rest.length; i++) {
     const word = rest[i]!;
@@ -98,6 +106,7 @@ function parse(argv: readonly string[], shellCwd: string): Parsed {
     if (word === "--target") target = value();
     else if (word === "--id") run = value();
     else if (word === "--event-id") id = value();
+    else if (word === "--source") source = value();
     else if (word.startsWith("--")) throw new Error(`unknown option ${word}`);
     else words.push(word);
   }
@@ -129,5 +138,12 @@ function parse(argv: readonly string[], shellCwd: string): Parsed {
       throw new Error(`the event's data is not JSON: ${messageOf(error)}`);
     }
   }
-  return { ...form, name, data, ...(id === undefined ? {} : { id }), json };
+  return {
+    ...form,
+    name,
+    data,
+    ...(id === undefined ? {} : { id }),
+    ...(source === undefined ? {} : { source }),
+    json,
+  };
 }