@bastani/atomic 0.9.16-alpha.7 → 0.9.16-alpha.9

package/dist/builtin/workflows/builtin/chunk-bfkmzv9h.js

@@ -0,0 +1,156 @@
+// dist/builtin/workflows/src/authoring/workflow.ts
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// dist/builtin/workflows/src/shared/budget.ts
+function validateWorkflowBudget(value, label = "budget") {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return `"${label}" must be a JSON object, got ${JSON.stringify(typeof value)}`;
+  }
+  const budget = value;
+  for (const field of ["maxDurationMs", "maxTokens"]) {
+    const limit = budget[field];
+    if (field in budget && (typeof limit !== "number" || !Number.isFinite(limit) || !Number.isInteger(limit) || limit < 0)) {
+      return `"${label}.${field}" must be a non-negative finite integer, got ${JSON.stringify(limit)}`;
+    }
+  }
+  for (const field of ["maxCost", "warnAtPercent"]) {
+    const limit = budget[field];
+    if (field in budget && (typeof limit !== "number" || !Number.isFinite(limit) || limit < 0)) {
+      return `"${label}.${field}" must be a non-negative finite number, got ${JSON.stringify(limit)}`;
+    }
+  }
+  return null;
+}
+function assertWorkflowBudget(value, label = "budget") {
+  if (value === undefined)
+    return;
+  const reason = validateWorkflowBudget(value, label);
+  if (reason !== null)
+    throw new TypeError(reason);
+}
+
+// dist/builtin/workflows/src/shared/workflow-heartbeat-contract.ts
+var DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES = 15;
+
+// dist/builtin/workflows/src/workflows/identity.ts
+function normalizeWorkflowName(name) {
+  if (!name || typeof name !== "string") {
+    throw new TypeError("normalizeWorkflowName: name must be a non-empty string");
+  }
+  return name.trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-{2,}/g, "-").replace(/^-|-$/g, "");
+}
+
+// dist/builtin/workflows/src/authoring/workflow.ts
+var BRANDED_WORKFLOW_DEFINITIONS = new WeakSet;
+function stampWorkflowDefinition(definition) {
+  BRANDED_WORKFLOW_DEFINITIONS.add(definition);
+  return definition;
+}
+function requireNonEmptyString(value, label) {
+  if (value.trim().length === 0) {
+    throw new TypeError(`workflow: ${label} must be a non-empty string`);
+  }
+}
+function freezeSchemaMap(schemas) {
+  return Object.freeze({ ...schemas });
+}
+function stackFilePath(line) {
+  const fileUrlMatch = line.match(/\(?((?:file:\/\/)[^\s)]+?\.[cm]?[jt]sx?):\d+:\d+\)?/);
+  const rawPath = fileUrlMatch?.[1] ?? line.match(/\(?((?:\/|[A-Za-z]:[\\/])[^():]+?\.[cm]?[jt]sx?):\d+:\d+\)?/)?.[1];
+  if (rawPath === undefined)
+    return;
+  if (!rawPath.startsWith("file://"))
+    return rawPath;
+  try {
+    return fileURLToPath(rawPath);
+  } catch {
+    return;
+  }
+}
+function isWorkflowAuthoringImplementationFrame(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  if (!/\/authoring\/workflow\.[cm]?[jt]sx?$/.test(normalized))
+    return false;
+  return normalized.includes("/packages/workflows/") || normalized.includes("/node_modules/@bastani/workflows/") || normalized.includes("/dist/builtin/workflows/") || normalized.includes("/.atomic/agent/extensions/workflows/") || normalized.includes("/.pi/agent/extensions/workflows/");
+}
+function workflowNameFromCaller() {
+  const stack = new Error().stack;
+  if (stack === undefined)
+    return;
+  for (const line of stack.split(`
+`)) {
+    const filePath = stackFilePath(line);
+    if (filePath === undefined)
+      continue;
+    if (isWorkflowAuthoringImplementationFrame(filePath))
+      continue;
+    const base = basename(filePath.replace(/\\/g, "/")).replace(/\.[cm]?[jt]sx?$/, "");
+    if (base.length > 0)
+      return base;
+  }
+  return;
+}
+function resolveWorkflowName(name) {
+  const resolved = name ?? workflowNameFromCaller();
+  if (resolved === undefined) {
+    throw new TypeError("workflow: name must be provided when caller filename cannot be inferred");
+  }
+  requireNonEmptyString(resolved, "name");
+  return resolved;
+}
+function freezeInputBindings(binding) {
+  if (binding === undefined)
+    return;
+  return Object.freeze({
+    worktree: Object.freeze({ ...binding })
+  });
+}
+function freezeBudget(budget) {
+  return budget === undefined ? undefined : Object.freeze({ ...budget });
+}
+function workflow(spec) {
+  const specRun = spec.run;
+  if (typeof spec.description !== "string") {
+    throw new TypeError("workflow: description must be a string");
+  }
+  if (typeof specRun !== "function") {
+    throw new TypeError("workflow: run must be a function");
+  }
+  if (spec.outputs === undefined || spec.outputs === null || typeof spec.outputs !== "object" || Array.isArray(spec.outputs)) {
+    throw new TypeError("workflow: outputs must be a schema map");
+  }
+  if (spec.inputs !== undefined && (spec.inputs === null || typeof spec.inputs !== "object" || Array.isArray(spec.inputs))) {
+    throw new TypeError("workflow: inputs must be a schema map");
+  }
+  const heartbeatIntervalMinutes = spec.heartbeatIntervalMinutes === undefined ? DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES : spec.heartbeatIntervalMinutes;
+  if (!Number.isFinite(heartbeatIntervalMinutes) || heartbeatIntervalMinutes < 0) {
+    throw new TypeError("workflow: heartbeatIntervalMinutes must be a non-negative finite number");
+  }
+  assertWorkflowBudget(spec.budget, "workflow: budget");
+  const name = resolveWorkflowName(spec.name);
+  const normalizedName = normalizeWorkflowName(name);
+  requireNonEmptyString(normalizedName, "normalized name");
+  const frozenInputs = freezeSchemaMap(spec.inputs ?? {});
+  const frozenOutputs = freezeSchemaMap(spec.outputs);
+  const inputBindings = freezeInputBindings(spec.worktreeFromInputs);
+  const budget = freezeBudget(spec.budget);
+  const run = async (ctx) => specRun(ctx);
+  const definition = {
+    __piWorkflow: true,
+    name,
+    normalizedName,
+    description: spec.description,
+    ...spec.autoAttach === true ? { autoAttach: true } : {},
+    heartbeatIntervalMinutes,
+    inputs: frozenInputs,
+    outputs: frozenOutputs,
+    ...inputBindings !== undefined ? { inputBindings } : {},
+    ...budget !== undefined ? { budget } : {},
+    run
+  };
+  const branded = stampWorkflowDefinition(definition);
+  return Object.freeze(branded);
+}
+
+export { workflow };

package/dist/builtin/workflows/builtin/chunk-c53y8bdh.js

@@ -0,0 +1,345 @@
+import {
+  stableArtifactRoot
+} from "./chunk-wpckd35c.js";
+import {
+  classify_trend,
+  score_progress
+} from "./chunk-6fqs7c01.js";
+import {
+  workflow
+} from "./chunk-bfkmzv9h.js";
+import {
+  withSteeringPropagationContext
+} from "./chunk-0x6e303p.js";
+
+// dist/builtin/workflows/builtin/loop-until-done.ts
+import { Type as Type2 } from "typebox";
+
+// dist/builtin/workflows/builtin/loop-until-done-runner.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Type } from "typebox";
+
+// dist/builtin/workflows/builtin/loop-until-done-prompts.ts
+var GROUNDED_REPORTING = "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.";
+var READABLE_REPORT = "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background and repetition. Use complete, readable sentences rather than compressed fragments.";
+function taggedPrompt(sections) {
+  return sections.map(([tag, content]) => `<${tag}>
+${content.trim()}
+</${tag}>`).join(`
+
+`);
+}
+function renderIterationPrompt(options) {
+  return taggedPrompt([
+    ["progress_ledger", `Read ${options.ledgerPath} first. It is the durable source of truth for attempted work, findings, failures, validation evidence, and remaining work.`],
+    ["role", "You are the active worker in a bounded evidence-driven completion loop."],
+    ["iteration", `${options.iteration} of ${options.maxIterations}`],
+    ["success_criteria", "This iteration makes measurable progress or supplies decisive evidence that the explicit objective is complete."],
+    ["requirements", [
+      "Select the highest-value unfinished item supported by the ledger and current state.",
+      "Perform concrete work; do not merely restate the objective or ledger.",
+      "Avoid repeating failed approaches unless new evidence justifies the retry.",
+      "Run the strongest practical validation for the work completed in this iteration.",
+      "Report exactly what changed, evidence gathered, failures encountered, and what remains.",
+      GROUNDED_REPORTING
+    ].join(`
+`)],
+    ["stop_rules", "End this iteration after delivering measurable progress, or after evidence shows the objective is complete."],
+    ["output_format", `Markdown with Work performed, Changes, Validation evidence, New findings, Failures, and Remaining work. ${READABLE_REPORT}`],
+    ["objective", options.task]
+  ]);
+}
+function renderEvaluationPrompt(options) {
+  return taggedPrompt([
+    ["artifacts", [
+      `Durable progress ledger: ${options.ledgerPath}`,
+      `Current iteration artifact: ${options.iterationPath}`,
+      "Read both files before deciding."
+    ].join(`
+`)],
+    ["role", "You are an independent completion evaluator. Judge evidence, not the worker's confidence."],
+    ["stop_condition", [
+      "Set done=true only when the objective is fully satisfied and current validation evidence proves it.",
+      "Set done=false when any required behavior, validation, cleanup, or evidence remains missing or uncertain.",
+      "Do not invent requirements beyond the objective."
+    ].join(`
+`)],
+    ["evidence_rules", [
+      "List concrete validation evidence supporting the decision, including commands and observed output; cite file:line where applicable.",
+      "Record new findings and failures distinctly.",
+      "When incomplete, state actionable remaining work for the next iteration.",
+      GROUNDED_REPORTING
+    ].join(`
+`)],
+    ["success_criteria", `The iteration ${options.iteration} decision is reproducible from cited artifact evidence.`],
+    ["output_format", `Return only the required structured decision with done, summary, new_findings, failures, validation_evidence, and remaining_work. ${READABLE_REPORT}`],
+    ["objective", options.task]
+  ]);
+}
+function renderCompletionPrompt(options) {
+  return taggedPrompt([
+    ["artifacts", `Read the complete ledger at ${options.ledgerPath} and final iteration artifact at ${options.iterationPath}.`],
+    ["role", "You are the final completion reporter."],
+    ["requirements", [
+      "Summarize the delivered outcome without adding unsupported claims.",
+      "Cite the validation evidence that satisfied the stop condition.",
+      "List artifact paths needed to audit the work.",
+      "Report residual risks even when no work remains.",
+      GROUNDED_REPORTING
+    ].join(`
+`)],
+    ["success_criteria", "The final report is evidence-backed and independently auditable from the ledger."],
+    ["stop_rules", "Stop after accounting for the outcome, supporting evidence, audit artifacts, residual risks, and any remaining work."],
+    ["output_format", `Markdown with Outcome, Evidence, Artifacts, Residual risks, and Remaining work (None). ${READABLE_REPORT}`],
+    ["objective", options.task]
+  ]);
+}
+
+// dist/builtin/workflows/builtin/loop-until-done-runner.ts
+var PROGRESS_DISCLAIMER = "Progress scores are a monitoring signal; VOC separation +0.079; never authoritative.";
+var evaluationSchema = Type.Object({
+  done: Type.Boolean(),
+  summary: Type.String(),
+  new_findings: Type.Array(Type.String()),
+  failures: Type.Array(Type.String()),
+  validation_evidence: Type.Array(Type.String()),
+  remaining_work: Type.String()
+}, { additionalProperties: false });
+function progressCurve(entries) {
+  return entries.flatMap((entry) => entry.progress === undefined ? [] : [entry.progress.score]);
+}
+function progressReport(entries) {
+  const curve = progressCurve(entries);
+  return { curve, trend: classify_trend(curve).trend };
+}
+function formatProgressReport(report) {
+  return [
+    `Progress curve: ${JSON.stringify(report.curve)}`,
+    `Final trend: ${report.trend}`,
+    PROGRESS_DISCLAIMER
+  ].join(`
+`);
+}
+function repeatCount(input) {
+  const repeats = input.progress_repeats;
+  return typeof repeats === "number" && Number.isInteger(repeats) && repeats > 0 ? repeats : 1;
+}
+async function scoreIteration(ctx, task, entries, repeats) {
+  try {
+    const curve = await score_progress(ctx, {
+      problem: task,
+      steps: entries.map((entry) => entry.summary),
+      checkpoints: [entries.length],
+      repeats
+    });
+    const score = curve.scores[0];
+    if (score === null || score === undefined)
+      return;
+    const trend = classify_trend([...progressCurve(entries), score]);
+    return {
+      score,
+      perRepeat: curve.perRepeat,
+      trend: trend.trend,
+      window: trend.evidence.window
+    };
+  } catch {
+    return;
+  }
+}
+function serializableObject(value) {
+  if (value === null || Array.isArray(value) || typeof value !== "object")
+    return;
+  return value;
+}
+function stringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
+}
+function evaluationFrom(result) {
+  const value = serializableObject(result.structured);
+  if (value === undefined) {
+    throw new Error(`loop-until-done: evaluator ${result.stageName} did not return a structured decision`);
+  }
+  const done = value.done;
+  const summary = value.summary;
+  const newFindings = stringArray(value.new_findings);
+  const failures = stringArray(value.failures);
+  const validationEvidence = stringArray(value.validation_evidence);
+  const remainingWork = value.remaining_work;
+  if (typeof done !== "boolean" || typeof summary !== "string" || newFindings === undefined || failures === undefined || validationEvidence === undefined || typeof remainingWork !== "string") {
+    throw new Error(`loop-until-done: evaluator ${result.stageName} returned an invalid decision`);
+  }
+  return { done, summary, newFindings, failures, validationEvidence, remainingWork };
+}
+async function writeLedger(path, task, maxIterations, status, entries) {
+  const report = progressReport(entries);
+  await writeFile(path, `${JSON.stringify({
+    task,
+    max_iterations: maxIterations,
+    status,
+    iterations_completed: entries.length,
+    entries,
+    progress_curve: report.curve,
+    final_trend: report.trend,
+    progress_disclaimer: PROGRESS_DISCLAIMER
+  }, null, 2)}
+`);
+}
+async function runLoopUntilDone(ctx) {
+  const artifactDir = await stableArtifactRoot(ctx, "loop-until-done");
+  const iterationsDir = join(artifactDir, "iterations");
+  const evaluationsDir = join(artifactDir, "evaluations");
+  await mkdir(iterationsDir, { recursive: true });
+  await mkdir(evaluationsDir, { recursive: true });
+  const ledgerPath = join(artifactDir, "progress-ledger.json");
+  const entries = [];
+  const iterationArtifactPaths = [];
+  const evaluationArtifactPaths = [];
+  await writeLedger(ledgerPath, ctx.inputs.prompt, ctx.inputs.max_iterations, "active", entries);
+  for (let iteration = 1;iteration <= ctx.inputs.max_iterations; iteration += 1) {
+    const iterationPath = join(iterationsDir, `iteration-${iteration}.md`);
+    const evaluationPath = join(evaluationsDir, `evaluation-${iteration}.json`);
+    iterationArtifactPaths.push(iterationPath);
+    evaluationArtifactPaths.push(evaluationPath);
+    await ctx.task(`iteration-${iteration}`, {
+      prompt: renderIterationPrompt({
+        task: ctx.inputs.prompt,
+        iteration,
+        maxIterations: ctx.inputs.max_iterations,
+        ledgerPath
+      }),
+      context: "fresh",
+      reads: [ledgerPath, ...iteration > 1 ? [iterationArtifactPaths[iteration - 2]] : []],
+      output: iterationPath,
+      outputMode: "file-only"
+    });
+    const evaluator = await ctx.task(`evaluate-${iteration}`, {
+      prompt: renderEvaluationPrompt({
+        task: ctx.inputs.prompt,
+        iteration,
+        ledgerPath,
+        iterationPath
+      }),
+      context: "fresh",
+      reads: [ledgerPath, iterationPath],
+      schema: evaluationSchema
+    });
+    const decision = evaluationFrom(evaluator);
+    await writeFile(evaluationPath, `${JSON.stringify(evaluator.structured, null, 2)}
+`);
+    const entry = {
+      iteration,
+      artifact_path: iterationPath,
+      evaluation_artifact_path: evaluationPath,
+      summary: decision.summary,
+      findings: decision.newFindings,
+      failures: decision.failures,
+      validation_evidence: decision.validationEvidence,
+      done: decision.done,
+      remaining_work: decision.remainingWork
+    };
+    entries.push(entry);
+    if (ctx.inputs.progress_scoring !== false) {
+      const progress = await scoreIteration(ctx, ctx.inputs.prompt, entries, repeatCount(ctx.inputs));
+      if (progress !== undefined)
+        entries[entries.length - 1] = { ...entry, progress };
+    }
+    await writeLedger(ledgerPath, ctx.inputs.prompt, ctx.inputs.max_iterations, decision.done ? "complete" : "active", entries);
+    if (decision.done) {
+      const report2 = progressReport(entries);
+      const resultPath = join(artifactDir, "result.md");
+      const final = await ctx.task("completion-summary", {
+        prompt: renderCompletionPrompt({ task: ctx.inputs.prompt, ledgerPath, iterationPath }),
+        context: "fresh",
+        reads: [ledgerPath, iterationPath],
+        output: resultPath,
+        outputMode: "file-only"
+      });
+      const result2 = `${final.text ? `${final.text.trimEnd()}
+
+` : ""}${formatProgressReport(report2)}
+`;
+      return {
+        result: result2,
+        status: "complete",
+        iterations_completed: iteration,
+        ledger_path: ledgerPath,
+        iteration_artifact_paths: iterationArtifactPaths,
+        evaluation_artifact_paths: evaluationArtifactPaths,
+        result_path: resultPath,
+        remaining_work: "",
+        artifact_dir: artifactDir,
+        progress_curve: report2.curve,
+        final_trend: report2.trend,
+        progress_disclaimer: PROGRESS_DISCLAIMER
+      };
+    }
+  }
+  const last = entries.at(-1);
+  const report = progressReport(entries);
+  await writeLedger(ledgerPath, ctx.inputs.prompt, ctx.inputs.max_iterations, "failed", entries);
+  const result = [
+    `Iteration limit exhausted after ${ctx.inputs.max_iterations} iterations. Inspect ${ledgerPath}.`,
+    formatProgressReport(report)
+  ].join(`
+
+`);
+  return {
+    result,
+    status: "failed",
+    iterations_completed: ctx.inputs.max_iterations,
+    ledger_path: ledgerPath,
+    iteration_artifact_paths: iterationArtifactPaths,
+    evaluation_artifact_paths: evaluationArtifactPaths,
+    result_path: ledgerPath,
+    remaining_work: last.remaining_work,
+    artifact_dir: artifactDir,
+    progress_curve: report.curve,
+    final_trend: report.trend,
+    progress_disclaimer: PROGRESS_DISCLAIMER
+  };
+}
+
+// dist/builtin/workflows/builtin/loop-until-done.ts
+var loop_until_done_default = workflow({
+  name: "loop-until-done",
+  description: "Repeat evidence-producing work and independent completion evaluation against a durable ledger until done or an inspectable iteration-limit failure.",
+  heartbeatIntervalMinutes: 15,
+  inputs: {
+    prompt: Type2.String({ description: "Objective whose explicit completion condition controls the bounded loop." }),
+    max_iterations: Type2.Integer({
+      minimum: 1,
+      maximum: 20,
+      default: 5,
+      description: "Maximum work/evaluation iterations before returning an inspectable failed status (1-20)."
+    }),
+    progress_scoring: Type2.Boolean({
+      default: true,
+      description: "Enable advisory progress scoring after each completed iteration."
+    }),
+    progress_repeats: Type2.Integer({
+      minimum: 1,
+      default: 1,
+      description: "Number of advisory progress-scoring repeats per iteration."
+    })
+  },
+  outputs: {
+    result: Type2.String({ description: "Compact reference to the evidence-backed completion report, or the deterministic exhaustion report; read `result_path` for the full report." }),
+    status: Type2.Union([Type2.Literal("complete"), Type2.Literal("failed")], {
+      description: "Complete when evidence satisfies the stop condition; failed when max_iterations is exhausted."
+    }),
+    iterations_completed: Type2.Integer({ description: "Number of completed work/evaluation iterations." }),
+    ledger_path: Type2.String({ description: "Path to the durable JSON progress ledger." }),
+    iteration_artifact_paths: Type2.Array(Type2.String(), { description: "Ordered paths to per-iteration work artifacts." }),
+    evaluation_artifact_paths: Type2.Array(Type2.String(), { description: "Ordered paths to structured evaluation artifacts." }),
+    result_path: Type2.String({ description: "Path to the final report, or the ledger on exhausted failure." }),
+    remaining_work: Type2.String({ description: "Actionable remaining work; empty only after proven completion." }),
+    artifact_dir: Type2.String({ description: "Run-specific directory containing loop artifacts." }),
+    progress_curve: Type2.Array(Type2.Number(), { description: "Advisory progress scores in iteration order." }),
+    final_trend: Type2.Union([Type2.Literal("rising"), Type2.Literal("flat"), Type2.Literal("regressing")], { description: "Final advisory trend classification; never a stop decision." }),
+    progress_disclaimer: Type2.String({ description: "Calibration disclaimer for the advisory progress signal." })
+  },
+  run: async (ctx) => await runLoopUntilDone(withSteeringPropagationContext(ctx))
+});
+
+export { loop_until_done_default };