@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/stage-plan.ts

@@ -1,186 +0,0 @@
-import type {
-  AttemptRecord,
-  AttemptStage,
-  StageNeed,
-  StageRecord,
-} from "@agentswf/contract/records";
-import { type JsonSchema, type SchemaError, validate } from "@agentswf/contract/schema";
-import type { JsonValue } from "@agentswf/contract/workflow";
-
-/**
- * What a continue does with a stage it enters: until its start point, each is reused from its
- * record, provided, or stops the attempt; from the start point on, every stage runs. The start
- * point is `--from-stage`, or else the first stage entered with no succeeded record. Before a
- * `--from-stage`, a stage whose record can't be reused takes its value from `--values`, one that
- * returns nothing is passed, and one with nothing recorded needs a value. Pure: the records, the values, the result and the version come
- * in, a decision goes out.
- */
-type StagePlanDecision =
-  | { kind: "reuse"; record: StageRecord; value: JsonValue | undefined }
-  /** A value given, checked by the stage's result; undefined for a stage that returns nothing. */
-  | { kind: "provide"; value: JsonValue | undefined }
-  /** `start` on the stage that is the start point, when the records it outdates are moved. */
-  | { kind: "run"; start: boolean }
-  | { kind: "stop"; reason: string }
-  /** Nothing recorded, and no value given that fits: `--values` lets the attempt go on. */
-  | { kind: "need"; reason: string; need: StageNeed };
-
-export type StagePlanState = {
-  records: ReadonlyMap<string, StageRecord>;
-  fromStage?: string;
-  /** `--values`: each stage's value, to start at `fromStage`. */
-  values?: ReadonlyMap<string, JsonValue>;
-  /** The workflow's `meta.version` now. */
-  workflowVersion?: string;
-  /** Whether this attempt has reached its start point. */
-  started: boolean;
-  /** The stages this attempt has entered so far. */
-  entered: readonly string[];
-};
-
-/**
- * Decides a stage entered, given its `result` as JSON Schema, absent for a stage that returns
- * nothing. A stop's reason says why; the command that goes on names the stage to redo.
- */
-export function planStage(
-  state: StagePlanState,
-  stage: string,
-  result: JsonSchema | undefined,
-): StagePlanDecision {
-  if (state.started) return { kind: "run", start: false };
-  if (stage === state.fromStage) return { kind: "run", start: true };
-  const record = state.records.get(stage);
-  const succeeded = record?.outcome === "succeeded" ? record : undefined;
-  const stale = succeeded && unreusable(state, succeeded, result);
-  if (succeeded && stale === undefined) {
-    return { kind: "reuse", record: succeeded, value: succeeded.value };
-  }
-  if (state.fromStage === undefined) {
-    return stale === undefined ? { kind: "run", start: true } : { kind: "stop", reason: stale };
-  }
-  // A record there that failed or went stale is redone from its stage, as on any continue, unless
-  // a value given replaces it.
-  const redo = record && {
-    kind: "stop" as const,
-    reason: stale ?? `${stage} did not succeed in attempt ${record.attempt}`,
-  };
-  if (result === undefined) return redo ?? { kind: "provide", value: undefined };
-  const need = { stage, schema: result };
-  const given = state.values?.get(stage);
-  if (given !== undefined) {
-    const errors = validate(result, given);
-    if (errors.length === 0) return { kind: "provide", value: given };
-    const misfit = problems(`${stage}'s value in --values does not fit its result:`, errors);
-    return redo ? { kind: "stop", reason: misfit } : { kind: "need", reason: misfit, need };
-  }
-  return (
-    redo ?? {
-      kind: "need",
-      reason: `nothing recorded for ${stage}${unreached(state, stage)}`,
-      need,
-    }
-  );
-}
-
-/**
- * Why a succeeded record can't be reused, as a stop says it, or undefined when it can: another
- * major version recorded it, or its value no longer fits the stage's `result`.
- */
-function unreusable(
-  state: StagePlanState,
-  record: StageRecord,
-  result: JsonSchema | undefined,
-): string | undefined {
-  const { stage } = record;
-  const recorded = majorOf(record.workflowVersion);
-  const now = majorOf(state.workflowVersion);
-  if (recorded !== undefined && now !== undefined && recorded !== now) {
-    return `${stage} was recorded by ${record.workflowVersion}; this is ${state.workflowVersion}`;
-  }
-  return misfitOf(record, result);
-}
-
-/** Why a succeeded record's value no longer fits the stage's `result`; undefined when it does. */
-function misfitOf(record: StageRecord, result: JsonSchema | undefined): string | undefined {
-  const { stage } = record;
-  if (result === undefined) {
-    return record.value === undefined
-      ? undefined
-      : `${stage}'s record holds a value, and the stage no longer has a result`;
-  }
-  if (record.value === undefined) {
-    return `${stage}'s record holds no value, and the stage's result now expects one`;
-  }
-  const errors = validate(result, record.value);
-  return errors.length === 0
-    ? undefined
-    : problems(`${stage}'s record no longer fits its result schema:`, errors);
-}
-
-/** A value's problems under what they are problems of, a line each. */
-function problems(heading: string, errors: readonly SchemaError[]): string {
-  return [heading, ...errors.map((error) => `  ${error.path}: ${error.message}`)].join("\n");
-}
-
-/** Recorded stages this attempt hasn't reached, which a rename in the code would leave behind. */
-function unreached(state: StagePlanState, stage: string): string {
-  const others = [...state.records.keys()].filter(
-    (name) => name !== stage && name !== state.fromStage && !state.entered.includes(name),
-  );
-  return others.length > 0 ? ` (recorded and not reached: ${others.join(", ")})` : "";
-}
-
-/** What must match for a record to be reused: the major, or `0.{minor}`, as semver has it. */
-function majorOf(version: string | undefined): string | undefined {
-  if (version === undefined) return undefined;
-  const [major, minor] = version.split(".");
-  return major === "0" ? `0.${minor}` : major;
-}
-
-/**
- * In a run of a workflow with `events`, a stage runs once ever: a succeeded record is reused
- * wherever and however often its name is entered, whatever version of the code recorded it, as
- * long as its value still fits the stage's `result`. One that doesn't fit stops the attempt; a
- * failed record, or none, runs.
- */
-export function planStageByContent(
-  record: StageRecord | undefined,
-  result: JsonSchema | undefined,
-): Extract<StagePlanDecision, { kind: "reuse" | "stop" }> | { kind: "run" } {
-  if (record?.outcome !== "succeeded") return { kind: "run" };
-  const misfit = misfitOf(record, result);
-  return misfit === undefined
-    ? { kind: "reuse", record, value: record.value }
-    : { kind: "stop", reason: misfit };
-}
-
-/**
- * A `--from-stage {stage}` that attempt `attempt` redid, in a run of a workflow with `events`. In
- * that attempt and every later one, a stage first entered after `stage` whose record an earlier
- * attempt than `attempt` wrote runs again, its record replaced: it was made against the stage
- * before the redo. A record never entered after the stage keeps its reuse.
- */
-export type StageRedo = { stage: string; attempt: number };
-
-/**
- * The last `--from-stage` an earlier attempt of a run with `events` redid: the latest attempt with
- * one that ran its stage. Its attempt record says so in `stages`, which a stop for a stage never
- * reached, a refusal and a crash leave without it; a crash after the stage's new record was written
- * leaves that record, the attempt's own. A redo whose stage failed and ran again on a wake is still
- * the redo. Only attempt and stage records are read, which a continue may read.
- */
-export function lastRedo(
-  attempts: readonly (Pick<AttemptRecord, "attempt" | "flags"> & {
-    stages?: readonly Pick<AttemptStage, "stage" | "source">[];
-  })[],
-  records: ReadonlyMap<string, StageRecord>,
-  before: number,
-): StageRedo | undefined {
-  for (const { attempt, flags, stages } of [...attempts].sort((a, b) => b.attempt - a.attempt)) {
-    const stage = flags.fromStage;
-    if (attempt >= before || stage === undefined) continue;
-    const ran = stages?.some((each) => each.stage === stage && each.source === "ran") ?? false;
-    if (ran || records.get(stage)?.attempt === attempt) return { stage, attempt };
-  }
-  return undefined;
-}

package/src/workflow-testing/coordinator.typecheck.ts

@@ -1,54 +0,0 @@
-// Checked by `tsc --noEmit`, never run: story 032's workflow and its test, as an author writes them.
-import {
-  defineWorkflow,
-  type ParticipantRef,
-  type WorkflowContext,
-} from "@agentswf/contract/workflow";
-import { answer, type ParticipantScript, testWorkflow } from ".";
-
-declare const runtime: string;
-
-const investigate = defineWorkflow<null, string>({
-  meta: { name: "investigate", description: "watches checkout-api" },
-  async run(wf: WorkflowContext) {
-    const investigator = await wf.agents.open({ key: "investigator", runtime });
-    const coordinator: ParticipantRef = await wf.participants.connect({
-      key: "coordinator",
-      labels: { audience: "operator" },
-    });
-    await wf.messages.allow({
-      between: [investigator, coordinator],
-      purpose: "report findings that hold up; ask when the logs can't settle it",
-      timeoutMs: 2 * 60 * 60_000,
-    });
-    const { outcome } = await investigator.run({ prompt: "Check the checkout-api logs." });
-    await coordinator.release("investigation done");
-    // A run has no deadline unless `awf run --timeout` gives it one.
-    const left = wf.deadline ? wf.deadline.unixMilliseconds - Date.now() : undefined;
-    return outcome.answered ? `${outcome.value} (${left ?? "no"} ms left)` : outcome.kind;
-  },
-});
-
-export async function story(): Promise<string> {
-  const run = await testWorkflow(investigate, {
-    agents: { investigator: [answer("…")] },
-    participants: {
-      coordinator: (event) =>
-        event.kind === "message" && event.asks
-          ? event.reply("Keep two, and link them.")
-          : undefined,
-    },
-  });
-  return run.value;
-}
-
-export const sendsFirst: ParticipantScript = async (event) => {
-  if (event.kind !== "route") return;
-  const sent = await event.send("Also check the 09:12 deploy.");
-  if (sent.code !== "delivered") throw new Error(sent.code);
-};
-
-export async function refused(wf: WorkflowContext): Promise<void> {
-  // @ts-expect-error bindingPath is gone: the socket's place is fixed.
-  await wf.participants.connect({ key: "coordinator", bindingPath: "/tmp/x" });
-}

package/src/workflow-testing/workflow-testing.typecheck.ts

@@ -1,67 +0,0 @@
-// Checked by `tsc --noEmit`, never run: each wrong answer is refused where it is written.
-import { defineWorkflow, type OutputSchema } from "@agentswf/contract/workflow";
-import Type from "typebox";
-import { answer, noAnswer, type Script, testWorkflow } from ".";
-
-const VERDICT = Type.Union([
-  Type.Object({ kind: Type.Literal("ready"), summary: Type.String() }),
-  Type.Object({ kind: Type.Literal("changes-requested"), feedback: Type.Array(Type.String()) }),
-]);
-/** A schema from another library, typed by the author surface's carrier. */
-const CARRIED = { type: "object" } as OutputSchema<{ count: number }>;
-
-export const valid: Script[] = [
-  answer(VERDICT, { kind: "ready", summary: "ok" }),
-  answer(VERDICT, (turn) =>
-    turn.n === 1
-      ? { kind: "changes-requested", feedback: ["more"] }
-      : { kind: "ready", summary: "ok" },
-  ),
-  answer(VERDICT, async (turn) =>
-    turn.nudge ? noAnswer.failed() : { kind: "ready", summary: "" },
-  ),
-  answer(CARRIED, { count: 1 }),
-  answer(CARRIED, () => ({ count: 2 })),
-  answer("text"),
-  answer((turn) => `turn ${turn.n}`),
-  noAnswer.silent(),
-  [answer(VERDICT, { kind: "ready", summary: "ok" }), noAnswer.hang(), answer("done")],
-];
-
-export const invalid: Script[] = [
-  // @ts-expect-error a missing field
-  answer(VERDICT, { kind: "ready" }),
-  // @ts-expect-error a kind the union doesn't have
-  answer(VERDICT, { kind: "approved", summary: "ok" }),
-  // @ts-expect-error an extra field
-  answer(VERDICT, { kind: "ready", summary: "ok", extra: 1 }),
-  // @ts-expect-error a function's literal must be one of the union's
-  answer(VERDICT, () => ({ kind: "approved", summary: "ok" })),
-  // @ts-expect-error the carrier's type
-  answer(CARRIED, { count: "one" }),
-  // @ts-expect-error no answer is a script entry of its own, not an answer's value
-  answer(VERDICT, noAnswer.silent()),
-  // @ts-expect-error text answers a turn with no schema
-  answer(42),
-];
-
-// @ts-expect-error raw JSON where a script expects answer(…)
-export const raw: Script = { kind: "ready", summary: "ok" };
-
-const withEvents = defineWorkflow({
-  meta: { name: "w", description: "w" },
-  file: import.meta.path,
-  events: { ping: { type: "object" } as OutputSchema<{ n: number }> },
-  run: async (wf) => (await wf.receive()).length,
-});
-export const tested = () => testWorkflow(withEvents, { id: "k" });
-// @ts-expect-error a workflow with events takes its args among its options
-export const byArgs = () => testWorkflow(withEvents, null);
-const plain = defineWorkflow({
-  meta: { name: "p", description: "p" },
-  prepare: ({ argv }) => ({ n: argv.length }),
-  run: async (_wf, args) => args.n,
-});
-// @ts-expect-error a workflow that takes args is given them
-export const byOptions = () => testWorkflow(plain, { id: "k" });
-export const argued = () => testWorkflow(plain, { id: "k", args: { n: 1 } });