@agentswf/contract 0.0.0-stage → 0.1.0-beta.1

package/src/workflow/decisions.ts

@@ -0,0 +1,176 @@
+import type { JsonObject, JsonValue } from "./json";
+import type { AbsoluteDeadline } from "./timing";
+
+/** Instructions, an option's description or a level: text, or structured text, as Jev allows. */
+export type DecisionText = string | JsonObject;
+
+/** An option's name and its description, or `null` when the name says enough. */
+export type DecisionOptions = Record<string, DecisionText | null>;
+export type DecisionLevels = readonly DecisionText[];
+
+export interface ChoiceQuestion<O extends DecisionOptions = DecisionOptions> {
+  readonly type: "choice";
+  readonly instructions: DecisionText;
+  readonly options: O;
+}
+
+export interface ScoreQuestion<L extends DecisionLevels = DecisionLevels> {
+  readonly type: "score";
+  readonly instructions: DecisionText;
+  /** Ordered, lowest first. */
+  readonly levels: L;
+}
+
+export interface YesNoQuestion {
+  readonly type: "yes-no";
+  readonly instructions: DecisionText;
+  readonly criteria?: { readonly yes: DecisionText; readonly no: DecisionText };
+}
+
+export type Question = ChoiceQuestion | ScoreQuestion | YesNoQuestion;
+
+/** Picks one of `options`. Its answer is typed by their names. */
+export function choice<const O extends DecisionOptions>(
+  instructions: DecisionText,
+  options: O,
+): ChoiceQuestion<O> {
+  assertInstructions(instructions);
+  if (Object.keys(options).length === 0) throw new Error("a choice needs at least one option");
+  return { type: "choice", instructions, options };
+}
+
+/** Places the state on `levels`, lowest first. Its answer is typed by their indices. */
+export function score<const L extends DecisionLevels>(
+  instructions: DecisionText,
+  levels: L,
+): ScoreQuestion<L> {
+  assertInstructions(instructions);
+  if (levels.length === 0) throw new Error("a score needs at least one level");
+  return { type: "score", instructions, levels };
+}
+
+/** The probability that the answer is yes. */
+export function yesNo(
+  instructions: DecisionText,
+  criteria?: { yes: DecisionText; no: DecisionText },
+): YesNoQuestion {
+  assertInstructions(instructions);
+  return criteria ? { type: "yes-no", instructions, criteria } : { type: "yes-no", instructions };
+}
+
+function assertInstructions(instructions: DecisionText): void {
+  if (typeof instructions === "string" && instructions.trim() === "") {
+    throw new Error("a question needs instructions");
+  }
+}
+
+/** A tuple's indices as numbers, or `number` for levels only known at run time. */
+type LevelOf<L extends DecisionLevels> = number extends L["length"]
+  ? number
+  : Extract<keyof L, `${number}`> extends `${infer N extends number}`
+    ? N
+    : never;
+
+type ChoiceAnswer<O extends DecisionOptions = DecisionOptions> = {
+  readonly type: "choice";
+  /** The most likely option; the first of them on a tie. */
+  readonly choice: keyof O & string;
+  readonly probabilities: { readonly [K in keyof O & string]: number };
+};
+
+type ScoreAnswer<L extends DecisionLevels = DecisionLevels> = {
+  readonly type: "score";
+  /** The most likely level; the lowest of them on a tie. */
+  readonly level: LevelOf<L>;
+  /** The probability-weighted level. */
+  readonly expected: number;
+  /** One per level, lowest first. */
+  readonly probabilities: readonly number[];
+};
+
+type YesNoAnswer = { readonly type: "yes-no"; readonly yes: number };
+
+/**
+ * Every answer carries its whole distribution, as the provider gave it: rounded, and not
+ * renormalised. The top pick is a convenience.
+ */
+export type Answer<Q extends Question> =
+  Q extends ChoiceQuestion<infer O>
+    ? ChoiceAnswer<O>
+    : Q extends ScoreQuestion<infer L>
+      ? ScoreAnswer<L>
+      : YesNoAnswer;
+
+export type Answers<Q extends Record<string, Question>> = { readonly [K in keyof Q]: Answer<Q[K]> };
+
+/** A decision model alias the operator configured, such as `jev`. */
+export type DecisionAliasName = string;
+
+export interface DecisionSpec<Q extends Record<string, Question> = Record<string, Question>> {
+  /** Names the call in its record, and its prefix before `:` is its accounting stage. Not unique. */
+  key: string;
+  model: DecisionAliasName;
+  /** What every question is asked about. The provider bills it once per call, however many questions. */
+  state: string | JsonObject | JsonValue[];
+  /** At least one. They are answered independently and do not see each other's answers. */
+  questions: Q;
+  /** Defaults to the current scope's deadline, and can only be earlier. */
+  deadline?: AbsoluteDeadline;
+}
+
+/** One `decide` call, as the run keeps it in `output.json`. */
+export type DecisionRecord = {
+  callPath: string[];
+  key: string;
+  /** The workflow stage it was asked in; absent between stages. */
+  stage?: string;
+  /** The alias the workflow asked for. */
+  alias: DecisionAliasName;
+  provider: string;
+  /** As the alias resolved it. */
+  model: string;
+  /** The versioned model that answered; absent when none did. A fitted threshold holds only for it. */
+  snapshot?: string;
+  startedAt: string;
+  settledAt: string;
+  questions: { id: string; type: Question["type"] }[];
+  /**
+   * SHA-256 of the questions: types, instructions, options, levels and criteria. With `snapshot`,
+   * it is what a fitted threshold binds to.
+   */
+  questionsDigest: string;
+  outcome: "answered" | "failed" | "timed-out" | "cancelled";
+  error?: string;
+  /** Requests sent, retries included; each may have been billed. */
+  attempts: number;
+  /** Summed over attempts, as far as the provider reported them. */
+  tokens?: { input: number; output: number };
+  requestId?: string;
+  /** The request and its answers, relative to the run's artifacts, for fitting thresholds offline. */
+  artifact: string;
+};
+
+export interface DecisionDirectory {
+  /**
+   * One request: the state once, every question about it. Once sent, a call is recorded whatever
+   * its outcome, and rejects with `DeadlineExceededError` past its deadline or `DecisionError`
+   * otherwise. A spec the engine refuses (an unknown alias, no questions) rejects with an `Error`
+   * before anything is sent, and leaves no record.
+   */
+  decide<const Q extends Record<string, Question>>(
+    spec: DecisionSpec<Q>,
+  ): Promise<{ answers: Answers<Q>; record: DecisionRecord }>;
+}
+
+/** A decision that was asked and did not answer. Its record is in the run's too. */
+export class DecisionError extends Error {
+  readonly code = "decision-failed" as const;
+
+  constructor(
+    message: string,
+    readonly record: DecisionRecord,
+  ) {
+    super(message);
+    this.name = "DecisionError";
+  }
+}

package/src/workflow/decisions.typecheck.ts

@@ -0,0 +1,97 @@
+import {
+  type ChoiceQuestion,
+  choice,
+  type DecisionSpec,
+  type Question,
+  score,
+  type WorkflowContext,
+  yesNo,
+} from "./index";
+
+declare const context: WorkflowContext;
+declare const issues: { id: string; mechanism: string }[];
+
+type Equal<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+function expectType<T extends true>(_proof?: T): void {}
+
+async function inline(): Promise<void> {
+  const { answers, record } = await context.decisions.decide({
+    key: "triage:1",
+    model: "jev",
+    state: { ticket: "Checkout double-charges on retry" },
+    questions: {
+      team: choice("Which team owns `ticket`?", { payments: "Checkout, billing", frontend: null }),
+      bug: yesNo("Does `ticket` report broken behaviour?"),
+      urgency: score("How urgent is `ticket`?", ["later", "this week", "now"]),
+    },
+  });
+  expectType<Equal<typeof answers.team.choice, "payments" | "frontend">>();
+  expectType<Equal<typeof answers.urgency.level, 0 | 1 | 2>>();
+  expectType<Equal<typeof answers.urgency.probabilities, readonly number[]>>();
+  expectType<Equal<typeof answers.bug.yes, number>>();
+  const payments: number = answers.team.probabilities.payments;
+  const expected: number = answers.urgency.expected;
+  const snapshot: string | undefined = record.snapshot;
+  // @ts-expect-error Not an option.
+  void answers.team.probabilities.account;
+  // @ts-expect-error Not a question.
+  void answers.severity;
+  // @ts-expect-error A yes-no has no pick of its own.
+  void answers.bug.choice;
+  void [payments, expected, snapshot];
+}
+
+/** A decision reused across workflows: a function that returns the call. */
+function matchIssue(text: string) {
+  const options = Object.fromEntries(issues.map((issue) => [issue.id, issue.mechanism]));
+  return {
+    key: "match:fixture",
+    model: "jev",
+    state: { finding: text },
+    questions: { issue: choice("Which known problem does `finding` raise?", options) },
+  };
+}
+
+const SEVERITY = score("How severe is `issue`?", ["nit", "could-fix", "should-fix", "must-fix"]);
+
+async function reused(): Promise<void> {
+  const { answers } = await context.decisions.decide(matchIssue("a finding"));
+  // Options only known at run time widen to `string`.
+  expectType<Equal<typeof answers.issue.choice, string>>();
+  const graded = await context.decisions.decide({
+    key: "grade:1",
+    model: "jev",
+    state: "an issue",
+    questions: { severity: SEVERITY },
+  });
+  expectType<Equal<typeof graded.answers.severity.level, 0 | 1 | 2 | 3>>();
+  const dynamic = await context.decisions.decide({
+    key: "grade:2",
+    model: "jev",
+    state: "an issue",
+    questions: {
+      severity: score(
+        "How severe?",
+        issues.map((issue) => issue.id),
+      ),
+    },
+  });
+  expectType<Equal<typeof dynamic.answers.severity.level, number>>();
+}
+
+function rejectedShapes(): void {
+  // @ts-expect-error A question's type is one of three.
+  const unknownType: Question = { type: "rank", instructions: "Rank it" };
+  // @ts-expect-error Questions are required.
+  const noQuestions: DecisionSpec = { key: "k", model: "jev", state: "s" };
+  // A question written as a bare literal outside the call needs `satisfies`, or its type widens.
+  const bare = {
+    type: "choice",
+    instructions: "Which?",
+    options: { a: null },
+  } satisfies ChoiceQuestion;
+  void [unknownType, noQuestions, bare];
+}
+
+void [inline, reused, rejectedShapes];

package/src/workflow/executable.ts

@@ -0,0 +1,87 @@
+import type { JsonValue } from "./json";
+import type { StageOutcome, WorkflowDefinition } from "./workflow";
+
+export const EXECUTABLE_WORKFLOW_KIND = "awf.executable-workflow/v1" as const;
+
+export type WorkflowInvocation = Readonly<{
+  argv: readonly string[];
+  cwd: string;
+}>;
+
+/** One stage an attempt entered: run, or reused from the attempt that ran it. */
+export type StageSummary = {
+  stage: string;
+  source: "ran" | "reused";
+  outcome: StageOutcome;
+  /** The attempt that ran it. */
+  attempt: number;
+  /** How long it ran in this attempt: zero for a reused one. */
+  spanMs: number;
+  summary?: string;
+  /** Its value, for a stage that returns one and succeeded. */
+  value?: JsonValue;
+  /** Reused from a value given rather than one a turn produced; see `StageRecord.provided`. */
+  provided?: true;
+};
+
+/** How an attempt ended. `interrupted` is never written: it is an attempt with no ending and no process. */
+export type AttemptOutcome = "completed" | UnfinishedOutcome;
+
+/**
+ * How an attempt that didn't complete ended. `cancelled` is the operator stopping it, and wins over
+ * the others. `timed-out` is its own deadline ending it; a deadline the workflow set and let escape
+ * is `failed`. `stopped` is a stop: the workflow's, or a continue that can't go on as asked.
+ */
+export type UnfinishedOutcome = "stopped" | "failed" | "timed-out" | "cancelled";
+
+/** How an attempt ended, which `report` renders. */
+export type Ending<Result> =
+  | { kind: "completed"; value: Result; stages: StageSummary[] }
+  | {
+      kind: UnfinishedOutcome;
+      /** The stage it ended in; absent between stages. */
+      stage?: string;
+      reason: string;
+      stages: StageSummary[];
+      /** The command that goes on from here. */
+      continue: string;
+    };
+
+/**
+ * Adapts operator input to one programmatic workflow call, and its result back to the operator,
+ * without owning runtime configuration.
+ */
+export interface ExecutableWorkflow<Args extends JsonValue, Result extends JsonValue> {
+  readonly kind: typeof EXECUTABLE_WORKFLOW_KIND;
+  readonly definition: WorkflowDefinition<Args, Result>;
+  prepare(invocation: WorkflowInvocation): Args;
+  /**
+   * The run's id, derived from its args, such as a ticket's key: unique within the workflow,
+   * letters, digits, `.`, `_` and `-`. `awf run --id` overrides it; without either, one is
+   * generated.
+   */
+  id?(args: Args): string;
+  /**
+   * Renders a completed attempt's value for a person at a terminal. Undefined, or no `present`, and
+   * awf prints the JSON. An attempt that didn't complete is awf's to print: its stage, its reason
+   * and the command that goes on.
+   */
+  present?(value: Result, ending: Ending<Result>): string | undefined;
+  /**
+   * A Markdown handoff of how the attempt ended for whoever acts on it, which the operator saves as
+   * report.md. Called for every ending, `value` only for a completed one, so a stopped attempt can
+   * hand off what its stages found. Undefined writes none.
+   */
+  report?(value: Result | undefined, ending: Ending<Result>): string | undefined;
+}
+
+type ExecutableWorkflowSpec<Args extends JsonValue, Result extends JsonValue> = Omit<
+  ExecutableWorkflow<Args, Result>,
+  "kind"
+>;
+
+export function defineExecutableWorkflow<Args extends JsonValue, Result extends JsonValue>(
+  spec: ExecutableWorkflowSpec<Args, Result>,
+): ExecutableWorkflow<Args, Result> {
+  return { ...spec, kind: EXECUTABLE_WORKFLOW_KIND };
+}

package/src/workflow/index.ts

@@ -0,0 +1,10 @@
+export * from "./agents";
+export * from "./composition";
+export * from "./decisions";
+export * from "./executable";
+export * from "./json";
+export * from "./messaging";
+export * from "./participants";
+export * from "./sandboxes";
+export * from "./timing";
+export * from "./workflow";

package/src/workflow/json.ts

@@ -0,0 +1,74 @@
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+
+export type JsonObject = { [key: string]: JsonValue };
+
+export function isJsonValue(value: unknown): value is JsonValue {
+  return isJsonValueAt(value, new Set<object>());
+}
+
+function isJsonValueAt(value: unknown, ancestors: Set<object>): value is JsonValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "object") return false;
+  if (ancestors.has(value)) return false;
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const keys = Reflect.ownKeys(value);
+      if (keys.length !== value.length + 1 || !keys.includes("length")) return false;
+      return keys.every((key) => {
+        if (key === "length") return true;
+        if (!isArrayIndex(key)) return false;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        return (
+          descriptor?.enumerable === true &&
+          "value" in descriptor &&
+          isJsonValueAt(descriptor.value, ancestors)
+        );
+      });
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) return false;
+    return Reflect.ownKeys(value).every((key) => {
+      if (typeof key !== "string") return false;
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      return (
+        descriptor?.enumerable === true &&
+        "value" in descriptor &&
+        isJsonValueAt(descriptor.value, ancestors)
+      );
+    });
+  } catch {
+    return false;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function isArrayIndex(key: PropertyKey): boolean {
+  if (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key)) return false;
+  const index = Number(key);
+  return Number.isSafeInteger(index) && index >= 0 && index < 4_294_967_295;
+}
+
+/**
+ * Any authoring library may supply a JSON Schema object; the engine checks its supported subset.
+ * That is why `object` is as narrow as the first arm gets: an unbranded schema from an unknown
+ * library has to be accepted here and rejected by `parseJsonSchema`, so only a branded one is
+ * checked against `Output`.
+ *
+ * The second arm looks subsumed by the first and is not: excess-property checking applies to an
+ * object literal written at this type, so without an index signature to land in, a schema written
+ * inline — `{ type: "object", properties: … }` — is rejected for every keyword it names.
+ */
+export type OutputSchema<Output extends JsonValue = JsonValue> =
+  | (object & {
+      /** Type-only carrier for structurally compatible schema libraries. */
+      readonly "~output"?: Output;
+    })
+  | {
+      readonly [keyword: string]: unknown;
+      readonly "~output"?: Output;
+    };

package/src/workflow/messaging.ts

@@ -0,0 +1,31 @@
+import type { ParticipantRef } from "./participants";
+
+/**
+ * A route: `from` may message `to`, which answers over it when asked; `between` is both directions,
+ * sharing one count. Its purpose is shown with every message on it.
+ */
+export type MessageAccess =
+  | {
+      from: ParticipantRef;
+      to: ParticipantRef;
+      between?: never;
+      purpose: string;
+      /** Lowers the engine's ceiling of messages on this route an attempt, answers included. */
+      maxMessages?: number;
+    }
+  | {
+      between: readonly [ParticipantRef, ParticipantRef];
+      from?: never;
+      to?: never;
+      purpose: string;
+      /** Lowers the engine's ceiling of messages on this route an attempt, answers included. */
+      maxMessages?: number;
+    };
+
+export interface Messaging {
+  /**
+   * Grants routes in the current scope atomically: a stage's close when it ends, the rest with the
+   * attempt. A pair has one open route at a time; granting it again must match, or it rejects.
+   */
+  allow(access: MessageAccess): Promise<void>;
+}

package/src/workflow/messaging.typecheck.ts

@@ -0,0 +1,114 @@
+import type { AgentRef, JsonValue, OutputSchema, ParticipantRef, WorkflowContext } from "./index";
+import { isAnswered } from "./index";
+
+// The sketches in docs/design/messaging.md's "Routes by shape", as a workflow writes them.
+declare const workflow: WorkflowContext;
+declare const implementer: AgentRef;
+declare const reviewer: AgentRef;
+declare const architect: AgentRef;
+declare const planner: AgentRef;
+declare const critic: AgentRef;
+declare const tester: AgentRef;
+declare const runtime: string;
+declare const LENSES: readonly { key: string }[];
+declare const FIX_REPORT: OutputSchema<{ fixed: string[] }>;
+declare const FINDINGS: OutputSchema<{ findings: number }>;
+declare const PLAN: OutputSchema<{ steps: string[] }>;
+declare function lensPrompt(key: string): string;
+declare function planPrompt(ticket: string): string;
+declare const ticket: string;
+
+async function bothWays(): Promise<void> {
+  await workflow.messages.allow({
+    between: [implementer, reviewer],
+    purpose: "Review and revise the implementation until both agree it is ready.",
+  });
+}
+
+async function oneWayNothingOwed(): Promise<JsonValue> {
+  const fixer = await workflow.agents.open({ key: "fixer", runtime });
+  const lenses = await workflow.parallel(LENSES, (lens) =>
+    workflow.agents.open({ key: lens.key, runtime }),
+  );
+  for (const lens of lenses) {
+    await workflow.messages.allow({
+      from: lens,
+      to: fixer,
+      purpose: "Report each finding as you confirm it, then `done`; the fixer does not reply.",
+    });
+  }
+  const [fixed] = await Promise.all([
+    fixer.run({
+      prompt:
+        "Fix each finding the lenses send; when every lens has said done, report what changed.",
+      schema: FIX_REPORT,
+    }),
+    workflow.parallel(lenses, (lens) =>
+      lens.run({ prompt: lensPrompt(lens.key), schema: FINDINGS }),
+    ),
+  ]);
+  return isAnswered(fixed.outcome) ? fixed.outcome.value : null;
+}
+
+async function oneWayWithAnAnswer(): Promise<void> {
+  await workflow.messages.allow({
+    from: implementer,
+    to: architect,
+    purpose: "Ask about the design when the ticket document does not settle it.",
+  });
+}
+
+async function room(): Promise<void> {
+  const members = [planner, critic, tester];
+  for (const [i, a] of members.entries()) {
+    for (const b of members.slice(i + 1)) {
+      await workflow.messages.allow({
+        between: [a, b],
+        purpose: "Agree the plan in PLAN.md; ask when an entry there is unclear.",
+      });
+    }
+  }
+}
+
+async function lowerLimit(): Promise<void> {
+  await workflow.messages.allow({
+    between: [implementer, reviewer],
+    purpose: "Review and revise the implementation until both agree it is ready.",
+    maxMessages: 10,
+  });
+}
+
+async function routeForOneStage(): Promise<{ steps: string[] }> {
+  const plan = await workflow.stage("plan", { result: PLAN }, async () => {
+    await workflow.messages.allow({
+      from: planner,
+      to: architect,
+      purpose: "Ask about the design while drafting the plan.",
+    });
+    const { outcome } = await planner.run({ prompt: planPrompt(ticket), schema: PLAN });
+    return isAnswered(outcome) ? outcome.value : workflow.stop(outcome.reason);
+  });
+  await workflow.agents.stop("architect", "design questions are settled");
+  return plan;
+}
+
+async function refused(): Promise<void> {
+  // A workflow names only participants the engine issued it.
+  // @ts-expect-error A `{ key }` literal is not a ParticipantRef.
+  const forged: ParticipantRef = { key: "reviewer" };
+  await workflow.messages.allow({
+    // @ts-expect-error Nor is one inline.
+    from: { key: "reviewer" },
+    to: implementer,
+    purpose: "forged",
+  });
+  await workflow.messages.allow({
+    // @ts-expect-error A route is one shape or the other.
+    between: [implementer, reviewer],
+    from: implementer,
+    purpose: "both shapes",
+  });
+  void forged;
+}
+
+void [bothWays, oneWayNothingOwed, oneWayWithAnAnswer, room, lowerLimit, routeForOneStage, refused];

package/src/workflow/participants.ts

@@ -0,0 +1,33 @@
+import type { PARTICIPANT } from "../participant";
+import type { JsonObject } from "./json";
+
+export type ParticipantKey = string;
+
+/**
+ * A participant the engine issued: an agent this workflow opened, or later a connected outside
+ * session. Only the engine makes one, so a workflow cannot name a participant it was not given.
+ */
+export interface ParticipantRef {
+  /** Logical key in the workflow context that issued this reference. */
+  readonly key: ParticipantKey;
+  readonly [PARTICIPANT]: true;
+}
+
+export interface ExternalParticipantSpec {
+  key: ParticipantKey;
+  /** Defaults to the workflow's discoverable session binding. */
+  bindingPath?: string;
+  labels?: JsonObject;
+}
+
+export interface ExternalParticipantRef extends ParticipantRef {
+  /** Stops routing and fails outstanding response obligations involving this participant. */
+  release(reason?: string): Promise<boolean>;
+}
+
+export interface ParticipantDirectory {
+  /** Connects a session the engine did not start; an occupied participant key rejects. */
+  connect(spec: ExternalParticipantSpec): Promise<ExternalParticipantRef>;
+  /** Finds an agent or connected participant visible in this workflow scope. */
+  get(key: ParticipantKey): Promise<ParticipantRef | null>;
+}