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

package/src/workflow/sandboxes.ts

@@ -0,0 +1,87 @@
+export type SandboxKey = string;
+
+/**
+ * A host name: exact (`registry.npmjs.org`), or `*.` and a name for its subdomains only
+ * (`*.npmjs.org`, which does not match `npmjs.org`). No scheme, port, path or IP address.
+ */
+export type Domain = string;
+
+/** What the agents inside see and reach. Every provider enforces it; each does so its own way. */
+export type SandboxReach = {
+  /** Host paths visible at the same path, read-only, beyond the sandbox's working directory. */
+  read?: readonly string[];
+  /** Host paths visible at the same path and writable. `"."` makes the working directory writable. */
+  write?: readonly string[];
+  /** Domains reachable beyond each harness's model API. */
+  network?: readonly Domain[];
+  /**
+   * Host unix sockets the agents inside may connect to: a socket, or a directory whose sockets they
+   * may connect to and, when it is also in `write`, create. Nothing else of the host's is reachable
+   * this way. srt only: docker refuses a sandbox that names one.
+   */
+  sockets?: readonly string[];
+  /**
+   * Keeps each harness's model-side web tools, which awf otherwise turns off inside: a search runs
+   * on the model provider's servers, past any `network` rule, so it can carry what the agents read
+   * out and bring the web in (X15).
+   */
+  webSearch?: boolean;
+};
+
+/** Anthropic's sandbox-runtime on this machine: the host system and the operator's toolchain. */
+export type SrtEnvironment = Record<string, never>;
+
+/** A container from `image`, running as the operator's uid. Absent image: the operator's default. */
+export type DockerEnvironment = { image?: string };
+
+/** The environments contract names, each the key of its settings in a spec and of its provider. */
+export const SANDBOX_ENVIRONMENTS = ["srt", "docker"] as const;
+export type SandboxEnvironmentKey = (typeof SANDBOX_ENVIRONMENTS)[number];
+
+/** At most one environment. Naming one pins the provider; naming none uses the operator's default. */
+export type SandboxEnvironment =
+  | { srt: SrtEnvironment; docker?: never }
+  | { docker: DockerEnvironment; srt?: never }
+  | { srt?: never; docker?: never };
+
+export type SandboxSpec = SandboxReach & SandboxEnvironment;
+
+/**
+ * A git directory the sandbox's `cwd` or a reach path belongs to, found when it opens: a
+ * repository's `.git`, a worktree's own gitdir and its common one, or a repository's nested in a
+ * writable path. Readable inside. Writable when the worktree it serves is, so a writable worktree
+ * can commit under every provider; what the host's git runs or follows in it never is.
+ */
+export type Gitdir = {
+  path: string;
+  writable: boolean;
+  /**
+   * Writable only through a linked worktree: the main worktree's `index` and `HEAD` in it stay
+   * read-only, so an agent cannot stage what the operator commits next.
+   */
+  linked?: true;
+};
+
+export type SandboxOpenSpec = SandboxSpec & {
+  key: SandboxKey;
+  /** Defaults to the workflow's working directory. Always readable inside. */
+  cwd?: string;
+};
+
+declare const sandboxRef: unique symbol;
+
+/** A sandbox this run opened. Only the engine makes one; a look-alike object is not a ref. */
+export interface SandboxRef {
+  readonly [sandboxRef]: true;
+  readonly key: SandboxKey;
+  /** Grows as providers are added: never switch over it exhaustively. */
+  readonly provider: SandboxEnvironmentKey;
+}
+
+/** A spec given inline to one agent: a private sandbox. It cannot carry a ref's or an open spec's fields. */
+export type InlineSandboxSpec = SandboxSpec & { key?: never; cwd?: never; provider?: never };
+
+export interface SandboxDirectory {
+  /** Opens a sandbox for this run. It closes when the run does, after every agent in it. */
+  open(spec: SandboxOpenSpec): Promise<SandboxRef>;
+}

package/src/workflow/sandboxes.typecheck.ts

@@ -0,0 +1,64 @@
+import type {
+  AgentOpenSpec,
+  InlineSandboxSpec,
+  SandboxEnvironment,
+  SandboxEnvironmentKey,
+  SandboxOpenSpec,
+  SandboxRef,
+  SandboxSpec,
+  WorkflowContext,
+} from "./index";
+
+declare const context: WorkflowContext;
+declare const ref: SandboxRef;
+
+const headless = { placement: "headless" } as const;
+
+async function acceptedShapes(): Promise<void> {
+  const box = await context.sandboxes.open({
+    key: "build",
+    write: ["."],
+    network: ["registry.npmjs.org", "*.npmjs.org"],
+    docker: { image: "awf-agent:node22" },
+  });
+  const local = await context.sandboxes.open({
+    key: "lint",
+    cwd: "/repo",
+    sockets: ["/tmp/app"],
+    webSearch: true,
+    srt: {},
+  });
+  const unpinned = { read: ["~/notes"] } satisfies SandboxSpec;
+  const opened: AgentOpenSpec[] = [
+    { key: "coder", runtime: { alias: "codex", ...headless }, sandbox: box },
+    { key: "linter", runtime: "pi", sandbox: local },
+    { key: "reviewer", runtime: "codex", sandbox: {} },
+    { key: "reader", runtime: "codex", sandbox: unpinned },
+    { key: "tester", runtime: "claude", sandbox: { write: ["."], docker: {} } },
+  ];
+  void [box.provider, opened];
+}
+
+function rejectedShapes(): void {
+  // @ts-expect-error A sandbox has at most one environment.
+  const twoEnvironments: SandboxOpenSpec = { key: "both", srt: {}, docker: {} };
+  // @ts-expect-error srt takes no settings yet.
+  const srtSettings: SandboxSpec = { srt: { image: "node" } };
+  const lookAlike = { key: "build", provider: "srt" };
+  // @ts-expect-error Only the engine makes a ref; a look-alike is not one.
+  const forged: AgentOpenSpec = { key: "coder", runtime: "codex", sandbox: lookAlike };
+  // @ts-expect-error An open spec is not an inline one: its key would name a shared sandbox.
+  const keyed: AgentOpenSpec = { key: "coder", runtime: "codex", sandbox: { key: "build" } };
+  // @ts-expect-error An inline sandbox's working directory is the agent's.
+  const inlineCwd: InlineSandboxSpec = { cwd: "/elsewhere" };
+  // @ts-expect-error A ref's provider cannot be written into a spec.
+  const inlineProvider: InlineSandboxSpec = { provider: "docker" };
+  void [twoEnvironments, srtSettings, forged, keyed, inlineCwd, inlineProvider, ref];
+}
+
+// Every environment key is a settings field in a spec, and every settings field is a key.
+type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+type SettingsFields = SandboxEnvironment extends infer E ? (E extends E ? keyof E : never) : never;
+const environmentsMatch: Same<SettingsFields, SandboxEnvironmentKey> = true;
+
+void [acceptedShapes, rejectedShapes, environmentsMatch];

package/src/workflow/timing.ts

@@ -0,0 +1,14 @@
+/** An absolute wall-clock deadline. `unixMilliseconds` is a non-negative finite integer. */
+export type AbsoluteDeadline = {
+  unixMilliseconds: number;
+};
+
+/** The single machine-readable rejection used by workflow waits without terminal outcomes. */
+export class DeadlineExceededError extends Error {
+  readonly code = "deadline-exceeded" as const;
+
+  constructor(readonly deadline: AbsoluteDeadline) {
+    super(`Deadline exceeded at ${deadline.unixMilliseconds}`);
+    this.name = "DeadlineExceededError";
+  }
+}

package/src/workflow/workflow.ts

@@ -0,0 +1,128 @@
+import type { AgentDirectory, OperationRecord } from "./agents";
+import type { WorkflowCallSpec } from "./composition";
+import type { DecisionDirectory } from "./decisions";
+import type { JsonObject, JsonValue, OutputSchema } from "./json";
+import type { Messaging } from "./messaging";
+import type { ParticipantDirectory } from "./participants";
+import type { SandboxDirectory } from "./sandboxes";
+import type { AbsoluteDeadline } from "./timing";
+
+export type WorkflowRunId = string;
+export type StepId = string;
+export type SignalId = string;
+
+export interface WorkflowMeta {
+  /** What its runs are kept under; a file may move or be copied and stay the same workflow. */
+  name: string;
+  description: string;
+  whenToUse?: string;
+  /** Semver, recorded with each attempt. */
+  version?: string;
+}
+
+export interface StepSpec {
+  /** Idempotency key scoped to this workflow context. Reusing it with a different spec rejects. */
+  id: StepId;
+  label?: string;
+}
+
+export interface Steps {
+  run<T extends JsonValue>(
+    spec: StepSpec & { deadline?: AbsoluteDeadline },
+    operation: () => Promise<T>,
+  ): Promise<T>;
+  /** Its requested duration is already a bound, so sleep has no second deadline. */
+  sleep(spec: StepSpec & { milliseconds: number }): Promise<void>;
+}
+
+export interface ParallelOptions {
+  /** Defaults to the current workflow scope deadline. */
+  deadline?: AbsoluteDeadline;
+  /** Positive integer local maximum; global admission may reduce it. */
+  concurrency?: number;
+  label?: string;
+}
+
+export interface SignalSpec {
+  /** Idempotency key scoped to this workflow context. Reusing it with a different spec rejects. */
+  id: SignalId;
+  name: string;
+  /** Defaults to the current workflow scope deadline. */
+  deadline?: AbsoluteDeadline;
+}
+
+export interface Signals {
+  /** Waits for one value and suspends only this branch, never workflow admission. */
+  receive(spec: SignalSpec): Promise<string>;
+  receive<T extends JsonValue>(spec: SignalSpec, schema: OutputSchema<T>): Promise<T>;
+}
+
+/**
+ * A stage's end: `stopped` is `workflow.stop` inside it; `failed` covers a throw, a value its
+ * schema rejects, and a cancellation.
+ */
+export type StageOutcome = "succeeded" | "stopped" | "failed";
+
+export interface StageOptions<T extends JsonValue> {
+  /** Checks the value when the stage records it, and whenever a continue reuses it. */
+  result: OutputSchema<T>;
+  /** One line about the value, for the view and the record. */
+  summary?: (value: T) => string;
+}
+
+export interface WorkflowContext {
+  /** The run's id, the same in every attempt of it. */
+  readonly runId: WorkflowRunId;
+  /** Which `awf run` of the run this is: 1, then one more for each continue. */
+  readonly attempt: number;
+  /** Working directory and hard bound for this invocation, supplied and enforced by the engine. */
+  readonly cwd: string;
+  readonly deadline: AbsoluteDeadline;
+  readonly agents: AgentDirectory;
+  readonly sandboxes: SandboxDirectory;
+  /** Closed questions to a decision model: probabilities back in a few hundred milliseconds. */
+  readonly decisions: DecisionDirectory;
+  readonly participants: ParticipantDirectory;
+  readonly messages: Messaging;
+  readonly steps: Steps;
+  readonly signals: Signals;
+  parallel<Item, Result>(
+    items: readonly Item[],
+    operation: (item: Item, index: number) => Promise<Result>,
+    options?: ParallelOptions,
+  ): Promise<Result[]>;
+
+  /**
+   * A named step of the run, recorded when it ends. One stage is open at a time, and a name is
+   * entered once per attempt; parallel work goes inside a stage. A stage with `result` returns a
+   * value it accepts; one without returns nothing.
+   */
+  stage(name: string, work: () => Promise<void>): Promise<void>;
+  stage<T extends JsonValue>(
+    name: string,
+    options: StageOptions<T>,
+    work: () => Promise<T>,
+  ): Promise<T>;
+
+  /**
+   * Ends the attempt `stopped`, apart from failed: in the stage it is called from, which a continue
+   * then redoes, or between stages, where a continue checks again. Caught, it fails the stage that
+   * caught it, or the attempt when the workflow returns. `return workflow.stop(…)` narrows where a
+   * bare call doesn't.
+   */
+  stop(reason: string): never;
+
+  call<Args extends JsonValue, Result extends JsonValue>(
+    spec: WorkflowCallSpec<Args, Result>,
+  ): Promise<Result>;
+
+  /** Completed operations in this workflow scope and its descendants, ordered by dispatch. */
+  usage(): OperationRecord[];
+
+  log(message: string, fields?: JsonObject): void;
+}
+
+export interface WorkflowDefinition<Args extends JsonValue, Result extends JsonValue> {
+  readonly meta: WorkflowMeta;
+  run(context: WorkflowContext, args: Args): Promise<Result>;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.