The model fills in the form. Your code runs the program.

npx astralis templates
npx astralis init pipeline my-project
cd my-project
npm install https://github.com/astralisone/astralis-harness/releases/download/v0.1.0/astralis-harness-0.1.0.tgz

coding-task             Plan, edit with a bounded agent behind a strict tool policy and sandbox, then verify with a stronger model.
map-reduce              Fan out infer workers over a list with a concurrency cap, then merge the results.
pipeline                Classify an input, branch in code on the typed result, then summarise (infer plus plain code).
research-with-memory    Read memory, infer with a pinned skill, write memory back.

created my-project/astralis.config.json
created my-project/package.json
created my-project/README.md
created my-project/workflow.ts
next: edit astralis.config.json, then run `astralis doctor`

{
	"defaultModel": "local/EXAMPLE-replace-with-a-model-you-have-pulled",
	"builtinProviders": true,
	"providers": {
		"local": {
			"baseUrl": "http://127.0.0.1:11434/v1",
			"models": [
				{
					"id": "EXAMPLE-replace-with-a-model-you-have-pulled",
					"name": "Example local model (replace the id)",
					"contextWindow": 32768,
					"maxTokens": 8192
				}
			]
		}
	}
}

npx astralis doctor

[ ok ] Node.js version: Node 26.13.1 satisfies >=22.18.0.
[ ok ] Config file: ~/my-project/astralis.config.json is valid.
[ ok ] Provider "local" API key: No apiKeyEnv configured; the endpoint is treated as keyless.
[ ok ] Provider "local" endpoint: Reachable (HTTP 200). Server offers: qwen2.5-coder:7b. All configured models are offered.
[ ok ] Default model: local/qwen2.5-coder:7b is a configured model.
[ ok ] Sandbox (bubblewrap): /usr/bin/bwrap ran a command in the sandbox.
[ ok ] Runs directory: ~/my-project/.astralis/runs does not exist yet; it can be created under ~/my-project.
All checks passed.

[ ok ] Node.js version: Node 26.13.1 satisfies >=22.18.0.
[ ok ] Config file: ~/my-project/astralis.config.json is valid.
[FAIL] Provider "local" API key: LOCAL_API_KEY is not set.
       fix: Export LOCAL_API_KEY in the environment that runs astralis.
[FAIL] Provider "local" endpoint: GET http://127.0.0.1:11434/v1/models failed: fetch failed (connect ECONNREFUSED 127.0.0.1:11434)
       fix: Start the server at http://127.0.0.1:11434/v1, or correct baseUrl in the config.
[ ok ] Default model: local/qwen2.5-coder:7b is a configured model.
[ ok ] Sandbox (bubblewrap): /usr/bin/bwrap ran a command in the sandbox.
[ ok ] Runs directory: ~/my-project/.astralis/runs does not exist yet; it can be created under ~/my-project.
2 checks failed.

npx astralis run workflow.ts --input '{"text":"The export button crashes when the list is empty."}'

{
  "category": "bug",
  "summary": "The export button crashes when the list is empty."
}
journal: .astralis/runs/<run-id>/journal.jsonl

npx astralis journal .astralis/runs/<run-id>/journal.jsonl
npx astralis report  .astralis/runs/<run-id>/journal.jsonl -o run.html

   1  -       run_start            pipeline
   2  1       step_start           infer classify
   3  1       inference_request    faux/faux-1 108a8e1b31b0
   4  1       inference_response   faux/faux-1 stop=toolUse
   5  1       step_end             infer classify
   6  2       step_start           infer summarise
   7  2       inference_request    faux/faux-1 8b38c9d1ce93
   8  2       inference_response   faux/faux-1 stop=toolUse
   9  2       step_end             infer summarise
  10  -       run_end              pipeline

const Triage = Type.Object(
	{ urgency: Type.Union([Type.Literal("low"), Type.Literal("high")]), reason: Type.String() },
	{ additionalProperties: false },
);

export const triage = defineWorkflow({
	name: "triage",
	input: Type.Object({ ticket: Type.String() }),
	output: Type.Object({ reply: Type.String() }),
	async run(ctx, input) {
		// Step 1: the model fills in a typed form. That is all it can do.
		const verdict = await ctx.infer({
			name: "classify",
			prompt: `How urgent is this ticket?\n\n${input.ticket}`,
			output: Triage,
		});

		// What happens next is ordinary code reading a typed value. The model does not choose.
		if (verdict.urgency === "high") return { reply: "Escalated to the on-call engineer." };

		const draft = await ctx.infer({
			name: "draft-reply",
			prompt: `Write a short, friendly reply.\n\n${input.ticket}`,
			output: Type.Object({ text: Type.String() }),
		});
		return { reply: draft.text };
	},
});

export async function callOutsideAStep(): Promise<void> {
	const gateway = await createGatewayFromConfig(loadConfig());
	// Throws NoActiveStepError: this is plain program code, not a step.
	await gateway.structured({ model: "local/my-model", prompt: "hello", output: Type.Object({ ok: Type.Boolean() }) });
}

same path, different results: 1 difference(s)
first divergence at step 2: Step 2, model call 0: same request, different response.
  [different_response] step 2: Step 2, model call 0: same request, different response.

{"seq":1,"ts":"2026-01-01T00:00:00.000Z","runId":"<run-id>","type":"run_start","data":{"workflow":"pipeline","input":{"text":"The export button crashes when the list is empty."}}}
{"seq":2,"ts":"2026-01-01T00:00:00.000Z","runId":"<run-id>","type":"step_start","stepId":"1","data":{"kind":"infer","name":"classify"}}

// removed: matched the start of the command
{ kind: "command", arg: "command", prefix: "git" }

safeBash.check("bash", { command: "git -c alias.x=!touch x x" })
// { allowed: false, reason: 'bash: command contains characters outside the permitted set: "git -c alias.x=!touch x x"' }

safeBash.check("bash", { command: "git diff --stat" })   // { allowed: true }
safeBash.check("bash", { command: "npm test; rm -rf ." })  // refused: ";" is not a permitted character

import { buildTools, connectMcp, createToolPolicy } from "astralis-harness";

export async function ticketTools() {
	// Servers get only the environment the config gives them; nothing is inherited from this process.
	const connection = await connectMcp({ tickets: { command: "node", args: ["tickets-server.js"] } });
	// Tool names are mcp__<server>__<tool>. This lists what the server offers, for building the allowlist.
	console.error(connection.toolNames());

	const policy = createToolPolicy({
		allow: {
			mcp__tickets__search: [{ kind: "pattern", arg: "query", patterns: [/[A-Za-z0-9 ]{1,80}/] }],
		},
	});
	const tools = buildTools({ cwd: process.cwd(), mcp: { connection, allow: ["mcp__tickets__search"] }, policy });
	// Pass `tools` to ctx.agent or ctx.tool, and close the connection when the run is over.
	return { tools, close: () => connection.close() };
}

{
	"defaultModel": "local/EXAMPLE-replace-with-a-model-you-have-pulled",
	"builtinProviders": true,
	"providers": {
		"local": {
			"baseUrl": "http://127.0.0.1:11434/v1",
			"models": [
				{
					"id": "EXAMPLE-replace-with-a-model-you-have-pulled",
					"name": "Example local model (Ollama)",
					"contextWindow": 32768,
					"maxTokens": 8192
				}
			]
		}
	},
	"tui": {
		"maxTurns": 20,
		"tools": ["read", "ls", "grep", "find"],
		"mods": [],
		"loadContextFiles": false
	}
}

{
	"defaultModel": "anthropic/claude-sonnet-5-5",
	"builtinProviders": true,
	"providers": {}
}

{
	"defaultModel": "ollama/qwen2.5-coder:7b",
	"builtinProviders": true,
	"providers": {
		"ollama": {
			"baseUrl": "http://127.0.0.1:11434/v1",
			"models": [
				{ "id": "qwen2.5-coder:7b", "contextWindow": 32768, "maxTokens": 8192 }
			]
		}
	}
}

const Plan = Type.Object({ steps: Type.Array(Type.String()) }, { additionalProperties: false });

export const plan = defineWorkflow({
	name: "plan-and-write",
	input: Type.Object({ goal: Type.String() }),
	output: Type.Object({ text: Type.String() }),
	async run(ctx, input) {
		// A small local model for the cheap structured step...
		const steps = await ctx.infer({ name: "plan", model: "ollama/qwen2.5-coder:7b", prompt: `Plan: ${input.goal}`, output: Plan });
		// ...and a hosted frontier model, through builtinProviders, for the part that needs it.
		return ctx.infer({
			name: "write",
			model: "anthropic/claude-sonnet-5-5",
			prompt: `Write it up.\n\n${steps.steps.join("\n")}`,
			output: Type.Object({ text: Type.String() }),
		});
	},
});

import { resolve } from "node:path";
import { buildTools, createToolPolicy, defineWorkflow, StepError, Type } from "astralis-harness";

const workspace = resolve(process.cwd());
const policy = createToolPolicy({
	allow: {
		read: [{ kind: "path", arg: "path", root: workspace, allow: ["src/**"] }],
		grep: [{ kind: "path", arg: "path", root: workspace, allow: ["src", "src/**"], default: "src" }],
	},
});
// One toolbox is fine to share: each agent step gets its own loop, journal events and turn count.
const tools = buildTools({ cwd: workspace, builtin: ["read", "grep"], policy });

const Report = Type.Object({ module: Type.String(), risks: Type.Array(Type.String()), ok: Type.Boolean() }, { additionalProperties: false });

export default defineWorkflow({
	name: "inspect-modules",
	input: Type.Object({ modules: Type.Array(Type.String({ pattern: "^[a-z][a-z0-9-]*$" }), { minItems: 1 }) }),
	output: Type.Object({ reports: Type.Array(Report) }),
	async run(ctx, input) {
		// A "subagent" is just an agent step inside a fanout worker, with its own tools and turn cap.
		const reports = await ctx.fanout({
			name: "inspect-each",
			items: input.modules,
			concurrency: 2,
			worker: async (module) => {
				try {
					return await ctx.agent({
						name: `inspect-${module}`,
						prompt: `Inspect src/${module}. List real risks you can point to in the code.`,
						output: Report,
						tools,
						maxTurns: 6,
					});
				} catch (error) {
					// Explicit partial results: this one worker is allowed to fail without failing the batch.
					// The failed step is still in the journal as a step_error; nothing is hidden.
					if (error instanceof StepError) return { module, risks: [error.message], ok: false };
					throw error;
				}
			},
		});
		return { reports };
	},
});

import { defineWorkflow, Type } from "astralis-harness";

const Finding = Type.Object({ file: Type.String(), issues: Type.Array(Type.String()) }, { additionalProperties: false });

// A fixed number of workers in parallel, then one stronger model checks the merged result.
export default defineWorkflow({
	name: "review-files",
	input: Type.Object({ files: Type.Array(Type.Object({ path: Type.String(), text: Type.String() }), { minItems: 1 }) }),
	output: Type.Object({ findings: Type.Array(Finding), verifierNotes: Type.Array(Type.String()) }),
	async run(ctx, input) {
		const findings = await ctx.fanout({
			name: "review-each",
			items: input.files,
			concurrency: 4,
			// The workers use a small, fast model. Each is its own journaled step.
			worker: (file) =>
				ctx.infer({
					name: `review-${file.path}`,
					model: "local/small",
					prompt: `List concrete problems in this file, or none.\n\n${file.text}`,
					output: Finding,
				}),
		});

		const verifierNotes = await ctx.verify({
			name: "check-review",
			// The checker is a different, stronger model than the one that produced the work.
			model: "local/strong",
			claim: "Every reported issue is real, and no file with a serious problem was reported clean.",
			evidence: JSON.stringify({ findings, files: input.files }),
		});
		return { findings, verifierNotes };
	},
});

import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { defineWorkflow, loadSkill, MemoryStore, renderSkills, Type } from "astralis-harness";

const here = dirname(fileURLToPath(import.meta.url));

// Pinned: if skills/research-method/SKILL.md changes, the run fails instead of silently behaving differently.
// After editing the skill on purpose, get the new hash with `sha256sum skills/<name>/SKILL.md` (or read the "found" value in the mismatch error) and update it here.
const SKILL_SHA256 = "d6a9f1ffdbca823fa1ea0b2a39d8581951e202bcf20d5c421911852d1b7d1af7";

// Notes persist between runs in this directory, one JSON file per key.
const store = new MemoryStore(join(here, ".astralis", "memory"));

const Notes = Type.Object({ notes: Type.Array(Type.String()) }, { additionalProperties: false });
const Answer = Type.Object({ answer: Type.String(), newNote: Type.String() }, { additionalProperties: false });

export default defineWorkflow({
	name: "research-with-memory",
	input: Type.Object({ question: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
	output: Type.Object({ answer: Type.String(), notesKept: Type.Integer() }, { additionalProperties: false }),
	async run(ctx, input) {
		const memory = await ctx.memoryRead({ name: "read-notes", store, key: "notes", schema: Notes });
		const notes = memory?.notes ?? [];

		const skill = loadSkill("research-method", [join(here, "skills")], SKILL_SHA256);

		const result = await ctx.infer({
			name: "answer",
			system: renderSkills([skill]),
			prompt: `Earlier notes:\n${notes.length === 0 ? "(none)" : notes.map((n) => `- ${n}`).join("\n")}\n\nQuestion: ${input.question}`,
			output: Answer,
		});

		const updated = [...notes, result.newNote];
		await ctx.memoryWrite({ name: "write-notes", store, key: "notes", schema: Notes, value: { notes: updated } });
		return { answer: result.answer, notesKept: updated.length };
	},
});

---
name: research-method
description: How to answer a question using earlier notes and record one new note.
---

# Research method

1. Check the earlier notes first. If they answer the question, use them and say so.
2. Separate what you know from what you are guessing. Mark guesses as guesses.
3. Answer in a short paragraph.
4. Write one new note: a single self-contained sentence a later run can rely on without this question.

sha256sum skills/research-method/SKILL.md

const started = new Map<string, number>();

export const timing = new HookRegistry()
	.beforeStep(({ stepId }) => {
		started.set(stepId, performance.now());
	})
	.afterStep(({ stepId, kind, name }) => {
		const ms = Math.round(performance.now() - (started.get(stepId) ?? performance.now()));
		console.error(`step ${stepId} ${kind} ${name}: ${ms} ms`);
	});

export const logging = new HookRegistry().onStepError(({ stepId, kind, name, error }) => {
	// `error` is a frozen snapshot (name, message, stack, details, cause), never the live error object.
	appendFileSync("failures.jsonl", `${JSON.stringify({ stepId, kind, name, error })}\n`);
});

export const readOnly = new HookRegistry().beforeStep(({ kind, name, stepId }) => {
	// Throwing from a hook fails the step it ran in, and the journal records why.
	if (kind === "memory" && name.startsWith("write-")) {
		throw new AstralisError(`Step ${stepId} (${name}) is a memory write, and this run is read-only.`, { stepId, name });
	}
});

// Cache by input: the key is a hash, so it always satisfies the key rules (letters, digits, . _ -).
const key = `answer-${createHash("sha256").update(input.question).digest("hex").slice(0, 32)}`;
const hit = await ctx.memoryRead({ name: "read-cache", store, key, schema: Cached });
if (hit !== undefined) return { answer: hit.answer, cached: true };

const fresh = await ctx.infer({ name: "answer", prompt: input.question, output: Cached });
await ctx.memoryWrite({ name: "write-cache", store, key, schema: Cached, value: fresh });

// A log is read-modify-write. There is no locking, so run one writer at a time.
const log = (await ctx.memoryRead({ name: "read-log", store, key: "log", schema: Log })) ?? { entries: [] };
await ctx.memoryWrite({ name: "write-log", store, key: "log", schema: Log, value: { entries: [...log.entries, input.question] } });

/**
 * Example Astralis mod: a `/hello [name]` slash command that shows a greeting in a
 * widget under the editor, plus a `/hello-clear` command that removes it.
 *
 * Install (the mod is loaded only from these two places, never from Pi's own
 * global or project extension directories):
 *
 *   mkdir -p .astralis/mods
 *   cp examples/mods/hello-mod.ts .astralis/mods/
 *
 * or list it in astralis.config.json:  { "tui": { "mods": ["examples/mods/hello-mod.ts"] } }
 *
 * Then run `astralis tui`. Startup prints every mod it loads.
 *
 * TRUST: a mod is ordinary code in the astralis process, with full permissions. The
 * harness's tool allowlist and turn cap apply to the chat model, not to a mod: this
 * file could just as well write files, run commands or call a model directly, and
 * nothing would stop or journal it. Read a mod before you install it.
 */
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

const WIDGET_KEY = "hello-mod";

export default function helloMod(pi: ExtensionAPI): void {
	pi.registerCommand("hello", {
		description: "Greet someone in a widget: /hello [name]",
		handler: async (args, ctx) => {
			const name = args.trim() === "" ? "world" : args.trim();
			ctx.ui.setWidget(WIDGET_KEY, [`Hello, ${name}! (from examples/mods/hello-mod.ts)`], { placement: "belowEditor" });
			ctx.ui.notify(`hello-mod: greeted ${name}`, "info");
		},
	});

	pi.registerCommand("hello-clear", {
		description: "Remove the hello widget",
		handler: async (_args, ctx) => {
			ctx.ui.setWidget(WIDGET_KEY, undefined);
		},
	});
}

mkdir -p .astralis/mods
cp examples/mods/hello-mod.ts .astralis/mods/
astralis tui

/**
 * A second mod, building on hello-mod: it counts completed chat turns and shows the count in the status
 * line. Like every mod it is ordinary code in the astralis process; read mods before you install them.
 */
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

const STATUS_KEY = "counter-mod";

export default function counterMod(pi: ExtensionAPI): void {
	let turns = 0;

	pi.on("session_start", async (_event, ctx) => {
		turns = 0;
		ctx.ui.setStatus(STATUS_KEY, "counter-mod: 0 turns");
	});

	pi.on("turn_end", async (event, ctx) => {
		// Pi starts one more request after an abort; it ends "aborted" and is not a real turn.
		if (event.outcome !== "completed") return;
		turns += 1;
		ctx.ui.setStatus(STATUS_KEY, `counter-mod: ${turns} turns`);
	});

	pi.registerCommand("turns", {
		description: "Show how many turns this session has taken",
		handler: async (_args, ctx) => {
			ctx.ui.notify(`${turns} completed turn(s) so far`, "info");
		},
	});
}

import { defineWorkflow, SchemaValidationError, StepError, Type } from "astralis-harness";

const Answer = Type.Object({ label: Type.Union([Type.Literal("yes"), Type.Literal("no")]) }, { additionalProperties: false });

// The harness never retries for you. If you want a retry, it is a loop you can read, with a cap.
const MAX_ATTEMPTS = 3;

export default defineWorkflow({
	name: "retry-with-cap",
	input: Type.Object({ question: Type.String({ minLength: 1 }) }),
	output: Type.Object({ label: Type.String(), attempts: Type.Integer() }),
	async run(ctx, input) {
		let lastFailure: unknown;
		for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
			try {
				// A different name per attempt, so the journal shows every try as its own step.
				const result = await ctx.infer({ name: `answer-attempt-${attempt}`, prompt: input.question, output: Answer });
				return { label: result.label, attempts: attempt };
			} catch (error) {
				// Retry only the failure you expect. Anything else (a network error, a policy refusal) propagates.
				if (error instanceof StepError && error.cause instanceof SchemaValidationError) {
					lastFailure = error;
					continue;
				}
				throw error;
			}
		}
		throw lastFailure;
	},
});

import { defineWorkflow, Type } from "astralis-harness";

const CHEAP = "ollama/qwen2.5-coder:7b";
const STRONG = "anthropic/claude-sonnet-5-5";

export default defineWorkflow({
	name: "model-per-step",
	input: Type.Object({ text: Type.String({ minLength: 1 }) }),
	output: Type.Object({ category: Type.String(), answer: Type.String() }),
	async run(ctx, input) {
		// Routing is easy: a small local model is enough.
		const route = await ctx.infer({
			name: "route",
			model: CHEAP,
			prompt: `Is this a billing question or a technical question?\n\n${input.text}`,
			output: Type.Object({ category: Type.Union([Type.Literal("billing"), Type.Literal("technical")]) }),
		});
		// Writing the answer is the hard part, so only this step pays for the stronger model.
		const answer = await ctx.infer({
			name: "answer",
			model: STRONG,
			prompt: `Answer this ${route.category} question.\n\n${input.text}`,
			output: Type.Object({ text: Type.String() }),
		});
		return { category: route.category, answer: answer.text };
	},
});

import { AstralisError, defineWorkflow, StepError, Type, VerificationFailedError } from "astralis-harness";

// Cheapest first. The verifier is always the strongest model, never the one that wrote the draft.
const WRITERS = ["ollama/qwen2.5-coder:7b", "ollama/qwen2.5-coder:32b", "anthropic/claude-sonnet-5-5"] as const;
const VERIFIER = "anthropic/claude-sonnet-5-5";

export default defineWorkflow({
	name: "escalate-on-verify-fail",
	input: Type.Object({ source: Type.String({ minLength: 1 }) }),
	output: Type.Object({ summary: Type.String(), writtenBy: Type.String() }),
	async run(ctx, input) {
		for (const [i, model] of WRITERS.entries()) {
			const draft = await ctx.infer({
				name: `summarise-${i}`,
				model,
				prompt: `Summarise in three sentences.\n\n${input.source}`,
				output: Type.Object({ summary: Type.String() }),
			});
			try {
				await ctx.verify({
					name: `verify-${i}`,
					model: VERIFIER,
					claim: `This is an accurate summary: ${draft.summary}`,
					evidence: input.source,
				});
				return { summary: draft.summary, writtenBy: model };
			} catch (error) {
				// A failed verdict is an expected outcome here, so only that is handled. Anything else propagates.
				if (!(error instanceof StepError && error.cause instanceof VerificationFailedError)) throw error;
			}
		}
		throw new AstralisError("No model produced a summary the verifier accepted.", { tried: [...WRITERS] });
	},
});

import { resolve } from "node:path";
import { buildTools, createToolPolicy, defineWorkflow, Type } from "astralis-harness";

const workspace = resolve(process.cwd());
// The policy is the hard limit (only notes/ is writable); the approval is the human check inside it.
const policy = createToolPolicy({ allow: { write: [{ kind: "path", arg: "path", root: workspace, allow: ["notes/**"] }] } });
const tools = buildTools({ cwd: workspace, builtin: ["write"], policy });

export default defineWorkflow({
	name: "approve-before-write",
	input: Type.Object({ topic: Type.String({ minLength: 1 }), file: Type.String({ pattern: "^notes/[A-Za-z0-9._-]+\\.md$" }) }),
	output: Type.Object({ written: Type.String() }),
	async run(ctx, input) {
		const draft = await ctx.infer({
			name: "draft-note",
			prompt: `Write a short note about ${input.topic}.`,
			output: Type.Object({ markdown: Type.String() }),
		});

		// Rejected, or nobody to ask: this throws and the write below never happens.
		await ctx.approve({ name: "approve-write", question: `Create ${input.file}?`, details: draft.markdown });

		await ctx.tool({ name: "write", args: { path: input.file, content: draft.markdown }, tools });
		return { written: input.file };
	},
});

import { randomUUID } from "node:crypto";
import { join } from "node:path";
import { AstralisError, createGatewayFromConfig, FileJournal, HookRegistry, type Journal, type JournalEvent, loadConfig, runWorkflow, type Workflow } from "astralis-harness";

/** Passes every event to the real journal and keeps a running total of the tokens the provider reported. */
class TokenCountingJournal implements Journal {
	totalTokens = 0;
	readonly inner: Journal;

	constructor(inner: Journal) {
		this.inner = inner;
	}

	append(event: JournalEvent): void {
		this.inner.append(event);
		if (event.type === "inference_response") {
			const usage = event.data.usage as { totalTokens?: unknown } | undefined;
			if (typeof usage?.totalTokens === "number") this.totalTokens += usage.totalTokens;
		}
	}
}

/** Runs a workflow and stops it at the first step boundary after `maxTokens` have been used. */
export async function runWithTokenCap(workflow: Workflow, input: unknown, maxTokens: number): Promise<unknown> {
	const config = loadConfig();
	const runId = randomUUID();
	const journal = new TokenCountingJournal(new FileJournal(join(".astralis", "runs", runId, "journal.jsonl")));
	const hooks = new HookRegistry().afterStep(({ stepId }) => {
		// A step that is already running is not interrupted: the cap bites when the step ends.
		if (journal.totalTokens > maxTokens) {
			throw new AstralisError(`Token cap of ${maxTokens} exceeded after step ${stepId}: ${journal.totalTokens} used.`, { maxTokens, used: journal.totalTokens });
		}
	});
	const gateway = await createGatewayFromConfig(config);
	const result = await runWorkflow(workflow, input, {
		gateway,
		journal,
		hooks,
		runId,
		...(config.defaultModel === undefined ? {} : { defaultModel: config.defaultModel }),
	});
	return result.output;
}

import { randomUUID } from "node:crypto";
import { join } from "node:path";
import { createGatewayFromConfig, FileJournal, loadConfig, runWorkflow, type Workflow } from "astralis-harness";

/** Runs one workflow against two models and prints the command that compares their journals. */
export async function runOnBoth(workflow: Workflow, input: unknown, models: readonly [string, string]): Promise<void> {
	const gateway = await createGatewayFromConfig(loadConfig());
	const journals: string[] = [];
	for (const model of models) {
		const runId = randomUUID();
		const path = join(".astralis", "runs", runId, "journal.jsonl");
		await runWorkflow(workflow, input, { gateway, defaultModel: model, journal: new FileJournal(path), runId });
		journals.push(path);
	}
	// The requests differ by design (the model is part of the hash). The diff shows where the paths split.
	console.log(`astralis diff ${journals.join(" ")}`);
	console.log(`astralis report ${journals[0]} -o a.html && astralis report ${journals[1]} -o b.html`);
}

import { defineWorkflow, MemoryStore, Type } from "astralis-harness";

const store = new MemoryStore(".astralis/memory/batch");
const Result = Type.Object({ summary: Type.String() }, { additionalProperties: false });

// There is no built-in resume. This makes a rerun skip the work a failed run already finished.
export default defineWorkflow({
	name: "resumable-batch",
	input: Type.Object({
		// Memory keys allow letters, digits, . _ - and must start with a letter or digit.
		items: Type.Array(Type.Object({ id: Type.String({ pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,100}$" }), text: Type.String() })),
	}),
	output: Type.Object({ summaries: Type.Array(Type.String()), reused: Type.Integer() }),
	async run(ctx, input) {
		const summaries: string[] = [];
		let reused = 0;
		for (const item of input.items) {
			const key = `done-${item.id}`;
			const saved = await ctx.memoryRead({ name: `check-${item.id}`, store, key, schema: Result });
			if (saved !== undefined) {
				summaries.push(saved.summary);
				reused += 1;
				continue;
			}
			const fresh = await ctx.infer({ name: `summarise-${item.id}`, prompt: `Summarise.\n\n${item.text}`, output: Result });
			// Written as soon as the item is done, so a crash on the next item loses nothing.
			await ctx.memoryWrite({ name: `save-${item.id}`, store, key, schema: Result, value: fresh });
			summaries.push(fresh.summary);
		}
		return { summaries, reused };
	},
});

import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { defineWorkflow, Type } from "astralis-harness";

const Invoice = Type.Object(
	{ vendor: Type.String(), total: Type.Number(), currency: Type.String({ minLength: 3, maxLength: 3 }) },
	{ additionalProperties: false },
);

export default defineWorkflow({
	name: "extract-invoices",
	input: Type.Object({ dir: Type.String({ minLength: 1 }) }),
	output: Type.Object({ invoices: Type.Array(Type.Object({ file: Type.String(), vendor: Type.String(), total: Type.Number(), currency: Type.String() })) }),
	async run(ctx, input) {
		// Listing a folder is ordinary code. Sort it, or the step ids depend on the filesystem's order.
		const files = readdirSync(input.dir).filter((f) => f.endsWith(".txt")).sort();

		const invoices = await ctx.fanout({
			name: "extract-each",
			items: files,
			concurrency: 3,
			worker: async (file) => {
				const fields = await ctx.infer({
					name: `extract-${file}`,
					prompt: `Extract the vendor, total and currency code.\n\n${readFileSync(join(input.dir, file), "utf8")}`,
					output: Invoice,
				});
				return { file, ...fields };
			},
		});
		return { invoices };
	},
});

import { createGatewayFromConfig, HookRegistry, loadConfig, PolicyError, runWorkflow, type Workflow } from "astralis-harness";

// Step names are your handle on a run, so they are also something a guard can match.
const BLOCKED = new Set(["publish", "send-email", "delete-branch"]);

export const guard = new HookRegistry().beforeStep(({ name, kind, stepId }) => {
	if (BLOCKED.has(name)) {
		throw new PolicyError(`Step ${stepId} (${kind} "${name}") is blocked by the run's guard hook.`, { stepId, name, kind });
	}
});

export async function runGuarded(workflow: Workflow, input: unknown): Promise<unknown> {
	const config = loadConfig();
	const result = await runWorkflow(workflow, input, {
		gateway: await createGatewayFromConfig(config),
		hooks: guard,
		...(config.defaultModel === undefined ? {} : { defaultModel: config.defaultModel }),
	});
	return result.output;
}

import assert from "node:assert/strict";
import { test } from "node:test";
import { createModels, fauxAssistantMessage, fauxProvider, fauxToolCall } from "@earendil-works/pi-ai";
import { defineWorkflow, Gateway, MemoryJournal, RESULT_TOOL, runWorkflow, stepSequence, Type } from "astralis-harness";

const workflow = defineWorkflow({
	name: "label-then-branch",
	input: Type.Object({ text: Type.String() }),
	output: Type.Object({ route: Type.String() }),
	async run(ctx, input) {
		const label = await ctx.infer({
			name: "label",
			prompt: input.text,
			output: Type.Object({ kind: Type.Union([Type.Literal("bug"), Type.Literal("question")]) }),
		});
		return { route: label.kind === "bug" ? "engineering" : "support" };
	},
});

test("a bug report is routed to engineering, with no network and no model", async () => {
	// Pi's scripted provider replays the answers you give it. The gateway recognises it by this api name.
	const faux = fauxProvider({ api: "faux" });
	const models = createModels();
	models.setProvider(faux.provider);
	const model = faux.getModel();
	faux.setResponses([fauxAssistantMessage(fauxToolCall(RESULT_TOOL, { kind: "bug" }), { stopReason: "toolUse" })]);

	const journal = new MemoryJournal();
	const result = await runWorkflow(workflow, { text: "It crashes" }, { gateway: new Gateway(models), defaultModel: `${model.provider}/${model.id}`, journal });

	assert.deepEqual(result.output, { route: "engineering" });
	// The path through the program is part of the contract too.
	assert.deepEqual(stepSequence(journal.events), ["1 infer label"]);
});

node --test cookbook-offline-test.ts

import { readFileSync } from "node:fs";

interface Line {
	type: string;
	stepId?: string;
	data: { model?: string; usage?: { totalTokens?: number } };
}

/** Total tokens per model from a journal file. The journal is plain JSON lines, so no harness import is needed. */
export function tokensByModel(journalPath: string): Map<string, number> {
	const totals = new Map<string, number>();
	for (const text of readFileSync(journalPath, "utf8").split("\n")) {
		if (text.trim() === "") continue;
		const event = JSON.parse(text) as Line;
		if (event.type !== "inference_response") continue;
		const model = event.data.model ?? "unknown";
		totals.set(model, (totals.get(model) ?? 0) + (event.data.usage?.totalTokens ?? 0));
	}
	return totals;
}

import { createToolPolicy } from "astralis-harness";

// Ask a policy what it would say, without running anything: handy in a unit test for your rules.
const policy = createToolPolicy({ allow: { bash: [{ kind: "command", arg: "command", commands: ["npm test"] }] } });

export const results = [
	policy.check("bash", { command: "npm test" }),
	policy.check("bash", { command: "npm test && curl example.com" }),
	policy.check("write", { path: "x", content: "y" }),
];

error: Step 1 (infer "classify") failed: Output of model faux/faux-1 does not match its schema: /category: must be equal to constant; /category: must be equal to constant; /category: must be equal to constant; /category: must match a schema in anyOf
failing step: 1 (infer "classify")
details: {
  "what": "Output of model faux/faux-1",
  "violations": [
    "/category: must be equal to constant",
    "/category: must be equal to constant",
    "/category: must be equal to constant",
    "/category: must match a schema in anyOf"
  ],
  "raw": {
    "category": "urgent",
    "reason": "It sounds important."
  }
}
caused by: SchemaValidationError: Output of model faux/faux-1 does not match its schema: /category: must be equal to constant; /category: must be equal to constant; /category: must be equal to constant; /category: must match a schema in anyOf
journal: .astralis/runs/<run-id>/journal.jsonl

   1  -       run_start            pipeline
   2  1       step_start           infer classify
   3  1       inference_request    faux/faux-1 108a8e1b31b0
   4  1       inference_response   faux/faux-1 stop=toolUse
   5  1       step_error           Step 1 (infer "classify") failed: Output of model faux/faux-1 does not match its schema: /category:…
   6  -       run_error            Step 1 (infer "classify") failed: Output of model faux/faux-1 does not match its schema: /category:…

jq -c 'select(.type=="step_error")' journal.jsonl
jq -c 'select(.stepId=="2")' journal.jsonl
jq -s '[.[] | select(.type=="inference_response") | .data.usage.totalTokens] | add' journal.jsonl

same path, different results: 1 difference(s)
first divergence at step 2: Step 2, model call 0: same request, different response.
  [different_response] step 2: Step 2, model call 0: same request, different response.

Usage: astralis [options] [command]

Run deterministic LLM workflows.

Options:
  -h, --help                              display help for command

Commands:
  run [options] <workflow-file>           Run a workflow file (a TypeScript module whose default export is made with defineWorkflow).
  tui [options]                           Interactive chat (Pi's TUI) under the harness: tool allowlist, turn cap, journaled prompts, /run for workflows.
  journal <journal-file>                  Print a one-line-per-event view of a run journal.
  doctor [options]                        Check the config, model endpoints, API key variables and the sandbox, with a fix for each problem.
  templates                               List the starter projects that `astralis init` can create.
  init <template> [dir]                   Create a starter project from a template. Never overwrites an existing file.
  report [options] <journal-file>         Write a self-contained HTML report of a run from its journal.
  diff [options] <journal-a> <journal-b>  Compare two runs: did they take the same path, and where did they first diverge?
  help [command]                          display help for command

Usage: astralis run [options] <workflow-file>

Run a workflow file (a TypeScript module whose default export is made with
defineWorkflow).

Options:
  --input <json>         workflow input as JSON
  --input-file <path>    read the workflow input JSON from a file
  --config <path>        config file (default: astralis.config.json)
  --model <provider/id>  default model for steps that name none
  --runs-dir <dir>       where journals are written (default: .astralis/runs)
  -h, --help             display help for command

astralis run workflow.ts --input '{"text":"hello"}'
astralis run workflow.ts --input-file input.json --model local/qwen --runs-dir /tmp/runs

Usage: astralis tui [options]

Interactive chat (Pi's TUI) under the harness: tool allowlist, turn cap,
journaled prompts, /run for workflows.

Options:
  --config <path>        config file (default: astralis.config.json)
  --model <provider/id>  chat model (default: defaultModel from the config)
  --runs-dir <dir>       where journals are written (default: .astralis/runs)
  --no-mods              do not load any mods
  -h, --help             display help for command

astralis tui
astralis tui --model anthropic/claude-sonnet-5-5 --no-mods

Usage: astralis journal [options] <journal-file>

Print a one-line-per-event view of a run journal.

Options:
  -h, --help  display help for command

astralis journal .astralis/runs/<run-id>/journal.jsonl

Usage: astralis doctor [options]

Check the config, model endpoints, API key variables and the sandbox, with a fix
for each problem.

Options:
  --config <path>   config file (default: astralis.config.json)
  --runs-dir <dir>  where journals are written (default: .astralis/runs)
  --offline         skip checks that contact model endpoints
  -h, --help        display help for command

astralis doctor
astralis doctor --offline --config ./astralis.config.json

Usage: astralis templates [options]

List the starter projects that `astralis init` can create.

Options:
  -h, --help  display help for command

astralis templates

Usage: astralis init [options] <template> [dir]

Create a starter project from a template. Never overwrites an existing file.

Arguments:
  template
  dir         target directory (default: ".")

Options:
  -h, --help  display help for command

astralis init pipeline my-project
astralis init coding-task .

Usage: astralis report [options] <journal-file>

Write a self-contained HTML report of a run from its journal.

Options:
  -o, --out <file>  output file (default: run-<runId>.html)
  -h, --help        display help for command

astralis report .astralis/runs/<run-id>/journal.jsonl -o run.html

Usage: astralis diff [options] <journal-a> <journal-b>

Compare two runs: did they take the same path, and where did they first diverge?

Options:
  --json      print the full comparison as JSON
  -h, --help  display help for command

astralis diff a/journal.jsonl b/journal.jsonl
astralis diff a/journal.jsonl b/journal.jsonl --json