@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/workflows/builtin/tournament-runner.ts

@@ -0,0 +1,188 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Type } from "typebox";
+import type {
+  WorkflowRunContext,
+  WorkflowSerializableObject,
+  WorkflowSerializableValue,
+  WorkflowTaskResult,
+} from "../src/shared/types.js";
+import {
+  renderBracketReducerPrompt,
+  renderPairwiseJudgePrompt,
+  renderTournamentAttemptPrompt,
+} from "./tournament-prompts.js";
+import { stableArtifactRoot } from "./pattern-artifact-root.js";
+
+const judgeDecisionSchema = Type.Object({
+  winner: Type.Union([Type.Literal("first"), Type.Literal("second")]),
+  rationale: Type.String(),
+  evidence: Type.Array(Type.String(), { minItems: 1 }),
+}, { additionalProperties: false });
+
+type TournamentInputs = {
+  readonly prompt: string;
+  readonly num_attempts: number;
+  readonly max_concurrency: number;
+} & Record<string, WorkflowSerializableValue>;
+
+type Entrant = { readonly label: string; readonly path: string };
+type MatchRecord = {
+  readonly round: number;
+  readonly match: number;
+  readonly first: string;
+  readonly second: string;
+  readonly winner: string;
+  readonly rationale: string;
+  readonly evidence: readonly string[];
+  readonly judge_artifact_path: string;
+};
+type ByeRecord = { readonly round: number; readonly entrant: string };
+
+function serializableObject(
+  value: WorkflowSerializableValue | undefined,
+): WorkflowSerializableObject | undefined {
+  if (value === null || Array.isArray(value) || typeof value !== "object") return undefined;
+  return value as WorkflowSerializableObject;
+}
+
+function decisionFrom(result: WorkflowTaskResult): {
+  readonly winner: "first" | "second";
+  readonly rationale: string;
+  readonly evidence: readonly string[];
+} {
+  const value = serializableObject(result.structured);
+  if (value === undefined) {
+    throw new Error(`tournament: judge ${result.stageName} did not return a structured decision`);
+  }
+  const winner = value.winner;
+  const rationale = value.rationale;
+  const evidence = value.evidence;
+  if ((winner !== "first" && winner !== "second") || typeof rationale !== "string" ||
+      !Array.isArray(evidence) || !evidence.every((item) => typeof item === "string")) {
+    throw new Error(`tournament: judge ${result.stageName} returned an invalid decision`);
+  }
+  return { winner, rationale, evidence };
+}
+
+function resultByName(results: readonly WorkflowTaskResult[], name: string): WorkflowTaskResult {
+  const result = results.find((candidate) => candidate.stageName === name || candidate.name === name);
+  if (result === undefined) throw new Error(`tournament: missing result for ${name}`);
+  return result;
+}
+
+export async function runTournament(ctx: WorkflowRunContext<TournamentInputs>) {
+  const artifactDir = await stableArtifactRoot(ctx, "tournament");
+  const attemptsDir = join(artifactDir, "attempts");
+  const judgesDir = join(artifactDir, "judges");
+  await mkdir(attemptsDir, { recursive: true });
+  await mkdir(judgesDir, { recursive: true });
+
+  const attemptArtifactPaths = Array.from({ length: ctx.inputs.num_attempts }, (_, index) =>
+    join(attemptsDir, `attempt-${index + 1}.md`));
+  await ctx.parallel(
+    attemptArtifactPaths.map((path, index) => ({
+      name: `attempt-${index + 1}`,
+      prompt: renderTournamentAttemptPrompt(ctx.inputs.prompt, index + 1),
+      context: "fresh" as const,
+      output: path,
+      outputMode: "file-only" as const,
+    })),
+    { concurrency: ctx.inputs.max_concurrency, failFast: true },
+  );
+
+  let entrants: Entrant[] = attemptArtifactPaths.map((path, index) => ({
+    label: `attempt-${index + 1}`,
+    path,
+  }));
+  const matches: MatchRecord[] = [];
+  const byes: ByeRecord[] = [];
+  const judgeArtifactPaths: string[] = [];
+  let round = 1;
+
+  while (entrants.length > 1) {
+    const pairs: Array<readonly [Entrant, Entrant]> = [];
+    const bye = entrants.length % 2 === 1 ? entrants.at(-1) : undefined;
+    if (bye !== undefined) byes.push({ round, entrant: bye.label });
+    for (let index = 0; index + 1 < entrants.length; index += 2) {
+      pairs.push([entrants[index]!, entrants[index + 1]!]);
+    }
+    const judgeSteps = pairs.map(([left, right], index) => {
+      const reverse = (round + index) % 2 === 0;
+      const first = reverse ? right : left;
+      const second = reverse ? left : right;
+      const path = join(judgesDir, `round-${round}-match-${index + 1}.json`);
+      judgeArtifactPaths.push(path);
+      return {
+        name: `judge-round-${round}-match-${index + 1}`,
+        prompt: renderPairwiseJudgePrompt({
+          task: ctx.inputs.prompt,
+          firstLabel: first.label,
+          secondLabel: second.label,
+          firstPath: first.path,
+          secondPath: second.path,
+        }),
+        context: "fresh" as const,
+        reads: [first.path, second.path],
+        schema: judgeDecisionSchema,
+        output: path,
+        outputMode: "file-only" as const,
+      };
+    });
+    const judgeResults = await ctx.parallel(judgeSteps, {
+      concurrency: Math.min(ctx.inputs.max_concurrency, Math.max(1, judgeSteps.length)),
+      failFast: true,
+    });
+    const next: Entrant[] = [];
+    for (let index = 0; index < pairs.length; index += 1) {
+      const [left, right] = pairs[index]!;
+      const reverse = (round + index) % 2 === 0;
+      const first = reverse ? right : left;
+      const second = reverse ? left : right;
+      const name = `judge-round-${round}-match-${index + 1}`;
+      const decision = decisionFrom(resultByName(judgeResults, name));
+      const winner = decision.winner === "first" ? first : second;
+      next.push(winner);
+      matches.push({
+        round,
+        match: index + 1,
+        first: first.label,
+        second: second.label,
+        winner: winner.label,
+        rationale: decision.rationale,
+        evidence: decision.evidence,
+        judge_artifact_path: judgeArtifactPaths.at(-pairs.length + index)!,
+      });
+    }
+    if (bye !== undefined) next.push(bye);
+    entrants = next;
+    round += 1;
+  }
+
+  const winner = entrants[0]!;
+  const bracketPath = join(artifactDir, "bracket.json");
+  await writeFile(bracketPath, `${JSON.stringify({ task: ctx.inputs.prompt, matches, byes, winner }, null, 2)}\n`);
+  const resultPath = join(artifactDir, "winner.md");
+  const reducer = await ctx.task("bracket-reducer", {
+    prompt: renderBracketReducerPrompt({
+      task: ctx.inputs.prompt,
+      bracketPath,
+      winnerLabel: winner.label,
+      winnerPath: winner.path,
+    }),
+    context: "fresh",
+    reads: [bracketPath, winner.path, ...judgeArtifactPaths],
+    output: resultPath,
+  });
+
+  return {
+    result: reducer.text,
+    winner: winner.label,
+    winner_artifact_path: winner.path,
+    result_path: resultPath,
+    attempt_artifact_paths: attemptArtifactPaths,
+    judge_artifact_paths: judgeArtifactPaths,
+    bracket_path: bracketPath,
+    artifact_dir: artifactDir,
+  };
+}

package/dist/builtin/workflows/builtin/tournament.d.ts

@@ -0,0 +1,33 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+export type TournamentWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly num_attempts: number;
+  readonly max_concurrency: number;
+};
+
+export type TournamentWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly num_attempts?: number;
+  readonly max_concurrency?: number;
+};
+
+export type TournamentWorkflowOutputs = WorkflowOutputValues & {
+  readonly result: string;
+  readonly winner: string;
+  readonly winner_artifact_path: string;
+  readonly result_path: string;
+  readonly attempt_artifact_paths: string[];
+  readonly judge_artifact_paths: string[];
+  readonly bracket_path: string;
+  readonly artifact_dir: string;
+};
+
+export type TournamentWorkflowDefinition = WorkflowDefinition<
+  TournamentWorkflowInputs,
+  TournamentWorkflowOutputs,
+  TournamentWorkflowRunInputs
+>;
+
+declare const workflow: TournamentWorkflowDefinition;
+export default workflow;

package/dist/builtin/workflows/builtin/tournament.ts

@@ -0,0 +1,34 @@
+import { Type } from "typebox";
+import { workflow } from "../src/authoring/workflow.js";
+import { runTournament } from "./tournament-runner.js";
+
+export default workflow({
+  name: "tournament",
+  description: "Run several independent whole-task attempts through a balanced pairwise judging bracket and return an auditable winner.",
+  inputs: {
+    prompt: Type.String({ description: "Task every competing agent must attempt independently." }),
+    num_attempts: Type.Integer({
+      minimum: 2,
+      maximum: 8,
+      default: 4,
+      description: "Number of independent whole-task attempts (2-8).",
+    }),
+    max_concurrency: Type.Integer({
+      minimum: 1,
+      maximum: 8,
+      default: 4,
+      description: "Maximum simultaneously active attempts or pairwise judges (1-8).",
+    }),
+  },
+  outputs: {
+    result: Type.String({ description: "Final reducer report containing the winning solution and decision trail." }),
+    winner: Type.String({ description: "Stable attempt label selected as the tournament winner." }),
+    winner_artifact_path: Type.String({ description: "Path to the original winning attempt artifact." }),
+    result_path: Type.String({ description: "Path to the final reducer report artifact." }),
+    attempt_artifact_paths: Type.Array(Type.String(), { description: "Paths to every independent attempt artifact." }),
+    judge_artifact_paths: Type.Array(Type.String(), { description: "Paths to all structured pairwise judge artifacts." }),
+    bracket_path: Type.String({ description: "Path to the durable JSON bracket with matches, byes, rationales, and winner." }),
+    artifact_dir: Type.String({ description: "Run-specific directory containing tournament artifacts." }),
+  },
+  run: async (ctx) => await runTournament(ctx),
+});

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.9",
+  "version": "0.9.10",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [
@@ -83,7 +83,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.80.7"
+    "@earendil-works/pi-tui": "^0.80.10"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/workflows/src/authoring.d.ts

@@ -1,10 +1,10 @@
 import type { TSchema } from "typebox";
 export type { Static, TSchema } from "typebox";
-export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSendUserMessageOptions, StageUserMessageContent, StageUserMessageDelivery, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildArgs, WorkflowRunChildOptions, WorkflowRunChildOptionsArgument, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
+export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSendUserMessageOptions, StageUserMessageContent, StageUserMessageDelivery, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildArgs, WorkflowRunChildOptions, WorkflowRunChildOptionsArgument, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
 import type * as AuthoringContract from "./shared/authoring-contract.js";
 import type { AuthoredWorkflowSpec as SharedAuthoredWorkflowSpec, WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas } from "./shared/workflow-authoring-types.js";
 export type { WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas, } from "./shared/workflow-authoring-types.js";
-import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowDetails, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionPolicy, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowSerializableObject, WorkflowChainStep } from "./shared/authoring-contract.js";
+import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowExecutionPolicy, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowSerializableObject } from "./shared/authoring-contract.js";
 declare const workflowDefinitionBrand: unique symbol;
 type WorkflowDefinitionBrand = {
     readonly [workflowDefinitionBrand]: true;
@@ -27,10 +27,6 @@ export type RunOpts = Omit<AuthoringContract.RunOpts, "registry"> & {
 export declare const INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy;
 export declare const NON_INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy;
 export declare function run<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues, TRunInputs extends WorkflowInputValues = TInputs>(definition: WorkflowDefinition<TInputs, TOutputs, TRunInputs>, inputs: Readonly<NoInfer<WorkflowRunInputArgument<TRunInputs>>>, opts?: RunOpts): Promise<RunResult<TOutputs>>;
-export declare function runTask(task: WorkflowDirectTaskItem, runOptions?: RunOpts): Promise<WorkflowDetails>;
-export declare function runTask(task: WorkflowDirectTaskItem, options?: WorkflowDirectOptions, runOptions?: RunOpts): Promise<WorkflowDetails>;
-export declare function runParallel(tasks: readonly WorkflowDirectTaskItem[], options?: WorkflowDirectOptions, runOptions?: RunOpts): Promise<WorkflowDetails>;
-export declare function runChain(steps: readonly WorkflowChainStep[], options?: WorkflowDirectOptions, runOptions?: RunOpts): Promise<WorkflowDetails>;
 export declare function resolveInputs<TInputs extends WorkflowInputValues>(schema: Readonly<Record<keyof TInputs & string, TSchema>>, provided: Partial<TInputs>): ResolvedInputs<TInputs>;
 export declare function setupGitWorktree(options: GitWorktreeSetupOptions): GitWorktreeSetupResult;
 export interface WorkflowRegistry {