scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-10-07 03:00:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Merge remote-tracking branch 'origin/main' into feat/backward-event-pagination

Browse source 
Resolved conflicts against main's shared-projection-cache rework:
- projection_cache.rs: kept main's projection_snapshot and dropped this
  branch's last_seq accessor, which it subsumes; latest_event_seq now
  reads the sequence from projection_snapshot.
- run_store.rs: kept main's EventScan cursor and added a seek_before
  constructor so the backward-pagination range scan bounds its end key
  through the same abstraction.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Bryan Helmkamp 2026-07-24 09:57:15 -04:00
commit ec100fca2b
No known key found for this signature in database
115 changed files with 3289 additions and 4256 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.env.example
View file

@ -1,6 +1,7 @@
ANTHROPIC_API_KEY=
BRAVE_SEARCH_API_KEY=
DAYTONA_API_KEY=
FIREWORKS_API_KEY=
GEMINI_API_KEY=
INCEPTION_API_KEY=
KIMI_API_KEY=

77
apps/fabro-web/app/components/stage-renderers/fan-in-results.test.tsx Normal file
View file

@ -0,0 +1,77 @@
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import type { EventEnvelope } from "@qltysh/fabro-api-client";
import TestRenderer, { act } from "react-test-renderer";
import { makeEventEnvelope, setupReactTestEnv } from "../../lib/test-utils";
import type { Stage } from "../stage-sidebar";
import { FanInResults } from "./fan-in-results";
let teardown: () => void;
beforeEach(() => {
teardown = setupReactTestEnv();
});
afterEach(() => teardown());
const fanInStage: Stage = {
id: "join@1",
name: "join",
handler: "parallel.fan_in",
status: "succeeded",
duration: "1s",
nodeId: "join",
visit: 1,
startedAt: "2026-04-09T12:00:00Z",
providerUsed: null,
};
function event(seq: number, partial: Partial<EventEnvelope>): EventEnvelope {
return makeEventEnvelope(seq, { stage_id: "join@1", ...partial });
}
function renderFanIn(events: EventEnvelope[]): string {
(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
let renderer!: TestRenderer.ReactTestRenderer;
act(() => {
renderer = TestRenderer.create(<FanInResults stage={fanInStage} events={events} />);
});
return JSON.stringify(renderer.toJSON());
}
describe("FanInResults", () => {
test("renders a neutral joined state without best-branch selection UI", () => {
const rendered = renderFanIn([]);
expect(rendered).toContain("Joined");
expect(rendered).not.toContain("Selected branch");
expect(rendered).not.toContain("Selected by");
expect(rendered).not.toContain("TrophyIcon");
});
test("optionally renders the standard reducer transcript", () => {
const rendered = renderFanIn([
event(1, {
event: "stage.prompt",
properties: {
mode: "prompt",
text: "Combine the useful findings.",
model: "claude-sonnet-4-6",
},
}),
event(2, {
event: "prompt.completed",
properties: {
response: "All branch findings are now available.",
billing: { input_tokens: 1200, output_tokens: 340 },
},
}),
]);
expect(rendered).toContain("Reducer transcript");
expect(rendered).toContain("Combine the useful findings.");
expect(rendered).toContain("All branch findings are now available.");
expect(rendered).toContain("claude-sonnet-4-6");
expect(rendered).toContain("1k");
expect(rendered).toContain("340");
expect(rendered).toContain("tokens");
});
});

132
apps/fabro-web/app/components/stage-renderers/fan-in-results.tsx
View file

@ -1,143 +1,53 @@
import { useMemo } from "react";
import {
CheckCircleIcon,
CpuChipIcon,
SparklesIcon,
TrophyIcon,
} from "@heroicons/react/20/solid";
import type { EventEnvelope } from "@qltysh/fabro-api-client";
import type { Stage } from "../stage-sidebar";
import { formatTokenCount } from "../../lib/format";
import { getString } from "../../lib/unknown";
import { Markdown } from "./primitives";
import { prettyJson } from "./pretty-json";
import { StageMetaBar } from "./meta-bar";
import { parseFanInOutcome } from "./helpers";
interface ReducerTurn {
prompt: string;
response: string;
model: string | null;
inputTokens: number;
outputTokens: number;
}
function extractReducerTurn(events: EventEnvelope[]): ReducerTurn | null {
let prompt = "";
let response = "";
let model: string | null = null;
let inputTokens = 0;
let outputTokens = 0;
let hasReducer = false;
for (const event of events) {
const props = event.properties ?? {};
if (event.event === "stage.prompt" && getString(props, "mode") === "fan_in") {
prompt = getString(props, "text") ?? prompt;
hasReducer = true;
} else if (event.event === "prompt.completed") {
response = getString(props, "response") ?? response;
model = getString(props, "model") ?? model;
const billing = props.billing as Record<string, unknown> | undefined;
if (billing) {
const it = billing.input_tokens;
const ot = billing.output_tokens;
if (typeof it === "number") inputTokens = it;
if (typeof ot === "number") outputTokens = ot;
}
hasReducer = true;
}
}
return hasReducer ? { prompt, response, model, inputTokens, outputTokens } : null;
}
/**
* The fan-in `stage.prompt.text` is built by the handler as
* "<prompt>\n\n<json>". Split it for nicer display so the JSON candidate set
* lands in a code block rather than fighting markdown rendering.
*/
function splitPromptAndCandidates(text: string): { prompt: string; candidatesJson: string } {
const trimmed = text.trim();
// Find the start of the JSON envelope. The handler always uses array results
// so look for the first opening bracket that begins a balanced array/object.
const idx = (() => {
for (let i = 0; i < trimmed.length; i += 1) {
const ch = trimmed[i];
if (ch === "[" || ch === "{") return i;
}
return -1;
})();
if (idx < 0) return { prompt: trimmed, candidatesJson: "" };
const promptPart = trimmed.slice(0, idx).trim();
const jsonPart = trimmed.slice(idx).trim();
const pretty = prettyJson(jsonPart);
return {
prompt: promptPart,
candidatesJson: pretty.isJson ? pretty.text : jsonPart,
};
}
import { parseReducerTranscript } from "./helpers";
export function FanInResults({
stage,
events,
notes,
}: {
stage: Stage;
events: EventEnvelope[];
notes: string | null;
}) {
const outcome = useMemo(() => parseFanInOutcome(events, notes), [events, notes]);
const reducer = useMemo(() => extractReducerTurn(events), [events]);
const promptParts = useMemo(
() => (reducer ? splitPromptAndCandidates(reducer.prompt) : null),
[reducer],
);
const reducer = useMemo(() => parseReducerTranscript(events), [events]);
return (
<div className="space-y-6 pl-3 pr-4 sm:pr-6 lg:pr-8">
<StageMetaBar stage={stage}>
{outcome.reducerModel ? (
{reducer?.model ? (
<span className="inline-flex items-center gap-1.5 text-xs text-fg-muted">
<CpuChipIcon className="size-3.5" aria-hidden="true" />
<span className="font-mono">{outcome.reducerModel}</span>
<span className="font-mono">{reducer.model}</span>
</span>
) : null}
</StageMetaBar>
<section className="overflow-hidden rounded-lg bg-gradient-to-br from-amber/10 via-panel to-panel outline-1 -outline-offset-1 outline-line">
<section className="overflow-hidden rounded-lg bg-gradient-to-br from-mint/10 via-panel to-panel outline-1 -outline-offset-1 outline-line">
<div className="flex flex-col gap-5 p-6 sm:flex-row sm:items-center sm:gap-8">
<div className="flex size-14 shrink-0 items-center justify-center rounded-full bg-amber/15 ring-1 ring-amber/30">
<TrophyIcon className="size-7 text-amber" aria-hidden="true" />
<div className="flex size-14 shrink-0 items-center justify-center rounded-full bg-mint/15 ring-1 ring-mint/30">
<CheckCircleIcon className="size-7 text-mint" aria-hidden="true" />
</div>
<div className="min-w-0 flex-1">
<div className="text-[10px] font-semibold uppercase tracking-[0.18em] text-amber">
Selected branch
<div className="text-[10px] font-semibold uppercase tracking-[0.18em] text-mint">
Joined
</div>
{outcome.selectedId ? (
<p className="mt-1 truncate font-mono text-2xl text-fg">
{outcome.selectedId}
</p>
) : (
<p className="mt-1 text-sm text-fg-muted">
Awaiting fan-in completion
</p>
)}
<p className="mt-2 inline-flex items-center gap-1.5 text-xs text-fg-muted">
{outcome.hasReducerTranscript ? (
<>
<SparklesIcon className="size-3.5" aria-hidden="true" />
Selected by LLM reducer
</>
) : (
<>Selected by heuristic (status &middot; score &middot; id)</>
)}
<p className="mt-1 text-sm text-fg-3">
Parallel branches rejoined the workflow.
</p>
</div>
</div>
</section>
{reducer && promptParts && (
{reducer && (
<section className="space-y-4">
<h3 className="text-xs font-medium uppercase tracking-wider text-fg-muted">
Reducer transcript
@ -149,18 +59,10 @@ export function FanInResults({
Prompt
</span>
</header>
{promptParts.prompt && (
<Markdown content={promptParts.prompt} />
)}
{promptParts.candidatesJson && (
<details className="mt-3 group">
<summary className="cursor-pointer text-xs text-fg-muted hover:text-fg-2">
Candidates JSON
</summary>
<pre className="mt-2 max-h-72 overflow-auto whitespace-pre-wrap rounded-md bg-overlay-strong p-3 font-mono text-xs leading-relaxed text-fg-3">
{promptParts.candidatesJson}
</pre>
</details>
{reducer.prompt ? (
<Markdown content={reducer.prompt} />
) : (
<p className="text-sm text-fg-muted">No prompt recorded.</p>
)}
</article>

143
apps/fabro-web/app/components/stage-renderers/helpers.test.ts
View file

@ -1,29 +1,18 @@
import { describe, expect, test } from "bun:test";
import type { EventEnvelope } from "@qltysh/fabro-api-client";
import { makeEventEnvelope } from "../../lib/test-utils";
import {
extractStageContext,
extractStageNotes,
parseFanInOutcome,
parseHumanInterviewPairs,
parseParallelOverview,
parseReducerTranscript,
} from "./helpers";
function envelope(seq: number, partial: Partial<EventEnvelope>): EventEnvelope {
return {
seq,
id: `evt-${seq}`,
ts: `2026-04-09T12:00:0${seq}Z`,
run_id: "run-1",
event: "stage.prompt",
...partial,
} as EventEnvelope;
}
describe("parseHumanInterviewPairs", () => {
test("pairs interview.started with interview.completed by question_id", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "interview.started",
properties: {
question_id: "q-1",
@ -36,7 +25,7 @@ describe("parseHumanInterviewPairs", () => {
allow_freeform: false,
},
}),
envelope(2, {
makeEventEnvelope(2, {
event: "interview.completed",
properties: {
question_id: "q-1",
@ -66,7 +55,7 @@ describe("parseHumanInterviewPairs", () => {
test("leaves resolution null for unanswered (still pending) questions", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "interview.started",
properties: {
question_id: "q-1",
@ -81,7 +70,7 @@ describe("parseHumanInterviewPairs", () => {
test("preserves option description and preview metadata from started events", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "interview.started",
properties: {
question_id: "q-1",
@ -111,19 +100,19 @@ describe("parseHumanInterviewPairs", () => {
test("captures timeout and interrupted resolutions", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "interview.started",
properties: { question_id: "q-1", question: "?", question_type: "freeform" },
}),
envelope(2, {
makeEventEnvelope(2, {
event: "interview.timeout",
properties: { question_id: "q-1", duration_ms: 30000 },
}),
envelope(3, {
makeEventEnvelope(3, {
event: "interview.started",
properties: { question_id: "q-2", question: "?", question_type: "freeform" },
}),
envelope(4, {
makeEventEnvelope(4, {
event: "interview.interrupted",
properties: {
question_id: "q-2",
@ -144,45 +133,58 @@ describe("parseHumanInterviewPairs", () => {
});
describe("parseParallelOverview", () => {
test("rolls up branch_count from started and results from completed", () => {
test("rolls up branch_count and status-only results", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "parallel.started",
properties: { branch_count: 3, join_policy: "wait_all" },
properties: { branch_count: 3 },
}),
envelope(2, {
makeEventEnvelope(2, {
event: "parallel.completed",
properties: {
duration_ms: 12000,
success_count: 2,
failure_count: 1,
results: [
{ id: "branch-a", status: "succeeded", head_sha: "abc1234567890" },
{ id: "branch-b", status: "succeeded" },
{ id: "branch-c", status: "failed" },
{
id: "branch-a",
status: "succeeded",
context_updates: { "response.branch-a": "A" },
},
{
id: "branch-b",
status: "succeeded",
context_updates: { "command.output": { stdout: "B" } },
},
{
id: "branch-c",
status: "failed",
context_updates: { "response.branch-c": "C" },
},
],
},
}),
];
const overview = parseParallelOverview(events);
expect(overview).toMatchObject({
expect(overview).toEqual({
branchCount: 3,
joinPolicy: "wait_all",
successCount: 2,
failureCount: 1,
durationMs: 12000,
results: [
{ id: "branch-a", status: "succeeded" },
{ id: "branch-b", status: "succeeded" },
{ id: "branch-c", status: "failed" },
],
isComplete: true,
});
expect(overview.results).toEqual([
{ id: "branch-a", status: "succeeded", headSha: "abc1234567890" },
{ id: "branch-b", status: "succeeded", headSha: null },
{ id: "branch-c", status: "failed", headSha: null },
]);
});
test("reports in-flight when only the started event is present", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "parallel.started",
properties: { branch_count: 4, join_policy: "first_success" },
properties: { branch_count: 4 },
}),
];
const overview = parseParallelOverview(events);
@ -192,56 +194,59 @@ describe("parseParallelOverview", () => {
});
});
describe("parseFanInOutcome", () => {
test("extracts the selected branch id from notes", () => {
const outcome = parseFanInOutcome([], "Selected best candidate: branch-42");
expect(outcome.selectedId).toBe("branch-42");
expect(outcome.hasReducerTranscript).toBe(false);
describe("parseReducerTranscript", () => {
test("returns null when fan-in joins without a reducer", () => {
expect(parseReducerTranscript([])).toBeNull();
});
test("flags reducer presence when fan-in prompt events exist", () => {
test("parses the standard prompt transcript when a reducer ran", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "stage.prompt",
properties: { mode: "fan_in", text: "rank these", model: "claude-sonnet-4-6" },
properties: {
mode: "prompt",
text: "Combine the branch results.",
model: "claude-sonnet-4-6",
},
}),
envelope(2, {
makeEventEnvelope(2, {
event: "prompt.completed",
properties: { response: "branch-a wins", model: "ignored-downstream-model" },
properties: {
response: "The branch results are joined.",
billing: { input_tokens: 1200, output_tokens: 340 },
},
}),
];
const outcome = parseFanInOutcome(events, "Selected best candidate: branch-a");
expect(outcome.hasReducerTranscript).toBe(true);
expect(outcome.reducerModel).toBe("claude-sonnet-4-6");
expect(outcome.selectedId).toBe("branch-a");
expect(parseReducerTranscript(events)).toEqual({
prompt: "Combine the branch results.",
response: "The branch results are joined.",
model: "claude-sonnet-4-6",
inputTokens: 1200,
outputTokens: 340,
});
});
test("returns null selection when notes lack the selected line", () => {
const outcome = parseFanInOutcome([], "all candidates failed");
expect(outcome.selectedId).toBeNull();
});
});
describe("extractStageNotes", () => {
test("returns notes from the stage.completed event", () => {
test("uses normal prompt mode for the reducer transcript", () => {
const events: EventEnvelope[] = [
envelope(1, {
event: "stage.completed",
properties: { notes: "Stop condition satisfied at cycle 7" },
makeEventEnvelope(1, {
event: "stage.prompt",
properties: { mode: "prompt", text: "Standard reducer" },
}),
makeEventEnvelope(2, {
event: "prompt.completed",
properties: { response: "Standard response" },
}),
];
expect(extractStageNotes(events)).toBe("Stop condition satisfied at cycle 7");
});
test("returns null when there is no stage.completed event", () => {
expect(extractStageNotes([])).toBeNull();
expect(parseReducerTranscript(events)?.response).toBe("Standard response");
});
});
describe("extractStageContext", () => {
test("keeps author-set keys and drops engine bookkeeping keys", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "stage.completed",
properties: {
context_updates: {
@ -269,7 +274,7 @@ describe("extractStageContext", () => {
test("extracts routing hints from preferred_label and suggested_next_ids", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "stage.completed",
properties: {
preferred_label: "approve",
@ -285,7 +290,7 @@ describe("extractStageContext", () => {
test("returns null when the stage only wrote engine keys", () => {
const events: EventEnvelope[] = [
envelope(1, {
makeEventEnvelope(1, {
event: "stage.completed",
properties: {
context_updates: { last_stage: "implement", "command.output": "blob:x" },

102
apps/fabro-web/app/components/stage-renderers/helpers.ts
View file

@ -1,7 +1,14 @@
import { StageOutcome } from "@qltysh/fabro-api-client";
import type { EventEnvelope } from "@qltysh/fabro-api-client";
import { getArray, getNumber, getObject, getString, type UnknownRecord } from "../../lib/unknown";
const STAGE_OUTCOMES: ReadonlySet<string> = new Set(Object.values(StageOutcome));
function asStageOutcome(value: string | undefined): StageOutcome | null {
return value !== undefined && STAGE_OUTCOMES.has(value) ? (value as StageOutcome) : null;
}
export interface InterviewOption {
key: string;
label: string;
@ -137,19 +144,18 @@ export function parseHumanInterviewPairs(events: EventEnvelope[]): HumanIntervie
return Array.from(pairs.values()).sort((a, b) => a.question.ts.localeCompare(b.question.ts));
}
export interface ParallelBranchResult {
/** Identity and outcome of one branch, parsed from `parallel.completed`. */
export interface ParallelBranchSummary {
id: string;
status: string;
headSha: string | null;
status: StageOutcome;
}
export interface ParallelOverview {
branchCount: number | null;
joinPolicy: string | null;
successCount: number | null;
failureCount: number | null;
durationMs: number | null;
results: ParallelBranchResult[];
results: ParallelBranchSummary[];
isComplete: boolean;
}
@ -160,18 +166,16 @@ export interface ParallelOverview {
*/
export function parseParallelOverview(events: EventEnvelope[]): ParallelOverview {
let branchCount: number | null = null;
let joinPolicy: string | null = null;
let successCount: number | null = null;
let failureCount: number | null = null;
let durationMs: number | null = null;
let results: ParallelBranchResult[] = [];
let results: ParallelBranchSummary[] = [];
let isComplete = false;
for (const event of events) {
const props: UnknownRecord = event.properties ?? {};
if (event.event === "parallel.started") {
branchCount = getNumber(props, "branch_count") ?? branchCount;
joinPolicy = getString(props, "join_policy") ?? joinPolicy;
} else if (event.event === "parallel.completed") {
isComplete = true;
successCount = getNumber(props, "success_count") ?? successCount;
@ -182,20 +186,18 @@ export function parseParallelOverview(events: EventEnvelope[]): ParallelOverview
.map((entry) => {
const record = entry && typeof entry === "object" ? (entry as UnknownRecord) : null;
if (!record) return null;
return {
id: getString(record, "id") ?? "",
status: getString(record, "status") ?? "unknown",
headSha: getString(record, "head_sha") ?? null,
} satisfies ParallelBranchResult;
const id = getString(record, "id");
const status = asStageOutcome(getString(record, "status"));
if (!id || !status) return null;
return { id, status } satisfies ParallelBranchSummary;
})
.filter((r): r is ParallelBranchResult => r != null && r.id !== "");
.filter((r): r is ParallelBranchSummary => r != null);
if (branchCount == null) branchCount = results.length;
}
}
return {
branchCount,
joinPolicy,
successCount,
failureCount,
durationMs,
@ -204,59 +206,39 @@ export function parseParallelOverview(events: EventEnvelope[]): ParallelOverview
};
}
export interface FanInOutcome {
selectedId: string | null;
hasReducerTranscript: boolean;
reducerModel: string | null;
export interface ReducerTranscript {
prompt: string;
response: string;
model: string | null;
inputTokens: number;
outputTokens: number;
}
const FAN_IN_NOTES_RE = /Selected best candidate:\s*(.+?)\s*$/;
/** Extract the standard prompt/response transcript emitted by an optional fan-in reducer. */
export function parseReducerTranscript(events: EventEnvelope[]): ReducerTranscript | null {
let prompt = "";
let response = "";
let model: string | null = null;
let inputTokens = 0;
let outputTokens = 0;
let hasReducer = false;
/**
* Derive the fan-in winner from the `parallel.completed`-style notes string,
* and report whether reducer LLM events were emitted (so the UI knows to show
* the embedded transcript).
*/
export function parseFanInOutcome(events: EventEnvelope[], notes: string | null): FanInOutcome {
const match = notes ? FAN_IN_NOTES_RE.exec(notes) : null;
let hasReducerTranscript = false;
let reducerModel: string | null = null;
for (const event of events) {
const props: UnknownRecord = event.properties ?? {};
if (event.event === "stage.prompt") {
const mode = getString(event.properties ?? {}, "mode");
if (mode === "fan_in") {
hasReducerTranscript = true;
const model = getString(event.properties ?? {}, "model");
if (model) reducerModel = model;
}
}
if (event.event === "prompt.completed") {
hasReducerTranscript = true;
prompt = getString(props, "text") ?? prompt;
model = getString(props, "model") ?? model;
hasReducer = true;
} else if (event.event === "prompt.completed" && hasReducer) {
response = getString(props, "response") ?? response;
model = getString(props, "model") ?? model;
const billing = getObject(props, "billing") ?? {};
inputTokens = getNumber(billing, "input_tokens") ?? inputTokens;
outputTokens = getNumber(billing, "output_tokens") ?? outputTokens;
}
}
return {
selectedId: match ? match[1].trim() : null,
hasReducerTranscript,
reducerModel,
};
}
function asUnknownRecord(value: unknown): UnknownRecord | null {
if (!value || typeof value !== "object" || Array.isArray(value)) return null;
return value as UnknownRecord;
}
/**
* Extract `notes` from the `stage.completed` event scoped to this stage.
* Returns null when the stage hasn't finished yet or when notes are absent.
*/
export function extractStageNotes(events: EventEnvelope[]): string | null {
for (const event of events) {
if (event.event !== "stage.completed") continue;
const notes = getString(event.properties ?? {}, "notes");
if (notes) return notes;
}
return null;
return hasReducer ? { prompt, response, model, inputTokens, outputTokens } : null;
}
export interface StageContextData {

85
apps/fabro-web/app/components/stage-renderers/parallel-children.test.tsx Normal file
View file

@ -0,0 +1,85 @@
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import type { EventEnvelope } from "@qltysh/fabro-api-client";
import TestRenderer, { act } from "react-test-renderer";
import { MemoryRouter } from "react-router";
import { makeEventEnvelope, setupReactTestEnv } from "../../lib/test-utils";
import type { Stage } from "../stage-sidebar";
import { ParallelChildren } from "./parallel-children";
let teardown: () => void;
beforeEach(() => {
teardown = setupReactTestEnv();
});
afterEach(() => teardown());
const parallelStage: Stage = {
id: "fork@1",
name: "fork",
handler: "parallel",
status: "succeeded",
duration: "12s",
nodeId: "fork",
visit: 1,
startedAt: "2026-04-09T12:00:00Z",
providerUsed: null,
};
function event(partial: Partial<EventEnvelope>): EventEnvelope {
return makeEventEnvelope(partial.seq ?? 1, { event: "parallel.completed", ...partial });
}
function renderParallel(events: EventEnvelope[]): TestRenderer.ReactTestRenderer {
let renderer!: TestRenderer.ReactTestRenderer;
act(() => {
renderer = TestRenderer.create(
<MemoryRouter>
<ParallelChildren
stage={parallelStage}
events={events}
runId="run-1"
allStages={[
{ ...parallelStage, id: "branch-a@1", name: "branch-a", nodeId: "branch-a", handler: "agent" },
{ ...parallelStage, id: "branch-b@1", name: "branch-b", nodeId: "branch-b", handler: "agent", status: "failed" },
]}
/>
</MemoryRouter>,
);
});
return renderer;
}
describe("ParallelChildren", () => {
test("renders branch status and stage links without checkout metadata", () => {
const renderer = renderParallel([
event({
event: "parallel.started",
properties: { branch_count: 2 },
}),
event({
seq: 2,
event: "parallel.completed",
properties: {
duration_ms: 12000,
success_count: 1,
failure_count: 1,
results: [
{ id: "branch-a", status: "succeeded", context_updates: {} },
{ id: "branch-b", status: "failed", context_updates: {} },
],
},
}),
]);
const rendered = JSON.stringify(renderer.toJSON());
expect(rendered).toContain("branch-a");
expect(rendered).toContain("Succeeded");
expect(rendered).toContain("branch-b");
expect(rendered).toContain("Failed");
const hrefs = renderer.root.findAllByType("a").map((link) => link.props.href);
expect(hrefs).toEqual([
"/runs/run-1/stages/branch-a@1",
"/runs/run-1/stages/branch-b@1",
]);
});
});

57
apps/fabro-web/app/components/stage-renderers/parallel-children.tsx
View file

@ -1,34 +1,19 @@
import { useMemo } from "react";
import { Link } from "react-router";
import { ArrowTopRightOnSquareIcon } from "@heroicons/react/20/solid";
import { StageState } from "@qltysh/fabro-api-client";
import type { EventEnvelope } from "@qltysh/fabro-api-client";
import type { Stage } from "../stage-sidebar";
import { CopyButton } from "../ui";
import { stageStatusLabel, stageStatusTone } from "../../lib/stage-sidebar";
import { formatDurationMs } from "../../lib/format";
import { StageMetaBar } from "./meta-bar";
import { parseParallelOverview, type ParallelBranchResult } from "./helpers";
import { parseParallelOverview } from "./helpers";
const RESULT_STATUS_TONE: Record<string, string> = {
succeeded: "bg-mint/15 text-mint",
partially_succeeded: "bg-amber/15 text-amber",
failed: "bg-coral/15 text-coral",
cancelled: "bg-overlay-strong text-fg-muted",
skipped: "bg-overlay-strong text-fg-muted",
};
function statusTone(status: string): string {
return RESULT_STATUS_TONE[status] ?? "bg-overlay-strong text-fg-muted";
}
function statusLabel(status: string): string {
if (!status) return "—";
return status.charAt(0).toUpperCase() + status.slice(1).replace(/_/g, " ");
}
function shortSha(sha: string | null): string | null {
if (!sha) return null;
return sha.length > 8 ? sha.slice(0, 8) : sha;
/** Branch row view state: completed outcomes plus a synthesized in-flight row. */
interface BranchRow {
id: string;
status: StageState;
}
function StatItem({
@ -56,27 +41,21 @@ function ChildRow({
result,
stageHref,
}: {
result: ParallelBranchResult;
result: BranchRow;
stageHref: string | null;
}) {
const sha = shortSha(result.headSha);
const tone = statusTone(result.status);
const tone = stageStatusTone(result.status);
const inner = (
<>
<span
className={`inline-flex w-24 shrink-0 justify-center rounded-full px-2 py-0.5 text-[10px] font-medium uppercase tracking-wider ${tone}`}
>
{statusLabel(result.status)}
{stageStatusLabel(result.status)}
</span>
<span className="min-w-0 flex-1 truncate font-mono text-sm text-fg-3">
{result.id}
</span>
{sha && (
<span className="inline-flex items-center gap-1 font-mono text-xs text-fg-muted">
{sha}
</span>
)}
{stageHref && (
<ArrowTopRightOnSquareIcon
className="size-3.5 shrink-0 text-fg-muted transition-colors group-hover:text-fg-2"
@ -98,9 +77,6 @@ function ChildRow({
) : (
<span className="flex flex-1 items-center gap-3">{inner}</span>
)}
{result.headSha && (
<CopyButton value={result.headSha} label="Copy commit SHA" className="shrink-0" />
)}
</li>
);
}
@ -128,25 +104,18 @@ export function ParallelChildren({
return new Map(Array.from(latest.entries()).map(([nodeId, s]) => [nodeId, s.id]));
}, [allStages]);
const items = overview.results.length > 0
const items: BranchRow[] = overview.results.length > 0
? overview.results
: overview.branchCount && overview.branchCount > 0
? Array.from({ length: overview.branchCount }, (_, i) => ({
id: `branch ${i + 1}`,
status: "running",
headSha: null,
status: StageState.RUNNING,
}))
: [];
return (
<div className="space-y-6 pl-3 pr-4 sm:pr-6 lg:pr-8">
<StageMetaBar stage={stage}>
{overview.joinPolicy ? (
<span className="inline-flex items-center rounded-full bg-overlay-strong px-2 py-0.5 font-mono text-[10px] uppercase tracking-wider text-fg-2">
{overview.joinPolicy.replace(/_/g, " ")}
</span>
) : null}
</StageMetaBar>
<StageMetaBar stage={stage} />
<section className="grid grid-cols-2 gap-x-6 gap-y-4 rounded-lg bg-panel p-5 outline-1 -outline-offset-1 outline-line sm:grid-cols-4">
<StatItem label="Branches" value={overview.branchCount ?? "—"} />

16
apps/fabro-web/app/lib/test-utils.tsx
View file

@ -1,4 +1,5 @@
import { createElement, type ReactNode } from "react";
import type { EventEnvelope } from "@qltysh/fabro-api-client";
import TestRenderer, { act } from "react-test-renderer";
const IS_REACT_ACT_ENV = "IS_REACT_ACT_ENVIRONMENT" as const;
@ -39,6 +40,21 @@ export function setupReactTestEnv(): () => void {
};
}
/** Build an event envelope fixture; override any field via `partial`. */
export function makeEventEnvelope(
seq: number,
partial: Partial<EventEnvelope>,
): EventEnvelope {
return {
seq,
id: `evt-${seq}`,
ts: `2026-04-09T12:00:0${seq}Z`,
run_id: "run-1",
event: "stage.prompt",
...partial,
} as EventEnvelope;
}
export function renderHook<T>(
hook: () => T,
options: { wrapper: React.ComponentType<{ children: ReactNode }> },

11
apps/fabro-web/app/routes/run-stages.tsx
View file

@ -42,10 +42,7 @@ import {
} from "../components/ui";
import { ConditionalDecision } from "../components/stage-renderers/conditional-decision";
import { FanInResults } from "../components/stage-renderers/fan-in-results";
import {
extractStageContext,
extractStageNotes,
} from "../components/stage-renderers/helpers";
import { extractStageContext } from "../components/stage-renderers/helpers";
import { HumanQA } from "../components/stage-renderers/human-qa";
import { ParallelChildren } from "../components/stage-renderers/parallel-children";
import {
@ -1579,11 +1576,7 @@ function StageActivityBody({
allStages={stages}
/>
) : renderer === "fan_in" ? (
<FanInResults
stage={selectedStage}
events={debugEvents}
notes={extractStageNotes(debugEvents)}
/>
<FanInResults stage={selectedStage} events={debugEvents} />
) : renderer === "wait" ? (
<WaitStatus stage={selectedStage} />
) : (

7
apps/fabro-web/public/images/providers/fireworks.svg Normal file
View file

@ -0,0 +1,7 @@
<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round">
<path d="M8.5 17H4"/>
<path d="M9.53 14.53L6.34 11.34"/>
<path d="M12 13.5V9"/>
<path d="M14.47 14.53L17.66 11.34"/>
<path d="M15.5 17H20"/>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 308 B

2
docs/internal/demo/06-parallel.fabro
View file

@ -5,7 +5,7 @@ digraph Parallel {
start [shape=Mdiamond, label="Start"]
exit [shape=Msquare, label="Exit"]
fork [label="Fork Analysis", shape=component, join_policy="wait_all"]
fork [label="Fork Analysis", shape=component]
security [label="Security Audit", prompt="Examine the codebase for security concerns: hardcoded secrets, injection risks, unsafe dependencies. List findings as bullet points.", shape=tab, reasoning_effort="low"]
architecture [label="Architecture Review", prompt="Assess the codebase architecture: separation of concerns, dependency structure, modularity. List findings as bullet points.", shape=tab, reasoning_effort="low"]

2
docs/internal/demo/11-ensemble.fabro
View file

@ -14,7 +14,7 @@ digraph Ensemble {
start [shape=Mdiamond, label="Start"]
exit [shape=Msquare, label="Exit"]
fork [label="Fan Out", shape=component, join_policy="wait_all"]
fork [label="Fan Out", shape=component]
opus [label="Opus", prompt="Analyze the goal. Provide your independent assessment, recommendations, and any code or prose needed. Be thorough.", shape=tab]
gemini [label="Gemini", prompt="Analyze the goal. Provide your independent assessment, recommendations, and any code or prose needed. Be thorough.", shape=tab]

75
docs/internal/events.md
View file

@ -523,16 +523,16 @@ Emitted when a parallel node begins executing branches.
"id": "...", "ts": "...", "run_id": "...",
"event": "parallel.started",
"properties": {
"branch_count": 3,
"join_policy": "all"
"visit": 1,
"branch_count": 3
}
}
```
| Property | Type | Description |
|----------|------|-------------|
| `visit` | number | Visit number for this parallel stage |
| `branch_count` | number | Number of parallel branches |
| `join_policy` | string | Join policy |
### `parallel.branch.started`
@ -587,18 +587,33 @@ Emitted when all parallel branches have finished.
"id": "...", "ts": "...", "run_id": "...",
"event": "parallel.completed",
"properties": {
"visit": 1,
"duration_ms": 12000,
"success_count": 2,
"failure_count": 1
"failure_count": 1,
"results": [
{
"id": "branch_a",
"status": "succeeded",
"context_updates": {"response.branch_a": "review complete"}
},
{
"id": "branch_b",
"status": "failed",
"context_updates": {"command.output": "validation failed"}
}
]
}
}
```
| Property | Type | Description |
|----------|------|-------------|
| `visit` | number | Visit number for this parallel stage |
| `duration_ms` | number | Total parallel duration |
| `success_count` | number | Branches that succeeded |
| `failure_count` | number | Branches that failed |
| `results` | array | Ordered typed branch results with `id`, `status`, and isolated `context_updates` |
---
@ -760,58 +775,6 @@ Note: `node_id` is optional — may be absent for non-stage commits.
| `branch` | string | Branch name |
| `success` | boolean | Whether push succeeded |
### `git.branch`
```json
{
"id": "...", "ts": "...", "run_id": "...",
"event": "git.branch",
"properties": {
"branch": "fabro/run-01JQXYZ",
"sha": "abc123..."
}
}
```
| Property | Type | Description |
|----------|------|-------------|
| `branch` | string | Branch name |
| `sha` | string | Branch HEAD SHA |
### `git.worktree.added`
```json
{
"id": "...", "ts": "...", "run_id": "...",
"event": "git.worktree.added",
"properties": {
"path": "/tmp/fabro-worktrees/...",
"branch": "fabro/run-01JQXYZ"
}
}
```
| Property | Type | Description |
|----------|------|-------------|
| `path` | string | Worktree directory path |
| `branch` | string | Branch name |
### `git.worktree.removed`
```json
{
"id": "...", "ts": "...", "run_id": "...",
"event": "git.worktree.removed",
"properties": {
"path": "/tmp/fabro-worktrees/..."
}
}
```
| Property | Type | Description |
|----------|------|-------------|
| `path` | string | Worktree directory path |
### `git.fetch`
```json

394
docs/internal/parallel-strategy.md
View file

@ -1,318 +1,154 @@
# Parallel fan-out / fan-in strategy
# Shared-checkout parallel execution strategy
Status: proposed (not yet implemented). Line numbers reference the tree at the
time of writing and will drift.
Status: implemented.
This document specifies the intended product behavior of parallel fan-out
(`shape=component`) and fan-in (`shape=tripleoctagon`). Appendix A catalogs
pre-existing bugs this design resolves. Appendix B lists behavior changes
relative to today's implementation.
This document defines Fabro's parallel fan-out (`shape=component`) and fan-in
(`shape=tripleoctagon`) behavior.
## 1. Introduction: goals and current weaknesses
## 1. Execution model
The goal of this design is a parallel execution model that is **simple**,
**coherent**, and **correct**:
A parallel node dispatches one branch for each outgoing edge. A branch executes
the single target node on that edge; parallel branches are not subgraph walks.
Every branch:
- **Simple** — a user should be able to predict what a fan-out/fan-in does
from the graph alone. One mental model ("branches produce candidates; fan-in
picks a commit; downstream sees all responses"), no new syntax for
synthesis, no incantations (special fidelity settings, escape-hatch
attributes) to make the flagship patterns work.
- **Coherent** — the same rules apply regardless of node type or channel.
What holds for a sequential command node's output should hold for a branch
command node's output; the workspace (git) facet and the text (context)
facet should follow parallel logic; selection should live in exactly one
place.
- **Correct** — the engine must do what the graph, the docs, and the recorded
run state say it does. Nodes drawn in the graph must run; documented outputs
must exist; a judge asked to pick the best candidate must be shown the
candidates.
- receives an independent fork of the parent workflow context;
- receives the same `Arc<dyn Sandbox>` as the parent run;
- inherits the same sandbox working directory and `internal.work_dir`;
- runs through the normal handler dispatch path, including dry-run behavior;
- retains its branch identity, lifecycle events, and hook scope.
Today's implementation misses all three. Issue #490 is the visible symptom:
a synthesis node after fan-in never sees branch responses — only
`{id, status, head_sha}` metadata — while two tutorials promise the opposite.
Investigation showed a broader incoherence:
Branches execute concurrently. `max_parallel` limits the number that may run at
once and defaults to 4. The parallel node always waits for every branch task,
even when a branch fails or run cancellation begins. There is no early-success
join mode.
- **Inherited spec gap.** The Attractor spec (fabro's ancestor) deliberately
isolates branch context and never defines a channel for branch output text.
Its fan-in pseudocode judges candidates it cannot see (`llm_evaluate`
receives only statuses) and sorts by a `score` field nothing sets. Fabro
inherited this gap faithfully.
- **Missing compensation.** Kilroy (a sibling Attractor implementation)
compensates with a file/git handoff: the post-merge node's prompt is
injected with each branch's `worktree_dir`, `logs_root`, and `head_sha` plus
instructions to read/merge them. Fabro has no equivalent, but its tutorials
promise kilroy-like behavior ("the synth node receives all four perspectives
in its preamble").
- **Accidental semantics.** Several adjacent behaviors are unprincipled
accidents rather than decisions: branches execute a single node and silently
skip chained nodes; two handlers fast-forward to two different definitions
of "winner"; branch nodes run with a stale preamble built for the fan-out
node; selection is vacuous in both modes; nested fan-outs silently lose git
isolation. Appendix A catalogs these.
The parent context is not used as shared mutable branch state. A branch can
change its context fork without exposing those changes as top-level values to
other branches or to the parent.
## 2. Core model: candidates
## 2. Shared checkout
A parallel branch is an isolated unit of execution that produces a
**candidate**. A candidate has exactly three facets:
All branches use the run's existing sandbox and checkout. Parallel execution
creates no branch-specific:
| Facet | Content | Carried by |
|---|---|---|
| Commit | Workspace state produced by the branch | Per-branch git commit (`head_sha`) |
| Response | Text output (LLM response, command output) | Branch stage records + context keys |
| Verdict | Terminal status plus optional numeric `score` | `parallel.results` entries |
- Git refs or branches;
- worktrees;
- base checkpoints;
- commits;
- cleanup operations;
- merges or fast-forwards.
Fan-out produces N candidates in isolation. Fan-in selects **one commit** to
continue on. Downstream nodes (synthesis) get **all responses**. Selection and
synthesis are distinct concerns: selection needs a node (`tripleoctagon`);
synthesis is any ordinary downstream node, because responses propagate.
Normal run-level checkpointing still occurs after the parallel node. Any files
left in the shared checkout by its branches are captured together by that
checkpoint.
The post-fan-in contract, in one sentence: **after fan-in, the run looks as if
every branch had run sequentially, and the winner ran last.**
Read-only parallel work is best effort: an agent or command can still write if
its configured capabilities permit it. Concurrent writes are allowed and are
entirely user-managed. Fabro does not lock files, enforce read-only access,
detect overlapping edits, or warn about races. Workflows that write in parallel
should coordinate externally or assign disjoint paths.
## 3. Topology: branches are subgraphs
## 3. Branch results
Each outgoing edge of a fan-out node starts a branch. A branch executes as a
subgraph walk: the engine traverses nodes and edges from the branch entry node
until it reaches the join node (the fan-in). Multi-node chains
(`fork -> plan_a; plan_a -> impl_a; impl_a -> merge`) run every node in the
chain. This matches the Attractor spec (`execute_subgraph`) and kilroy
(`runSubgraphUntil`); today fabro executes exactly one node per branch and
silently skips the rest (Appendix A.2).
The shared result type is:
Structural validation (lint):
```rust
ParallelBranchResult {
id: String,
status: StageOutcome,
context_updates: BTreeMap<String, serde_json::Value>,
}
```
- Every path from a branch entry must converge on the run's join node.
A branch path that escapes the join (reaches exit, or a node outside the
fan-out region) is a validation error.
- A nested `component` node inside a branch is rejected until
worktree-from-worktree isolation is implemented (today it silently runs with
no git isolation; Appendix A.6).
- `fidelity="full"` on a fan-in's outgoing edge gets a lint warning: branches
run on different threads, so full fidelity can never carry branch outputs
(it drops the preamble entirely).
The parallel handler stores one result per outgoing edge in
`parallel.results`. Results preserve outgoing-edge order, independent of branch
completion order. `parallel.branch_count` stores the number of dispatched
branches.
## 4. Node types in branches
`context_updates` includes changes made in the branch context and updates
returned by the branch outcome. This applies to successful and failed branches,
including structured values, `response.<node_id>`, and `command.output`.
Engine-internal context keys are omitted. A task failure or panic cannot provide
updates that were never returned, but its result still preserves the original
branch ID and index.
No type-based restrictions. Restriction is structural (§3), not by allowlist:
Branch updates remain nested in their result. Fabro never merges them into the
parent's top-level context, so branches cannot collide through context keys.
- **Agent / prompt nodes** — the primary case.
- **Command / script / tool nodes** — first-class. Deterministic fan-out
(test matrices, benchmark bake-offs across worktrees) is a supported pattern
with no LLM anywhere: branches emit `score` via status fields, heuristic
selection picks the winner by measurement.
- **Conditionals** — meaningful under subgraph branches: they route *within*
the branch.
- **Human gates** — allowed; each branch may pause independently.
- **Nested parallel** — rejected by lint until isolation composes (§3).
The parallel stage outcome is:
## 5. Git isolation
- `succeeded` when every branch succeeds;
- `failed` when every branch fails;
- `partially_succeeded` for mixed outcomes, partial outcomes, and zero branches.
Unchanged mechanics, with ownership fixed:
## 4. Artifacts and downstream context
1. Before fan-out, checkpoint the sandbox to produce `base_sha`.
2. Each branch gets a worktree on a branch ref
(`fabro/run/parallel/<run>/<node>/pass<N>/<branch>`), rooted at `base_sha`.
The branch's `internal.work_dir` points at the worktree.
3. After a branch completes, `git add -A` + commit (`--allow-empty`) yields the
candidate's `head_sha`.
4. Worktrees are removed after the join. Loser branch refs are **kept** so
downstream nodes and humans can `git show`/`git diff` any candidate.
5. **Fan-in exclusively owns the fast-forward.** The parallel handler performs
no merge. After selection, fan-in fast-forwards the primary workspace to the
winner's `head_sha`. (Today both handlers fast-forward, to potentially
different winners; Appendix A.3.)
Large context values use the normal artifact store. Offloading replaces
oversized values within each branch's `context_updates` while retaining the
outer object and array structure of `parallel.results`.
Degradation without git (no repo, or git isolation disabled): branches share
the primary sandbox with no workspace isolation, `head_sha` is absent from
candidates, and fan-in performs no merge. Response and verdict facets work
unchanged — prompt-only ensembles do not require git.
When Fabro constructs execution or prompt context, it resolves nested textual
blob references under `response.*` and `command.output`, including those keys
inside a branch result's `context_updates`. This lets a prompted fan-in inspect
complete branch text without flattening branch state into the parent context.
## 6. Execution and stage recording
`parallel.results` is runtime context. Fabro does not materialize a
`parallel_results.json` file in the workspace. Diagnostic run dumps may export
stage projection data, but that export is not a workflow handoff mechanism and
is not visible as a checkout file to downstream nodes.
Branch nodes execute as **real stages**, recorded through the normal
`ExecutionState::record` path and namespaced under the fan-out
(e.g. stage `a@1` within `fork@1`). Consequences (all fixes to current
behavior):
## 5. Fan-in
- Branch prompts/responses appear in events, `fabro dump`, and the web UI as
ordinary stages.
- Each branch node gets a **freshly built preamble** for its own position, via
the standard lifecycle, instead of reusing the fan-out node's stale preamble.
- Branch stages participate in the standard retry policy per node.
Fan-in is an explicit join node.
## 7. Context merge-back at fan-in
A fan-in node without a nonblank prompt validates that `parallel.results`
exists and deserializes as typed branch results. It then succeeds with a joined
branches note. It is a no-op barrier: it does not alter context or workspace
state.
When fan-in completes, branch context updates are applied to the parent
context with a collision rule:
A fan-in node with a prompt delegates to the standard prompt handler. It sees
the aggregated runtime context in the normal prompt preamble and records the
normal prompt-stage outputs:
- **Per-node keys** (`response.<branch_node_id>`, structured-output fields
namespaced by node) apply for **all** branches. Branch node IDs are unique,
so no collisions.
- **Singleton keys** (`last_stage`, `last_response`, `command.output`,
un-namespaced status fields) are taken from the **winner only**.
- Failed branches' `response.<id>` values are still applied (a synthesis node
analyzing disagreement wants to see the failure text). Their singletons are
never applied.
- `response.<fan_in_id>`;
- `last_response`;
- model usage and timing;
- prompt and response events.
Fan-in additionally writes (as today):
A prompted fan-in synthesizes results. It does not rank branches, select a
winner, restore files, or choose workspace state.
- `parallel.results` — one entry per candidate: `{id, status, head_sha?,
score?}`.
- `parallel.branch_count`, `parallel.fan_in.best_id`,
`parallel.fan_in.best_outcome`, `parallel.fan_in.best_head_sha`.
## 6. Events and projections
No file is materialized into the run workspace. `parallel.results` reaches LLM
consumers through the preamble's context section, and agents can `git show`
any candidate via its `head_sha`. (The current docs claim
`parallel_results.json` is available to downstream nodes; that claim is false
today and should be corrected rather than implemented — see open question 4
for the one consumer this leaves unserved.)
Parallel execution emits:
## 8. Selection
- `parallel.started` with `visit` and `branch_count`;
- `parallel.branch.started` with stable branch identity and index;
- `parallel.branch.completed` with index, duration, and status;
- `parallel.completed` with counts and the ordered typed result array.
Fan-in selects the winning candidate. Two modes, as today, but with real
signal:
Every branch task emits one terminal branch completion event, including handler
failure, cancellation before semaphore acquisition, panic, or join failure.
The final typed array is also projected into
`StageProjection.parallel_results`.
- **Heuristic** (no prompt on the fan-in node): rank by status
(succeeded < partially_succeeded < failed), then `score` descending, then
lexical id. `score` becomes settable: branches emit it via structured-output
/ status fields, which now survive into `parallel.results` (§7).
- **LLM judge** (fan-in node has a `prompt` and a backend is configured): the
judge prompt includes, per candidate: id, status, score, a bounded response
excerpt, and `git diff --stat` vs. `base_sha` when git isolation is active.
Today the judge sees only `{id, status, head_sha}` and cannot possibly
discriminate (Appendix A.4).
## 7. Cancellation
Selection determines the commit facet only. It does not suppress loser
responses (§7) or loser refs (§5).
Semaphore acquisition observes the run cancellation token. Branches still
waiting for a permit when cancellation fires stop without executing; because
`StageOutcome` has no cancelled variant, their results record a failed outcome
(reason `branch cancelled`). Branches already executing continue through their
handler's cooperative cancellation path. The parallel handler joins every task
before returning `Error::Cancelled` to the run executor.
## 9. Downstream visibility (preamble)
Cancellation does not trigger branch Git cleanup because no branch Git state is
created.
Prompt templates render once at manifest build time with `{goal, inputs}`
only; the preamble is the sole channel for runtime context into a
fresh-session node. Therefore:
## 8. Product constraints
- At **`compact`** (default) fidelity, branch stage summaries render their
responses **inline**, bounded, with a `See: <blob path>` reference when
truncated — the same treatment `command.output` already receives at compact.
Rationale: post-fan-in branch responses are unrecoverable through any
fidelity setting (different threads), exactly like command output.
- The per-branch response budget is larger than command output's 25-line tail
(ensemble analyses front-load their substance; a small tail amputates it).
Exact budget TBD at implementation; must remain bounded so N long branches
cannot blow the downstream context. Agent-type synthesis nodes can read the
full text from the blob/artifact reference.
- `summary:high` renders the same with its larger budget. `truncate` carries
goal only (explicit opt-out). `full` remains the degenerate case and lints
(§3).
## 10. Join policies
- `wait_all` (default): all branches run to completion; join proceeds when all
are terminal. Succeeds if no branch failed, else partially succeeds (fan-in
fails only when *all* candidates failed).
- `first_success`: join proceeds at the first successful branch. Remaining
branches are cancelled; cancelled branches record a terminal cancelled stage
(their partial responses are not merged back). The sole successful branch is
the winner.
- `k_of_n` / `quorum` (kilroy has them): deliberately **not** added now. The
surface stays minimal until a concrete need appears.
## Open questions
1. Implementation phasing: subgraph branches (§3) are the largest lift.
Response propagation (§6–§9) fixes #490 and both tutorials on its own and
can ship first.
2. `first_success` cancellation semantics for in-flight agent sessions
(graceful stop vs. abort; what the cancelled stage records).
3. Exact preamble budget per branch response (§9).
4. Context access for deterministic post-fan-in consumers. Command/script
nodes have no channel to context (no preamble, no template rendering in
`script`), so a deterministic aggregator after fan-in cannot learn
candidate `head_sha`s. Candidate mechanisms: a results file under a
checkpoint-excluded workspace path, or an env var (e.g.
`FABRO_PARALLEL_RESULTS`) pointing at a file outside the workspace. A bare
workspace file is ruled out: checkpoint commits `git add -A`, so it would
leak into run history and PRs. Design alongside the deterministic fan-out
pattern (§4).
---
## Appendix A: pre-existing bugs
Cataloged against the current tree; line numbers will drift.
1. **Branch outputs dropped (#490).** The fan-out task reads only
`outcome.status` and `head_sha` from each branch; branch `context_updates`
(including `response.<id>`) are discarded with the forked context
(`fabro-workflow/src/handler/parallel.rs:389-397,465-470`). No channel
carries branch text to downstream nodes. Confirmed by live repro on
fabro-testing (run `01KX148ZAMMJRAADHK1HBF7PC3`, server 0.287.0-nightly.0).
2. **Chained branch nodes silently skipped.** Branches execute exactly one
node; the engine then jumps to the join (`parallel.rs:388-397,612,628`;
`fabro-core/src/executor.rs:421`). In `fork -> a; a -> a2; a2 -> merge`,
`a2` never runs and nothing warns.
3. **Double fast-forward with two different winner definitions.** The parallel
handler fast-forwards the *lexically first* successful branch
(`parallel.rs:511-538`); fan-in then fast-forwards *its* selected winner
(`fan_in.rs:120-131`). If selection ever picks a non-lexical-first branch,
the second `--ff-only` merge cannot succeed (sibling commits diverge).
Masked today only because selection is vacuous (A.4).
4. **Selection is vacuous.** Heuristic tie-breaks on a `score` field nothing
can set (scores would arrive via branch context updates, which are dropped
per A.1). The LLM judge prompt is `serde_json::to_string_pretty` of
`parallel.results` — id/status/head_sha only (`fan_in.rs:247-250`). Both
modes reduce to "first successful branch, alphabetically."
5. **Branch preambles are stale.** Branches run via `dispatch_handler`,
bypassing the lifecycle's per-node preamble rebuild; each branch node
inherits `current.preamble` as computed for the fan-out node itself.
6. **Nested parallel silently loses git isolation.** Branch `EngineServices`
are built with `git_state: RwLock::new(None)` (`parallel.rs:380`), so a
`component` node inside a branch runs its own branches with no worktrees
and no warning.
7. **Docs contradict the engine.** `tutorials/ensemble.mdx:85` and
`tutorials/parallel-review.mdx:81` claim the post-merge node receives all
branch perspectives in its preamble (false, per A.1).
`workflows/stages-and-nodes.mdx:195` claims merged results are available to
downstream nodes as `parallel_results.json` (the file exists only under
`stages/<fork>@1/` in dumps, not in any node's working directory).
8. **`fidelity="full"` across a fan-in is a trap.** It drops the preamble
(metadata included) and cannot attach to any branch thread; raising
fidelity strictly reduces what the downstream node sees. No lint warns.
## Appendix B: behavior changes vs. today
Changes a user could observe if this spec is implemented as written.
1. **Chained branch nodes execute.** Graphs that (unknowingly) relied on
single-node branch semantics will now run the full chain (fixes A.2; may
lengthen existing runs).
2. **New validation errors.** Branch paths that don't converge on the join,
and nested `component` nodes inside branches, become lint failures for
graphs that previously ran (with wrong or silently degraded semantics).
3. **Fan-in owns the fast-forward.** The workspace after fan-in may land on a
different commit than today whenever selection (scores, LLM judge)
disagrees with lexical-first order. The parallel handler no longer merges.
4. **Post-fan-in context is richer.** `response.<id>` for every branch,
winner-sourced singletons (`last_stage`, `last_response`,
`command.output`), and `score` in `parallel.results`. Today those
singletons retain their pre-fork values; workflows with edge conditions
over them could route differently.
5. **Preambles after fan-in grow.** Branch responses render inline at
`compact` fidelity (bounded). Downstream nodes see more tokens per run;
snapshot tests over preambles will churn.
6. **Branch executions become visible stages.** Events, dumps, the web UI, and
the stage list gain per-branch stages (`a@1` under `fork@1`). Consumers of
`events.jsonl` / the API will see new stage records.
7. **`parallel_results.json` docs claim is corrected, not implemented.**
`workflows/stages-and-nodes.mdx:195` is updated to describe the real
channels (context key + preamble); no file appears in the workspace
(open question 4 covers deterministic consumers).
8. **Loser branch refs are documented as retained** and become part of the
product contract instead of an accident of not deleting them.
9. **`first_success` cancels losers explicitly** and records cancelled stages;
today's exact cancellation behavior is unspecified.
10. **LLM judge prompts change shape.** Fan-in nodes with prompts now send
candidate excerpts and diff stats to the judge — more tokens, different
(better) selections than today's id-only prompt.
- Branches remain single-node executions.
- `max_parallel` remains supported.
- Results are deterministic in outgoing-edge order.
- There is no branch-selection score, SHA, model-usage mode, notice, or UI.
- Server-owned independent checkout/worktree behavior is separate and remains
unchanged.

1
docs/public/administration/server-configuration.mdx
View file

@ -377,6 +377,7 @@ Standalone CLI/library usage can still opt into env-backed credential sources ex
| `INCEPTION_API_KEY` | Inception (Mercury) |
| `POOLSIDE_API_KEY` | Poolside (Laguna) |
| `OPENROUTER_API_KEY` | OpenRouter (when enabled) |
| `FIREWORKS_API_KEY` | Fireworks AI (when enabled) |
### Sandbox and tools

37
docs/public/api-reference/fabro-api.yaml
View file

@ -8329,6 +8329,20 @@ components:
description: Cost per million cached input tokens in USD.
example: 1.50
ModelControls:
description: Request-control values accepted by a provider/model offering.
type: object
required:
- reasoning_effort
properties:
reasoning_effort:
type: array
description: >-
Exact reasoning-effort values accepted by this offering. An empty
array means the request control is unsupported.
items:
$ref: "#/components/schemas/ReasoningEffort"
Model:
description: |
One provider's offering of an LLM model. The `id` is unique within
@ -8343,6 +8357,7 @@ components:
- training
- knowledge_cutoff
- features
- controls
- costs
- estimated_output_tps
- aliases
@ -8376,6 +8391,8 @@ components:
example: "May 2025"
features:
$ref: "#/components/schemas/ModelFeatures"
controls:
$ref: "#/components/schemas/ModelControls"
costs:
$ref: "#/components/schemas/ModelCosts"
estimated_output_tps:
@ -10540,6 +10557,22 @@ components:
items:
$ref: "#/components/schemas/StageContextWindowWarning"
ParallelBranchResult:
description: The outcome and isolated context updates from one parallel branch.
type: object
required:
- id
- status
- context_updates
properties:
id:
type: string
status:
$ref: "#/components/schemas/StageOutcome"
context_updates:
type: object
additionalProperties: true
StageProjection:
description: Observable projection data for one workflow stage execution.
type: object
@ -10577,8 +10610,8 @@ components:
parallel_results:
type: ["array", "null"]
items:
type: object
description: Per-branch result objects produced by a parallel stage.
$ref: "#/components/schemas/ParallelBranchResult"
description: Ordered per-branch results produced by a parallel stage.
output:
type: ["string", "null"]
output_bytes:

1
docs/public/docs.json
View file

@ -98,6 +98,7 @@
"integrations/bedrock",
"integrations/poolside",
"integrations/openrouter",
"integrations/fireworks",
"integrations/slack",
"integrations/brave-search"
]

10
docs/public/examples/clone-substack.mdx
View file

@ -153,8 +153,8 @@ Write to .workflow/plan_b.md."
label="Debate & Consolidate",
prompt="Synthesize the two implementation plans into a single best-of-breed \
final plan.\n\n\
Read branch outputs via parallel_results.json. If parallel_results.json is missing, \
fall back to reading .workflow/plan_a.md and .workflow/plan_b.md.\n\n\
Review every branch result in parallel.results from the prompt context, then read \
.workflow/plan_a.md and .workflow/plan_b.md from the shared checkout.\n\n\
If .workflow/postmortem_latest.md exists, read it FIRST. The postmortem contains \
root-cause analysis and concrete fixes from the previous iteration. The final plan \
MUST be adjusted to address every issue identified in the postmortem — add new \
@ -481,8 +481,8 @@ Write to .workflow/review_b.md."
goal_gate=true,
retry_target="postmortem",
prompt="Synthesize the two reviews into a consensus verdict.\n\n\
Read branch outputs via parallel_results.json. If parallel_results.json is \
missing, fall back to reading .workflow/review_a.md and .workflow/review_b.md.\n\n\
Review every branch result in parallel.results from the prompt context, then read \
.workflow/review_a.md and .workflow/review_b.md from the shared checkout.\n\n\
Read .workflow/definition_of_done.md for acceptance criteria reference.\n\n\
Consensus rules:\n\
- Both APPROVED with no critical gaps: the implementation passes\n\
@ -513,7 +513,7 @@ Read (if they exist):\n\
- .workflow/test-evidence/latest/manifest.json\n\
- Evidence files referenced by manifest entries for failed or suspicious IT \
scenarios\n\
- Branch review outputs via parallel_results.json (if available)\n\n\
- Parallel branch review status and context updates from parallel.results (if available)\n\n\
Output to .workflow/postmortem_latest.md (overwrite previous):\n\
- Root causes of failure\n\
- What works and must be preserved\n\

9
docs/public/execution/context.mdx
View file

@ -57,13 +57,14 @@ Agents can also emit arbitrary context updates by including a JSON object with a
| `human.gate.<node>.answer` | The answer text for a specific human gate node |
| `human.gate.<node>.label` | The selected label for a specific human gate node, when applicable |
### Parallel merge (fan-in)
### Parallel fan-out and fan-in
| Key | Value |
|---|---|
| `parallel.fan_in.best_id` | Node ID of the best-performing branch |
| `parallel.fan_in.best_outcome` | Status of the best branch |
| `parallel.fan_in.best_head_sha` | Git SHA from the best branch (if applicable) |
| `parallel.results` | Ordered branch results. Each entry contains `id`, `status`, and the branch's isolated `context_updates`. |
| `parallel.branch_count` | Number of outgoing branches dispatched by the parallel node. |
Branch updates remain nested inside `parallel.results`; they are not merged into top-level context. Prompted fan-in nodes can synthesize the complete result array, while promptless fan-in nodes act as barriers.
### Engine-managed keys

2
docs/public/execution/outcomes.mdx
View file

@ -26,7 +26,7 @@ Each node type has its own rules for which outcomes it can return:
|---|---|---|
| **Command** | `succeeded`, `failed` | `succeeded` when exit code is 0; `failed` otherwise |
| **Agent / Prompt** | `succeeded`, `failed`, `partially_succeeded`, `skipped` | Defaults to `succeeded`. The LLM can set any outcome via a [routing directive](/agents/outputs#routing-directives) JSON object in its response. Backend errors request retry when retryable or finish as `failed`. |
| **Parallel** | `succeeded`, `partially_succeeded`, `failed` | Depends on the `join_policy`. `wait_all`: `succeeded` if no failures, `partially_succeeded` if some branches failed. `first_success`: `succeeded` if threshold met, else `failed`. |
| **Parallel** | `succeeded`, `partially_succeeded`, `failed` | Waits for every branch. `succeeded` when all branches succeed, `failed` when all branches fail, and `partially_succeeded` for mixed, partial, or zero-branch results. |
| **Human** | `succeeded` | Always succeeds — the user's selection becomes a routing signal via `preferred_label` |
| **Conditional** | `succeeded` | Always succeeds — routing is handled by the engine's edge selection |
| **Start / Exit / Wait** | `succeeded` | Always succeed |

139
docs/public/integrations/fireworks.mdx Normal file
View file

@ -0,0 +1,139 @@
---
title: "Fireworks AI"
description: "Run open-weights models on Fireworks AI's serverless inference platform"
---
[Fireworks AI](https://fireworks.ai/) serves open-weights models (Kimi, DeepSeek, GLM, Qwen, GPT-OSS, and more) behind an OpenAI-compatible API. Fabro ships a disabled `fireworks` provider entry with a curated model catalog, so you can opt in from `settings.toml` without changing Fabro code.
## Prerequisites
- A [Fireworks AI account](https://fireworks.ai/) with serverless credit
- An API key from [app.fireworks.ai/settings/users/api-keys](https://app.fireworks.ai/settings/users/api-keys)
## Enable the provider
Fabro runs execute through a Fabro server. Add the provider override to the settings file used by that server. For a local server, this is usually `~/.fabro/settings.toml`; for a remote deployment, update the server host's Fabro settings.
```toml title="settings.toml"
_version = 1
[llm.providers.fireworks]
enabled = true
```
## Configure credentials
Store the key in the target Fabro server vault:
```bash
fabro provider login --provider fireworks
# For a non-default remote server:
fabro provider login --server https://your-fabro.example --provider fireworks
# Or set the vault token directly:
fabro secret set FIREWORKS_API_KEY fw_...
fabro secret --server https://your-fabro.example set FIREWORKS_API_KEY fw_...
```
Direct SDK usage outside a Fabro server can use an env-backed credential source explicitly:
```bash
export FIREWORKS_API_KEY=fw_...
```
## Included models
The built-in catalog gives Fireworks offerings the same human-facing model slugs used by other providers. Fireworks account-scoped model paths remain opaque `api_id` values:
| Fabro model slug | Fireworks API ID / notes |
| --- | --- |
| `kimi-k2.7-code` | `accounts/fireworks/models/kimi-k2p7-code`; provider default |
| `kimi-k2.6` | `accounts/fireworks/models/kimi-k2p6` |
| `deepseek-v4-pro`, `deepseek-v4-flash` | `accounts/fireworks/models/deepseek-v4-...` |
| `glm-5.2` | `accounts/fireworks/models/glm-5p2` |
| `minimax-m2.7` | `accounts/fireworks/models/minimax-m2p7` |
| `qwen3.7-plus` | `accounts/fireworks/models/qwen3p7-plus` |
| `gpt-oss-120b` | `accounts/fireworks/models/gpt-oss-120b` |
| `gpt-oss-20b` | `accounts/fireworks/models/gpt-oss-20b`; provider small default |
Any other Fireworks serverless model can be added under the provider. Choose a stable Fabro model slug as the table key and put the Fireworks account-scoped path in `api_id` (dots in upstream model names become `p`, e.g. `glm-5.2` → `glm-5p2`):
```toml title="settings.toml"
[llm.providers.fireworks.models."llama-4-maverick"]
api_id = "accounts/fireworks/models/llama4-maverick-instruct-basic"
display_name = "Llama 4 Maverick"
family = "llama-4"
[llm.providers.fireworks.models."llama-4-maverick".limits]
context_window = 1000000
[llm.providers.fireworks.models."llama-4-maverick".features]
tools = true
vision = false
reasoning = false
```
Note that Fireworks' `GET /v1/models` endpoint only returns a featured subset of serverless models; a model absent from that list may still be servable. Verify custom additions with `fabro model test`.
## Use Fireworks models
```bash
fabro model list --provider fireworks
fabro model test --provider fireworks --model kimi-k2.7-code
fabro run workflow.fabro --provider fireworks --model deepseek-v4-flash
```
When targeting a non-default remote server, pass the same `--server` value to verification commands:
```bash
fabro model list --server https://your-fabro.example --provider fireworks
fabro model test --server https://your-fabro.example --provider fireworks --model kimi-k2.7-code
```
In workflow stylesheets:
```dot title="workflow.fabro"
digraph Example {
graph [
model_stylesheet="
* { model: fireworks/kimi-k2.7-code; }
"
]
start [shape=Mdiamond, label="Start"]
work [label="Work", prompt="Use the configured Fireworks model."]
exit [shape=Msquare, label="Exit"]
start -> work -> exit
}
```
## Prompt caching
Fireworks caches prompt prefixes automatically — no cache breakpoints or request changes are needed. Serverless responses report cached tokens in the usage body, and cached input tokens are billed at a per-model discount (typically 50% or better). Fabro reads the cached-token counts and applies the catalog's `cache_input_cost_per_mtok` rates when estimating costs.
## Costs
Catalog prices mirror [Fireworks serverless pricing](https://docs.fireworks.ai/serverless/pricing) (standard tier). Fireworks does not return in-band billing, so Fabro reports `cost_source = "estimated"` from catalog rates. Fireworks' "Fast" model variants and Priority service tier are not included in the built-in catalog.
## Troubleshooting
**"No API key configured"** — Set the key on the target server with `fabro provider login --provider fireworks` or `fabro secret set FIREWORKS_API_KEY ...`. For direct SDK usage outside a Fabro server, export `FIREWORKS_API_KEY` in the invoking shell.
**"provider 'fireworks' is not configured in the server model catalog"** — Confirm the server host's `settings.toml` has `[llm.providers.fireworks]` with `enabled = true`. Fabro live-reloads `settings.toml` within a few seconds; after that, `fabro model list --provider fireworks` against the same server should show the enabled catalog.
**402 / insufficient credits** — Serverless inference requires prepaid credit; check your balance in the [Fireworks billing dashboard](https://app.fireworks.ai/settings/billing).
**Unknown model** — Confirm the model's `api_id` matches a Fireworks account-scoped path exactly (`accounts/fireworks/models/...`), then run `fabro model test --model <fabro-model-id>`. Remember that `GET /v1/models` only lists a featured subset, so absence from that list is not conclusive.
## Further reading
<Columns cols={2}>
<Card title="Models" icon="microchip" href="/core-concepts/models">
How Fabro routes model IDs, providers, and fallbacks.
</Card>
<Card title="Settings Configuration" icon="gear" href="/reference/user-configuration">
Full reference for provider settings and provider-scoped model offerings.
</Card>
</Columns>

3
docs/public/reference/dot-language.mdx
View file

@ -252,8 +252,7 @@ audit [
| Attribute | Type | Description |
|---|---|---|
| `join_policy` | String | When the merge can proceed: `wait_all` (default), `first_success` |
| `max_parallel` | Integer | Maximum concurrent branches (default: 4) |
| `max_parallel` | Integer | Maximum concurrent branches (default: 4). The node always waits for every branch. |
For the first node in each branch, `fidelity` resolves from the fork-to-branch edge, then the branch node; without either, the fork preamble is inherited unchanged. Branch-specific preambles are rendered before fan-out from the fork's context snapshot. Concurrent branches cannot share sessions, so explicit branch `full` becomes `summary:high`, and branch-level `thread_id` is inert.

8
docs/public/tutorials/ensemble.mdx
View file

@ -1,6 +1,6 @@
---
title: "Ensemble"
description: "Multi-provider fan-out, error policies, and result synthesis"
description: "Multi-provider fan-out and shared-checkout result synthesis"
---
This tutorial combines parallel execution with multi-model routing to get independent opinions from four different LLM providers, then synthesizes the results. This is the ensemble pattern — useful when you want diverse perspectives, consensus-based decisions, or protection against any single model's blind spots.
@ -28,15 +28,15 @@ digraph Ensemble {
start [shape=Mdiamond, label="Start"]
exit [shape=Msquare, label="Exit"]
fork [label="Fan Out", shape=component, join_policy="wait_all"]
fork [label="Fan Out", shape=component]
opus [label="Opus", prompt="Analyze the goal. Provide your independent assessment, recommendations, and any code or prose needed. Be thorough.", shape=tab]
gemini [label="Gemini", prompt="Analyze the goal. Provide your independent assessment, recommendations, and any code or prose needed. Be thorough.", shape=tab]
codex [label="Codex", prompt="Analyze the goal. Provide your independent assessment, recommendations, and any code or prose needed. Be thorough.", shape=tab]
mercury [label="Mercury", prompt="Analyze the goal. Provide your independent assessment, recommendations, and any code or prose needed. Be thorough.", shape=tab]
merge [label="Merge", shape=tripleoctagon]
synth [label="Synthesize", prompt="You have received independent analyses from four different models (Opus, Gemini, Codex, Mercury). Compare their perspectives: identify consensus, highlight disagreements, and synthesize the strongest ideas into a single coherent recommendation. Note where models agreed and where they diverged.", shape=tab]
merge [label="Synthesize", shape=tripleoctagon, prompt="Compare every branch result: identify consensus, highlight disagreements, and synthesize the strongest ideas into one recommendation. Note where models agreed and diverged."]
synth [label="Write Recommendation", prompt="Write the synthesized analysis as a single coherent recommendation.", shape=tab]
start -> fork
fork -> opus

41
docs/public/tutorials/parallel-review.mdx
View file

@ -1,6 +1,6 @@
---
title: "Parallel Review"
description: "Fan-out, fan-in, join policies, and merge nodes"
description: "Shared-checkout fan-out, fan-in, and result synthesis"
---
This tutorial runs three code review perspectives in parallel — security, architecture, and quality — then merges the results into a single report.
@ -19,14 +19,14 @@ digraph Parallel {
start [shape=Mdiamond, label="Start"]
exit [shape=Msquare, label="Exit"]
fork [label="Fork Analysis", shape=component, join_policy="wait_all"]
fork [label="Fork Analysis", shape=component]
security [label="Security Audit", prompt="Examine the codebase for security concerns: hardcoded secrets, injection risks, unsafe dependencies. List findings as bullet points.", shape=tab, reasoning_effort="low"]
architecture [label="Architecture Review", prompt="Assess the codebase architecture: separation of concerns, dependency structure, modularity. List findings as bullet points.", shape=tab, reasoning_effort="low"]
quality [label="Code Quality", prompt="Check code quality: naming conventions, dead code, test coverage gaps, error handling. List findings as bullet points.", shape=tab, reasoning_effort="low"]
merge [label="Merge Findings", shape=tripleoctagon]
report [label="Final Report", prompt="Synthesize the security, architecture, and code quality findings into a prioritized summary report with top 5 action items.", shape=tab]
merge [label="Synthesize Findings", shape=tripleoctagon, prompt="Synthesize every branch result into a prioritized summary report with the top 5 action items."]
report [label="Write Final Report", prompt="Write the synthesized review as a clear final report.", shape=tab]
start -> fork
fork -> security
@ -48,37 +48,38 @@ fabro run docs/internal/demo/06-parallel.fabro
The `fork` node has `shape=component`, making it a **parallel fan-out node**. Every outgoing edge becomes a concurrent branch:
```dot
fork [label="Fork Analysis", shape=component, join_policy="wait_all"]
fork [label="Fork Analysis", shape=component]
fork -> security
fork -> architecture
fork -> quality
```
All three branches start at the same time. Each gets an isolated copy of the run context, so branches can't interfere with each other.
All three branches start concurrently and operate in the same sandbox checkout and working directory. This review is safe because the branches are prompt nodes with no workspace tools.
### Join policies
<Warning>
Parallel branches are not isolated from one another. If branches edit files, they can observe, race with, or overwrite each other's changes. Fabro does not lock files, detect overlapping writes, or warn about races. Keep branches read-only or give each branch responsibility for disjoint paths.
</Warning>
The `join_policy` controls when execution can proceed past the merge:
| Policy | Behavior |
|---|---|
| `wait_all` | Wait for every branch to finish (default) |
| `first_success` | Proceed as soon as one branch succeeds |
The parallel node always waits for every branch to finish before continuing.
## Fan-in with the merge node
The `merge` node has `shape=tripleoctagon`, making it a **merge (fan-in) node**. It collects results from all branches into a single context:
The `merge` node has `shape=tripleoctagon`, making it a **merge (fan-in) node**. It receives every branch's status and context updates in `parallel.results` and synthesizes them with its prompt:
```dot
merge [label="Merge Findings", shape=tripleoctagon]
merge [
label="Synthesize Findings",
shape=tripleoctagon,
prompt="Synthesize every branch result into a prioritized summary report with the top 5 action items."
]
security -> merge
architecture -> merge
quality -> merge
```
The merged branch results are available to downstream nodes. The `report` node receives all three perspectives in its preamble and synthesizes them.
`parallel.results` is runtime context, not a `parallel_results.json` file in the checkout. Fan-in never selects a branch's files or changes workspace state; every branch has already worked in the same checkout. The downstream `report` node writes the synthesis produced by fan-in as the final report.
## Concurrency control
@ -92,10 +93,10 @@ This is useful when branches are resource-intensive (e.g., each running a full a
## What you've learned
- **Fan-out nodes** (`shape=component`) spawn concurrent branches
- **Merge nodes** (`shape=tripleoctagon`) collect branch results
- **Join policies** control when execution can proceed past the merge
- Each branch gets an isolated copy of the context
- **Fan-out nodes** (`shape=component`) spawn concurrent branches and wait for all of them
- Parallel branches share one checkout, so workflows must prevent or tolerate file races
- **Fan-in nodes** (`shape=tripleoctagon`) can synthesize `parallel.results` with a prompt
- Fan-in never selects or restores workspace state, and no results file is created
## Next

24
docs/public/workflows/stages-and-nodes.mdx
View file

@ -155,10 +155,10 @@ Conditions support `=`, `!=`, `&&`, and context variable lookups (e.g. `context.
**Shape:** `component`
Fans out to execute multiple branches concurrently. Each branch gets its own isolated context.
Fans out to execute multiple branches concurrently. Every branch runs in the same sandbox checkout and working directory, and the parallel node waits for every branch to finish.
```dot
fork [label="Fan Out", shape=component, join_policy="wait_all"]
fork [label="Fan Out", shape=component]
fork -> security
fork -> architecture
@ -167,26 +167,24 @@ fork -> quality
| Attribute | Description |
|---|---|
| `join_policy` | When the merge can proceed (see table below) |
| `max_parallel` | Maximum concurrent branches (default: 4) |
Because the checkout is shared, file changes from one branch are immediately visible to the others. Concurrent writes can race or overwrite each other. Fabro does not isolate branch files, lock paths, detect conflicts, or warn about overlapping writes. Design branches to be read-only or assign each branch disjoint files and directories when deterministic workspace changes matter.
For each branch's first node, fidelity resolves from the fork-to-branch edge, then the branch node; otherwise it inherits the fork preamble unchanged. Fabro renders branch-specific preambles before fan-out from the fork snapshot. Branch-level `full` degrades to `summary:high` because concurrent branches cannot share sessions, and `thread_id` on a branch node or fork-to-branch edge is inert.
**Join policies:**
| Policy | Behavior |
|---|---|
| `wait_all` | Wait for every branch to finish (default) |
| `first_success` | Proceed as soon as one branch succeeds |
### Merge (fan-in)
**Shape:** `tripleoctagon`
Collects results from parallel branches into a single context. Typically paired with a parallel fan-out node:
Converges parallel branches after all of them finish. Branch status and context updates are collected in the runtime context at `parallel.results`; Fabro does not create a `parallel_results.json` file in the checkout.
```dot
merge [label="Merge Results", shape=tripleoctagon]
merge [
label="Synthesize Results",
shape=tripleoctagon,
prompt="Synthesize every branch result into one report."
]
security -> merge
architecture -> merge
@ -194,7 +192,7 @@ quality -> merge
merge -> report
```
The merged results are available to downstream nodes as `parallel_results.json`.
A fan-in node with a `prompt` synthesizes the collected results. It never chooses, restores, or merges a branch's workspace state: all branches have already operated on the same checkout. Without a prompt, fan-in is only a convergence barrier.
## Common node attributes

1
lib/apps/fabro-cli/src/commands/install.rs
View file

@ -3511,6 +3511,7 @@ root = "{}"
assert!(ids.contains(&ProviderId::new("inception")));
assert!(ids.contains(&ProviderId::new("venice")));
assert!(ids.contains(&ProviderId::new("poolside")));
assert!(!ids.contains(&ProviderId::new("fireworks")));
assert!(!ids.contains(&ProviderId::new("ollama")));
assert!(!ids.contains(&ProviderId::new("litellm")));
}

6
lib/apps/fabro-cli/src/commands/model.rs
View file

@ -517,7 +517,9 @@ impl Default for ModelsCommand {
#[cfg(test)]
mod tests {
use fabro_model::{ModelCosts, ModelFeatures, ModelLimits, ReasoningEffortFeature};
use fabro_model::{
ModelControls, ModelCosts, ModelFeatures, ModelLimits, ReasoningEffortFeature,
};
use super::*;
@ -546,6 +548,7 @@ mod tests {
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls::default(),
costs: ModelCosts {
input_cost_per_mtok: Some(1.0),
output_cost_per_mtok: Some(2.0),
@ -581,6 +584,7 @@ mod tests {
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls::default(),
costs: ModelCosts {
input_cost_per_mtok: Some(1.0),
output_cost_per_mtok: Some(2.0),

4
lib/apps/fabro-cli/src/commands/run/run_progress/event.rs
View file

@ -130,7 +130,7 @@ pub(super) enum ProgressEvent {
ParallelBranchCompleted {
branch: String,
duration_ms: u64,
status: String,
status: fabro_types::StageOutcome,
},
ParallelCompleted,
AssistantMessage {
@ -318,7 +318,7 @@ pub(super) fn from_run_event(stored: &RunEvent) -> Option<ProgressEvent> {
EventBody::ParallelBranchCompleted(props) => Some(ProgressEvent::ParallelBranchCompleted {
branch: node_id,
duration_ms: props.duration_ms,
status: props.status.clone(),
status: props.status,
}),
EventBody::ParallelCompleted(_) => Some(ProgressEvent::ParallelCompleted),
EventBody::AgentMessage(props) => Some(ProgressEvent::AssistantMessage {

11
lib/apps/fabro-cli/src/commands/run/run_progress/mod.rs
View file

@ -248,7 +248,7 @@ impl ProgressUI {
status,
} => {
self.stage
.on_parallel_branch_completed(renderer, &branch, duration_ms, &status);
.on_parallel_branch_completed(renderer, &branch, duration_ms, status);
}
ProgressEvent::ParallelCompleted => {
self.stage.on_parallel_completed();
@ -587,7 +587,6 @@ mod tests {
node_id: "fork1".into(),
visit: 1,
branch_count: 2,
join_policy: "wait_all".into(),
});
assert_eq!(ui.stage.parallel_parent.as_deref(), Some("fork1"));
@ -611,8 +610,7 @@ mod tests {
branch: "security".into(),
index: 0,
duration_ms: 2000,
status: "succeeded".into(),
head_sha: None,
status: fabro_workflow::outcome::StageOutcome::Succeeded,
});
let stage = &ui.stage.active_stages["fork1"];
assert!(matches!(
@ -630,7 +628,6 @@ mod tests {
node_id: "fork1".into(),
visit: 1,
branch_count: 1,
join_policy: "wait_all".into(),
});
emit(&mut ui, Event::ParallelBranchStarted {
parallel_group_id: StageId::new("fork1", 1),
@ -1246,7 +1243,6 @@ mod tests {
node_id: "fork1".into(),
visit: 1,
branch_count: 1,
join_policy: "wait_all".into(),
});
emit(&mut ui, Event::ParallelBranchStarted {
parallel_group_id: StageId::new("fork1", 1),
@ -1260,8 +1256,7 @@ mod tests {
branch: "security".into(),
index: 0,
duration_ms: 500,
status: "succeeded".into(),
head_sha: None,
status: fabro_workflow::outcome::StageOutcome::Succeeded,
});
let stage = &ui.stage.active_stages["fork1"];

4
lib/apps/fabro-cli/src/commands/run/run_progress/stage_display.rs
View file

@ -244,7 +244,7 @@ impl StageDisplay {
renderer: &ProgressRenderer,
branch: &str,
duration_ms: u64,
status: &str,
status: StageOutcome,
) {
let Some(parent_id) = self.parallel_parent.clone() else {
return;
@ -261,7 +261,7 @@ impl StageDisplay {
return;
};
let succeeded = matches!(status, "succeeded" | "partially_succeeded");
let succeeded = status.is_successful();
entry.status = if succeeded {
ToolCallStatus::Succeeded
} else {

12
lib/apps/fabro-cli/tests/it/cmd/model.rs
View file

@ -108,6 +108,9 @@ fn list_with_filters_renders_server_models_table() {
"vision": false,
"reasoning": false
},
"controls": {
"reasoning_effort": []
},
"costs": {
"input_cost_per_mtok": 1.2,
"output_cost_per_mtok": 3.4,
@ -134,6 +137,9 @@ fn list_with_filters_renders_server_models_table() {
"vision": true,
"reasoning": true
},
"controls": {
"reasoning_effort": []
},
"costs": {
"input_cost_per_mtok": null,
"output_cost_per_mtok": null,
@ -206,6 +212,9 @@ fn list_uses_configured_server_target_without_server_flag() {
"vision": false,
"reasoning": false
},
"controls": {
"reasoning_effort": []
},
"costs": {
"input_cost_per_mtok": 1.0,
"output_cost_per_mtok": 2.0,
@ -260,6 +269,9 @@ fn list_uses_fabro_config_for_machine_settings() {
"vision": false,
"reasoning": false
},
"controls": {
"reasoning_effort": []
},
"costs": {
"input_cost_per_mtok": 1.0,
"output_cost_per_mtok": 2.0,

3
lib/apps/fabro-cli/tests/it/cmd/model_test.rs
View file

@ -42,6 +42,9 @@ fn model_json(id: &str, provider: &str, configured: bool) -> serde_json::Value {
"vision": false,
"reasoning": false
},
"controls": {
"reasoning_effort": []
},
"costs": {
"input_cost_per_mtok": 1.0,
"output_cost_per_mtok": 2.0,

6
lib/apps/fabro-cli/tests/it/workflow/dry_run_examples.rs
View file

@ -80,7 +80,9 @@ fn dry_run_parallel() {
let mut cmd = context.run_cmd();
cmd.args(["--dry-run", "--auto-approve"]);
cmd.arg(&workflow);
fabro_snapshot!(run_output_filters(&context), cmd, @"
let mut filters = run_output_filters(&context);
filters.push((r"\bbranch[12]\b".to_string(), "[BRANCH]".to_string()));
fabro_snapshot!(filters, cmd, @"
success: true
exit_code: 0
----- stdout -----
@ -93,6 +95,8 @@ fn dry_run_parallel() {
Web UI: http://localhost:3000/runs/[ULID]
Sandbox: local (ready in [TIME])
✓ start [TIME]
✓ [BRANCH] [TIME]
✓ [BRANCH] [TIME]
✓ Fork Work [TIME]
✓ Merge Results [TIME]
✓ Review [TIME]

12
lib/apps/fabro-server/src/run_files.rs
View file

@ -1194,16 +1194,8 @@ fn to_sha_wrapper(sha: &str) -> RunFilesMetaToSha {
async fn load_projection(
state: &Arc<AppState>,
run_id: &RunId,
) -> std::result::Result<fabro_store::RunProjection, ApiError> {
let reader = state
.store_ref()
.open_run_reader(run_id)
.await
.map_err(|_| ApiError::not_found("Run not found."))?;
reader
.state()
.await
.map_err(|err| ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()))
) -> std::result::Result<Arc<fabro_store::RunProjection>, ApiError> {
Ok(state.cached_run(run_id).await?.projection)
}
async fn reconnect_run_sandbox(

39
lib/apps/fabro-server/src/server.rs
View file

@ -85,8 +85,8 @@ use fabro_slack::threads::ThreadRegistry;
use fabro_slack::{blocks as slack_blocks, connection as slack_connection};
use fabro_static::EnvVars;
use fabro_store::{
ArtifactKey, ArtifactStore, Database, EventEnvelope, EventPayload, NodeArtifact,
PendingInterviewRecord, RunSummaryStore, StageArtifactEntry, StageId,
ArtifactKey, ArtifactStore, CachedRunProjection, Database, EventEnvelope, EventPayload,
NodeArtifact, PendingInterviewRecord, RunSummaryStore, StageArtifactEntry, StageId,
};
#[cfg(test)]
use fabro_types::BlockedReason;
@ -1532,6 +1532,18 @@ impl AppState {
&self.stores.runs
}
/// Current cached projection for `run_id`, with the standard HTTP error
/// mapping: storage failures become 500s and a missing run becomes the
/// canonical 404.
pub(crate) async fn cached_run(&self, run_id: &RunId) -> Result<CachedRunProjection, ApiError> {
self.stores
.runs
.get_cached_run(run_id)
.await
.map_err(|err| ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()))?
.ok_or_else(|| ApiError::not_found("Run not found."))
}
pub(crate) fn session_runtimes(&self) -> &SessionRuntimeManager {
&self.session_runtimes
}
@ -2698,9 +2710,8 @@ async fn delete_run_internal(
}
async fn load_durable_run_status(state: &AppState, id: &RunId) -> Option<RunStatus> {
let run_store = state.stores.runs.open_run(id).await.ok()?;
let projection = run_store.state().await.ok()?;
Some(projection.status)
let cached = state.cached_run(id).await.ok()?;
Some(cached.projection.status)
}
async fn delete_run_sandbox_resource(
@ -3749,15 +3760,10 @@ async fn load_pending_interview(
run_id: RunId,
qid: &str,
) -> Result<LoadedPendingInterview, Response> {
let cached = match state.stores.runs.get_cached_run(&run_id).await {
Ok(Some(cached)) => cached,
Ok(None) => return Err(ApiError::not_found("Run not found.").into_response()),
Err(err) => {
return Err(
ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response(),
);
}
};
let cached = state
.cached_run(&run_id)
.await
.map_err(IntoResponse::into_response)?;
let Some(record) = cached.projection.pending_interviews.get(qid) else {
return Err(ApiError::new(
StatusCode::CONFLICT,
@ -4533,9 +4539,8 @@ async fn append_control_request(
/// run is currently archived. Returns `None` otherwise (including when the run
/// doesn't exist — the caller's own not-found handling will surface that).
async fn reject_if_archived(state: &AppState, run_id: &RunId) -> Option<Response> {
let run_store = state.stores.runs.open_run_reader(run_id).await.ok()?;
let projection = run_store.state().await.ok()?;
projection.archived_at.is_some().then(|| {
let cached = state.cached_run(run_id).await.ok()?;
cached.projection.archived_at.is_some().then(|| {
ApiError::new(
StatusCode::CONFLICT,
operations::archived_rejection_message(run_id),

32
lib/apps/fabro-server/src/server/handler/artifacts.rs
View file

@ -68,15 +68,12 @@ async fn get_checkpoint(
Ok(id) => id,
Err(response) => return response,
};
match state.stores.runs.get_cached_run(&id).await {
Ok(Some(cached)) => match cached.projection.current_checkpoint() {
match state.cached_run(&id).await {
Ok(cached) => match cached.projection.current_checkpoint() {
Some(cp) => (StatusCode::OK, Json(cp.clone())).into_response(),
None => (StatusCode::OK, Json(serde_json::json!(null))).into_response(),
},
Ok(None) => ApiError::not_found("Run not found.").into_response(),
Err(err) => {
ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response()
}
Err(err) => err.into_response(),
}
}
@ -118,17 +115,12 @@ async fn read_run_blob(
}
}
async fn load_run_spec(state: &AppState, run_id: &RunId) -> Result<fabro_types::RunSpec, Response> {
let run_store = state
.stores
.runs
.open_run_reader(run_id)
async fn ensure_run_exists(state: &AppState, run_id: &RunId) -> Result<(), Response> {
state
.cached_run(run_id)
.await
.map_err(|_| ApiError::not_found("Run not found.").into_response())?;
let run_state = run_store.state().await.map_err(|err| {
ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response()
})?;
Ok(run_state.spec)
.map(|_| ())
.map_err(IntoResponse::into_response)
}
async fn list_run_artifacts(
@ -140,7 +132,7 @@ async fn list_run_artifacts(
Ok(id) => id,
Err(response) => return response,
};
if let Err(response) = load_run_spec(state.as_ref(), &id).await {
if let Err(response) = ensure_run_exists(state.as_ref(), &id).await {
return response;
}
@ -186,7 +178,7 @@ async fn list_stage_artifacts(
Ok(stage_id) => stage_id,
Err(response) => return response,
};
if let Err(response) = load_run_spec(state.as_ref(), &id).await {
if let Err(response) = ensure_run_exists(state.as_ref(), &id).await {
return response;
}
@ -568,7 +560,7 @@ async fn put_stage_artifact(
if let Some(response) = reject_if_archived(state.as_ref(), &id).await {
return response;
}
if let Err(response) = load_run_spec(state.as_ref(), &id).await.map(|_| ()) {
if let Err(response) = ensure_run_exists(state.as_ref(), &id).await {
return response;
}
let retry = match required_query_param(params.retry.as_ref(), "retry") {
@ -636,7 +628,7 @@ async fn get_stage_artifact(
Ok(path) => path,
Err(response) => return response,
};
if let Err(response) = load_run_spec(state.as_ref(), &id).await {
if let Err(response) = ensure_run_exists(state.as_ref(), &id).await {
return response;
}

26
lib/apps/fabro-server/src/server/handler/billing.rs
View file

@ -5,9 +5,9 @@ use chrono::{DateTime, Utc};
use fabro_types::{RunProjection, StageHandler, StageProjection, StageState, StageTiming};
use super::super::{
ApiError, AppState, BillingByModel, BillingStageRef, IntoResponse, Json, ListResponse,
PaginationParams, Path, Query, RequiredUser, Response, Router, RunBilling, RunBillingStage,
RunBillingTotals, RunId, State, StatusCode, get, parse_run_id_path, run_stage_from_stage_id,
AppState, BillingByModel, BillingStageRef, IntoResponse, Json, ListResponse, PaginationParams,
Path, Query, RequiredUser, Response, Router, RunBilling, RunBillingStage, RunBillingTotals,
RunId, State, StatusCode, get, parse_run_id_path, run_stage_from_stage_id,
};
pub(super) fn routes() -> Router<Arc<AppState>> {
@ -27,13 +27,9 @@ async fn list_run_stages(
Err(response) => return response,
};
let cached = match state.stores.runs.get_cached_run(&id).await {
Ok(Some(cached)) => cached,
Ok(None) => return ApiError::not_found("Run not found.").into_response(),
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
let cached = match state.cached_run(&id).await {
Ok(cached) => cached,
Err(err) => return err.into_response(),
};
let projection = cached.projection;
@ -70,13 +66,9 @@ async fn get_run_billing(
State(state): State<Arc<AppState>>,
Path(id): Path<RunId>,
) -> Response {
let cached = match state.stores.runs.get_cached_run(&id).await {
Ok(Some(cached)) => cached,
Ok(None) => return ApiError::not_found("Run not found.").into_response(),
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
let cached = match state.cached_run(&id).await {
Ok(cached) => cached,
Err(err) => return err.into_response(),
};
let projection = cached.projection;

4
lib/apps/fabro-server/src/server/handler/events.rs
View file

@ -427,8 +427,8 @@ async fn attach_run_events(
let start_seq = match params.since_seq {
Some(seq) if seq >= 1 => seq,
Some(_) => 1,
None => match run_store.list_events().await {
Ok(events) => events.last().map_or(1, |event| event.seq.saturating_add(1)),
None => match run_store.last_event_seq().await {
Ok(last_seq) => last_seq.map_or(1, |seq| seq.saturating_add(1)),
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();

19
lib/apps/fabro-server/src/server/handler/graph.rs
View file

@ -242,17 +242,14 @@ async fn load_run_dot_source(state: &AppState, id: &RunId) -> Result<String, Res
let dot_source = if let Some(dot) = live_dot_source.filter(|d| !d.is_empty()) {
Some(dot)
} else {
match state.stores.runs.open_run_reader(id).await {
Ok(run_store) => match run_store.state().await {
Ok(run_state) => run_state.spec.graph_source,
Err(err) => {
return Err(
ApiError::new(StatusCode::BAD_GATEWAY, err.to_string()).into_response()
);
}
},
Err(_) => return Err(ApiError::not_found("Run not found.").into_response()),
}
state
.cached_run(id)
.await
.map_err(IntoResponse::into_response)?
.projection
.spec
.graph_source
.clone()
};
dot_source

38
lib/apps/fabro-server/src/server/handler/pull_requests.rs
View file

@ -131,17 +131,8 @@ async fn load_pull_request_record(
state: &Arc<AppState>,
id: &RunId,
) -> Result<PullRequestLink, ApiError> {
let run_store = state
.stores
.runs
.open_run_reader(id)
.await
.map_err(|_| ApiError::not_found("Run not found."))?;
let run_state = run_store
.state()
.await
.map_err(|err| ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()))?;
run_state.pull_request.ok_or_else(|| {
let cached = state.cached_run(id).await?;
cached.projection.pull_request.clone().ok_or_else(|| {
ApiError::with_code(
StatusCode::NOT_FOUND,
format!("No pull request found in store. Create one first with: fabro pr create {id}"),
@ -297,14 +288,12 @@ async fn create_run_pull_request(
let Ok(run_store) = state.stores.runs.open_run(&id).await else {
return ApiError::not_found("Run not found.").into_response();
};
let run_state = match run_store.state().await {
Ok(run_state) => run_state,
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
let cached = match state.cached_run(&id).await {
Ok(cached) => cached,
Err(err) => return err.into_response(),
};
let inputs = match RunPrInputs::extract(&run_state, body.force) {
let run_state = cached.projection.as_ref();
let inputs = match RunPrInputs::extract(run_state, body.force) {
Ok(inputs) => inputs,
Err(err) => return err.into_response(),
};
@ -343,7 +332,7 @@ async fn create_run_pull_request(
llm_source: state.llm_source.as_ref(),
catalog,
conclusion: Some(inputs.conclusion),
run_state: Some(&run_state),
run_state: Some(run_state),
};
let created_pull_request = match pull_request::maybe_open_pull_request(request).await {
Ok(Some(created)) => created,
@ -401,14 +390,11 @@ async fn unlink_run_pull_request(
let Ok(run_store) = state.stores.runs.open_run(&id).await else {
return ApiError::not_found("Run not found.").into_response();
};
let run_state = match run_store.state().await {
Ok(run_state) => run_state,
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
let cached = match state.cached_run(&id).await {
Ok(cached) => cached,
Err(err) => return err.into_response(),
};
let Some(pull_request) = run_state.pull_request else {
let Some(pull_request) = cached.projection.pull_request.clone() else {
return ApiError::with_code(
StatusCode::NOT_FOUND,
format!("No pull request found in store. Create one first with: fabro pr create {id}"),

61
lib/apps/fabro-server/src/server/handler/runs.rs
View file

@ -935,13 +935,9 @@ async fn get_run_settings(
Ok(id) => id,
Err(response) => return response,
};
let cached = match state.stores.runs.get_cached_run(&id).await {
Ok(Some(cached)) => cached,
Ok(None) => return ApiError::not_found("Run not found.").into_response(),
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
let cached = match state.cached_run(&id).await {
Ok(cached) => cached,
Err(err) => return err.into_response(),
};
(
StatusCode::OK,
@ -954,8 +950,8 @@ async fn get_questions(
RequireRunManagementTarget(id, _actor): RequireRunManagementTarget,
State(state): State<Arc<AppState>>,
) -> Response {
match state.stores.runs.get_cached_run(&id).await {
Ok(Some(cached)) => {
match state.cached_run(&id).await {
Ok(cached) => {
let questions = cached
.projection
.pending_interviews
@ -964,10 +960,7 @@ async fn get_questions(
.collect::<Vec<_>>();
(StatusCode::OK, Json(ListResponse::new(questions))).into_response()
}
Ok(None) => ApiError::not_found("Run not found.").into_response(),
Err(err) => {
ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response()
}
Err(err) => err.into_response(),
}
}
@ -999,12 +992,9 @@ async fn get_run_state(
RequireRunManagementTarget(id, _actor): RequireRunManagementTarget,
State(state): State<Arc<AppState>>,
) -> Response {
match state.stores.runs.get_cached_run(&id).await {
Ok(Some(cached)) => Json((*cached.projection).clone()).into_response(),
Ok(None) => ApiError::not_found("Run not found.").into_response(),
Err(err) => {
ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response()
}
match state.cached_run(&id).await {
Ok(cached) => Json(&*cached.projection).into_response(),
Err(err) => err.into_response(),
}
}
@ -1039,13 +1029,9 @@ async fn get_run_stage_context_window(
Ok(stage_id) => stage_id,
Err(response) => return response,
};
let cached = match state.stores.runs.get_cached_run(&id).await {
Ok(Some(cached)) => cached,
Ok(None) => return ApiError::not_found("Run not found.").into_response(),
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
let cached = match state.cached_run(&id).await {
Ok(cached) => cached,
Err(err) => return err.into_response(),
};
let Some(stage) = cached.projection.stage(&stage_id) else {
return ApiError::not_found("Stage not found.").into_response();
@ -1099,17 +1085,11 @@ async fn get_run_stage_command_log(
return ApiError::bad_request("limit must be greater than 0").into_response();
}
let limit = query.limit.min(MAX_COMMAND_LOG_LIMIT);
let Ok(run_store) = state.stores.runs.open_run_reader(&id).await else {
return ApiError::not_found("Run not found.").into_response();
let cached = match state.cached_run(&id).await {
Ok(cached) => cached,
Err(err) => return err.into_response(),
};
let run_state = match run_store.state().await {
Ok(run_state) => run_state,
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
};
let Some(node) = run_state.stage(&stage_id) else {
let Some(node) = cached.projection.stage(&stage_id) else {
return ApiError::not_found("Stage not found.").into_response();
};
@ -1145,7 +1125,14 @@ async fn get_run_stage_command_log(
}
if let Some(cas_ref) = cas_ref {
let text = match read_json_string_blob(&run_store.clone().into(), &cas_ref).await {
let run_store = match state.stores.runs.open_run_reader(&id).await {
Ok(run_store) => run_store,
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
};
let text = match read_json_string_blob(&run_store.into(), &cas_ref).await {
Ok(Some(text)) => text,
Ok(None) => String::new(),
Err(err) => {

22
lib/apps/fabro-server/src/server/handler/sandbox.rs
View file

@ -951,18 +951,16 @@ async fn load_run_sandbox_instance(
state: &Arc<AppState>,
run_id: &RunId,
) -> Result<fabro_types::RunSandboxInstance, Response> {
match state.stores.runs.open_run_reader(run_id).await {
Ok(run_store) => match run_store.state().await {
Ok(run_state) => run_state
.sandbox
.and_then(fabro_types::RunSandbox::into_instance)
.ok_or_else(|| ApiError::not_found("Run sandbox was not created.").into_response()),
Err(err) => Err(
ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response(),
),
},
Err(_) => Err(ApiError::not_found("Run not found.").into_response()),
}
let cached = state
.cached_run(run_id)
.await
.map_err(IntoResponse::into_response)?;
cached
.projection
.sandbox
.clone()
.and_then(fabro_types::RunSandbox::into_instance)
.ok_or_else(|| ApiError::not_found("Run sandbox was not created.").into_response())
}
#[cfg(test)]

4
lib/apps/fabro-server/src/server/handler/sessions.rs
View file

@ -305,8 +305,8 @@ async fn attach_session_events(
};
let start_seq = match params.since_seq {
Some(seq) => seq.max(1),
None => match run_store.list_events().await {
Ok(events) => events.last().map_or(1, |event| event.seq.saturating_add(1)),
None => match run_store.last_event_seq().await {
Ok(last_seq) => last_seq.map_or(1, |seq| seq.saturating_add(1)),
Err(err) => return store_error(&err).into_response(),
},
};

10
lib/apps/fabro-server/src/server/handler/worker_control.rs
View file

@ -35,13 +35,9 @@ async fn worker_control_stream(
Query(query): Query<WorkerControlStreamQuery>,
ws: WebSocketUpgrade,
) -> Response {
let cached = match state.stores.runs.get_cached_run(&id).await {
Ok(Some(cached)) => cached,
Ok(None) => return ApiError::not_found("Run not found.").into_response(),
Err(err) => {
return ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, err.to_string())
.into_response();
}
let cached = match state.cached_run(&id).await {
Ok(cached) => cached,
Err(err) => return err.into_response(),
};
if cached.projection.archived_at.is_some() {
return ApiError::new(StatusCode::CONFLICT, "Run is archived.").into_response();

29
lib/apps/fabro-server/src/server/tests.rs
View file

@ -6768,6 +6768,35 @@ async fn list_models_filters_by_provider() {
);
}
#[tokio::test]
async fn list_models_exposes_reasoning_effort_controls() {
let app = test_app_with();
let req = Request::builder()
.method("GET")
.uri(api("/models?provider=kimi"))
.body(Body::empty())
.unwrap();
let response = app.oneshot(req).await.unwrap();
let body = response_json!(response, StatusCode::OK).await;
let models = body["data"].as_array().unwrap();
let kimi_k3 = models
.iter()
.find(|model| model["id"] == "kimi-k3")
.expect("Kimi K3 should be listed");
let kimi_k2_5 = models
.iter()
.find(|model| model["id"] == "kimi-k2.5")
.expect("Kimi K2.5 should be listed");
assert_eq!(
kimi_k3["controls"]["reasoning_effort"],
json!(["low", "high", "max"])
);
assert_eq!(kimi_k2_5["controls"]["reasoning_effort"], json!([]));
}
#[tokio::test]
async fn list_models_marks_configured_true_when_provider_has_credential_material() {
let state = test_app_state_with_env_lookup(

3
lib/components/fabro-agent/src/lib.rs
View file

@ -57,8 +57,7 @@ pub use read_before_write_sandbox::ReadBeforeWriteSandbox;
pub use sandbox::{
CommandOutputCallback, DirEntry, ExecResult, ExecStreamingResult, GrepOptions, RefreshOutcome,
Sandbox, SandboxEvent, SandboxEventCallback, StderrCollector, StdioProcess, StdioProcessHandle,
WorktreeEvent, WorktreeEventCallback, WorktreeOptions, WorktreeSandbox, format_lines_numbered,
shell_quote,
format_lines_numbered, shell_quote,
};
pub use session::{
CompletionCoordinator, Session, SessionControlHandle, SessionInputTiming,

3
lib/components/fabro-agent/src/sandbox.rs
View file

@ -4,6 +4,5 @@
pub use fabro_sandbox::{
CommandOutputCallback, DirEntry, ExecResult, ExecStreamingResult, GrepOptions, RefreshOutcome,
Sandbox, SandboxEvent, SandboxEventCallback, StderrCollector, StdioProcess, StdioProcessHandle,
StdioProcessTermination, WorktreeEvent, WorktreeEventCallback, WorktreeOptions,
WorktreeSandbox, delegate_sandbox, format_lines_numbered, shell_quote,
StdioProcessTermination, delegate_sandbox, format_lines_numbered, shell_quote,
};

11
lib/components/fabro-dump/src/lib.rs
View file

@ -127,7 +127,7 @@ impl RunDump {
if let Some(parallel_results) = stage.parallel_results.as_ref() {
entries.push(RunDumpEntry::json_path(
&base.join("parallel_results.json"),
parallel_results.clone(),
serde_json::to_value(parallel_results)?,
));
}
if let Some(output) = stage.output.as_ref() {
@ -605,7 +605,14 @@ mod tests {
stage.diff = Some("diff --git a/a b/a".to_string());
stage.script_invocation = Some(serde_json::json!({ "command": "cargo test" }));
stage.script_timing = Some(serde_json::json!({ "duration_ms": 10 }));
stage.parallel_results = Some(serde_json::json!([{ "stage": "fanout@1" }]));
stage.parallel_results = Some(vec![fabro_types::ParallelBranchResult {
id: "review".to_string(),
status: fabro_types::StageOutcome::Succeeded,
context_updates: std::collections::BTreeMap::from([(
"response.review".to_string(),
serde_json::json!("looks good"),
)]),
}]);
stage.output = Some("output".to_string());
let dump = RunDump::from_projection(&projection).unwrap();

5
lib/components/fabro-llm/src/model_test.rs
View file

@ -169,7 +169,9 @@ fn validate_deep_result(result: &GenerateResult) -> Result<(), String> {
mod tests {
use std::collections::HashMap;
use fabro_model::{ModelCosts, ModelFeatures, ModelLimits, ProviderId, ReasoningEffortFeature};
use fabro_model::{
ModelControls, ModelCosts, ModelFeatures, ModelLimits, ProviderId, ReasoningEffortFeature,
};
use super::*;
use crate::types::{FinishReason, Message, Response, StepResult, TokenCounts, ToolResult};
@ -187,6 +189,7 @@ mod tests {
training: None,
knowledge_cutoff: None,
features,
controls: ModelControls::default(),
costs: ModelCosts {
input_cost_per_mtok: None,
output_cost_per_mtok: None,

57
lib/components/fabro-llm/tests/integration.rs
View file

@ -548,6 +548,63 @@ async fn openrouter_poolside_laguna_complete() {
assert_eq!(response.cost_source, Some(CostSource::Authoritative));
}
#[fabro_macros::e2e_test(live("FIREWORKS_API_KEY"))]
async fn fireworks_complete() {
let api_key = std::env::var(EnvVars::FIREWORKS_API_KEY).expect("FIREWORKS_API_KEY must be set");
let adapter = OpenAiCompatibleAdapter::new(api_key, "https://api.fireworks.ai/inference/v1")
.with_name("fireworks");
// gpt-oss models spend reasoning tokens before the final text, so the
// completion budget must cover both.
let request = Request {
max_tokens: Some(2048),
..make_request("accounts/fireworks/models/gpt-oss-20b")
};
let response = adapter.complete(&request).await.unwrap();
assert!(
!response.text().is_empty(),
"response text should not be empty"
);
assert!(response.usage.input_tokens > 0);
assert!(response.usage.output_tokens > 0);
assert_eq!(response.provider, "fireworks");
}
#[fabro_macros::e2e_test(live("FIREWORKS_API_KEY"))]
async fn fireworks_kimi_k2_7_code_deep_tool_round_trip() {
let api_key = std::env::var(EnvVars::FIREWORKS_API_KEY).expect("FIREWORKS_API_KEY must be set");
let provider = ProviderId::new("fireworks");
let mut settings = LlmCatalogSettings::default();
settings
.providers
.insert(provider.to_string(), ProviderCatalogSettings {
enabled: Some(true),
..ProviderCatalogSettings::default()
});
let catalog = Arc::new(
Catalog::from_builtin_with_overrides(&settings)
.expect("enabled Fireworks catalog should build"),
);
let credential = ApiCredential::from_api_key(provider, api_key, &catalog)
.expect("Fireworks credential should resolve from the catalog");
let client = Arc::new(
Client::from_credentials(vec![credential], Arc::clone(&catalog))
.await
.expect("Fireworks client should build from the catalog"),
);
let model = catalog
.get_on_provider(&ProviderId::new("fireworks"), "kimi-k2.7-code")
.expect("Fireworks Kimi K2.7 Code should be present");
let outcome = run_model_test(model, ModelTestMode::Deep, client).await;
assert_eq!(
outcome.status,
ModelTestStatus::Ok,
"Fireworks Kimi K2.7 Code deep test failed: {:?}",
outcome.error_message
);
}
#[fabro_macros::e2e_test(live("OPENROUTER_API_KEY"))]
async fn openrouter_kimi_k3_deep_tool_round_trip() {
let api_key =

16
lib/components/fabro-sandbox/src/daytona/mod.rs
View file

@ -1311,22 +1311,6 @@ impl Sandbox for DaytonaSandbox {
crate::git_push_via_exec(self, refspec).await
}
fn parallel_worktree_path(
&self,
_run_dir: &std::path::Path,
run_id: &str,
node_id: &str,
key: &str,
) -> String {
format!(
"{}/.fabro/scratch/{}/parallel/{}/{}",
self.working_directory(),
run_id,
node_id,
key
)
}
async fn ssh_access_command(&self) -> crate::Result<Option<String>> {
self.create_ssh_access(Some(60.0)).await.map(Some)
}

16
lib/components/fabro-sandbox/src/docker.rs
View file

@ -1929,22 +1929,6 @@ impl Sandbox for DockerSandbox {
crate::git_push_via_exec(self, refspec).await
}
fn parallel_worktree_path(
&self,
_run_dir: &std::path::Path,
run_id: &str,
node_id: &str,
key: &str,
) -> String {
format!(
"{}/.fabro/scratch/{}/parallel/{}/{}",
self.working_directory(),
run_id,
node_id,
key
)
}
fn origin_url(&self) -> Option<&str> {
if !self.repo_cloned() {
return None;

3
lib/components/fabro-sandbox/src/lib.rs
View file

@ -22,8 +22,6 @@ pub mod details;
pub mod reconnect;
pub mod worktree;
pub mod terminal;
pub mod local;
@ -62,4 +60,3 @@ pub use sandbox::{
};
pub use sandbox_spec::SandboxSpec;
pub use terminal::{TerminalSession, TerminalSize, open_terminal_for_run};
pub use worktree::{WorktreeEvent, WorktreeEventCallback, WorktreeOptions, WorktreeSandbox};

27
lib/components/fabro-sandbox/src/sandbox.rs
View file

@ -217,16 +217,6 @@ macro_rules! delegate_sandbox {
self.$field.git_push_ref(refspec).await
}
fn parallel_worktree_path(
&self,
run_dir: &std::path::Path,
run_id: &str,
node_id: &str,
key: &str,
) -> String {
self.$field.parallel_worktree_path(run_dir, run_id, node_id, key)
}
async fn ssh_access_command(&self) -> $crate::Result<Option<String>> {
self.$field.ssh_access_command().await
}
@ -1005,23 +995,6 @@ pub trait Sandbox: Send + Sync {
))
}
/// Compute the filesystem path for a parallel branch worktree.
fn parallel_worktree_path(
&self,
run_dir: &std::path::Path,
_run_id: &str,
node_id: &str,
key: &str,
) -> String {
run_dir
.join("parallel")
.join(node_id)
.join(key)
.join("worktree")
.to_string_lossy()
.into_owned()
}
/// Return an SSH command string for connecting to this sandbox, if
/// supported.
async fn ssh_access_command(&self) -> crate::Result<Option<String>> {

908
lib/components/fabro-sandbox/src/worktree.rs
View file

@ -1,908 +0,0 @@
use std::collections::HashMap;
use std::path::Path;
use std::sync::Arc;
use async_trait::async_trait;
use tokio_util::sync::CancellationToken;
use crate::sandbox::fetch_source_run_ref;
use crate::{
CommandOutputCallback, DirEntry, ExecResult, ExecStreamingResult, GitRunInfo, GitSetupIntent,
GrepOptions, Sandbox, StdioProcess, shell_quote,
};
/// Git command prefix that disables background maintenance.
const GIT: &str = "git -c maintenance.auto=0 -c gc.auto=0";
// ---------------------------------------------------------------------------
// Public types
// ---------------------------------------------------------------------------
/// Events emitted during worktree lifecycle operations.
pub enum WorktreeEvent {
BranchCreated { branch: String, sha: String },
WorktreeAdded { path: String, branch: String },
WorktreeRemoved { path: String },
}
/// Callback type for worktree lifecycle events.
pub type WorktreeEventCallback = Arc<dyn Fn(WorktreeEvent) + Send + Sync>;
/// Configuration for a `WorktreeSandbox`.
pub struct WorktreeOptions {
pub branch_name: String,
pub base_sha: String,
pub worktree_path: String,
/// Skip branch creation and hard reset (for resume, where branch already
/// exists).
pub skip_branch_creation: bool,
pub setup_intent: Option<GitSetupIntent>,
}
/// Wraps any `Sandbox`, manages a git worktree lifecycle in
/// `initialize()`/`cleanup()`, and overrides `working_directory()` and
/// `exec_command()` to use the worktree path.
///
/// `initialize()` and `cleanup()` do NOT call the inner sandbox's lifecycle
/// methods. The inner sandbox's lifecycle is managed separately by the caller.
pub struct WorktreeSandbox {
inner: Arc<dyn Sandbox>,
config: WorktreeOptions,
event_callback: Option<WorktreeEventCallback>,
initialized: std::sync::atomic::AtomicBool,
}
impl WorktreeSandbox {
/// Create a new `WorktreeSandbox` wrapping `inner` with the given
/// configuration.
pub fn new(inner: Arc<dyn Sandbox>, config: WorktreeOptions) -> Self {
Self {
inner,
config,
event_callback: None,
initialized: std::sync::atomic::AtomicBool::new(false),
}
}
/// Set the callback to receive worktree lifecycle events.
pub fn set_event_callback(&mut self, cb: WorktreeEventCallback) {
self.event_callback = Some(cb);
}
/// The git branch name managed by this sandbox.
pub fn branch_name(&self) -> &str {
&self.config.branch_name
}
/// The base commit SHA used when initializing the worktree.
pub fn base_sha(&self) -> &str {
&self.config.base_sha
}
/// The filesystem path to the worktree directory.
pub fn worktree_path(&self) -> &str {
&self.config.worktree_path
}
fn emit(&self, event: WorktreeEvent) {
if let Some(ref cb) = self.event_callback {
cb(event);
}
}
fn resolve_path(&self, path: &str) -> String {
if std::path::Path::new(path).is_absolute() {
path.to_string()
} else {
format!("{}/{path}", self.config.worktree_path)
}
}
async fn fetch_fork_source_if_needed(&self) -> crate::Result<()> {
if let Some(GitSetupIntent::ForkFromCheckpoint {
source_run_id,
checkpoint_sha,
..
}) = self.config.setup_intent.as_ref()
{
fetch_source_run_ref(&*self.inner, source_run_id, checkpoint_sha).await?;
}
Ok(())
}
}
// ---------------------------------------------------------------------------
// Sandbox implementation
// ---------------------------------------------------------------------------
#[async_trait]
impl Sandbox for WorktreeSandbox {
// --- Lifecycle ---
/// Set up the git worktree:
/// 1. Best-effort remove any stale worktree at `path` (so the branch is
/// free to be updated).
/// 2. Unless `skip_branch_creation`: force-create the branch at `base_sha`,
/// emit `BranchCreated`.
/// 3. Add the worktree, emit `WorktreeAdded`.
///
/// Does NOT call `inner.initialize()`.
async fn initialize(&self) -> crate::Result<()> {
if self
.initialized
.swap(true, std::sync::atomic::Ordering::Relaxed)
{
return Ok(());
}
let path = shell_quote(&self.config.worktree_path);
let branch = shell_quote(&self.config.branch_name);
let sha = shell_quote(&self.config.base_sha);
self.fetch_fork_source_if_needed().await?;
// Best-effort remove any stale worktree registration + directory first,
// so that the branch is not "in use" when we try to force-update it.
let rm_cmd = format!("{GIT} worktree remove --force {path}");
let _ = self
.inner
.exec_command(&rm_cmd, 30_000, None, None, None)
.await;
// Prune all stale worktree references whose directories no longer exist.
// Without this, a branch may remain locked by a worktree in a deleted
// temp directory from a previous run.
let prune_cmd = format!("{GIT} worktree prune");
let _ = self
.inner
.exec_command(&prune_cmd, 30_000, None, None, None)
.await;
if !self.config.skip_branch_creation {
let cmd = format!("{GIT} branch --force {branch} {sha}");
let result = self
.inner
.exec_command(&cmd, 30_000, None, None, None)
.await?;
if !result.is_success() {
return Err(crate::Error::message(format!(
"git branch --force failed (exit {}): {}",
result.display_exit_code(),
result.stderr.trim()
)));
}
self.emit(WorktreeEvent::BranchCreated {
branch: self.config.branch_name.clone(),
sha: self.config.base_sha.clone(),
});
}
let add_cmd = format!("{GIT} worktree add {path} {branch}");
let result = self
.inner
.exec_command(&add_cmd, 30_000, None, None, None)
.await?;
if !result.is_success() {
// Roll back the branch created above so we don't leak partial state.
if !self.config.skip_branch_creation {
let rollback_cmd = format!("{GIT} branch -D {branch}");
let _ = self
.inner
.exec_command(&rollback_cmd, 30_000, None, None, None)
.await;
}
return Err(crate::Error::message(format!(
"git worktree add failed (exit {}): {}",
result.display_exit_code(),
result.stderr.trim()
)));
}
self.emit(WorktreeEvent::WorktreeAdded {
path: self.config.worktree_path.clone(),
branch: self.config.branch_name.clone(),
});
Ok(())
}
/// No-op — the worktree must survive cleanup for `fabro cp` access.
/// Worktrees are pruned separately by `system prune`.
async fn cleanup(&self) -> crate::Result<()> {
Ok(())
}
async fn start(&self) -> crate::Result<()> {
self.inner.start().await
}
async fn stop(&self) -> crate::Result<()> {
self.inner.stop().await
}
async fn delete(&self) -> crate::Result<()> {
self.inner.delete().await
}
fn working_directory(&self) -> &str {
&self.config.worktree_path
}
/// Execute a command, defaulting `working_dir` to the worktree path when
/// `None`.
async fn exec_command(
&self,
command: &str,
timeout_ms: u64,
working_dir: Option<&str>,
env_vars: Option<&HashMap<String, String>>,
cancel_token: Option<CancellationToken>,
) -> crate::Result<ExecResult> {
let wd = working_dir.unwrap_or(&self.config.worktree_path);
self.inner
.exec_command(command, timeout_ms, Some(wd), env_vars, cancel_token)
.await
}
/// Stream a command's output, forwarding to the inner sandbox's streaming
/// implementation so live output and `streams_separated` / `live_streaming`
/// flags survive the worktree wrapping.
async fn exec_command_streaming(
&self,
command: &str,
timeout_ms: Option<u64>,
working_dir: Option<&str>,
env_vars: Option<&HashMap<String, String>>,
cancel_token: Option<CancellationToken>,
output_callback: CommandOutputCallback,
) -> crate::Result<ExecStreamingResult> {
let wd = working_dir.unwrap_or(&self.config.worktree_path);
self.inner
.exec_command_streaming(
command,
timeout_ms,
Some(wd),
env_vars,
cancel_token,
output_callback,
)
.await
}
async fn spawn_stdio_process(
&self,
command: &str,
working_dir: Option<&str>,
env_vars: Option<&HashMap<String, String>>,
cancel_token: Option<CancellationToken>,
) -> crate::Result<StdioProcess> {
let wd = working_dir.unwrap_or(&self.config.worktree_path);
self.inner
.spawn_stdio_process(command, Some(wd), env_vars, cancel_token)
.await
}
// --- Delegated methods ---
async fn read_file_bytes(&self, path: &str) -> crate::Result<Vec<u8>> {
let resolved = self.resolve_path(path);
self.inner.read_file_bytes(&resolved).await
}
async fn write_file(&self, path: &str, content: &str) -> crate::Result<()> {
let resolved = self.resolve_path(path);
self.inner.write_file(&resolved, content).await
}
async fn delete_file(&self, path: &str) -> crate::Result<()> {
let resolved = self.resolve_path(path);
self.inner.delete_file(&resolved).await
}
async fn file_exists(&self, path: &str) -> crate::Result<bool> {
let resolved = self.resolve_path(path);
self.inner.file_exists(&resolved).await
}
async fn list_directory(
&self,
path: &str,
depth: Option<usize>,
) -> crate::Result<Vec<DirEntry>> {
let resolved = self.resolve_path(path);
self.inner.list_directory(&resolved, depth).await
}
async fn grep(
&self,
pattern: &str,
path: &str,
options: &GrepOptions,
) -> crate::Result<Vec<String>> {
let resolved = self.resolve_path(path);
self.inner.grep(pattern, &resolved, options).await
}
async fn glob(&self, pattern: &str, path: Option<&str>) -> crate::Result<Vec<String>> {
let resolved = path.map(|p| self.resolve_path(p));
let glob_path = resolved.as_deref().unwrap_or(&self.config.worktree_path);
self.inner.glob(pattern, Some(glob_path)).await
}
async fn download_file_to_local(
&self,
remote_path: &str,
local_path: &Path,
) -> crate::Result<()> {
let resolved = self.resolve_path(remote_path);
self.inner
.download_file_to_local(&resolved, local_path)
.await
}
async fn upload_file_from_local(
&self,
local_path: &Path,
remote_path: &str,
) -> crate::Result<()> {
let resolved = self.resolve_path(remote_path);
self.inner
.upload_file_from_local(local_path, &resolved)
.await
}
fn platform(&self) -> &str {
self.inner.platform()
}
fn os_version(&self) -> String {
self.inner.os_version()
}
fn sandbox_info(&self) -> String {
self.inner.sandbox_info()
}
async fn refresh_push_credentials(&self) -> crate::Result<crate::RefreshOutcome> {
self.inner.refresh_push_credentials().await
}
async fn set_autostop_interval(&self, minutes: i32) -> crate::Result<()> {
self.inner.set_autostop_interval(minutes).await
}
async fn setup_git(
&self,
intent: &crate::GitSetupIntent,
) -> crate::Result<Option<crate::GitRunInfo>> {
if let GitSetupIntent::ForkFromCheckpoint {
source_run_id,
checkpoint_sha,
..
} = intent
{
fetch_source_run_ref(&*self.inner, source_run_id, checkpoint_sha).await?;
}
Ok(Some(GitRunInfo {
base_sha: self.config.base_sha.clone(),
run_branch: self.config.branch_name.clone(),
base_branch: None,
}))
}
fn resume_setup_commands(&self, run_branch: &str) -> Vec<String> {
self.inner.resume_setup_commands(run_branch)
}
async fn git_push_ref(&self, refspec: &str) -> crate::Result<()> {
let has_origin = match self
.exec_command("git remote get-url origin", 10_000, None, None, None)
.await
{
Ok(result) if result.is_success() => true,
Ok(_) => false,
Err(err) => return Err(crate::Error::context("git remote get-url origin", err)),
};
if !has_origin {
return Ok(());
}
crate::git_push_via_exec(self, refspec).await
}
fn parallel_worktree_path(
&self,
run_dir: &Path,
run_id: &str,
node_id: &str,
key: &str,
) -> String {
self.inner
.parallel_worktree_path(run_dir, run_id, node_id, key)
}
async fn ssh_access_command(&self) -> crate::Result<Option<String>> {
self.inner.ssh_access_command().await
}
fn origin_url(&self) -> Option<&str> {
self.inner.origin_url()
}
async fn get_preview_url(
&self,
port: u16,
) -> crate::Result<Option<(String, HashMap<String, String>)>> {
self.inner.get_preview_url(port).await
}
fn mark_agent_read(&self, path: &str) {
let resolved = self.resolve_path(path);
self.inner.mark_agent_read(&resolved);
}
}
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------
#[cfg(test)]
#[expect(
clippy::disallowed_methods,
reason = "worktree tests stage fixtures with sync std::fs writes in temp dirs"
)]
mod tests {
use std::sync::Mutex;
use fabro_types::CommandTermination;
use super::*;
use crate::local::LocalSandbox;
use crate::test_support::MockSandbox;
fn make_config(wt_path: &str) -> WorktreeOptions {
WorktreeOptions {
branch_name: "fabro/run/test-branch".to_string(),
base_sha: "abc123def456".to_string(),
worktree_path: wt_path.to_string(),
skip_branch_creation: false,
setup_intent: None,
}
}
fn make_config_skip(wt_path: &str) -> WorktreeOptions {
WorktreeOptions {
branch_name: "fabro/run/test-branch".to_string(),
base_sha: "abc123def456".to_string(),
worktree_path: wt_path.to_string(),
skip_branch_creation: true,
setup_intent: None,
}
}
/// Create a shared mock and return both the `Arc<dyn Sandbox>` (passed to
/// WorktreeSandbox) and the `Arc<MockSandbox>` (used to assert captured
/// state).
fn make_mock() -> (Arc<dyn Sandbox>, Arc<MockSandbox>) {
let mock = Arc::new(MockSandbox::linux());
let as_sandbox: Arc<dyn Sandbox> = mock.clone();
(as_sandbox, mock)
}
// -----------------------------------------------------------------------
// initialize() — full setup (skip_branch_creation = false)
// -----------------------------------------------------------------------
#[tokio::test]
async fn initialize_issues_correct_git_commands() {
let (inner, mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
wt.initialize().await.unwrap();
let cmds = mock.captured_commands.lock().unwrap().clone();
// worktree remove (best-effort), worktree prune, branch --force, worktree add
assert_eq!(cmds.len(), 4, "expected 4 git commands, got: {cmds:?}");
assert!(
cmds[0].contains("worktree remove --force"),
"cmd[0]: {}",
cmds[0]
);
assert!(cmds[1].contains("worktree prune"), "cmd[1]: {}", cmds[1]);
assert!(cmds[2].contains("branch --force"), "cmd[2]: {}", cmds[2]);
assert!(cmds[3].contains("worktree add"), "cmd[3]: {}", cmds[3]);
}
#[tokio::test]
async fn initialize_emits_branch_and_worktree_events() {
let (inner, _mock) = make_mock();
let mut wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
let events: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
let events_clone = Arc::clone(&events);
wt.set_event_callback(Arc::new(move |event| {
let label = match &event {
WorktreeEvent::BranchCreated { .. } => "BranchCreated",
WorktreeEvent::WorktreeAdded { .. } => "WorktreeAdded",
WorktreeEvent::WorktreeRemoved { .. } => "WorktreeRemoved",
};
events_clone.lock().unwrap().push(label.to_string());
}));
wt.initialize().await.unwrap();
let captured = events.lock().unwrap();
assert_eq!(*captured, vec!["BranchCreated", "WorktreeAdded"]);
}
#[tokio::test]
async fn initialize_uses_shell_quoted_values_in_commands() {
let (inner, mock) = make_mock();
let config = WorktreeOptions {
branch_name: "fabro/run/my-branch".to_string(),
base_sha: "deadbeef".to_string(),
worktree_path: "/tmp/my worktree".to_string(), // path with space
skip_branch_creation: false,
setup_intent: None,
};
let wt = WorktreeSandbox::new(inner, config);
wt.initialize().await.unwrap();
let cmds = mock.captured_commands.lock().unwrap().clone();
// The path "/tmp/my worktree" should be quoted in the worktree remove command
// (cmd[0])
assert!(
cmds[0].contains("'/tmp/my worktree'") || cmds[0].contains("\"/tmp/my worktree\""),
"worktree path should be shell-quoted: {}",
cmds[0]
);
}
// -----------------------------------------------------------------------
// initialize() — skip_branch_creation = true
// -----------------------------------------------------------------------
#[tokio::test]
async fn initialize_skip_branch_creation_issues_only_worktree_commands() {
let (inner, mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config_skip("/tmp/wt"));
wt.initialize().await.unwrap();
let cmds = mock.captured_commands.lock().unwrap().clone();
// worktree remove (best-effort), worktree prune, worktree add
assert_eq!(cmds.len(), 3, "expected 3 git commands, got: {cmds:?}");
assert!(
cmds[0].contains("worktree remove --force"),
"cmd[0]: {}",
cmds[0]
);
assert!(cmds[1].contains("worktree prune"), "cmd[1]: {}", cmds[1]);
assert!(cmds[2].contains("worktree add"), "cmd[2]: {}", cmds[2]);
}
#[tokio::test]
async fn initialize_skip_branch_creation_emits_only_worktree_added() {
let (inner, _mock) = make_mock();
let mut wt = WorktreeSandbox::new(inner, make_config_skip("/tmp/wt"));
let events: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
let events_clone = Arc::clone(&events);
wt.set_event_callback(Arc::new(move |event| {
let label = match &event {
WorktreeEvent::BranchCreated { .. } => "BranchCreated",
WorktreeEvent::WorktreeAdded { .. } => "WorktreeAdded",
WorktreeEvent::WorktreeRemoved { .. } => "WorktreeRemoved",
};
events_clone.lock().unwrap().push(label.to_string());
}));
wt.initialize().await.unwrap();
let captured = events.lock().unwrap();
assert_eq!(*captured, vec!["WorktreeAdded"]);
}
// -----------------------------------------------------------------------
// initialize() — error propagation
// -----------------------------------------------------------------------
#[tokio::test]
async fn initialize_propagates_error_on_nonzero_exit() {
let inner: Arc<dyn Sandbox> = Arc::new(MockSandbox {
exec_result: ExecResult {
stdout: String::new(),
stderr: "fatal: not a git repo".to_string(),
exit_code: Some(128),
termination: CommandTermination::Exited,
duration_ms: 5,
},
..MockSandbox::linux()
});
let wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
let result = wt.initialize().await;
assert!(result.is_err(), "should return Err on non-zero exit");
let err = result.unwrap_err().to_string();
assert!(
err.contains("branch --force failed") || err.contains("128"),
"error should mention the failure: {err}"
);
}
// -----------------------------------------------------------------------
// cleanup()
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
// working_directory()
// -----------------------------------------------------------------------
#[test]
fn working_directory_returns_worktree_path() {
let (inner, _mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config("/tmp/my_worktree"));
assert_eq!(wt.working_directory(), "/tmp/my_worktree");
}
// -----------------------------------------------------------------------
// exec_command() working_dir defaulting
// -----------------------------------------------------------------------
#[tokio::test]
async fn exec_command_none_working_dir_defaults_to_worktree_path() {
let (inner, mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
wt.exec_command("echo hello", 5000, None, None, None)
.await
.unwrap();
let wdirs = mock.captured_working_dirs.lock().unwrap().clone();
assert_eq!(
wdirs.last(),
Some(&Some("/tmp/wt".to_string())),
"None working_dir should be replaced with worktree path"
);
}
#[tokio::test]
async fn exec_command_explicit_working_dir_passes_through() {
let (inner, mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
wt.exec_command("echo hello", 5000, Some("/explicit/path"), None, None)
.await
.unwrap();
let wdirs = mock.captured_working_dirs.lock().unwrap().clone();
assert_eq!(
wdirs.last(),
Some(&Some("/explicit/path".to_string())),
"explicit working_dir should be passed through unchanged"
);
}
#[tokio::test]
async fn stdio_process_none_working_dir_defaults_to_worktree_path() {
let (inner, mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
wt.spawn_stdio_process("python fake_agent.py", None, None, None)
.await
.unwrap();
let wdirs = mock.captured_working_dirs.lock().unwrap().clone();
assert_eq!(
wdirs.last(),
Some(&Some("/tmp/wt".to_string())),
"None working_dir should be replaced with worktree path"
);
}
// -----------------------------------------------------------------------
// Accessors
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
// Bug: cleanup() destroys worktree, breaking `fabro cp`
// -----------------------------------------------------------------------
#[tokio::test]
async fn cleanup_should_preserve_worktree_for_post_run_access() {
// The worktree directory must survive cleanup() so that `fabro cp` can
// access run artifacts afterward. It is pruned separately by `system prune`.
// LocalSandbox.cleanup() was a no-op; WorktreeSandbox should match.
let (inner, mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
wt.cleanup().await.unwrap();
let cmds = mock.captured_commands.lock().unwrap().clone();
assert!(
cmds.is_empty(),
"cleanup should not issue destructive git commands \
(worktree must be preserved for fabro cp), but got: {cmds:?}"
);
}
#[tokio::test]
async fn lifecycle_operations_forward_to_inner_sandbox() {
let (inner, mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
wt.start().await.unwrap();
wt.stop().await.unwrap();
wt.delete().await.unwrap();
assert_eq!(mock.start_count(), 1);
assert_eq!(mock.stop_count(), 1);
assert_eq!(mock.delete_count(), 1);
}
// -----------------------------------------------------------------------
// Bug: initialize() is not idempotent — double call destroys worktree
// -----------------------------------------------------------------------
#[tokio::test]
async fn initialize_is_idempotent_on_second_call() {
// engine.run_with_lifecycle() calls sandbox.initialize() unconditionally,
// even when run.rs already called it during sandbox construction.
// The second call must be a no-op; it must NOT re-run
// `git worktree remove --force` which would destroy the worktree.
let (inner, mock) = make_mock();
let wt = WorktreeSandbox::new(inner, make_config("/tmp/wt"));
wt.initialize().await.unwrap();
let first_count = mock.captured_commands.lock().unwrap().len();
wt.initialize().await.unwrap();
let second_count = mock.captured_commands.lock().unwrap().len();
assert_eq!(
first_count,
second_count,
"second initialize() should be a no-op, but it issued {} additional commands",
second_count - first_count
);
}
// -----------------------------------------------------------------------
// Bug: file operations resolve against inner working_directory, not worktree
// -----------------------------------------------------------------------
#[tokio::test]
async fn grep_should_search_worktree_not_inner_working_directory() {
// WorktreeSandbox delegates grep() to the inner sandbox without path
// adjustment. When the inner LocalSandbox was created with original_cwd,
// grep("pattern", ".") searches the original repo instead of the worktree.
let original =
std::env::temp_dir().join(format!("fabro-test-original-{}", uuid::Uuid::new_v4()));
let worktree =
std::env::temp_dir().join(format!("fabro-test-worktree-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&original).unwrap();
std::fs::create_dir_all(&worktree).unwrap();
// Put a marker file ONLY in the worktree directory
std::fs::write(worktree.join("marker.txt"), "UNIQUE_WORKTREE_MARKER").unwrap();
let inner: Arc<dyn Sandbox> = Arc::new(LocalSandbox::new(original.clone()));
let config = WorktreeOptions {
branch_name: "test-branch".into(),
base_sha: "abc123".into(),
worktree_path: worktree.to_string_lossy().to_string(),
skip_branch_creation: false,
setup_intent: None,
};
let wt = WorktreeSandbox::new(inner, config);
// working_directory() correctly returns the worktree path
assert_eq!(wt.working_directory(), worktree.to_string_lossy().as_ref());
// grep with "." should search the worktree, not the original repo
let results = wt
.grep("UNIQUE_WORKTREE_MARKER", ".", &GrepOptions::default())
.await
.unwrap();
assert!(
!results.is_empty(),
"grep(\".\") should search the worktree directory, not the inner sandbox's working directory"
);
std::fs::remove_dir_all(&original).ok();
std::fs::remove_dir_all(&worktree).ok();
}
#[tokio::test]
async fn glob_should_search_worktree_when_path_is_none() {
// WorktreeSandbox delegates glob() to the inner sandbox without path
// adjustment. LocalSandbox::glob(pattern, None) defaults to
// self.working_directory, which is the original repo path.
let original =
std::env::temp_dir().join(format!("fabro-test-original-{}", uuid::Uuid::new_v4()));
let worktree =
std::env::temp_dir().join(format!("fabro-test-worktree-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&original).unwrap();
std::fs::create_dir_all(&worktree).unwrap();
// Put a file ONLY in the worktree directory
std::fs::write(worktree.join("worktree_only.txt"), "content").unwrap();
let inner: Arc<dyn Sandbox> = Arc::new(LocalSandbox::new(original.clone()));
let config = WorktreeOptions {
branch_name: "test-branch".into(),
base_sha: "abc123".into(),
worktree_path: worktree.to_string_lossy().to_string(),
skip_branch_creation: false,
setup_intent: None,
};
let wt = WorktreeSandbox::new(inner, config);
let results = wt.glob("*.txt", None).await.unwrap();
assert!(
results.iter().any(|r| r.contains("worktree_only.txt")),
"glob(pattern, None) should search the worktree directory, not the inner sandbox's working directory. Got: {results:?}"
);
std::fs::remove_dir_all(&original).ok();
std::fs::remove_dir_all(&worktree).ok();
}
#[tokio::test]
async fn read_file_relative_should_resolve_against_worktree() {
// WorktreeSandbox delegates read_file() to the inner sandbox without
// path adjustment. Relative paths resolve against the inner
// LocalSandbox's working_directory (original repo), not the worktree.
let original =
std::env::temp_dir().join(format!("fabro-test-original-{}", uuid::Uuid::new_v4()));
let worktree =
std::env::temp_dir().join(format!("fabro-test-worktree-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&original).unwrap();
std::fs::create_dir_all(&worktree).unwrap();
// Put the file ONLY in the worktree directory
std::fs::write(worktree.join("only_in_worktree.txt"), "worktree content").unwrap();
let inner: Arc<dyn Sandbox> = Arc::new(LocalSandbox::new(original.clone()));
let config = WorktreeOptions {
branch_name: "test-branch".into(),
base_sha: "abc123".into(),
worktree_path: worktree.to_string_lossy().to_string(),
skip_branch_creation: false,
setup_intent: None,
};
let wt = WorktreeSandbox::new(inner, config);
let result = wt.read_file("only_in_worktree.txt", None, None).await;
assert!(
result.is_ok(),
"read_file with relative path should resolve against worktree, not inner sandbox's working directory. Error: {}",
result.unwrap_err()
);
std::fs::remove_dir_all(&original).ok();
std::fs::remove_dir_all(&worktree).ok();
}
// -----------------------------------------------------------------------
// Accessors
// -----------------------------------------------------------------------
#[test]
fn accessors_return_config_values() {
let (inner, _mock) = make_mock();
let config = WorktreeOptions {
branch_name: "my-branch".to_string(),
base_sha: "sha123".to_string(),
worktree_path: "/path/to/wt".to_string(),
skip_branch_creation: false,
setup_intent: None,
};
let wt = WorktreeSandbox::new(inner, config);
assert_eq!(wt.branch_name(), "my-branch");
assert_eq!(wt.base_sha(), "sha123");
assert_eq!(wt.worktree_path(), "/path/to/wt");
}
}

30
lib/components/fabro-store/src/run_state.rs
View file

@ -1,5 +1,6 @@
use std::collections::{BTreeMap, HashMap};
use std::str::FromStr;
use std::sync::Arc;
use chrono::{DateTime, Utc};
use fabro_types::run_event::{
@ -26,7 +27,9 @@ use crate::{Error, EventEnvelope, Result};
#[derive(Debug, Clone, Default)]
pub(crate) struct EventProjectionCache {
pub last_seq: u32,
pub state: Option<RunProjection>,
// Arc-shared with the shared projection cache so opening a run does not
// deep-copy the projection; mutated copy-on-write via `Arc::make_mut`.
pub state: Option<Arc<RunProjection>>,
}
pub trait RunProjectionReducer {
@ -529,13 +532,10 @@ impl RunProjectionReducer for RunProjection {
)?;
}
EventBody::ParallelCompleted(props) => {
let parallel_results = serde_json::to_value(&props.results).map_err(|err| {
Error::InvalidEvent(format!("invalid parallel.completed payload: {err}"))
})?;
let Some(stage) = stage_at_stored_or_current_visit(self, stored, event.seq) else {
return Ok(());
};
stage.parallel_results = Some(parallel_results);
stage.parallel_results = Some(props.results.clone());
}
EventBody::ParallelBranchStarted(_) => {
// Branches bypass the engine's StageStarted/StageCompleted
@ -553,21 +553,17 @@ impl RunProjectionReducer for RunProjection {
// A branch never emits its own StageCompleted, so finalize it
// here; otherwise the stage spins Running forever after the run
// (and the fan-in) is done.
let outcome =
StageOutcome::from_str(&props.status).unwrap_or(StageOutcome::Failed {
retry_requested: false,
});
let Some(stage) = stage_at_stored_or_current_visit(self, stored, event.seq) else {
return Ok(());
};
stage.completion = Some(StageCompletion {
outcome,
notes: None,
outcome: props.status,
notes: None,
failure_reason: None,
timestamp: ts,
timestamp: ts,
});
stage.timing = Some(fabro_types::StageTiming::wall_only(props.duration_ms));
stage.state = StageState::from(outcome);
stage.state = StageState::from(props.status);
stage.agent_control = AgentControlState::Running;
}
EventBody::TodoCreated(props) => {
@ -2091,8 +2087,7 @@ mod tests {
EventBody::ParallelBranchCompleted(ParallelBranchCompletedProps {
index: 0,
duration_ms: 1234,
status: "succeeded".to_string(),
head_sha: None,
status: StageOutcome::Succeeded,
}),
branch.clone(),
))
@ -2125,8 +2120,9 @@ mod tests {
EventBody::ParallelBranchCompleted(ParallelBranchCompletedProps {
index: 0,
duration_ms: 500,
status: "failed".to_string(),
head_sha: None,
status: StageOutcome::Failed {
retry_requested: false,
},
}),
branch.clone(),
))

42
lib/components/fabro-store/src/slate/mod.rs
View file

@ -1591,6 +1591,48 @@ mod tests {
});
}
#[tokio::test]
async fn opening_cached_run_does_not_read_older_event_history() {
let (object_store, store) = make_store();
let run_id = test_run_id("run-1");
let run = store.create_run(&run_id).await.unwrap();
append_completed(&run, "run-1", dt("2026-03-27T12:00:00Z")).await;
let reopened = Database::new(object_store, "runs", Duration::from_millis(1), None);
reopened.warm_projection_cache().await.unwrap();
// If opening or projecting the run starts at the beginning, this
// unreadable old key makes the operation fail. A hydrated run starts
// after the shared projection's last sequence instead.
let mut unreadable_old_key = keys::run_event_seq_prefix(&run_id, 2).as_ref().to_vec();
unreadable_old_key.push(0xff);
reopened
.open_db()
.await
.unwrap()
.put(unreadable_old_key, b"invalid json")
.await
.unwrap();
let fresh_writer = reopened.open_run(&run_id).await.unwrap();
assert_eq!(fresh_writer.last_event_seq().await.unwrap(), Some(5));
let state = fresh_writer.state().await.unwrap();
assert_eq!(state.status, RunStatus::Succeeded {
reason: SuccessReason::Completed,
});
let seq = fresh_writer
.append_event(&event_payload(
"run-1",
"2026-03-27T12:00:05Z",
"run.title.updated",
&serde_json::json!({ "title": "Renamed completed run" }),
))
.await
.unwrap();
assert_eq!(seq, 6);
}
#[tokio::test]
async fn append_event_hydrates_local_projection_cache_for_fresh_writer() {
let (object_store, store) = make_store();

9
lib/components/fabro-store/src/slate/projection_cache.rs
View file

@ -171,13 +171,18 @@ impl RunProjectionCache {
.map(|entry| state.with_children_count(entry))
}
pub(crate) async fn last_seq(&self, run_id: &RunId) -> Option<u32> {
/// Projection and last sequence for `run_id`, without the summary clone
/// and children count that `get` computes under the cache mutex.
pub(crate) async fn projection_snapshot(
&self,
run_id: &RunId,
) -> Option<(Arc<RunProjection>, u32)> {
self.state
.lock()
.await
.entries
.get(run_id)
.map(|entry| entry.last_seq)
.map(|entry| (Arc::clone(&entry.projection), entry.last_seq))
}
pub(crate) async fn get_summary(&self, run_id: &RunId, now: DateTime<Utc>) -> Option<Run> {

243
lib/components/fabro-store/src/slate/run_store.rs
View file

@ -6,7 +6,7 @@ use bytes::Bytes;
use chrono::Utc;
use fabro_types::{RunBlobId, RunEvent, RunId, SessionId};
use futures::Stream;
use slatedb::{Db, DbRead};
use slatedb::{Db, DbIterator, DbRead};
use tokio::sync::{Mutex, broadcast, mpsc};
use tokio_stream::wrappers::UnboundedReceiverStream;
use tracing::{error, warn};
@ -86,12 +86,24 @@ impl RunDatabase {
shared_projection_cache: Arc<RunProjectionCache>,
run_summary_store: Arc<OnceLock<Arc<RunSummaryStore>>>,
) -> Result<Self> {
let cached_projection = shared_projection_cache.projection_snapshot(&run_id).await;
let projection_cache = cached_projection.as_ref().map_or_else(
EventProjectionCache::default,
|(projection, last_seq)| EventProjectionCache {
last_seq: *last_seq,
state: Some(Arc::clone(projection)),
},
);
let event_seq = if read_only {
// Readers never append, so they do not need to scan the full event
// history to recover the next write sequence.
None
} else {
Some(AtomicU32::new(recover_next_seq(&db, &run_id).await?))
let next_seq = match &cached_projection {
Some((_, last_seq)) => last_seq.saturating_add(1),
None => recover_next_seq(&db, &run_id).await?,
};
Some(AtomicU32::new(next_seq))
};
let (event_tx, _) = broadcast::channel(DEFAULT_EVENT_TAIL_LIMIT.max(16));
let blob_store = BlobStore::new(Arc::new(db.clone()));
@ -103,7 +115,7 @@ impl RunDatabase {
event_seq,
close_lock: Mutex::new(()),
state_lock: Mutex::new(()),
projection_cache: Mutex::new(EventProjectionCache::default()),
projection_cache: Mutex::new(projection_cache),
shared_projection_cache,
run_summary_store,
recent_events: Mutex::new(VecDeque::with_capacity(DEFAULT_EVENT_TAIL_LIMIT)),
@ -174,12 +186,12 @@ impl RunDatabase {
)))
}
async fn projected_state(&self) -> Result<RunProjection> {
async fn projected_state(&self) -> Result<Arc<RunProjection>> {
let _state_guard = self.inner.state_lock.lock().await;
self.projected_state_locked().await
}
async fn projected_state_locked(&self) -> Result<RunProjection> {
async fn projected_state_locked(&self) -> Result<Arc<RunProjection>> {
let next_seq = {
let cache = self.inner.projection_cache.lock().await;
cache.last_seq.saturating_add(1)
@ -236,7 +248,7 @@ impl RunDatabase {
let state = RunProjection::apply_events(&events)?;
let mut projection_cache = self.inner.projection_cache.lock().await;
projection_cache.state = Some(state);
projection_cache.state = Some(Arc::new(state));
projection_cache.last_seq = last_seq;
Ok(())
}
@ -368,6 +380,18 @@ impl RunDatabase {
self.list_events_from_with_limit(1, usize::MAX).await
}
/// Returns the newest stored event sequence without reading event bodies
/// when a current projection is available.
pub async fn last_event_seq(&self) -> Result<Option<u32>> {
let local_last_seq = self.inner.projection_cache.lock().await.last_seq;
if local_last_seq > 0 {
return Ok(Some(local_last_seq));
}
let next_seq = recover_next_seq(&self.inner.db, &self.inner.run_id).await?;
Ok(next_seq.checked_sub(1).filter(|seq| *seq > 0))
}
/// Returns up to `limit + 1` events starting at `start_seq`. The extra
/// item lets callers compute `has_more` without a second read.
pub async fn list_events_from_with_limit(
@ -427,10 +451,10 @@ impl RunDatabase {
match self
.inner
.shared_projection_cache
.last_seq(&self.inner.run_id)
.projection_snapshot(&self.inner.run_id)
.await
{
Some(seq) => Ok(seq),
Some((_, seq)) => Ok(seq),
None => Ok(recover_next_seq(&self.inner.db, &self.inner.run_id)
.await?
.saturating_sub(1)),
@ -444,11 +468,10 @@ impl RunDatabase {
/// Returns up to `limit + 1` events for the given stage visit,
/// starting at `start_seq`. The `+1` lets callers compute `has_more`.
///
/// Implementation note: scans the unbounded run-event prefix and
/// filters by stage identity *before* applying `limit`, so a stage with
/// matches sparsely scattered late in the event log still returns its
/// full slice (no premature truncation from a generic `limit`-bounded
/// scan).
/// Implementation note: filters by stage identity *before* applying
/// `limit`, so a stage with matches sparsely scattered late in the event
/// log still returns its full slice (no premature truncation from a
/// generic `limit`-bounded scan).
pub async fn list_events_for_stage_from_with_limit(
&self,
stage_id: &StageId,
@ -559,7 +582,7 @@ impl RunDatabase {
}
pub async fn state(&self) -> Result<RunProjection> {
self.projected_state().await
Ok(Arc::unwrap_or_clone(self.projected_state().await?))
}
}
@ -574,13 +597,15 @@ fn allocate_event_seq(event_seq: &AtomicU32) -> Result<u32> {
}
fn apply_cached_projection_event(
state: &mut Option<RunProjection>,
state: &mut Option<Arc<RunProjection>>,
event: &EventEnvelope,
) -> Result<()> {
if let Some(projection) = state {
projection.apply_event(event)?;
Arc::make_mut(projection).apply_event(event)?;
} else {
*state = Some(RunProjection::apply_events(std::slice::from_ref(event))?);
*state = Some(Arc::new(RunProjection::apply_events(
std::slice::from_ref(event),
)?));
}
Ok(())
}
@ -600,6 +625,46 @@ where
Ok(max_seq.saturating_add(1).max(1))
}
/// Cursor over a run's stored events starting at `start_seq`, yielding raw
/// `(seq, payload)` entries in ascending sequence order (event keys embed a
/// zero-padded sequence, so key order matches sequence order).
struct EventScan {
iter: DbIterator,
}
impl EventScan {
async fn seek<R>(db: &R, run_id: &RunId, start_seq: u32) -> Result<Self>
where
R: DbRead + Sync,
{
let iter = db.scan(keys::run_events_range(run_id, start_seq)).await?;
Ok(Self { iter })
}
/// Like `seek`, but stops before `end_seq` instead of scanning to the
/// end of the run's event namespace.
async fn seek_before<R>(db: &R, run_id: &RunId, start_seq: u32, end_seq: u32) -> Result<Self>
where
R: DbRead + Sync,
{
let range = keys::run_event_seq_prefix(run_id, start_seq)
..keys::run_event_seq_prefix(run_id, end_seq);
let iter = db.scan(range).await?;
Ok(Self { iter })
}
async fn next(&mut self) -> Result<Option<(u32, Bytes)>> {
while let Some(entry) = self.iter.next().await? {
let key = key_to_str(&entry.key)?;
let Some(seq) = keys::parse_event_seq(key) else {
continue;
};
return Ok(Some((seq, entry.value)));
}
Ok(None)
}
}
async fn list_events_from<R>(db: &R, run_id: &RunId, start_seq: u32) -> Result<Vec<EventEnvelope>>
where
R: DbRead + Sync,
@ -637,31 +702,19 @@ where
let max_events = limit.saturating_add(1);
// Seek to the page cursor and decode only the requested page plus the
// sentinel used to compute `has_more`. Bound forward scans to this run's
// event namespace.
let range = match end_seq {
Some(end_seq) => {
let end_key = keys::run_event_seq_prefix(run_id, end_seq);
keys::run_event_seq_prefix(run_id, start_seq)..end_key
}
None => keys::run_events_range(run_id, start_seq),
// sentinel used to compute `has_more`.
let mut scan = match end_seq {
Some(end_seq) => EventScan::seek_before(db, run_id, start_seq, end_seq).await?,
None => EventScan::seek(db, run_id, start_seq).await?,
};
let mut iter = db.scan(range).await?;
let mut events = Vec::new();
while events.len() < max_events {
let Some(entry) = iter.next().await? else {
let Some((seq, value)) = scan.next().await? else {
break;
};
let key = key_to_str(&entry.key)?;
let Some(seq) = keys::parse_event_seq(key) else {
continue;
};
if seq < start_seq {
continue;
}
events.push(EventEnvelope {
seq,
event: serde_json::from_slice(&entry.value)?,
event: serde_json::from_slice(&value)?,
});
}
Ok(events)
@ -693,7 +746,7 @@ async fn list_events_for_stage_from_with_limit<R>(
where
R: DbRead + Sync,
{
// Unbounded scan first: filtering by stage identity with a generic
// Filter by stage identity *before* applying `limit`: a generic
// limit-bounded scan would silently drop matches whenever the stage's
// events are sparse late in the event log.
//
@ -711,17 +764,13 @@ where
let stage_id_string = stage_id.to_string();
let max_events = limit.saturating_add(1);
let mut iter = db.scan_prefix(keys::run_events_prefix(run_id)).await?;
let mut events: Vec<EventEnvelope> = Vec::new();
while let Some(entry) = iter.next().await? {
let key = key_to_str(&entry.key)?;
let Some(seq) = keys::parse_event_seq(key) else {
continue;
let mut scan = EventScan::seek(db, run_id, start_seq).await?;
let mut events = Vec::new();
while events.len() < max_events {
let Some((seq, value)) = scan.next().await? else {
break;
};
if seq < start_seq {
continue;
}
let probe: StageIdProbe = serde_json::from_slice(&entry.value)?;
let probe: StageIdProbe = serde_json::from_slice(&value)?;
let matches_stage_id = probe.stage_id == Some(stage_id_string.as_str());
let matches_legacy_node_id = probe.stage_id.is_none()
&& stage_id.visit() == 1
@ -729,25 +778,9 @@ where
if !matches_stage_id && !matches_legacy_node_id {
continue;
}
let event: RunEvent = serde_json::from_slice(&entry.value)?;
let envelope = EventEnvelope { seq, event };
if events.len() < max_events {
events.push(envelope);
continue;
}
if let Some((max_index, max_seq)) = events
.iter()
.enumerate()
.max_by_key(|(_, existing)| existing.seq)
.map(|(index, existing)| (index, existing.seq))
{
if seq < max_seq {
events[max_index] = envelope;
}
}
let event: RunEvent = serde_json::from_slice(&value)?;
events.push(EventEnvelope { seq, event });
}
events.sort_by_key(|event| event.seq);
Ok(events)
}
@ -771,18 +804,13 @@ where
let session_id_string = session_id.to_string();
let max_events = limit.saturating_add(1);
let mut iter = db.scan_prefix(keys::run_events_prefix(run_id)).await?;
let mut scan = EventScan::seek(db, run_id, start_seq).await?;
let mut events = Vec::new();
while let Some(entry) = iter.next().await? {
let key = key_to_str(&entry.key)?;
let Some(seq) = keys::parse_event_seq(key) else {
continue;
while events.len() < max_events {
let Some((seq, value)) = scan.next().await? else {
break;
};
if seq < start_seq {
continue;
}
let probe: SessionEventProbe = serde_json::from_slice(&entry.value)?;
let probe: SessionEventProbe = serde_json::from_slice(&value)?;
if probe.session_id != Some(session_id_string.as_str())
|| !probe
.event_name
@ -791,12 +819,9 @@ where
continue;
}
let event: RunEvent = serde_json::from_slice(&entry.value)?;
let event: RunEvent = serde_json::from_slice(&value)?;
if event.body.is_run_session_event() {
events.push(EventEnvelope { seq, event });
if events.len() >= max_events {
break;
}
}
}
Ok(events)
@ -1189,6 +1214,36 @@ mod tests {
assert_eq!(seqs, vec![4, 6]);
}
#[tokio::test]
async fn list_events_for_stage_seeks_to_start_sequence() {
let run = fresh_run().await;
let run_id = run.run_id();
run.append_event(&stage_prompt_payload(&run_id, 1, Some("alpha")))
.await
.unwrap();
run.append_event(&stage_prompt_payload(&run_id, 2, Some("beta")))
.await
.unwrap();
run.append_event(&stage_prompt_payload(&run_id, 3, Some("alpha")))
.await
.unwrap();
let mut unreadable_earlier_key = keys::run_event_seq_prefix(&run_id, 2).as_ref().to_vec();
unreadable_earlier_key.push(0xff);
run.inner
.db
.put(unreadable_earlier_key, b"invalid json")
.await
.unwrap();
let events = run
.list_events_for_stage_from_with_limit(&StageId::new("alpha", 1), 3, 100)
.await
.unwrap();
let seqs: Vec<u32> = events.iter().map(|event| event.seq).collect();
assert_eq!(seqs, vec![4]);
}
#[tokio::test]
async fn list_events_for_stage_walks_past_unrelated_events_for_sparse_matches() {
let run = fresh_run().await;
@ -1297,6 +1352,38 @@ mod tests {
assert_eq!(seqs, vec![3, 5]);
}
#[tokio::test]
async fn list_events_for_session_seeks_to_start_sequence() {
let run = fresh_run().await;
let run_id = run.run_id();
let session_id = SessionId::new();
let other_session_id = SessionId::new();
run.append_event(&session_message_payload(&run_id, 1, session_id))
.await
.unwrap();
run.append_event(&session_message_payload(&run_id, 2, other_session_id))
.await
.unwrap();
run.append_event(&session_message_payload(&run_id, 3, session_id))
.await
.unwrap();
let mut unreadable_earlier_key = keys::run_event_seq_prefix(&run_id, 2).as_ref().to_vec();
unreadable_earlier_key.push(0xff);
run.inner
.db
.put(unreadable_earlier_key, b"invalid json")
.await
.unwrap();
let events = run
.list_events_for_session_from_with_limit(session_id, 3, 100)
.await
.unwrap();
let seqs: Vec<u32> = events.iter().map(|event| event.seq).collect();
assert_eq!(seqs, vec![4]);
}
#[tokio::test]
async fn list_events_for_session_returns_limit_plus_one_for_has_more_signal() {
let run = fresh_run().await;

18
lib/components/fabro-store/tests/serializable_projection.rs
View file

@ -6,9 +6,9 @@ use fabro_types::graph::Graph;
use fabro_types::run::RunSpec;
use fabro_types::{
BilledModelUsage, BilledTokenCounts, Checkpoint, CheckpointRecord, InterviewQuestionRecord,
QuestionType, RunDiff, RunSandbox, RunSandboxInstance, RunSandboxPlan, RunSandboxRuntime,
RunStatus, SandboxProviderKind, StageCompletion, StageModelUsage, StageOutcome, StartRecord,
WorkflowSettings, first_event_seq, fixtures, test_support,
ParallelBranchResult, QuestionType, RunDiff, RunSandbox, RunSandboxInstance, RunSandboxPlan,
RunSandboxRuntime, RunStatus, SandboxProviderKind, StageCompletion, StageModelUsage,
StageOutcome, StartRecord, WorkflowSettings, first_event_seq, fixtures, test_support,
};
use serde_json::json;
@ -143,7 +143,12 @@ fn serializable_projection_round_trips_and_trims_bulky_node_fields() {
stage.diff = Some("diff --git a/a b/a".to_string());
stage.script_invocation = Some(json!({ "command": "cargo test" }));
stage.script_timing = Some(json!({ "duration_ms": 10 }));
stage.parallel_results = Some(json!([{ "stage": "fanout@1" }]));
let parallel_results = vec![ParallelBranchResult {
id: "review".to_string(),
status: StageOutcome::Succeeded,
context_updates: BTreeMap::from([("response.review".to_string(), json!("looks good"))]),
}];
stage.parallel_results = Some(parallel_results.clone());
stage.timing = Some(fabro_types::StageTiming::wall_only(1234));
let usage = sample_usage();
let usage_counts = BilledTokenCounts::from_billed_usage(std::slice::from_ref(&usage));
@ -203,10 +208,7 @@ fn serializable_projection_round_trips_and_trims_bulky_node_fields() {
Some(json!({ "command": "cargo test" }))
);
assert_eq!(node.script_timing, Some(json!({ "duration_ms": 10 })));
assert_eq!(
node.parallel_results,
Some(json!([{ "stage": "fanout@1" }]))
);
assert_eq!(node.parallel_results, Some(parallel_results));
assert_eq!(node.timing.map(|t| t.wall_time_ms), Some(1234));
assert_eq!(node.usage, usage_counts);
assert_eq!(node.model.as_ref(), Some(usage.model()));

48
lib/components/fabro-validate/src/lib.rs
View file

@ -257,6 +257,54 @@ reasoning = false
assert!(result.is_ok());
}
#[test]
fn validate_rejects_join_policy_on_any_node() {
let mut g = minimal_valid_graph();
let mut fork = Node::new("fork");
fork.attrs.insert(
"shape".to_string(),
AttrValue::String("component".to_string()),
);
fork.attrs.insert(
"join_policy".to_string(),
AttrValue::String("wait_all".to_string()),
);
g.nodes.insert("fork".to_string(), fork);
let mut custom = Node::new("custom");
custom.attrs.insert(
"type".to_string(),
AttrValue::String("custom.handler".to_string()),
);
custom.attrs.insert(
"join_policy".to_string(),
AttrValue::String("first_success".to_string()),
);
g.nodes.insert("custom".to_string(), custom);
let diagnostics = validate(&g, &[]);
let removed = diagnostics
.iter()
.filter(|d| d.rule == "join_policy_removed")
.collect::<Vec<_>>();
assert_eq!(removed.len(), 2, "diagnostics: {diagnostics:?}");
assert!(removed.iter().all(|d| d.severity == Severity::Error));
assert!(
removed
.iter()
.all(|d| d.message.contains("Remove 'join_policy'"))
);
assert_eq!(
removed
.iter()
.filter_map(|d| d.node_id.as_deref())
.collect::<std::collections::BTreeSet<_>>(),
std::collections::BTreeSet::from(["custom", "fork"]),
);
}
#[test]
fn validate_or_raise_fails_for_missing_start() {
let mut g = Graph::new("test");

9
lib/components/fabro-validate/src/rules/inert_attribute.rs
View file

@ -18,7 +18,6 @@ const HANDLER_SPECIFIC_ATTRS: &[(&str, &[&str])] = &[
("script", &["command"]),
("language", &["command"]),
("duration", &["wait"]),
("join_policy", &["parallel"]),
("max_parallel", &["parallel"]),
("output_retries", &["agent", "prompt"]),
("output_schema", &["agent", "prompt", "command"]),
@ -141,15 +140,11 @@ mod tests {
fn warns_on_parallel_attrs_on_agent_node() {
let mut g = minimal_graph();
let mut node = Node::new("work");
node.attrs.insert(
"join_policy".to_string(),
AttrValue::String("wait_all".to_string()),
);
node.attrs
.insert("max_parallel".to_string(), AttrValue::Integer(4));
g.nodes.insert("work".to_string(), node);
let d = Rule.apply(&g);
assert_eq!(d.len(), 2);
assert_eq!(d.len(), 1);
}
#[test]
@ -192,7 +187,7 @@ mod tests {
);
g.nodes.insert(
"fork".to_string(),
node_with_attr("fork", "component", "join_policy", "wait_all"),
node_with_attr("fork", "component", "max_parallel", "4"),
);
g.nodes.insert(
"spec".to_string(),

35
lib/components/fabro-validate/src/rules/join_policy_removed.rs Normal file
View file

@ -0,0 +1,35 @@
use fabro_graphviz::graph::Graph;
use crate::{Diagnostic, LintRule, Severity};
pub(super) fn rule() -> Box<dyn LintRule> {
Box::new(Rule)
}
struct Rule;
impl LintRule for Rule {
fn name(&self) -> &'static str {
"join_policy_removed"
}
fn apply(&self, graph: &Graph) -> Vec<Diagnostic> {
graph
.nodes
.values()
.filter(|node| node.attrs.contains_key("join_policy"))
.map(|node| Diagnostic {
rule: self.name().to_string(),
severity: Severity::Error,
message: format!(
"Node '{}' sets the removed 'join_policy' attribute. Remove 'join_policy'; parallel nodes always wait for every branch to finish",
node.id,
),
node_id: Some(node.id.clone()),
edge: None,
fix: Some("Remove 'join_policy' from this node".to_string()),
..Diagnostic::default()
})
.collect()
}
}

2
lib/components/fabro-validate/src/rules/mod.rs
View file

@ -9,6 +9,7 @@ mod freeform_edge_count;
mod goal_gate_has_retry;
mod import_error;
mod inert_attribute;
mod join_policy_removed;
mod model_support;
mod node_model_known;
mod orphan_custom_outcome;
@ -59,6 +60,7 @@ pub fn built_in_rules() -> Vec<Box<dyn LintRule>> {
orphan_custom_outcome::rule(),
script_absolute_cd::rule(),
import_error::rule(),
join_policy_removed::rule(),
unresolved_file_ref::rule(),
thread_id_requires_fidelity_full::rule(),
selection_valid::rule(),

2
lib/components/fabro-workflow/README.md
View file

@ -140,7 +140,7 @@ Nodes with `shape=hexagon` or `type="human"` pause execution for human input. Ou
### Parallel Execution
Nodes with `shape=component` fan out to branches concurrently. Configurable join policies: `wait_all` (default), `first_success`.
Nodes with `shape=component` fan out to branches concurrently. Branches receive isolated context forks, share the same sandbox checkout, and always finish before the workflow continues. Use `max_parallel` to limit concurrency; concurrent workspace writes are user-managed.
### Checkpoints and Resume

260
lib/components/fabro-workflow/src/artifact.rs
View file

@ -3,7 +3,9 @@ use std::path::{Path, PathBuf};
use fabro_agent::Sandbox;
use fabro_config::RunScratch;
use fabro_types::{RunBlobId, format_blob_ref, parse_blob_ref, parse_managed_blob_file_ref};
use fabro_types::{
ParallelBranchResult, RunBlobId, format_blob_ref, parse_blob_ref, parse_managed_blob_file_ref,
};
use futures::future::BoxFuture;
use serde_json::Value;
use tokio::fs;
@ -27,6 +29,10 @@ const ARTIFACT_POINTER_PREFIX: &str = "file://";
/// and replaced with a `"blob://sha256/{blob_id}"` reference.
/// Small values are left untouched.
///
/// `parallel.results` is offloaded at each branch context-update boundary
/// instead of as one value so it stays a structured array that fan-in prompts,
/// projections, and the UI can read without hydrating the whole payload.
///
/// # Errors
///
/// Returns an error if blob persistence fails.
@ -34,21 +40,77 @@ pub async fn offload_large_values(
updates: &mut HashMap<String, Value>,
run_store: &RunStoreHandle,
) -> Result<()> {
for value in updates.values_mut() {
let bytes = serde_json::to_vec(&*value)
.map_err(|e| Error::engine_with_source("artifact serialize failed", e))?;
if bytes.len() > BLOB_OFFLOAD_THRESHOLD {
let blob_id = run_store
.write_blob(&bytes)
.await
.map_err(|e| Error::engine_with_anyhow("artifact blob write failed", e))?;
*value = Value::String(format_blob_ref(&blob_id));
for (key, value) in updates {
if key == context::keys::PARALLEL_RESULTS {
offload_parallel_result_updates(value, run_store).await?;
} else {
offload_value(value, run_store).await?;
}
}
Ok(())
}
/// Offload large context-update values from typed parallel branch results
/// before they are emitted through `parallel.completed` and stored in
/// projections.
///
/// # Errors
///
/// Returns an error if blob persistence fails.
pub async fn offload_parallel_branch_updates(
results: &mut [ParallelBranchResult],
run_store: &RunStoreHandle,
) -> Result<()> {
for result in results.iter_mut() {
for value in result.context_updates.values_mut() {
offload_value(value, run_store).await?;
}
}
Ok(())
}
async fn offload_parallel_result_updates(
value: &mut Value,
run_store: &RunStoreHandle,
) -> Result<()> {
let Some(results) = value.as_array_mut() else {
return Ok(());
};
for result in results {
let Some(context_updates) = result
.get_mut("context_updates")
.and_then(Value::as_object_mut)
else {
continue;
};
for value in context_updates.values_mut() {
offload_value(value, run_store).await?;
}
}
Ok(())
}
async fn offload_value(value: &mut Value, run_store: &RunStoreHandle) -> Result<()> {
// JSON escaping expands a string to at most 6 bytes per char plus quotes,
// so short strings can never cross the threshold — skip serializing them.
if let Value::String(text) = &*value {
if text.len().saturating_mul(6) + 2 <= BLOB_OFFLOAD_THRESHOLD {
return Ok(());
}
}
let bytes = serde_json::to_vec(&*value)
.map_err(|e| Error::engine_with_source("artifact serialize failed", e))?;
if bytes.len() > BLOB_OFFLOAD_THRESHOLD {
let blob_id = run_store
.write_blob(&bytes)
.await
.map_err(|e| Error::engine_with_anyhow("artifact blob write failed", e))?;
*value = Value::String(format_blob_ref(&blob_id));
}
Ok(())
}
/// Extract the file path from an artifact pointer value.
///
/// Returns `Some(path)` if the value is a string starting with `"file://"`,
@ -269,6 +331,10 @@ fn resolve_execution_values<'a>(
})
}
fn is_text_context_key(key: &str) -> bool {
key == context::keys::COMMAND_OUTPUT || key.starts_with(context::keys::RESPONSE_PREFIX)
}
fn resolve_execution_value<'a>(
key: Option<&'a str>,
value: &'a mut Value,
@ -279,7 +345,7 @@ fn resolve_execution_value<'a>(
Box::pin(async move {
match value {
Value::String(current) => {
if matches!(key, Some(context::keys::COMMAND_OUTPUT)) {
if key.is_some_and(is_text_context_key) {
*current = resolve_text_or_blob_ref_str(current, run_store).await?;
} else if let Some(blob_id) = parse_blob_ref(current) {
*current = materialize_blob_ref(&blob_id, run_store, env, run_dir).await?;
@ -291,12 +357,18 @@ fn resolve_execution_value<'a>(
}
Value::Array(items) => {
for item in items {
resolve_execution_value(None, item, run_store, env, run_dir).await?;
resolve_execution_value(key, item, run_store, env, run_dir).await?;
}
}
Value::Object(map) => {
for item in map.values_mut() {
resolve_execution_value(None, item, run_store, env, run_dir).await?;
for (child_key, item) in map.iter_mut() {
let child_context_key = if key.is_some_and(is_text_context_key) {
key
} else {
Some(child_key.as_str())
};
resolve_execution_value(child_context_key, item, run_store, env, run_dir)
.await?;
}
}
Value::Null | Value::Bool(_) | Value::Number(_) => {}
@ -311,15 +383,12 @@ async fn materialize_blob_ref(
env: &dyn Sandbox,
run_dir: &Path,
) -> Result<String> {
let bytes = run_store
.read_blob(blob_id)
.await
.map_err(|e| Error::engine_with_anyhow("artifact blob read failed", e))?
.ok_or_else(|| Error::engine(format!("artifact blob missing: {blob_id}")))?;
// Blobs are content-addressed, so an existing materialized file is always
// current — check before paying for the store read.
if is_local_execution(env, run_dir).await? {
let path = local_materialized_blob_path(run_dir, blob_id);
if !path.exists() {
let bytes = read_required_blob(blob_id, run_store).await?;
if let Some(parent) = path.parent() {
fs::create_dir_all(parent).await.map_err(|err| {
Error::Io(format!(
@ -341,6 +410,7 @@ async fn materialize_blob_ref(
.await
.map_err(|e| Error::engine_with_source("failed to check blob existence", e))?
{
let bytes = read_required_blob(blob_id, run_store).await?;
let content = String::from_utf8(bytes.to_vec())
.map_err(|e| Error::engine_with_source("artifact blob was not valid UTF-8 JSON", e))?;
env.write_file(&remote_path, &content).await.map_err(|e| {
@ -351,6 +421,17 @@ async fn materialize_blob_ref(
Ok(format!("{ARTIFACT_POINTER_PREFIX}{remote_path}"))
}
async fn read_required_blob(
blob_id: &RunBlobId,
run_store: &RunStoreHandle,
) -> Result<bytes::Bytes> {
run_store
.read_blob(blob_id)
.await
.map_err(|e| Error::engine_with_anyhow("artifact blob read failed", e))?
.ok_or_else(|| Error::engine(format!("artifact blob missing: {blob_id}")))
}
async fn resolve_explicit_file_ref(value: &str, env: &dyn Sandbox) -> Result<String> {
let local_path = value
.strip_prefix(ARTIFACT_POINTER_PREFIX)
@ -471,6 +552,79 @@ mod tests {
assert_eq!(updates.get("small_key").unwrap(), &small_value);
}
#[tokio::test]
async fn offload_preserves_parallel_results_and_replaces_large_context_updates() {
let run_store = make_run_store("parallel-result-artifact-offload").await;
let large_response = "r".repeat(BLOB_OFFLOAD_THRESHOLD + 1);
let large_output = "o".repeat(BLOB_OFFLOAD_THRESHOLD + 1);
let large_report = Value::Array(vec![
Value::String("small".to_string());
BLOB_OFFLOAD_THRESHOLD / 4
]);
let expected_report_blob = RunBlobId::new(&serde_json::to_vec(&large_report).unwrap());
let mut typed_results = vec![ParallelBranchResult {
id: "branch_a".to_string(),
status: fabro_types::StageOutcome::Succeeded,
context_updates: std::collections::BTreeMap::from([
(
"response.branch_a".to_string(),
serde_json::json!(large_response),
),
(
context::keys::COMMAND_OUTPUT.to_string(),
serde_json::json!(large_output),
),
("report".to_string(), large_report.clone()),
("small".to_string(), serde_json::json!("kept inline")),
]),
}];
offload_parallel_branch_updates(&mut typed_results, &run_store.clone().into())
.await
.unwrap();
let mut updates = HashMap::from([(
context::keys::PARALLEL_RESULTS.to_string(),
serde_json::to_value(typed_results).unwrap(),
)]);
// The ordinary lifecycle pass must preserve the typed result structure
// and the values already offloaded before the completion event.
offload_large_values(&mut updates, &run_store.clone().into())
.await
.unwrap();
let results = updates[context::keys::PARALLEL_RESULTS]
.as_array()
.expect("parallel.results must remain a structured array");
let branch_updates = results[0]["context_updates"]
.as_object()
.expect("context_updates must remain a structured object");
assert!(
branch_updates["response.branch_a"]
.as_str()
.is_some_and(|value| fabro_types::parse_blob_ref(value).is_some())
);
assert!(
branch_updates[context::keys::COMMAND_OUTPUT]
.as_str()
.is_some_and(|value| fabro_types::parse_blob_ref(value).is_some())
);
assert_eq!(
branch_updates["report"],
serde_json::json!(format_blob_ref(&expected_report_blob))
);
let stored_report = run_store
.read_blob(&expected_report_blob)
.await
.unwrap()
.expect("structured report blob should exist");
assert_eq!(
serde_json::from_slice::<Value>(&stored_report).unwrap(),
large_report
);
assert_eq!(branch_updates["small"], serde_json::json!("kept inline"));
}
#[test]
fn artifact_path_extracts_path_from_pointer() {
let value = serde_json::json!("file:///tmp/logs/runtime/blobs/response.plan.json");
@ -492,6 +646,70 @@ mod tests {
assert_eq!(artifact_path(&value), None);
}
#[tokio::test]
async fn resolve_context_hydrates_nested_parallel_text_blob_references() {
let run_store = make_run_store("parallel-result-text-resolution").await;
let response = "full branch response";
let output = "full command output";
let response_blob = run_store
.write_blob(&serde_json::to_vec(response).unwrap())
.await
.unwrap();
let output_blob = run_store
.write_blob(&serde_json::to_vec(output).unwrap())
.await
.unwrap();
let unrelated_blob = run_store
.write_blob(&serde_json::to_vec("unrelated artifact").unwrap())
.await
.unwrap();
let context = Context::new();
context.set(
context::keys::PARALLEL_RESULTS,
serde_json::json!([{
"id": "branch_a",
"status": "succeeded",
"context_updates": {
"response.branch_a": fabro_types::format_blob_ref(&response_blob),
"response.nested": {
"text": fabro_types::format_blob_ref(&response_blob),
"items": [fabro_types::format_blob_ref(&output_blob)],
},
"command.output": fabro_types::format_blob_ref(&output_blob),
"report": fabro_types::format_blob_ref(&unrelated_blob),
}
}]),
);
let env = TestSyncEnv::new(true, "/workspace");
let run_dir = tempfile::tempdir().unwrap();
let resolved =
resolved_context_snapshot(&context, &run_store.clone().into(), &env, run_dir.path())
.await
.unwrap();
let updates = &resolved[context::keys::PARALLEL_RESULTS][0]["context_updates"];
assert_eq!(updates["response.branch_a"], serde_json::json!(response));
assert_eq!(
updates["response.nested"]["text"],
serde_json::json!(response)
);
assert_eq!(
updates["response.nested"]["items"][0],
serde_json::json!(output)
);
assert_eq!(
updates[context::keys::COMMAND_OUTPUT],
serde_json::json!(output)
);
assert!(
updates["report"]
.as_str()
.is_some_and(|value| value.starts_with("file://")),
"non-textual nested values should retain artifact semantics"
);
}
#[test]
fn normalize_durable_updates_rewrites_managed_blob_file_refs_recursively() {
let blob_id = fabro_types::RunBlobId::new(b"hello");

106
lib/components/fabro-workflow/src/context.rs
View file

@ -44,9 +44,6 @@ pub mod keys {
// --- parallel.* keys ---
pub const PARALLEL_RESULTS: &str = "parallel.results";
pub const PARALLEL_BRANCH_COUNT: &str = "parallel.branch_count";
pub const PARALLEL_FAN_IN_BEST_ID: &str = "parallel.fan_in.best_id";
pub const PARALLEL_FAN_IN_BEST_OUTCOME: &str = "parallel.fan_in.best_outcome";
pub const PARALLEL_FAN_IN_BEST_HEAD_SHA: &str = "parallel.fan_in.best_head_sha";
/// Runtime-only keys stripped from durable context projections.
pub(crate) const TRANSIENT_CONTEXT_KEYS: &[&str] =
@ -140,13 +137,41 @@ pub mod keys {
}
}
use std::collections::HashMap;
pub use fabro_core::Context;
use fabro_graphviz::Fidelity;
use fabro_types::{ParallelBranchId, StageId};
use fabro_types::{ParallelBranchId, RunId, StageId};
use serde::{Deserialize, Serialize};
use crate::error::Error;
use crate::event::StageScope;
/// Keys whose values changed or were added in `after` relative to `before`.
/// Takes `after` by value so changed entries move instead of clone.
pub(crate) fn context_diff(
before: &HashMap<String, serde_json::Value>,
after: HashMap<String, serde_json::Value>,
) -> HashMap<String, serde_json::Value> {
after
.into_iter()
.filter(|(key, value)| before.get(key) != Some(value))
.collect()
}
/// [`context_diff`] restricted to user-visible keys: the diff that should
/// propagate outside the executing scope (to a parent workflow or across a
/// parallel fork), with engine-internal keys removed.
pub(crate) fn context_diff_public(
before: &HashMap<String, serde_json::Value>,
after: HashMap<String, serde_json::Value>,
) -> HashMap<String, serde_json::Value> {
context_diff(before, after)
.into_iter()
.filter(|(key, _)| !keys::is_engine_internal_key(key))
.collect()
}
/// One entry of the [`keys::INTERNAL_PARALLEL_BRANCH_PREAMBLES`] stash.
///
/// The stash is a JSON array indexed by the parallel node's outgoing-edge
@ -164,6 +189,9 @@ pub trait WorkflowContext {
fn thread_id(&self) -> Option<String>;
fn preamble(&self) -> String;
fn run_id(&self) -> String;
/// Parse `internal.run_id`, failing when the engine did not seed a
/// valid run ID.
fn parsed_run_id(&self) -> Result<RunId, Error>;
fn parallel_group_id(&self) -> Option<StageId>;
fn parallel_branch_id(&self) -> Option<ParallelBranchId>;
/// Build the stage-level emit scope from the currently-executing node and
@ -192,6 +220,12 @@ impl WorkflowContext for Context {
self.get_string(keys::INTERNAL_RUN_ID, "unknown")
}
fn parsed_run_id(&self) -> Result<RunId, Error> {
self.run_id()
.parse()
.map_err(|err| Error::handler_with_source("invalid internal run_id", err))
}
fn parallel_group_id(&self) -> Option<StageId> {
self.get(keys::INTERNAL_PARALLEL_GROUP_ID)
.and_then(|value| serde_json::from_value(value).ok())
@ -235,6 +269,70 @@ mod tests {
assert_eq!(ctx.get("missing"), None);
}
#[test]
fn context_diff_detects_additions() {
let before = HashMap::new();
let mut after = HashMap::new();
after.insert("key".to_string(), serde_json::json!("value"));
let diff = context_diff(&before, after);
assert_eq!(diff.len(), 1);
assert_eq!(diff.get("key"), Some(&serde_json::json!("value")));
}
#[test]
fn context_diff_detects_changes() {
let mut before = HashMap::new();
before.insert("key".to_string(), serde_json::json!("old"));
let mut after = HashMap::new();
after.insert("key".to_string(), serde_json::json!("new"));
let diff = context_diff(&before, after);
assert_eq!(diff.len(), 1);
assert_eq!(diff.get("key"), Some(&serde_json::json!("new")));
}
#[test]
fn context_diff_ignores_unchanged() {
let mut before = HashMap::new();
before.insert("key".to_string(), serde_json::json!("same"));
let mut after = HashMap::new();
after.insert("key".to_string(), serde_json::json!("same"));
let diff = context_diff(&before, after);
assert!(diff.is_empty());
}
#[test]
fn context_diff_ignores_deletions() {
let mut before = HashMap::new();
before.insert("removed".to_string(), serde_json::json!("gone"));
let after = HashMap::new();
let diff = context_diff(&before, after);
assert!(diff.is_empty());
}
#[test]
fn context_diff_public_excludes_engine_internal_keys() {
let before = HashMap::new();
let mut after = HashMap::new();
after.insert("graph.goal".to_string(), serde_json::json!("child goal"));
after.insert(
"internal.run_id".to_string(),
serde_json::json!("child-run"),
);
after.insert(
"thread.main.current_node".to_string(),
serde_json::json!("exit"),
);
after.insert("current_node".to_string(), serde_json::json!("exit"));
after.insert("response.plan".to_string(), serde_json::json!("the plan"));
after.insert("review.result".to_string(), serde_json::json!("approved"));
let filtered = context_diff_public(&before, after);
assert_eq!(filtered.len(), 2);
assert!(filtered.contains_key("response.plan"));
assert!(filtered.contains_key("review.result"));
}
#[test]
fn get_string_with_value() {
let ctx = Context::new();

104
lib/components/fabro-workflow/src/event/convert.rs
View file

@ -371,12 +371,10 @@ fn event_body_from_event(event: &Event) -> EventBody {
Event::ParallelStarted {
visit,
branch_count,
join_policy,
..
} => EventBody::ParallelStarted(fabro_types::ParallelStartedProps {
visit: *visit,
branch_count: *branch_count,
join_policy: join_policy.clone(),
}),
Event::ParallelBranchStarted { index, .. } => {
EventBody::ParallelBranchStarted(fabro_types::ParallelBranchStartedProps {
@ -387,13 +385,11 @@ fn event_body_from_event(event: &Event) -> EventBody {
index,
duration_ms,
status,
head_sha,
..
} => EventBody::ParallelBranchCompleted(fabro_types::ParallelBranchCompletedProps {
index: *index,
duration_ms: *duration_ms,
status: status.clone(),
head_sha: head_sha.clone(),
status: *status,
}),
Event::ParallelCompleted {
visit,
@ -516,19 +512,6 @@ fn event_body_from_event(event: &Event) -> EventBody {
success: *success,
exec_output_tail: exec_output_tail.clone(),
}),
Event::GitBranch { branch, sha } => EventBody::GitBranch(fabro_types::GitBranchProps {
branch: branch.clone(),
sha: sha.clone(),
}),
Event::GitWorktreeAdd { path, branch } => {
EventBody::GitWorktreeAdd(fabro_types::GitWorktreeAddProps {
path: path.clone(),
branch: branch.clone(),
})
}
Event::GitWorktreeRemove { path } => {
EventBody::GitWorktreeRemove(fabro_types::GitWorktreeRemoveProps { path: path.clone() })
}
Event::GitFetch { branch, success } => EventBody::GitFetch(fabro_types::GitFetchProps {
branch: branch.clone(),
success: *success,
@ -1716,15 +1699,96 @@ mod tests {
}
#[test]
fn parallel_started_populates_parallel_group_id() {
fn parallel_started_populates_group_id_and_public_properties() {
let stored = to_run_event(&fixtures::RUN_1, &Event::ParallelStarted {
node_id: "fanout".to_string(),
visit: 2,
branch_count: 3,
join_policy: "wait_all".to_string(),
});
assert_eq!(stored.parallel_group_id, Some(StageId::new("fanout", 2)));
assert!(stored.parallel_branch_id.is_none());
assert_eq!(
stored.properties().unwrap(),
serde_json::json!({
"visit": 2,
"branch_count": 3,
})
);
}
#[test]
fn parallel_branch_completed_public_properties() {
let group_id = StageId::new("fanout", 2);
let stored = to_run_event(&fixtures::RUN_1, &Event::ParallelBranchCompleted {
parallel_group_id: group_id.clone(),
parallel_branch_id: ParallelBranchId::new(group_id, 1),
branch: "review".to_string(),
index: 1,
duration_ms: 42,
status: StageOutcome::Succeeded,
});
assert_eq!(
stored.properties().unwrap(),
serde_json::json!({
"index": 1,
"duration_ms": 42,
"status": "succeeded",
})
);
}
#[test]
fn parallel_completed_exposes_typed_results_in_input_order() {
let stored = to_run_event(&fixtures::RUN_1, &Event::ParallelCompleted {
node_id: "fanout".to_string(),
visit: 2,
duration_ms: 84,
success_count: 1,
failure_count: 1,
results: vec![
::fabro_types::ParallelBranchResult {
id: "review_api".to_string(),
status: StageOutcome::Succeeded,
context_updates: BTreeMap::from([(
"response.review_api".to_string(),
serde_json::json!("looks good"),
)]),
},
::fabro_types::ParallelBranchResult {
id: "review_ux".to_string(),
status: StageOutcome::Failed {
retry_requested: false,
},
context_updates: BTreeMap::from([(
"response.review_ux".to_string(),
serde_json::json!("needs work"),
)]),
},
],
});
assert_eq!(
stored.properties().unwrap(),
serde_json::json!({
"visit": 2,
"duration_ms": 84,
"success_count": 1,
"failure_count": 1,
"results": [
{
"id": "review_api",
"status": "succeeded",
"context_updates": {"response.review_api": "looks good"},
},
{
"id": "review_ux",
"status": "failed",
"context_updates": {"response.review_ux": "needs work"},
},
],
})
);
}
#[test]

17
lib/components/fabro-workflow/src/event/emitter.rs
View file

@ -3,7 +3,6 @@ use std::sync::atomic::{AtomicI64, Ordering};
use ::fabro_types::{ExecOutputTail, RunEvent, RunId, RunNoticeCode, RunNoticeLevel};
use chrono::Utc;
use fabro_agent::{WorktreeEvent, WorktreeEventCallback};
use super::Event;
use super::convert::to_run_event_at;
@ -139,22 +138,6 @@ impl Emitter {
pub fn touch(&self) {
self.last_event_at.store(epoch_millis(), Ordering::Relaxed);
}
/// Build a [`WorktreeEventCallback`] that forwards worktree lifecycle
/// events as [`Event`]s on this emitter.
pub fn worktree_callback(self: Arc<Self>) -> WorktreeEventCallback {
Arc::new(move |event| match event {
WorktreeEvent::BranchCreated { branch, sha } => {
self.emit(&Event::GitBranch { branch, sha });
}
WorktreeEvent::WorktreeAdded { path, branch } => {
self.emit(&Event::GitWorktreeAdd { path, branch });
}
WorktreeEvent::WorktreeRemoved { path } => {
self.emit(&Event::GitWorktreeRemove { path });
}
})
}
}
#[cfg(test)]

48
lib/components/fabro-workflow/src/event/events.rs
View file

@ -3,10 +3,10 @@ use std::collections::BTreeMap;
use ::fabro_types::{
AutomationRef, BilledTokenCounts, BlockedReason, CommandTermination, DiffSummary,
FailureReason, ForkSourceRef, GitContext, PairId, PairMessageId, PairSystemMessageKind,
PairTarget, ParallelBranchId, PendingReason, PermissionLevel, Principal, PullRequestLink,
RunBlobId, RunFailure, RunId, RunNoticeLevel, RunPairEndedReason, RunPairFailedReason,
RunProvenance, RunRunnableSource, RunTiming, SandboxProviderKind, StageId, StageTiming,
SuccessReason, run_event as fabro_types,
PairTarget, ParallelBranchId, ParallelBranchResult, PendingReason, PermissionLevel, Principal,
PullRequestLink, RunBlobId, RunFailure, RunId, RunNoticeLevel, RunPairEndedReason,
RunPairFailedReason, RunProvenance, RunRunnableSource, RunTiming, SandboxProviderKind, StageId,
StageOutcome, StageTiming, SuccessReason, run_event as fabro_types,
};
use fabro_agent::{AgentEvent, SandboxEvent};
use fabro_model::{ReasoningEffort, Speed};
@ -304,7 +304,6 @@ pub enum Event {
node_id: String,
visit: u32,
branch_count: usize,
join_policy: String,
},
ParallelBranchStarted {
parallel_group_id: StageId,
@ -318,9 +317,7 @@ pub enum Event {
branch: String,
index: usize,
duration_ms: u64,
status: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
head_sha: Option<String>,
status: StageOutcome,
},
ParallelCompleted {
node_id: String,
@ -329,7 +326,7 @@ pub enum Event {
success_count: usize,
failure_count: usize,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
results: Vec<serde_json::Value>,
results: Vec<ParallelBranchResult>,
},
InterviewStarted {
question_id: String,
@ -414,17 +411,6 @@ pub enum Event {
#[serde(default, skip_serializing_if = "Option::is_none")]
exec_output_tail: Option<fabro_types::ExecOutputTail>,
},
GitBranch {
branch: String,
sha: String,
},
GitWorktreeAdd {
path: String,
branch: String,
},
GitWorktreeRemove {
path: String,
},
GitFetch {
branch: String,
success: bool,
@ -1116,12 +1102,8 @@ impl Event {
"Stage retrying"
);
}
Self::ParallelStarted {
branch_count,
join_policy,
..
} => {
debug!(branch_count, join_policy, "Parallel execution started");
Self::ParallelStarted { branch_count, .. } => {
debug!(branch_count, "Parallel execution started");
}
Self::ParallelBranchStarted { branch, index, .. } => {
debug!(branch, index, "Parallel branch started");
@ -1135,7 +1117,10 @@ impl Event {
} => {
debug!(
branch,
index, duration_ms, status, "Parallel branch completed"
index,
duration_ms,
status = %status,
"Parallel branch completed"
);
}
Self::ParallelCompleted {
@ -1233,15 +1218,6 @@ impl Event {
);
}
}
Self::GitBranch { branch, sha } => {
debug!(branch, sha, "Git branch created");
}
Self::GitWorktreeAdd { path, branch } => {
debug!(path, branch, "Git worktree added");
}
Self::GitWorktreeRemove { path } => {
debug!(path, "Git worktree removed");
}
Self::GitFetch { branch, success } => {
if *success {
debug!(branch, "Git fetch succeeded");

3
lib/components/fabro-workflow/src/event/names.rs
View file

@ -56,9 +56,6 @@ pub fn event_name(event: &Event) -> &'static str {
Event::CheckpointFailed { .. } => "checkpoint.failed",
Event::GitCommit { .. } => "git.commit",
Event::GitPush { .. } => "git.push",
Event::GitBranch { .. } => "git.branch",
Event::GitWorktreeAdd { .. } => "git.worktree.added",
Event::GitWorktreeRemove { .. } => "git.worktree.removed",
Event::GitFetch { .. } => "git.fetch",
Event::GitReset { .. } => "git.reset",
Event::EdgeSelected { .. } => "edge.selected",

148
lib/components/fabro-workflow/src/git.rs
View file

@ -74,60 +74,6 @@ pub fn head_sha(repo: &Path) -> Result<String> {
Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())
}
/// Create a new branch at HEAD without checking it out.
pub fn create_branch(repo: &Path, name: &str) -> Result<()> {
let output = git_cmd(repo)
.args(["branch", "--force", name, "HEAD"])
.output()
.map_err(|e| Error::engine_with_source("git branch failed", e))?;
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
return Err(git_error(format!("git branch failed: {stderr}")));
}
Ok(())
}
/// Add a git worktree for the given branch at `path`.
pub fn add_worktree(repo: &Path, path: &Path, branch: &str) -> Result<()> {
let output = git_cmd(repo)
.args(["worktree", "add"])
.arg(path)
.arg(branch)
.output()
.map_err(|e| Error::engine_with_source("git worktree add failed", e))?;
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
return Err(git_error(format!("git worktree add failed: {stderr}")));
}
Ok(())
}
/// Remove a git worktree.
pub fn remove_worktree(repo: &Path, path: &Path) -> Result<()> {
let output = git_cmd(repo)
.args(["worktree", "remove", "--force"])
.arg(path)
.output()
.map_err(|e| Error::engine_with_source("git worktree remove failed", e))?;
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
return Err(git_error(format!("git worktree remove failed: {stderr}")));
}
Ok(())
}
/// Remove any stale worktree at `path` (best-effort), then add a fresh one.
pub fn replace_worktree(repo: &Path, path: &Path, branch: &str) -> Result<()> {
let _ = remove_worktree(repo, path);
add_worktree(repo, path, branch)
}
/// Run a `git push` command and check for success.
fn run_git_push(cmd: &mut Command) -> Result<()> {
let output = cmd
@ -313,23 +259,6 @@ pub fn sync_status(repo: &Path, remote: &str, branch: Option<&str>) -> GitSyncSt
}
}
/// Sanitize a string for use as a git ref component.
/// Lowercases, replaces non-alphanumeric chars with dashes, collapses runs.
pub fn sanitize_ref_component(s: &str) -> String {
let mut result = String::with_capacity(s.len());
let mut prev_dash = false;
for c in s.chars() {
if c.is_ascii_alphanumeric() {
result.push(c.to_ascii_lowercase());
prev_dash = false;
} else if !prev_dash {
result.push('-');
prev_dash = true;
}
}
result.trim_matches('-').to_string()
}
/// Filenames allowed in per-node directories on the shadow branch.
#[cfg(test)]
#[expect(
@ -416,39 +345,6 @@ mod tests {
assert!(sha.chars().all(|c| c.is_ascii_hexdigit()));
}
#[test]
#[expect(
clippy::disallowed_methods,
reason = "This synchronous test verifies git branch listing against the real git CLI."
)]
fn create_branch_and_list() {
let dir = tempfile::tempdir().unwrap();
init_repo(dir.path());
create_branch(dir.path(), "test-branch").unwrap();
let output = Command::new("git")
.args(["branch", "--list", "test-branch"])
.current_dir(dir.path())
.output()
.unwrap();
let stdout = String::from_utf8_lossy(&output.stdout);
assert!(stdout.contains("test-branch"));
}
#[test]
fn add_and_remove_worktree() {
let dir = tempfile::tempdir().unwrap();
init_repo(dir.path());
create_branch(dir.path(), "wt-branch").unwrap();
let wt_path = dir.path().join("my-worktree");
add_worktree(dir.path(), &wt_path, "wt-branch").unwrap();
assert!(wt_path.join(".git").exists());
remove_worktree(dir.path(), &wt_path).unwrap();
assert!(!wt_path.exists());
}
#[tokio::test]
async fn scan_node_files_from_state_reconstructs_allowlisted_entries() {
use crate::event::{Event, append_event};
@ -550,7 +446,11 @@ mod tests {
duration_ms: 100,
success_count: 1,
failure_count: 0,
results: vec![serde_json::json!({"id": "a"})],
results: vec![fabro_types::ParallelBranchResult {
id: "a".to_string(),
status: fabro_types::StageOutcome::Succeeded,
context_updates: std::collections::BTreeMap::new(),
}],
})
.await
.unwrap();
@ -588,44 +488,6 @@ mod tests {
assert!(paths.contains(&"stages/001-work@2/parallel_results.json"));
}
#[test]
fn sanitize_ref_component_lowercases() {
assert_eq!(sanitize_ref_component("Hello"), "hello");
}
#[test]
fn sanitize_ref_component_replaces_special_chars() {
assert_eq!(sanitize_ref_component("a/b:c d"), "a-b-c-d");
}
#[test]
fn sanitize_ref_component_collapses_consecutive_dashes() {
assert_eq!(sanitize_ref_component("a///b"), "a-b");
}
#[test]
fn sanitize_ref_component_trims_leading_trailing_dashes() {
assert_eq!(sanitize_ref_component("--abc--"), "abc");
}
#[test]
fn sanitize_ref_component_mixed() {
assert_eq!(sanitize_ref_component("My Node!@#123"), "my-node-123");
}
#[test]
fn replace_worktree_on_clean_path() {
let dir = tempfile::tempdir().unwrap();
init_repo(dir.path());
create_branch(dir.path(), "rw-branch").unwrap();
let wt_path = dir.path().join("rw-worktree");
replace_worktree(dir.path(), &wt_path, "rw-branch").unwrap();
assert!(wt_path.join(".git").exists());
remove_worktree(dir.path(), &wt_path).unwrap();
}
#[test]
fn push_branch_fails_for_nonexistent_remote() {
let dir = tempfile::tempdir().unwrap();

7
lib/components/fabro-workflow/src/handler/agent.rs
View file

@ -4,7 +4,7 @@ use std::sync::Arc;
use async_trait::async_trait;
use fabro_agent::Sandbox;
use fabro_graphviz::graph::{Graph, Node};
use fabro_types::{RunId, StageModelUsage, StageTiming};
use fabro_types::{StageModelUsage, StageTiming};
pub(crate) use structured_output::extract_status_fields;
use tokio_util::sync::CancellationToken;
@ -286,10 +286,7 @@ impl Handler for AgentHandler {
// 3. Call LLM backend (agent loop)
let thread_id = context.thread_id();
let run_id = context
.run_id()
.parse::<RunId>()
.map_err(|err| Error::handler_with_source("invalid internal run_id", err))?;
let run_id = context.parsed_run_id()?;
let tool_hooks: Option<Arc<dyn fabro_agent::ToolHookCallback>> =
services.run.hook_runner.as_ref().map(|hr| {
Arc::new(fabro_hooks::WorkflowToolHookCallback {

724
lib/components/fabro-workflow/src/handler/fan_in.rs
View file

@ -2,665 +2,253 @@ use std::path::Path;
use std::sync::Arc;
use async_trait::async_trait;
use fabro_agent::Sandbox;
use fabro_graphviz::graph::{Graph, Node};
use fabro_types::{StageModelUsage, StageTiming};
use tokio_util::sync::CancellationToken;
use fabro_types::ParallelBranchResult;
use super::agent::{CodergenBackend, CodergenResult, CodergenRunRequest};
use super::agent::CodergenBackend;
use super::prompt::PromptHandler;
use super::{EngineServices, Handler};
use crate::context::{Context, keys};
use crate::error::Error;
use crate::event::{Emitter, Event, StageScope};
use crate::outcome::{Outcome, OutcomeExt};
use crate::sandbox_git::git_merge_ff_only;
use crate::event::Emitter;
use crate::outcome::Outcome;
/// Consolidates results from a preceding parallel node and selects the best
/// candidate.
/// Joins results from a preceding parallel node.
///
/// Promptless fan-in nodes are barriers. Prompted fan-in nodes use the same
/// execution path as standard prompt stages and synthesize the full ordered
/// branch result set without selecting workspace state.
pub struct FanInHandler {
backend: Option<Box<dyn CodergenBackend>>,
prompt_handler: PromptHandler,
}
impl FanInHandler {
#[must_use]
pub fn new(backend: Option<Box<dyn CodergenBackend>>) -> Self {
Self { backend }
Self {
prompt_handler: PromptHandler::new(backend),
}
}
}
impl FanInHandler {
async fn run_join(
&self,
node: &Node,
context: &Context,
graph: &Graph,
run_dir: &Path,
services: &EngineServices,
simulated: bool,
) -> Result<Outcome, Error> {
let branch_count = validated_branch_count(context)?;
if node
.prompt()
.is_some_and(|prompt| !prompt.trim().is_empty())
{
return if simulated {
self.prompt_handler
.simulate(node, context, graph, run_dir, services)
.await
} else {
self.prompt_handler
.execute(node, context, graph, run_dir, services)
.await
};
}
Ok(joined_outcome(branch_count, simulated))
}
}
#[async_trait]
impl Handler for FanInHandler {
async fn shutdown(&self, emitter: &Arc<Emitter>) {
if let Some(backend) = self.backend.as_ref() {
backend.shutdown(emitter).await;
}
self.prompt_handler.shutdown(emitter).await;
}
async fn simulate(
&self,
node: &Node,
context: &Context,
_graph: &Graph,
_run_dir: &Path,
_services: &EngineServices,
graph: &Graph,
run_dir: &Path,
services: &EngineServices,
) -> Result<Outcome, Error> {
let results = context.get(keys::PARALLEL_RESULTS);
let Some(results) = results else {
return Ok(Outcome::fail_deterministic(
"No parallel results to evaluate",
));
};
let best = heuristic_select(&results);
let mut outcome = Outcome::simulated(&node.id);
outcome.context_updates.insert(
keys::PARALLEL_FAN_IN_BEST_ID.to_string(),
serde_json::json!(best.id),
);
outcome.context_updates.insert(
keys::PARALLEL_FAN_IN_BEST_OUTCOME.to_string(),
serde_json::json!(best.status),
);
// Override the generic simulated notes with handler-specific detail.
outcome.notes = Some(format!("[Simulated] Selected best candidate: {}", best.id));
Ok(outcome)
self.run_join(node, context, graph, run_dir, services, true)
.await
}
async fn execute(
&self,
node: &Node,
context: &Context,
_graph: &Graph,
graph: &Graph,
run_dir: &Path,
services: &EngineServices,
) -> Result<Outcome, Error> {
let results = context.get(keys::PARALLEL_RESULTS);
let Some(results) = results else {
return Ok(Outcome::fail_deterministic(
"No parallel results to evaluate",
));
};
self.run_join(node, context, graph, run_dir, services, false)
.await
}
}
let prompt = node.prompt().filter(|p| !p.is_empty());
/// Validate that `parallel.results` exists and has the typed shape.
fn validated_branch_count(context: &Context) -> Result<usize, Error> {
let value = context
.get(keys::PARALLEL_RESULTS)
.ok_or_else(|| Error::handler("No parallel results to join"))?;
let results: Vec<ParallelBranchResult> = serde_json::from_value(value)
.map_err(|err| Error::handler_with_source("Invalid parallel results", err))?;
Ok(results.len())
}
let best = if let (Some(prompt_text), Some(backend)) = (prompt, &self.backend) {
llm_evaluate(
backend.as_ref(),
prompt_text,
&results,
context,
run_dir,
&node.id,
&services.run.emitter,
&services.run.sandbox,
services.run.cancel_token(),
)
.await?
fn joined_outcome(branch_count: usize, simulated: bool) -> Outcome {
let mut outcome = Outcome::success();
let prefix = if simulated { "[Simulated] " } else { "" };
outcome.notes = Some(format!(
"{prefix}Joined {branch_count} parallel {}",
if branch_count == 1 {
"branch"
} else {
heuristic_select(&results)
};
// Check if all candidates failed — if so, return fail
let all_failed = if best.status == "failed" {
let empty_vec = vec![];
let arr = results.as_array().unwrap_or(&empty_vec);
arr.iter()
.all(|v| v.get("status").and_then(|v| v.as_str()).unwrap_or("failed") == "failed")
} else {
false
};
if all_failed {
let mut outcome = Outcome::fail_deterministic("all candidates failed");
outcome.timing = Some(best.timing);
return Ok(outcome);
"branches"
}
// --- Fast-forward to winner's HEAD when git isolation is active ---
let best_head_sha = {
let empty_vec = vec![];
let arr = results.as_array().unwrap_or(&empty_vec);
arr.iter()
.find(|v| v.get("id").and_then(|v| v.as_str()) == Some(&best.id))
.and_then(|v| v.get("head_sha").and_then(|v| v.as_str()).map(String::from))
};
if let (Some(ref sha), Some(_)) = (&best_head_sha, services.git_state()) {
git_merge_ff_only(&*services.run.sandbox, sha).await;
}
let mut outcome = Outcome::success();
outcome.context_updates.insert(
keys::PARALLEL_FAN_IN_BEST_ID.to_string(),
serde_json::json!(best.id),
);
outcome.context_updates.insert(
keys::PARALLEL_FAN_IN_BEST_OUTCOME.to_string(),
serde_json::json!(best.status),
);
if let Some(ref sha) = best_head_sha {
outcome.context_updates.insert(
keys::PARALLEL_FAN_IN_BEST_HEAD_SHA.to_string(),
serde_json::json!(sha),
);
}
outcome.notes = Some(format!("Selected best candidate: {}", best.id));
outcome.timing = Some(best.timing);
Ok(outcome)
}
}
struct Candidate {
id: String,
status: String,
score: f64,
timing: StageTiming,
}
fn status_rank(status: &str) -> u32 {
match status {
"succeeded" => 0,
"partially_succeeded" => 1,
"failed" => 2,
_ => 4,
}
}
fn heuristic_select(results: &serde_json::Value) -> Candidate {
let empty_vec = vec![];
let arr = results.as_array().unwrap_or(&empty_vec);
if arr.is_empty() {
return Candidate {
id: "unknown".to_string(),
status: "failed".to_string(),
score: 0.0,
timing: StageTiming::default(),
};
}
let mut candidates: Vec<Candidate> = arr
.iter()
.map(|v| Candidate {
id: v
.get("id")
.and_then(|v| v.as_str())
.unwrap_or("unknown")
.to_string(),
status: v
.get("status")
.and_then(|v| v.as_str())
.unwrap_or("failed")
.to_string(),
score: v
.get("score")
.and_then(serde_json::Value::as_f64)
.unwrap_or(0.0),
timing: StageTiming::default(),
})
.collect();
candidates.sort_by(|a, b| {
let rank_cmp = status_rank(&a.status).cmp(&status_rank(&b.status));
if rank_cmp != std::cmp::Ordering::Equal {
return rank_cmp;
}
// Higher score is better, so reverse the comparison
let score_cmp = b
.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal);
if score_cmp != std::cmp::Ordering::Equal {
return score_cmp;
}
a.id.cmp(&b.id)
});
candidates.into_iter().next().unwrap_or_else(|| Candidate {
id: "unknown".to_string(),
status: "failed".to_string(),
score: 0.0,
timing: StageTiming::default(),
})
}
/// Use an LLM backend to evaluate and rank parallel branch results.
#[allow(
clippy::too_many_arguments,
reason = "Fan-in evaluation passes prompt, results, context, and runtime handles separately."
)]
async fn llm_evaluate(
backend: &dyn CodergenBackend,
prompt: &str,
results: &serde_json::Value,
context: &Context,
_run_dir: &Path,
node_id: &str,
emitter: &Arc<Emitter>,
sandbox: &Arc<dyn Sandbox>,
cancel_token: CancellationToken,
) -> Result<Candidate, Error> {
let results_text =
serde_json::to_string_pretty(results).unwrap_or_else(|_| results.to_string());
let full_prompt = format!(
"{prompt}\n\nParallel branch results:\n{results_text}\n\n\
Respond with the ID of the best candidate."
);
let stage_scope = StageScope::for_handler(context, node_id);
emitter.emit_scoped(
&Event::Prompt {
stage: node_id.to_string(),
visit: stage_scope.visit,
text: full_prompt.clone(),
mode: Some(StageModelUsage::MODE_FAN_IN.to_string()),
provider: None,
model: None,
reasoning_effort: None,
speed: None,
},
&stage_scope,
);
// Build a synthetic node for the backend call
let eval_node = Node::new("fan_in_eval");
// Fan-in evaluation runs outside a thread context, so pass None
match backend
.run(CodergenRunRequest {
node: &eval_node,
prompt: &full_prompt,
context,
thread_id: None,
emitter,
sandbox,
tool_hooks: None,
cancel_token,
agent_tool_runtime: fabro_agent::AgentToolRuntime::default(),
})
.await
{
Ok(CodergenResult::Full(outcome)) => {
let timing = outcome.timing.unwrap_or_default();
// If the backend returned a full Outcome, extract best_id from context_updates
let best_id = outcome
.context_updates
.get(keys::PARALLEL_FAN_IN_BEST_ID)
.and_then(|v| v.as_str())
.map(String::from)
.or_else(|| outcome.notes.clone())
.unwrap_or_else(|| "unknown".to_string());
let response_text =
serde_json::to_string_pretty(&outcome).unwrap_or_else(|_| "{}".to_string());
emitter.emit_scoped(
&Event::PromptCompleted {
node_id: node_id.to_string(),
response: response_text.clone(),
model: String::new(),
provider: String::new(),
billing: None,
},
&stage_scope,
);
Ok(Candidate {
id: best_id,
status: outcome.status.to_string(),
score: 0.0,
timing,
})
}
Ok(CodergenResult::Text { text, timing, .. }) => {
emitter.emit_scoped(
&Event::PromptCompleted {
node_id: node_id.to_string(),
response: text.clone(),
model: String::new(),
provider: String::new(),
billing: None,
},
&stage_scope,
);
// The LLM responded with text; try to find a matching candidate ID
let text = text.trim().to_string();
let empty_vec = vec![];
let arr = results.as_array().unwrap_or(&empty_vec);
// Check if the response text matches any candidate ID
for v in arr {
if let Some(id) = v.get("id").and_then(|v| v.as_str()) {
if text.contains(id) {
let status = v
.get("status")
.and_then(|v| v.as_str())
.unwrap_or("succeeded")
.to_string();
let score = v
.get("score")
.and_then(serde_json::Value::as_f64)
.unwrap_or(0.0);
return Ok(Candidate {
id: id.to_string(),
status,
score,
timing,
});
}
}
}
// No match found; fall back to heuristic
let mut fallback = heuristic_select(results);
fallback.timing = timing;
Ok(fallback)
}
Err(_) => {
// LLM call failed; fall back to heuristic
Ok(heuristic_select(results))
}
}
));
outcome
}
#[cfg(test)]
mod tests {
use fabro_graphviz::graph::AttrValue;
use fabro_types::StageTiming;
use tempfile::TempDir;
use super::*;
use crate::handler::agent::{CodergenResult, CodergenRunRequest, OneShotRequest};
use crate::outcome::StageOutcome;
fn make_services() -> EngineServices {
EngineServices::test_default()
}
#[tokio::test]
async fn fan_in_no_results() {
let handler = FanInHandler::new(None);
let node = Node::new("fan_in");
let context = Context::new();
let graph = Graph::new("test");
let run_dir = Path::new("/tmp/test");
let outcome = handler
.execute(&node, &context, &graph, run_dir, &make_services())
.await
.unwrap();
assert_eq!(outcome.status, StageOutcome::Failed {
retry_requested: false,
});
}
#[tokio::test]
async fn fan_in_selects_best() {
let handler = FanInHandler::new(None);
let node = Node::new("fan_in");
fn context_with_results() -> Context {
let context = Context::new();
context.set(
keys::PARALLEL_RESULTS,
serde_json::json!([
{"id": "branch_a", "status": "failed"},
{"id": "branch_b", "status": "succeeded"},
{
"id": "branch_a",
"status": "failed",
"context_updates": {"command.output": "failure details"}
},
{
"id": "branch_b",
"status": "succeeded",
"context_updates": {"response.branch_b": "complete response"}
}
]),
);
let graph = Graph::new("test");
let run_dir = Path::new("/tmp/test");
context
}
let outcome = handler
.execute(&node, &context, &graph, run_dir, &make_services())
#[tokio::test]
async fn promptless_fan_in_is_a_noop_barrier() {
let outcome = FanInHandler::new(None)
.execute(
&Node::new("fan_in"),
&context_with_results(),
&Graph::new("test"),
Path::new("/tmp/test"),
&make_services(),
)
.await
.unwrap();
assert_eq!(outcome.status, StageOutcome::Succeeded);
assert_eq!(
outcome.context_updates.get(keys::PARALLEL_FAN_IN_BEST_ID),
Some(&serde_json::json!("branch_b"))
);
assert_eq!(outcome.notes.as_deref(), Some("Joined 2 parallel branches"));
assert!(outcome.context_updates.is_empty());
}
#[tokio::test]
async fn fan_in_lexical_tiebreak() {
let handler = FanInHandler::new(None);
let node = Node::new("fan_in");
async fn fan_in_requires_typed_parallel_results() {
let context = Context::new();
context.set(
keys::PARALLEL_RESULTS,
serde_json::json!([
{"id": "c", "status": "succeeded"},
{"id": "a", "status": "succeeded"},
{"id": "b", "status": "succeeded"},
]),
);
let graph = Graph::new("test");
let run_dir = Path::new("/tmp/test");
let missing = FanInHandler::new(None)
.execute(
&Node::new("fan_in"),
&context,
&Graph::new("test"),
Path::new("/tmp/test"),
&make_services(),
)
.await;
assert!(missing.is_err());
let outcome = handler
.execute(&node, &context, &graph, run_dir, &make_services())
.await
.unwrap();
assert_eq!(
outcome.context_updates.get(keys::PARALLEL_FAN_IN_BEST_ID),
Some(&serde_json::json!("a"))
);
}
#[test]
fn status_rank_ordering() {
assert!(status_rank("succeeded") < status_rank("partially_succeeded"));
assert!(status_rank("partially_succeeded") < status_rank("failed"));
assert!(status_rank("failed") < status_rank("unknown"));
context.set(keys::PARALLEL_RESULTS, serde_json::json!([{"id": "a"}]));
let invalid = FanInHandler::new(None)
.execute(
&Node::new("fan_in"),
&context,
&Graph::new("test"),
Path::new("/tmp/test"),
&make_services(),
)
.await;
assert!(invalid.is_err());
}
#[tokio::test]
async fn fan_in_no_backend_ignores_prompt() {
// When there's a prompt but no backend, it should fall back to heuristic
let handler = FanInHandler::new(None);
let mut node = Node::new("fan_in");
node.attrs.insert(
"prompt".to_string(),
fabro_graphviz::graph::AttrValue::String("Pick the best branch".to_string()),
);
let context = Context::new();
context.set(
keys::PARALLEL_RESULTS,
serde_json::json!([
{"id": "branch_a", "status": "succeeded"},
{"id": "branch_b", "status": "failed"},
]),
);
let graph = Graph::new("test");
let run_dir = Path::new("/tmp/test");
let outcome = handler
.execute(&node, &context, &graph, run_dir, &make_services())
.await
.unwrap();
assert_eq!(outcome.status, StageOutcome::Succeeded);
// Should still pick branch_a via heuristic (success beats fail)
assert_eq!(
outcome.context_updates.get(keys::PARALLEL_FAN_IN_BEST_ID),
Some(&serde_json::json!("branch_a"))
);
}
#[tokio::test]
async fn fan_in_with_backend_llm_eval() {
use tempfile::TempDir;
use crate::handler::agent::{CodergenBackend, CodergenRunRequest};
struct MockBackend;
async fn prompted_fan_in_uses_standard_prompt_response_fields() {
struct ReducerBackend;
#[async_trait]
impl CodergenBackend for MockBackend {
impl CodergenBackend for ReducerBackend {
async fn run(&self, _request: CodergenRunRequest<'_>) -> Result<CodergenResult, Error> {
// Return text that contains the ID "branch_b"
panic!("prompted fan-in must use one_shot like a standard prompt")
}
async fn one_shot(&self, request: OneShotRequest<'_>) -> Result<CodergenResult, Error> {
assert!(request.prompt.contains("Synthesize every result"));
Ok(CodergenResult::Text {
text: "The best candidate is branch_b".to_string(),
text: "combined result".to_string(),
usage: None,
files_touched: Vec::new(),
last_file_touched: None,
timing: StageTiming::default(),
timing: StageTiming::new(0, 20, 30),
})
}
}
let handler = FanInHandler::new(Some(Box::new(MockBackend)));
let handler = FanInHandler::new(Some(Box::new(ReducerBackend)));
let mut node = Node::new("fan_in");
node.attrs.insert(
"prompt".to_string(),
fabro_graphviz::graph::AttrValue::String("Pick the best branch".to_string()),
AttrValue::String("Synthesize every result".to_string()),
);
let context = Context::new();
context.set(
keys::PARALLEL_RESULTS,
serde_json::json!([
{"id": "branch_a", "status": "succeeded"},
{"id": "branch_b", "status": "succeeded"},
]),
);
let graph = Graph::new("test");
let tmp = TempDir::new().unwrap();
let run_dir = TempDir::new().unwrap();
let outcome = handler
.execute(&node, &context, &graph, tmp.path(), &make_services())
.execute(
&node,
&context_with_results(),
&Graph::new("test"),
run_dir.path(),
&make_services(),
)
.await
.unwrap();
assert_eq!(outcome.status, StageOutcome::Succeeded);
// LLM chose branch_b
assert_eq!(
outcome.context_updates.get(keys::PARALLEL_FAN_IN_BEST_ID),
Some(&serde_json::json!("branch_b"))
outcome.context_updates.get(&keys::response_key("fan_in")),
Some(&serde_json::json!("combined result"))
);
}
#[tokio::test]
async fn fan_in_with_backend_copies_llm_timing_to_outcome() {
use tempfile::TempDir;
use crate::handler::agent::{CodergenBackend, CodergenRunRequest};
struct TimingBackend;
#[async_trait]
impl CodergenBackend for TimingBackend {
async fn run(&self, _request: CodergenRunRequest<'_>) -> Result<CodergenResult, Error> {
Ok(CodergenResult::Text {
text: "branch_b".to_string(),
usage: None,
files_touched: Vec::new(),
last_file_touched: None,
timing: StageTiming::new(0, 200, 300),
})
}
}
let handler = FanInHandler::new(Some(Box::new(TimingBackend)));
let mut node = Node::new("fan_in");
node.attrs.insert(
"prompt".to_string(),
fabro_graphviz::graph::AttrValue::String("Pick the best branch".to_string()),
assert_eq!(
outcome.context_updates.get(keys::LAST_RESPONSE),
Some(&serde_json::json!("combined result"))
);
let context = Context::new();
context.set(
keys::PARALLEL_RESULTS,
serde_json::json!([
{"id": "branch_a", "status": "succeeded"},
{"id": "branch_b", "status": "succeeded"},
]),
);
let graph = Graph::new("test");
let tmp = TempDir::new().unwrap();
let outcome = handler
.execute(&node, &context, &graph, tmp.path(), &make_services())
.await
.unwrap();
assert_eq!(outcome.timing, Some(StageTiming::new(0, 200, 300)));
}
#[tokio::test]
async fn fan_in_all_fail_returns_fail() {
let handler = FanInHandler::new(None);
let node = Node::new("fan_in");
let context = Context::new();
context.set(
keys::PARALLEL_RESULTS,
serde_json::json!([
{"id": "branch_a", "status": "failed"},
{"id": "branch_b", "status": "failed"},
{"id": "branch_c", "status": "failed"},
]),
);
let graph = Graph::new("test");
let run_dir = Path::new("/tmp/test");
let outcome = handler
.execute(&node, &context, &graph, run_dir, &make_services())
.await
.unwrap();
assert_eq!(outcome.status, StageOutcome::Failed {
retry_requested: false,
});
assert_eq!(outcome.timing, Some(StageTiming::new(0, 20, 30)));
assert!(
outcome
.failure_reason()
.unwrap()
.contains("all candidates failed")
);
}
#[tokio::test]
async fn fan_in_score_tiebreak() {
let handler = FanInHandler::new(None);
let node = Node::new("fan_in");
let context = Context::new();
context.set(
keys::PARALLEL_RESULTS,
serde_json::json!([
{"id": "branch_a", "status": "succeeded", "score": 0.5},
{"id": "branch_b", "status": "succeeded", "score": 0.9},
{"id": "branch_c", "status": "succeeded", "score": 0.7},
]),
);
let graph = Graph::new("test");
let run_dir = Path::new("/tmp/test");
let outcome = handler
.execute(&node, &context, &graph, run_dir, &make_services())
.await
.unwrap();
assert_eq!(outcome.status, StageOutcome::Succeeded);
// branch_b has highest score
assert_eq!(
outcome.context_updates.get(keys::PARALLEL_FAN_IN_BEST_ID),
Some(&serde_json::json!("branch_b"))
);
}
#[tokio::test]
async fn fan_in_simulate_uses_heuristic() {
let handler = FanInHandler::new(None);
let node = Node::new("fan_in");
let context = Context::new();
context.set(
keys::PARALLEL_RESULTS,
serde_json::json!([
{"id": "branch_a", "status": "failed"},
{"id": "branch_b", "status": "succeeded"},
]),
);
let graph = Graph::new("test");
let run_dir = Path::new("/tmp/test");
let outcome = handler
.simulate(&node, &context, &graph, run_dir, &make_services())
.await
.unwrap();
assert_eq!(outcome.status, StageOutcome::Succeeded);
assert!(outcome.notes.as_deref().unwrap().contains("[Simulated]"));
assert_eq!(
outcome.context_updates.get(keys::PARALLEL_FAN_IN_BEST_ID),
Some(&serde_json::json!("branch_b"))
.context_updates
.keys()
.all(|key| !key.starts_with("parallel.fan_in.best_"))
);
}
}

95
lib/components/fabro-workflow/src/handler/manager_loop.rs
View file

@ -14,7 +14,7 @@ use tokio::time::{sleep, timeout};
use super::{EngineServices, Handler};
use crate::artifact_upload::ArtifactSink;
use crate::condition::evaluate_condition;
use crate::context::{Context, WorkflowContext, keys};
use crate::context::{Context, WorkflowContext, context_diff_public, keys};
use crate::error::Error;
use crate::operations::{ValidateInput, WorkflowInput, validate};
use crate::outcome::{Outcome, OutcomeExt, StageOutcome};
@ -133,21 +133,6 @@ fn parse_child_graph(node: &Node, services: &EngineServices) -> Result<ParsedChi
Err(Error::handler("No child workflow source".to_string()))
}
/// Compute the context diff: keys that changed or were added relative to
/// `before`.
fn context_diff(
before: &HashMap<String, serde_json::Value>,
after: &HashMap<String, serde_json::Value>,
) -> HashMap<String, serde_json::Value> {
let mut diff = HashMap::new();
for (key, value) in after {
if before.get(key) != Some(value) {
diff.insert(key.clone(), value.clone());
}
}
diff
}
#[async_trait]
impl Handler for SubWorkflowHandler {
async fn execute(
@ -273,7 +258,6 @@ impl Handler for SubWorkflowHandler {
run: child_run,
registry,
interviewer,
git_state: std::sync::RwLock::new(None),
base_env,
github_token,
inputs,
@ -298,13 +282,8 @@ impl Handler for SubWorkflowHandler {
Err(e) => return Ok(Outcome::fail_classify(format!("Child task panicked: {e}"))),
};
// Compute context diff, filtering engine-internal keys
let after_snapshot = child_final_context.snapshot();
let raw_diff = context_diff(&before_snapshot, &after_snapshot);
let diff: HashMap<String, serde_json::Value> = raw_diff
.into_iter()
.filter(|(key, _)| !keys::is_engine_internal_key(key))
.collect();
let diff =
context_diff_public(&before_snapshot, child_final_context.snapshot());
tracing::debug!(
node = %node.id,
@ -819,74 +798,6 @@ mod tests {
assert_eq!(parse_duration_str("bad"), Duration::from_secs(45));
}
#[test]
fn context_diff_detects_additions() {
let before = HashMap::new();
let mut after = HashMap::new();
after.insert("key".to_string(), serde_json::json!("value"));
let diff = context_diff(&before, &after);
assert_eq!(diff.len(), 1);
assert_eq!(diff.get("key"), Some(&serde_json::json!("value")));
}
#[test]
fn context_diff_detects_changes() {
let mut before = HashMap::new();
before.insert("key".to_string(), serde_json::json!("old"));
let mut after = HashMap::new();
after.insert("key".to_string(), serde_json::json!("new"));
let diff = context_diff(&before, &after);
assert_eq!(diff.len(), 1);
assert_eq!(diff.get("key"), Some(&serde_json::json!("new")));
}
#[test]
fn context_diff_ignores_unchanged() {
let mut before = HashMap::new();
before.insert("key".to_string(), serde_json::json!("same"));
let mut after = HashMap::new();
after.insert("key".to_string(), serde_json::json!("same"));
let diff = context_diff(&before, &after);
assert!(diff.is_empty());
}
#[test]
fn context_diff_ignores_deletions() {
let mut before = HashMap::new();
before.insert("removed".to_string(), serde_json::json!("gone"));
let after = HashMap::new();
let diff = context_diff(&before, &after);
assert!(diff.is_empty());
}
#[test]
fn context_diff_excludes_engine_internal_keys() {
let before = HashMap::new();
let mut after = HashMap::new();
after.insert("graph.goal".to_string(), serde_json::json!("child goal"));
after.insert(
"internal.run_id".to_string(),
serde_json::json!("child-run"),
);
after.insert(
"thread.main.current_node".to_string(),
serde_json::json!("exit"),
);
after.insert("current_node".to_string(), serde_json::json!("exit"));
after.insert("response.plan".to_string(), serde_json::json!("the plan"));
after.insert("review.result".to_string(), serde_json::json!("approved"));
let raw_diff = context_diff(&before, &after);
let filtered: HashMap<String, serde_json::Value> = raw_diff
.into_iter()
.filter(|(key, _)| !keys::is_engine_internal_key(key))
.collect();
assert_eq!(filtered.len(), 2);
assert!(filtered.contains_key("response.plan"));
assert!(filtered.contains_key("review.result"));
}
#[tokio::test]
async fn context_flows_parent_to_child_and_back_excludes_internals() {
struct ContextEchoHandler;

1370
lib/components/fabro-workflow/src/handler/parallel.rs
View file

File diff suppressed because it is too large Load diff

14
lib/components/fabro-workflow/src/pipeline/execute.rs
View file

@ -17,7 +17,6 @@ use crate::lifecycle::WorkflowLifecycle;
use crate::node_handler::WorkflowNodeHandler;
use crate::outcome::Outcome;
use crate::records::Checkpoint;
use crate::sandbox_git::GitState;
fn seed_context_from_checkpoint(checkpoint: Option<&Checkpoint>) -> Context {
let context = Context::new();
@ -55,19 +54,6 @@ pub async fn execute(init: Initialized) -> Executed {
let graph_arc = Arc::new(graph.clone());
let wf_graph = WorkflowGraph(Arc::clone(&graph_arc));
let git_state = run_options.git.as_ref().and_then(|git| {
let base_sha = git.base_sha.clone()?;
Some(Arc::new(GitState {
run_id: run_options.run_id,
base_sha,
run_branch: git.run_branch.clone(),
meta_branch: git.meta_branch.clone(),
checkpoint: run_options.checkpoint().clone(),
git_author: run_options.git_author(),
}))
});
engine.set_git_state(git_state);
let handler = Arc::new(WorkflowNodeHandler {
services: Arc::clone(&engine),
run_dir: run_options.run_dir.clone(),

1
lib/components/fabro-workflow/src/pipeline/initialize.rs
View file

@ -624,7 +624,6 @@ pub async fn initialize(
run: Arc::clone(&run_services),
registry,
interviewer: Arc::clone(&options.interviewer),
git_state: std::sync::RwLock::new(None),
base_env,
github_token,
inputs: options.run_options.settings.run.inputs.clone(),

54
lib/components/fabro-workflow/src/sandbox_git.rs
View file

@ -4,7 +4,6 @@ use fabro_agent::Sandbox;
use fabro_checkpoint::trailer as trailerlink;
use fabro_checkpoint::trailer::Trailer;
use fabro_sandbox::shell_quote;
use fabro_types::RunId;
use fabro_types::settings::run::RunCheckpointSettings;
use fabro_util::error::SharedError;
@ -20,17 +19,6 @@ pub struct GitCommandError {
pub source: fabro_sandbox::Error,
}
/// Captured git state for a workflow run, shared with handlers.
#[derive(Debug, Clone)]
pub struct GitState {
pub run_id: RunId,
pub base_sha: String,
pub run_branch: Option<String>,
pub meta_branch: Option<String>,
pub checkpoint: RunCheckpointSettings,
pub git_author: GitAuthor,
}
pub const GIT_REMOTE: &str =
"git -c maintenance.auto=0 -c gc.auto=0 -c commit.gpgsign=false -c tag.gpgsign=false";
@ -237,48 +225,6 @@ pub(crate) async fn git_diff_with_timeout(
}
}
/// Create a branch at a specific SHA via the sandbox.
pub async fn git_create_branch_at(sandbox: &dyn Sandbox, name: &str, sha: &str) -> bool {
let cmd = format!("{GIT_REMOTE} branch --force {name} {sha}");
matches!(
sandbox.exec_command(&cmd, 30_000, None, None, None).await,
Ok(r) if r.is_success()
)
}
/// Add a git worktree via the sandbox.
pub async fn git_add_worktree(sandbox: &dyn Sandbox, path: &str, branch: &str) -> bool {
let cmd = format!("{GIT_REMOTE} worktree add {path} {branch}");
matches!(
sandbox.exec_command(&cmd, 30_000, None, None, None).await,
Ok(r) if r.is_success()
)
}
/// Remove a git worktree via the sandbox.
pub async fn git_remove_worktree(sandbox: &dyn Sandbox, path: &str) -> bool {
let cmd = format!("{GIT_REMOTE} worktree remove --force {path}");
matches!(
sandbox.exec_command(&cmd, 30_000, None, None, None).await,
Ok(r) if r.is_success()
)
}
/// Fast-forward merge to a given SHA via the sandbox.
pub async fn git_merge_ff_only(sandbox: &dyn Sandbox, sha: &str) -> bool {
let cmd = format!("{GIT_REMOTE} merge --ff-only {sha}");
matches!(
sandbox.exec_command(&cmd, 30_000, None, None, None).await,
Ok(r) if r.is_success()
)
}
/// Remove any stale worktree at `path` (best-effort), then add a fresh one.
pub async fn git_replace_worktree(sandbox: &dyn Sandbox, path: &str, branch: &str) -> bool {
let _ = git_remove_worktree(sandbox, path).await;
git_add_worktree(sandbox, path, branch).await
}
// ── Machine-readable diff enumeration (Run Files endpoint) ─────────────────
/// Hardened git-command prefix for the Run Files endpoint.

41
lib/components/fabro-workflow/src/services.rs
View file

@ -20,7 +20,6 @@ use crate::handler::HandlerRegistry;
use crate::interview_runtime::RunInterviewBlocker;
use crate::run_metadata::{RunMetadataRuntime, RunMetadataWriterHandle};
use crate::runtime_store::RunStoreHandle;
use crate::sandbox_git::GitState;
use crate::sandbox_git_runtime::SandboxGitRuntime;
use crate::workflow_bundle::WorkflowBundle;
@ -225,26 +224,24 @@ impl RunServices {
}
/// Services available only while executing workflow nodes.
#[derive(Clone)]
pub struct EngineServices {
pub run: Arc<RunServices>,
pub registry: Arc<HandlerRegistry>,
pub interviewer: Arc<dyn Interviewer>,
/// Git state for the current run. Set via `set_git_state` at the start of
/// `execute` and read by parallel/fan-in handlers.
pub(crate) git_state: std::sync::RwLock<Option<Arc<GitState>>>,
pub run: Arc<RunServices>,
pub registry: Arc<HandlerRegistry>,
pub interviewer: Arc<dyn Interviewer>,
/// Environment variables from `[sandbox.env]` config.
pub base_env: HashMap<String, String>,
pub base_env: HashMap<String, String>,
/// GitHub token source used to inject `GITHUB_TOKEN` at the point of use.
pub github_token: Option<Arc<GitHubTokenSource>>,
pub github_token: Option<Arc<GitHubTokenSource>>,
/// Typed values from `[run.inputs]`, available to prompt templates.
pub inputs: HashMap<String, toml::Value>,
pub inputs: HashMap<String, toml::Value>,
/// When true, handlers should skip real execution and return simulated
/// results.
pub dry_run: bool,
pub dry_run: bool,
/// Manifest path of the current workflow when running from a bundle.
pub workflow_path: Option<ManifestPath>,
pub workflow_path: Option<ManifestPath>,
/// Bundled workflows available for child-workflow resolution.
pub workflow_bundle: Option<Arc<WorkflowBundle>>,
pub workflow_bundle: Option<Arc<WorkflowBundle>>,
}
impl EngineServices {
@ -252,23 +249,6 @@ impl EngineServices {
resolve_workflow_env(&self.base_env, self.github_token.as_ref()).await
}
/// Read the current git state (if any).
pub fn git_state(&self) -> Option<Arc<GitState>> {
self.git_state
.read()
.expect("git_state lock is never poisoned: no code panics while holding this lock")
.clone()
}
/// Set the git state for the current run.
pub fn set_git_state(&self, state: Option<Arc<GitState>>) {
*self
.git_state
.write()
.expect("git_state lock is never poisoned: no code panics while holding this lock") =
state;
}
/// Test-only default: empty registry and cross-phase services.
#[cfg(test)]
#[expect(
@ -343,7 +323,6 @@ impl EngineServices {
),
registry: Arc::new(HandlerRegistry::new(Box::new(start::StartHandler))),
interviewer: Arc::new(fabro_interview::AutoApproveInterviewer::engine()),
git_state: std::sync::RwLock::new(None),
base_env: HashMap::new(),
github_token: None,
inputs: HashMap::new(),

3
lib/components/fabro-workflow/src/stage_scope.rs
View file

@ -37,8 +37,7 @@ impl StageScope {
}
/// Build scope for the branch-lifecycle events emitted by the parallel
/// handler (`ParallelBranchStarted`, `ParallelBranchCompleted`, and the
/// pre-dispatch `GitCommit` for the branch worktree).
/// handler (`ParallelBranchStarted` and `ParallelBranchCompleted`).
///
/// `target_visit` is the visit count of `target_node_id` for this
/// particular branch dispatch. The parallel handler currently passes

1
lib/components/fabro-workflow/src/test_support.rs
View file

@ -256,7 +256,6 @@ async fn initialized(
),
registry: Arc::new(registry),
interviewer: Arc::new(AutoApproveInterviewer::engine()),
git_state: std::sync::RwLock::new(None),
base_env: options.env,
github_token: None,
inputs: run_options.settings.run.inputs.clone(),

230
lib/components/fabro-workflow/tests/it/daytona_integration.rs
View file

@ -35,7 +35,7 @@ use fabro_workflow::event::Emitter;
use fabro_workflow::handler::exit::ExitHandler;
use fabro_workflow::handler::start::StartHandler;
use fabro_workflow::handler::{Handler, HandlerRegistry};
use fabro_workflow::outcome::{Outcome, OutcomeExt, StageOutcome};
use fabro_workflow::outcome::{Outcome, StageOutcome};
use fabro_workflow::records::Checkpoint;
use fabro_workflow::run_options::{GitCheckpointOptions, RunOptions};
use fabro_workflow::test_support::{WorkflowRunner, test_store_dir};
@ -767,234 +767,6 @@ async fn daytona_git_checkpoint_remote_emits_events() {
env.cleanup().await.unwrap();
}
// ---------------------------------------------------------------------------
// Parallel git branching on Daytona
// ---------------------------------------------------------------------------
use fabro_workflow::handler::fan_in::FanInHandler;
use fabro_workflow::handler::parallel::ParallelHandler;
/// End-to-end: parallel branches get isolated worktrees in Daytona sandbox,
/// fan-in fast-forwards to winner.
#[fabro_macros::e2e_test(live("DAYTONA_API_KEY"), live("GITHUB_APP_PRIVATE_KEY"))]
async fn daytona_parallel_git_branching_e2e() {
let env = create_env().await;
env.initialize().await.unwrap();
let env: Arc<dyn Sandbox> = Arc::new(env);
// Install git if not available
let git_check = env
.exec_command("git --version", 10_000, None, None, None)
.await;
if git_check.as_ref().map_or(true, |r| !r.is_success()) {
let install = env
.exec_command(
"apt-get update -qq && apt-get install -y -qq git >/dev/null 2>&1",
120_000,
None,
None,
None,
)
.await
.expect("apt-get install git should not error");
assert_eq!(
install.exit_code,
Some(0),
"git install failed: {}",
install.stderr
);
}
// Set up git in the sandbox (uses existing repo from Daytona project clone)
let (run_id, base_sha, branch_name) = setup_daytona_git(&*env).await;
// Pipeline: start -> fan_out -> {branch_a, branch_b} -> fan_in -> exit
let mut graph = Graph::new("DaytonaParallelGitBranching");
graph.attrs.insert(
"goal".to_string(),
AttrValue::String("Test parallel git branching on Daytona".to_string()),
);
let mut start = Node::new("start");
start.attrs.insert(
"shape".to_string(),
AttrValue::String("Mdiamond".to_string()),
);
graph.nodes.insert("start".to_string(), start);
let mut fan_out = Node::new("fan_out");
fan_out.attrs.insert(
"shape".to_string(),
AttrValue::String("component".to_string()),
);
graph.nodes.insert("fan_out".to_string(), fan_out);
let branch_a = Node::new("branch_a");
graph.nodes.insert("branch_a".to_string(), branch_a);
let branch_b = Node::new("branch_b");
graph.nodes.insert("branch_b".to_string(), branch_b);
let mut fan_in = Node::new("fan_in");
fan_in.attrs.insert(
"shape".to_string(),
AttrValue::String("tripleoctagon".to_string()),
);
graph.nodes.insert("fan_in".to_string(), fan_in);
let mut exit_node = Node::new("exit");
exit_node.attrs.insert(
"shape".to_string(),
AttrValue::String("Msquare".to_string()),
);
graph.nodes.insert("exit".to_string(), exit_node);
graph.edges.push(Edge::new("start", "fan_out"));
graph.edges.push(Edge::new("fan_out", "branch_a"));
graph.edges.push(Edge::new("fan_out", "branch_b"));
graph.edges.push(Edge::new("branch_a", "fan_in"));
graph.edges.push(Edge::new("branch_b", "fan_in"));
graph.edges.push(Edge::new("fan_in", "exit"));
let run_tmp = tempfile::tempdir().unwrap();
let emitter = Emitter::default();
let events = Arc::new(std::sync::Mutex::new(Vec::new()));
{
let events_clone = Arc::clone(&events);
emitter.on_event(move |event| {
events_clone.lock().unwrap().push(event.clone());
});
}
let mut registry = HandlerRegistry::new(Box::new(FileWriterHandler));
registry.register("start", Box::new(StartHandler));
registry.register("exit", Box::new(ExitHandler));
registry.register("parallel", Box::new(ParallelHandler));
registry.register("parallel.fan_in", Box::new(FanInHandler::new(None)));
let engine = WorkflowRunner::new(registry, Arc::new(emitter), Arc::clone(&env));
let run_options = RunOptions {
settings: WorkflowSettings::default(),
run_dir: run_tmp.path().to_path_buf(),
cancel_token: CancellationToken::new(),
run_id,
labels: std::collections::HashMap::new(),
workflow_slug: None,
github_app: None,
base_branch: None,
display_base_sha: None,
pre_run_git: None,
fork_source_ref: None,
git: Some(GitCheckpointOptions {
base_sha: Some(base_sha),
run_branch: Some(branch_name),
meta_branch: None,
}),
};
let outcome = engine
.run(&graph, &run_options)
.await
.expect("daytona parallel pipeline should succeed");
assert_eq!(
outcome.status,
StageOutcome::Succeeded,
"pipeline failed: {:?}",
outcome.failure_reason()
);
// Verify parallel.results has head_sha for each branch
let checkpoint = load_run_checkpoint(run_tmp.path()).expect("checkpoint should load");
let parallel_results = checkpoint
.context_values
.get("parallel.results")
.expect("parallel.results should be in context");
let results_arr = parallel_results.as_array().expect("should be an array");
assert_eq!(results_arr.len(), 2, "should have 2 branch results");
// Both branches should have head_sha (40-char hex)
let has_sha = results_arr.iter().all(|v| {
v.get("head_sha")
.and_then(|v| v.as_str())
.is_some_and(|s| s.len() == 40 && s.chars().all(|c| c.is_ascii_hexdigit()))
});
assert!(has_sha, "all branches should have 40-char hex head_sha");
// Branch SHAs should differ (each branch made unique changes)
let sha_a = results_arr
.iter()
.find(|v| v.get("id").and_then(|v| v.as_str()) == Some("branch_a"))
.and_then(|v| v.get("head_sha").and_then(|v| v.as_str()))
.unwrap();
let sha_b = results_arr
.iter()
.find(|v| v.get("id").and_then(|v| v.as_str()) == Some("branch_b"))
.and_then(|v| v.get("head_sha").and_then(|v| v.as_str()))
.unwrap();
assert_ne!(sha_a, sha_b, "branch SHAs should differ");
// Verify fan_in selected a winner and set best_head_sha
let best_id = checkpoint
.context_values
.get("parallel.fan_in.best_id")
.and_then(|v| v.as_str().map(String::from))
.expect("fan_in should have selected a best_id");
assert_eq!(
best_id, "branch_a",
"heuristic should pick branch_a (lexical)"
);
let best_head_sha = checkpoint
.context_values
.get("parallel.fan_in.best_head_sha")
.and_then(|v| v.as_str().map(String::from));
assert!(
best_head_sha.is_some(),
"fan_in should have set best_head_sha"
);
// Verify winner's file exists in sandbox
let winner_check = env
.exec_command("cat branch_a.txt", 10_000, None, None, None)
.await
.expect("cat should succeed");
assert_eq!(
winner_check.exit_code,
Some(0),
"winner's file should exist"
);
assert!(
winner_check.stdout.contains("branch_a"),
"winner's file should have correct content, got: {}",
winner_check.stdout
);
// Verify events
{
let events = events.lock().unwrap();
let parallel_started: Vec<_> = events
.iter()
.filter(|e| e.event_name() == "parallel.started")
.collect();
assert_eq!(
parallel_started.len(),
1,
"should have exactly one ParallelStarted event"
);
let parallel_completed: Vec<_> = events
.iter()
.filter(|e| e.event_name() == "parallel.completed")
.collect();
assert_eq!(
parallel_completed.len(),
1,
"should have exactly one ParallelCompleted event"
);
}
env.cleanup().await.expect("Daytona cleanup should succeed");
}
// ---------------------------------------------------------------------------
// Daytona shadow commit E2E with sandbox-native metadata
// ---------------------------------------------------------------------------

23
lib/components/fabro-workflow/tests/it/git_integration.rs
View file

@ -12,10 +12,7 @@ use fabro_agent::Sandbox;
use fabro_graphviz::graph::{AttrValue, Edge, Graph, Node};
use fabro_types::{RunEvent, WorkflowSettings, fixtures};
use fabro_workflow::event::Emitter;
use fabro_workflow::git::{
add_worktree, branch_needs_push, create_branch, push_branch, push_ref, remove_worktree,
replace_worktree,
};
use fabro_workflow::git::{branch_needs_push, push_branch, push_ref};
use fabro_workflow::handler::HandlerRegistry;
use fabro_workflow::handler::exit::ExitHandler;
use fabro_workflow::handler::start::StartHandler;
@ -169,22 +166,6 @@ fn test_run_options(run_dir: &Path) -> RunOptions {
}
}
#[test]
fn replace_worktree_replaces_stale() {
let dir = tempfile::tempdir().unwrap();
init_repo(dir.path());
create_branch(dir.path(), "stale-branch").unwrap();
let wt_path = dir.path().join("stale-wt");
add_worktree(dir.path(), &wt_path, "stale-branch").unwrap();
assert!(wt_path.join(".git").exists());
replace_worktree(dir.path(), &wt_path, "stale-branch").unwrap();
assert!(wt_path.join(".git").exists());
remove_worktree(dir.path(), &wt_path).unwrap();
}
#[test]
fn push_ref_to_bare_remote() {
let dir = tempfile::tempdir().unwrap();
@ -195,7 +176,7 @@ fn push_ref_to_bare_remote() {
init_repo(&repo_dir);
add_origin(&repo_dir, &remote_dir);
create_branch(&repo_dir, "test-push").unwrap();
rename_branch(&repo_dir, "test-push");
let url = format!("file://{}", remote_dir.display());
push_ref(&repo_dir, &url, "refs/heads/test-push").unwrap();

249
lib/components/fabro-workflow/tests/it/integration.rs
View file

@ -10051,7 +10051,7 @@ async fn artifact_pointers_rewritten_for_remote_sandbox() {
}
#[tokio::test]
async fn downstream_local_execution_materializes_blob_refs_to_runtime_files() {
async fn downstream_local_execution_resolves_response_blob_refs_as_text() {
let mut graph = make_graph_with_start_exit("ArtifactMaterializeLocal");
graph.attrs.insert(
"goal".to_string(),
@ -10114,31 +10114,19 @@ async fn downstream_local_execution_materializes_blob_refs_to_runtime_files() {
.expect("pipeline should succeed");
assert_eq!(outcome.status, StageOutcome::Succeeded);
let expected_blob_id = fabro_types::RunBlobId::new(
&serde_json::to_vec(&serde_json::json!("x".repeat(150 * 1024)))
.expect("large value should serialize"),
);
let captured_value = captured.lock().unwrap().first().cloned().unwrap();
let expected_path = RunScratch::new(dir.path())
.runtime_dir()
.join("blobs")
.join(format!("{expected_blob_id}.json"));
assert_eq!(
captured_value,
format!("file://{}", expected_path.display()),
"downstream handlers should receive a local file ref"
assert_eq!(captured_value, "x".repeat(150 * 1024));
assert!(
!RunScratch::new(dir.path())
.runtime_dir()
.join("blobs")
.exists(),
"textual response values should resolve without file materialization"
);
let artifact_content = std::fs::read_to_string(&expected_path).expect("should read artifact");
let artifact_value: serde_json::Value =
serde_json::from_str(&artifact_content).expect("should parse artifact JSON");
let artifact_str = artifact_value
.as_str()
.expect("artifact should be a string");
assert_eq!(artifact_str.len(), 150 * 1024);
}
#[tokio::test]
async fn downstream_remote_execution_materializes_blob_refs_to_sandbox_files() {
async fn downstream_remote_execution_resolves_response_blob_refs_as_text() {
let mut graph = make_graph_with_start_exit("ArtifactMaterializeRemote");
graph.attrs.insert(
"goal".to_string(),
@ -10202,27 +10190,11 @@ async fn downstream_remote_execution_materializes_blob_refs_to_sandbox_files() {
.expect("pipeline should succeed");
assert_eq!(outcome.status, StageOutcome::Succeeded);
let expected_blob_id = fabro_types::RunBlobId::new(
&serde_json::to_vec(&serde_json::json!("x".repeat(150 * 1024)))
.expect("large value should serialize"),
);
let captured_value = captured.lock().unwrap().first().cloned().unwrap();
assert_eq!(
captured_value,
format!("file:///sandbox/.fabro/blobs/{expected_blob_id}.json"),
"downstream handlers should receive a sandbox-local file ref"
);
let written = remote_env.written.lock().unwrap();
assert_eq!(written.len(), 1, "should materialize the blob once");
assert_eq!(
written[0].0,
format!("/sandbox/.fabro/blobs/{expected_blob_id}.json")
);
assert_eq!(captured_value, "x".repeat(150 * 1024));
assert!(
written[0].1.len() > 100 * 1024,
"written content should be >100KB, got {} bytes",
written[0].1.len()
remote_env.written.lock().unwrap().is_empty(),
"textual response values should resolve without sandbox file materialization"
);
}
@ -10361,7 +10333,7 @@ use fabro_workflow::handler::fan_in::FanInHandler;
use fabro_workflow::handler::parallel::ParallelHandler;
/// A handler that writes a file named `{node_id}.txt` into the sandbox's
/// working directory. Used to verify git worktree isolation in parallel
/// working directory. Used to verify shared-checkout writes from parallel
/// branches.
struct FileWriterHandler;
@ -10709,18 +10681,13 @@ async fn git_checkpoint_host_skips_metadata_branch_without_writer_prereqs() {
}
// ---------------------------------------------------------------------------
// Host e2e: parallel git branching with worktree isolation
// Host e2e: shared-checkout parallel execution
// ---------------------------------------------------------------------------
/// End-to-end: parallel branches get isolated worktrees, fan-in fast-forwards
/// to winner.
///
/// Pipeline: start -> fan_out -> {branch_a, branch_b} -> fan_in -> exit
///
/// Each branch writes a unique file. After fan-in, only the winner's file
/// should be present in the main worktree.
/// End-to-end: parallel branches write to one shared checkout and normal
/// run-level checkpointing captures all branch changes after the parallel node.
#[tokio::test]
async fn parallel_git_branching_host_e2e() {
async fn parallel_shared_checkout_host_e2e() {
// 1. Create a temporary git repo with an initial commit
let repo = tempfile::tempdir().unwrap();
std::process::Command::new("git")
@ -10828,10 +10795,7 @@ async fn parallel_git_branching_host_e2e() {
registry.register("start", Box::new(StartHandler));
registry.register("exit", Box::new(ExitHandler));
registry.register("parallel", Box::new(ParallelHandler));
registry.register(
"parallel.fan_in",
Box::new(FanInHandler::new(None)), // heuristic select — picks branch_a (lexical tiebreak)
);
registry.register("parallel.fan_in", Box::new(FanInHandler::new(None)));
let engine = WorkflowRunner::new(registry, Arc::new(emitter), env);
@ -10865,113 +10829,107 @@ async fn parallel_git_branching_host_e2e() {
outcome.failure_reason()
);
// 6. Verify parallel.results has head_sha for each branch
// 6. Verify ordered typed results and that no fan-in selection state exists.
let checkpoint = load_run_checkpoint(run_dir.path()).expect("checkpoint should load");
let parallel_results = checkpoint
.context_values
.get("parallel.results")
.expect("parallel.results should be in context");
let results_arr = parallel_results.as_array().expect("should be an array");
assert_eq!(results_arr.len(), 2, "should have 2 branch results");
// Both branches should have head_sha
let branch_a_result = results_arr
.iter()
.find(|v| v.get("id").and_then(|v| v.as_str()) == Some("branch_a"))
.expect("branch_a result should exist");
let branch_b_result = results_arr
.iter()
.find(|v| v.get("id").and_then(|v| v.as_str()) == Some("branch_b"))
.expect("branch_b result should exist");
let sha_a = branch_a_result
.get("head_sha")
.and_then(|v| v.as_str())
.expect("branch_a should have head_sha");
let sha_b = branch_b_result
.get("head_sha")
.and_then(|v| v.as_str())
.expect("branch_b should have head_sha");
assert_eq!(sha_a.len(), 40, "SHA should be 40 hex chars");
assert_eq!(sha_b.len(), 40, "SHA should be 40 hex chars");
assert_ne!(sha_a, sha_b, "branch SHAs should differ");
// 7. Verify fan_in selected a winner and set best_head_sha
let best_id = checkpoint
.context_values
.get("parallel.fan_in.best_id")
.and_then(|v| v.as_str().map(String::from))
.expect("fan_in should have selected a best_id");
let best_head_sha = checkpoint
.context_values
.get("parallel.fan_in.best_head_sha")
.and_then(|v| v.as_str().map(String::from))
.expect("fan_in should have set best_head_sha");
// Heuristic select with both success: lexical tiebreak picks "branch_a"
let results: Vec<fabro_types::ParallelBranchResult> =
serde_json::from_value(parallel_results.clone()).expect("results should be typed");
assert_eq!(
best_id, "branch_a",
"heuristic should pick branch_a (lexical)"
results
.iter()
.map(|result| (result.id.as_str(), result.status))
.collect::<Vec<_>>(),
[
("branch_a", fabro_types::StageOutcome::Succeeded),
("branch_b", fabro_types::StageOutcome::Succeeded),
]
);
assert!(
results
.iter()
.all(|result| result.context_updates.is_empty())
);
assert!(
checkpoint
.context_values
.keys()
.all(|key| !key.starts_with("parallel.fan_in."))
);
// 8. Verify winner's file is in the main worktree, loser's is NOT
let winner_file = worktree_path.join(format!("{best_id}.txt"));
assert!(
winner_file.exists(),
"winner's file ({best_id}.txt) should exist in main worktree after ff-merge"
);
let winner_content = std::fs::read_to_string(&winner_file).unwrap();
assert!(
winner_content.contains(&format!("written by {best_id}")),
"winner's file should have correct content"
);
// 7. Both branches wrote into the one shared checkout.
for branch in ["branch_a", "branch_b"] {
let file = worktree_path.join(format!("{branch}.txt"));
assert!(
file.exists(),
"{branch} output should remain in the checkout"
);
assert_eq!(
std::fs::read_to_string(file).unwrap(),
format!("written by {branch}")
);
}
let loser_id = if best_id == "branch_a" {
"branch_b"
} else {
"branch_a"
};
let loser_file = worktree_path.join(format!("{loser_id}.txt"));
assert!(
!loser_file.exists(),
"loser's file ({loser_id}.txt) should NOT exist in main worktree"
);
// 9. Verify the main worktree HEAD matches the winner's head_sha
let main_head = {
let out = std::process::Command::new("git")
.args(["rev-parse", "HEAD"])
.current_dir(&worktree_path)
.output()
.unwrap();
String::from_utf8_lossy(&out.stdout).trim().to_string()
};
// After fan-in ff-only + engine's own checkpoint commits, HEAD should be a
// descendant of best_head_sha.
let is_ancestor = std::process::Command::new("git")
.args(["merge-base", "--is-ancestor", &best_head_sha, &main_head])
// 8. Normal run-level checkpointing captured both files together.
let committed_files = std::process::Command::new("git")
.args(["ls-tree", "-r", "--name-only", "HEAD"])
.current_dir(&worktree_path)
.output()
.unwrap();
assert!(
is_ancestor.status.success(),
"best_head_sha ({best_head_sha}) should be an ancestor of current HEAD ({main_head})"
);
assert!(committed_files.status.success());
let committed_files = String::from_utf8_lossy(&committed_files.stdout);
assert!(committed_files.lines().any(|path| path == "branch_a.txt"));
assert!(committed_files.lines().any(|path| path == "branch_b.txt"));
// 10. Verify parallel branch refs still exist (for debugging)
let branch_ref_a = format!("fabro/run/parallel/{run_id}/fan-out/pass1/branch-a");
let ref_check = std::process::Command::new("git")
.args(["rev-parse", "--verify", &branch_ref_a])
// 9. Fabro created no branch-specific refs, commits, or worktrees.
let parallel_refs = std::process::Command::new("git")
.args([
"for-each-ref",
"--format=%(refname)",
"refs/heads/fabro/run/parallel/",
])
.current_dir(repo.path())
.output()
.unwrap();
assert!(parallel_refs.status.success());
assert!(
ref_check.status.success(),
"parallel branch ref should still exist for debugging"
parallel_refs.stdout.is_empty(),
"parallel refs must not exist"
);
// 11. Verify events
let worktrees = std::process::Command::new("git")
.args(["worktree", "list", "--porcelain"])
.current_dir(repo.path())
.output()
.unwrap();
assert!(worktrees.status.success());
let worktree_count = String::from_utf8_lossy(&worktrees.stdout)
.lines()
.filter(|line| line.starts_with("worktree "))
.count();
assert_eq!(
worktree_count, 2,
"parallel branches must not add worktrees"
);
let commit_count = std::process::Command::new("git")
.args(["rev-list", "--count", &format!("{base_sha}..HEAD")])
.current_dir(&worktree_path)
.output()
.unwrap();
assert!(commit_count.status.success());
let commit_count: usize = String::from_utf8_lossy(&commit_count.stdout)
.trim()
.parse()
.unwrap();
assert!(
(1..=2).contains(&commit_count),
"only run-level parallel/fan-in checkpoints should be committed, got {commit_count}"
);
// 10. Verify lifecycle events without parallel Git/worktree events.
let events = events.lock().unwrap();
let parallel_started: Vec<_> = events
.iter()
@ -10992,6 +10950,13 @@ async fn parallel_git_branching_host_e2e() {
1,
"should have exactly one ParallelCompleted event"
);
assert!(
events.iter().all(|event| !matches!(
event.event_name(),
"git.branch" | "git.worktree.added" | "git.worktree.removed"
)),
"parallel execution must not emit Git branch or worktree lifecycle events"
);
// Cleanup
let _ = std::process::Command::new("git")

6
lib/foundation/fabro-api/build.rs
View file

@ -349,6 +349,11 @@ fn main() {
("AgentControlState", "fabro_types::AgentControlState", &[]),
("CommandTermination", "fabro_types::CommandTermination", &[]),
("StageModelUsage", "fabro_types::StageModelUsage", &[]),
(
"ParallelBranchResult",
"fabro_types::ParallelBranchResult",
&[],
),
("StageProjection", "fabro_types::StageProjection", &[]),
("PermissionLevel", "fabro_types::PermissionLevel", &[]),
(
@ -479,6 +484,7 @@ fn main() {
),
("ReasoningEffort", "fabro_model::ReasoningEffort", &[]),
("ModelFeatures", "fabro_model::ModelFeatures", &[]),
("ModelControls", "fabro_model::ModelControls", &[]),
("ModelCosts", "fabro_model::ModelCosts", &[]),
("ModelTestMode", "fabro_model::ModelTestMode", &[]),
("RunProjection", "fabro_types::RunProjection", &[]),

10
lib/foundation/fabro-api/src/lib.rs
View file

@ -20,9 +20,9 @@ pub mod types {
};
pub use fabro_environment::Environment;
pub use fabro_model::{
CostSource, Model, ModelCosts, ModelFeatures, ModelLimits, ModelRef as BillingModelRef,
ModelTestMode, Provider, ReasoningEffort, ReasoningEffortFeature, Speed as BillingSpeed,
TokenCounts as CompletionUsage,
CostSource, Model, ModelControls, ModelCosts, ModelFeatures, ModelLimits,
ModelRef as BillingModelRef, ModelTestMode, Provider, ReasoningEffort,
ReasoningEffortFeature, Speed as BillingSpeed, TokenCounts as CompletionUsage,
};
pub use fabro_types::run_event::AgentSessionActivatedProps;
pub use fabro_types::settings::run::McpHttpProtocol;
@ -52,8 +52,8 @@ pub mod types {
McpServerReplace as ReplaceMcpServerRequest, McpServerStatus, McpServerView as McpServer,
McpTransportView, Message, PairId, PairMessageId, PairMessageRecord, PairMessageRequest,
PairRecord, PairStartRequest, PairStatus, PairTarget, PairTranscriptEntry,
PairTranscriptResponse, PendingInterviewRecord, PermissionLevel, PreRunPushOutcome,
Principal, PullRequest, PullRequestDetails, PullRequestDetailsStatus,
PairTranscriptResponse, ParallelBranchResult, PendingInterviewRecord, PermissionLevel,
PreRunPushOutcome, Principal, PullRequest, PullRequestDetails, PullRequestDetailsStatus,
PullRequestDetailsUnavailableReason, PullRequestLink, PullRequestMeta, PullRequestResponse,
QuestionType, RepositoryRef, Role, Run, RunApproval, RunApprovalState, RunClientProvenance,
RunEvent, RunEventDetailContentKind, RunEventDetailResponse, RunFailure,

17
lib/foundation/fabro-api/tests/model_round_trip.rs
View file

@ -1,13 +1,15 @@
use std::any::{TypeId, type_name};
use fabro_api::types::Model as ApiModel;
use fabro_api::types::{Model as ApiModel, ModelControls as ApiModelControls};
use fabro_model::{
Model, ModelCosts, ModelFeatures, ModelLimits, ProviderId, ReasoningEffortFeature,
Model, ModelControls, ModelCosts, ModelFeatures, ModelLimits, ProviderId, ReasoningEffort,
ReasoningEffortFeature,
};
#[test]
fn model_reuses_canonical_type() {
assert_same_type::<ApiModel, Model>();
assert_same_type::<ApiModelControls, ModelControls>();
}
#[test]
@ -32,6 +34,13 @@ fn model_json_matches_openapi_shape() {
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls {
reasoning_effort: vec![
ReasoningEffort::Low,
ReasoningEffort::High,
ReasoningEffort::Max,
],
},
costs: ModelCosts {
input_cost_per_mtok: Some(5.0),
output_cost_per_mtok: Some(25.0),
@ -50,6 +59,10 @@ fn model_json_matches_openapi_shape() {
assert_eq!(json["knowledge_cutoff"], "May 2025");
assert_eq!(json["features"]["reasoning_effort"], "levels");
assert_eq!(json["features"]["prompt_cache"], true);
assert_eq!(
json["controls"]["reasoning_effort"],
serde_json::json!(["low", "high", "max"])
);
assert_eq!(json["estimated_output_tps"], 25.0);
assert_eq!(json["small_default"], true);
assert_eq!(json["configured"], true);

4
lib/foundation/fabro-api/tests/provider_id_round_trip.rs
View file

@ -2,7 +2,8 @@ use std::any::{TypeId, type_name};
use fabro_api::types::Model as ApiModel;
use fabro_model::{
Model, ModelCosts, ModelFeatures, ModelLimits, ProviderId, ReasoningEffortFeature,
Model, ModelControls, ModelCosts, ModelFeatures, ModelLimits, ProviderId,
ReasoningEffortFeature,
};
use serde_json::json;
@ -42,6 +43,7 @@ fn provider_id_json_matches_openapi_shape_through_model() {
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls::default(),
costs: ModelCosts {
input_cost_per_mtok: None,
output_cost_per_mtok: None,

59
lib/foundation/fabro-api/tests/run_event_round_trip.rs
View file

@ -250,6 +250,65 @@ fn run_event_round_trips_stage_started() {
assert_run_event_round_trip(value);
}
#[test]
fn run_event_round_trips_parallel_public_contracts() {
assert_run_event_round_trip(json!({
"id": "evt_parallel_started",
"ts": "2026-04-29T12:02:00Z",
"run_id": fixtures::RUN_1,
"event": "parallel.started",
"node_id": "fanout",
"node_label": "Fanout",
"parallel_group_id": "fanout@2",
"properties": {
"visit": 2,
"branch_count": 2
}
}));
assert_run_event_round_trip(json!({
"id": "evt_parallel_branch_completed",
"ts": "2026-04-29T12:02:01Z",
"run_id": fixtures::RUN_1,
"event": "parallel.branch.completed",
"node_id": "review_api",
"node_label": "Review API",
"parallel_group_id": "fanout@2",
"parallel_branch_id": "fanout@2:0",
"properties": {
"index": 0,
"duration_ms": 1000,
"status": "succeeded"
}
}));
assert_run_event_round_trip(json!({
"id": "evt_parallel_completed",
"ts": "2026-04-29T12:02:02Z",
"run_id": fixtures::RUN_1,
"event": "parallel.completed",
"node_id": "fanout",
"node_label": "Fanout",
"parallel_group_id": "fanout@2",
"properties": {
"visit": 2,
"duration_ms": 2000,
"success_count": 1,
"failure_count": 1,
"results": [
{
"id": "review_api",
"status": "succeeded",
"context_updates": {"response.review_api": "looks good"}
},
{
"id": "review_ux",
"status": "failed",
"context_updates": {}
}
]
}
}));
}
#[test]
fn run_event_round_trips_agent_tool_started() {
let value = json!({

25
lib/foundation/fabro-api/tests/stage_projection_round_trip.rs
View file

@ -8,8 +8,8 @@ use fabro_api::types::{
AgentToolSource as ApiAgentToolSource, AgentToolSummary as ApiAgentToolSummary,
AgentToolsAvailableProps as ApiAgentToolsAvailableProps,
McpServerProjection as ApiMcpServerProjection, McpServerStatus as ApiMcpServerStatus,
PermissionLevel as ApiPermissionLevel, SkillsProjection as ApiSkillsProjection,
StageContextWindow as ApiStageContextWindow,
ParallelBranchResult as ApiParallelBranchResult, PermissionLevel as ApiPermissionLevel,
SkillsProjection as ApiSkillsProjection, StageContextWindow as ApiStageContextWindow,
StageContextWindowBreakdownItem as ApiStageContextWindowBreakdownItem,
StageContextWindowCategory as ApiStageContextWindowCategory,
StageContextWindowCountMethod as ApiStageContextWindowCountMethod,
@ -23,8 +23,8 @@ use fabro_api::types::{
use fabro_types::{
ActivatedSkill, AgentControlState, AgentMcpToolSummary, AgentSkillActivationSource,
AgentSkillSummary, AgentToolCategory, AgentToolSource, AgentToolSummary,
AgentToolsAvailableProps, McpServerProjection, McpServerStatus, PermissionLevel,
SkillsProjection, StageContextWindow, StageContextWindowBreakdownItem,
AgentToolsAvailableProps, McpServerProjection, McpServerStatus, ParallelBranchResult,
PermissionLevel, SkillsProjection, StageContextWindow, StageContextWindowBreakdownItem,
StageContextWindowCategory, StageContextWindowCountMethod, StageContextWindowProjection,
StageContextWindowStaleness, StageContextWindowUnavailableReason, StageContextWindowWarning,
StageProjection, SubAgentProjection, SubAgentStatus, TodoListKind, TodoListProjection,
@ -39,6 +39,7 @@ fn stage_projection_reuses_canonical_type() {
#[test]
fn stage_projection_reuses_nested_agent_state_types() {
assert_same_type::<ApiAgentControlState, AgentControlState>();
assert_same_type::<ApiParallelBranchResult, ParallelBranchResult>();
assert_same_type::<ApiTodoListProjection, TodoListProjection>();
assert_same_type::<ApiSubAgentProjection, SubAgentProjection>();
assert_same_type::<ApiSubAgentStatus, SubAgentStatus>();
@ -87,7 +88,21 @@ fn stage_projection_round_trips_representative_json() {
"diff": "diff --git a/file b/file",
"script_invocation": { "command": "cargo test" },
"script_timing": { "duration_ms": 42 },
"parallel_results": [{ "branch": 0, "status": "succeeded" }],
"parallel_results": [
{
"id": "review_api",
"status": "succeeded",
"context_updates": {
"response.review_api": "looks good",
"score": 0.95
}
},
{
"id": "review_ux",
"status": "failed",
"context_updates": {}
}
],
"output": "ok",
"termination": "exited",
"started_at": "2026-04-29T12:34:00Z",

321
lib/foundation/fabro-model/src/catalog.rs
View file

@ -15,7 +15,9 @@ use crate::codec::CodecKind;
use crate::ids::{ModelId, ProviderId};
use crate::provider::Provider;
use crate::reasoning::ReasoningEffort;
use crate::types::{Model, ModelCosts, ModelFeatures, ModelLimits, ReasoningEffortFeature};
use crate::types::{
Model, ModelControls, ModelCosts, ModelFeatures, ModelLimits, ReasoningEffortFeature,
};
#[derive(RustEmbed)]
#[folder = "src/catalog/providers"]
@ -2228,6 +2230,9 @@ fn build_model(
training: settings.training.clone(),
knowledge_cutoff: settings.knowledge_cutoff.clone(),
features: model_features,
controls: ModelControls {
reasoning_effort: controls.reasoning_effort.clone(),
},
costs,
estimated_output_tps: settings.estimated_output_tps,
aliases: settings.aliases.clone().unwrap_or_default(),
@ -3324,6 +3329,12 @@ enabled = true
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls {
reasoning_effort: [
High,
XHigh,
],
},
costs: ModelCosts {
input_cost_per_mtok: Some(
0.784,
@ -3394,6 +3405,13 @@ enabled = true
cache_control_breakpoints: false,
sampling_params: false,
},
controls: ModelControls {
reasoning_effort: [
Low,
High,
Max,
],
},
costs: ModelCosts {
input_cost_per_mtok: Some(
3.0,
@ -3469,6 +3487,264 @@ enabled = true
}
}
#[test]
fn builtin_fireworks_provider_is_opt_in() {
let fireworks = ProviderId::new("fireworks");
let builtin = Catalog::builtin();
assert!(builtin.provider(&fireworks).is_none());
assert!(builtin.list(Some(&fireworks)).is_empty());
let catalog = Catalog::from_builtin_with_overrides(&minimal_settings(
r"
[providers.fireworks]
enabled = true
",
))
.expect("enabled Fireworks override should build from the built-in provider settings");
let provider = catalog
.provider(&fireworks)
.expect("enabled Fireworks provider should be present");
assert_eq!(provider.adapter, AdapterKind::OpenAiCompatible);
assert_eq!(provider.codec, CodecKind::OpenAiCompatible);
assert_eq!(
provider.base_url.as_deref(),
Some("https://api.fireworks.ai/inference/v1")
);
assert_eq!(provider.billing_policy, BillingPolicy::OpenAi);
assert_eq!(provider.priority, 30);
assert_eq!(provider.auth.as_ref().unwrap().credentials, vec![
CredentialRef::Env("FIREWORKS_API_KEY".to_string()),
CredentialRef::Vault("FIREWORKS_API_KEY".to_string()),
]);
assert_eq!(
catalog
.default_for_provider(&fireworks)
.map(|model| model.id.as_str()),
Some("kimi-k2.7-code")
);
assert_eq!(
catalog
.small_default_for_provider(&fireworks)
.map(|model| model.id.as_str()),
Some("gpt-oss-20b")
);
assert_eq!(
catalog
.probe_for_provider(&fireworks)
.map(|model| model.id.as_str()),
Some("gpt-oss-20b")
);
}
#[test]
fn builtin_fireworks_models_when_enabled() {
let fireworks = ProviderId::new("fireworks");
let catalog = Catalog::from_builtin_with_overrides(&minimal_settings(
r"
[providers.fireworks]
enabled = true
",
))
.expect("enabled Fireworks override should build from the built-in provider settings");
// (id, api_id, family, context_window, max_output, vision, reasoning,
// input, output, cache_read)
let expected = [
(
"kimi-k2.7-code",
"accounts/fireworks/models/kimi-k2p7-code",
"kimi-k2",
262_144,
32_768,
true,
true,
0.95,
4.0,
0.19,
),
(
"kimi-k2.6",
"accounts/fireworks/models/kimi-k2p6",
"kimi-k2",
262_144,
16_384,
false,
false,
0.95,
4.0,
0.16,
),
(
"deepseek-v4-pro",
"accounts/fireworks/models/deepseek-v4-pro",
"deepseek-v4",
1_048_576,
16_384,
false,
true,
1.74,
3.48,
0.145,
),
(
"deepseek-v4-flash",
"accounts/fireworks/models/deepseek-v4-flash",
"deepseek-v4",
1_048_576,
16_384,
false,
false,
0.14,
0.28,
0.028,
),
(
"glm-5.2",
"accounts/fireworks/models/glm-5p2",
"glm-5",
1_048_576,
131_072,
false,
true,
1.4,
4.4,
0.14,
),
(
"minimax-m2.7",
"accounts/fireworks/models/minimax-m2p7",
"minimax-m2",
196_608,
16_384,
false,
false,
0.3,
1.2,
0.059,
),
(
"qwen3.7-plus",
"accounts/fireworks/models/qwen3p7-plus",
"qwen3",
262_144,
16_384,
true,
false,
0.4,
1.6,
0.08,
),
(
"gpt-oss-120b",
"accounts/fireworks/models/gpt-oss-120b",
"gpt-oss",
131_072,
32_768,
false,
true,
0.15,
0.6,
0.015,
),
(
"gpt-oss-20b",
"accounts/fireworks/models/gpt-oss-20b",
"gpt-oss",
131_072,
32_768,
false,
true,
0.07,
0.3,
0.035,
),
];
let mut model_ids: Vec<&str> = catalog
.list(Some(&fireworks))
.iter()
.map(|model| model.id.as_str())
.collect();
model_ids.sort_unstable();
let mut expected_ids: Vec<&str> = expected.iter().map(|row| row.0).collect();
expected_ids.sort_unstable();
assert_eq!(
model_ids, expected_ids,
"expected rows must cover every Fireworks model"
);
for (
id,
api_id,
family,
context,
max_output,
vision,
reasoning,
input,
output,
cache_read,
) in expected
{
let model = catalog
.get_on_provider(&fireworks, id)
.unwrap_or_else(|| panic!("Fireworks model '{id}' should be present"));
assert_eq!(model.family, family, "{id}");
assert_eq!(model.limits.context_window, context, "{id}");
assert_eq!(model.limits.max_output, Some(max_output), "{id}");
assert!(model.features.tools, "{id}");
assert_eq!(model.features.vision, vision, "{id}");
assert_eq!(model.features.reasoning, reasoning, "{id}");
assert!(model.features.prompt_cache, "{id}");
assert_eq!(model.costs.input_cost_per_mtok, Some(input), "{id}");
assert_eq!(model.costs.output_cost_per_mtok, Some(output), "{id}");
assert_eq!(
model.costs.cache_input_cost_per_mtok,
Some(cache_read),
"{id}"
);
let settings = catalog
.model_settings_on_provider(&fireworks, id)
.unwrap_or_else(|| panic!("Fireworks settings for '{id}' should be present"));
assert_eq!(settings.api_id, api_id, "{id}");
assert_eq!(settings.billing_policy, BillingPolicy::OpenAi, "{id}");
}
}
#[test]
fn builtin_fireworks_shared_slugs_are_portable_with_openrouter() {
let catalog = Catalog::from_builtin_with_overrides(&minimal_settings(
r"
[providers.fireworks]
enabled = true
[providers.openrouter]
enabled = true
",
))
.expect("enabled Fireworks and OpenRouter overrides should build");
for provider in [ProviderId::new("fireworks"), ProviderId::new("openrouter")] {
for id in [
"kimi-k2.6",
"deepseek-v4-pro",
"deepseek-v4-flash",
"glm-5.2",
"minimax-m2.7",
] {
let model = catalog
.get_on_provider(&provider, id)
.unwrap_or_else(|| panic!("'{id}' should resolve on provider '{provider}'"));
assert_eq!(model.id, id, "{provider}/{id}");
assert_eq!(model.provider, provider, "{provider}/{id}");
}
}
}
#[test]
fn builtin_ollama_provider_is_opt_in() {
let ollama = ProviderId::new("ollama");
@ -6018,6 +6294,15 @@ sampling_params = false
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls {
reasoning_effort: [
Low,
Medium,
High,
XHigh,
Max,
],
},
costs: ModelCosts {
input_cost_per_mtok: Some(
5.0,
@ -6075,6 +6360,9 @@ sampling_params = false
cache_control_breakpoints: false,
sampling_params: false,
},
controls: ModelControls {
reasoning_effort: [],
},
costs: ModelCosts {
input_cost_per_mtok: Some(
0.6,
@ -6124,6 +6412,13 @@ sampling_params = false
cache_control_breakpoints: false,
sampling_params: false,
},
controls: ModelControls {
reasoning_effort: [
Low,
High,
Max,
],
},
costs: ModelCosts {
input_cost_per_mtok: Some(
3.0,
@ -6197,6 +6492,12 @@ sampling_params = false
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls {
reasoning_effort: [
High,
Max,
],
},
costs: ModelCosts {
input_cost_per_mtok: Some(
1.4,
@ -6267,6 +6568,15 @@ sampling_params = false
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls {
reasoning_effort: [
Low,
Medium,
High,
XHigh,
Max,
],
},
costs: ModelCosts {
input_cost_per_mtok: Some(
0.25,
@ -6324,6 +6634,15 @@ sampling_params = false
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls {
reasoning_effort: [
Low,
Medium,
High,
XHigh,
Max,
],
},
costs: ModelCosts {
input_cost_per_mtok: Some(
30.0,

211
lib/foundation/fabro-model/src/catalog/providers/fireworks.toml Normal file
View file

@ -0,0 +1,211 @@
[providers.fireworks]
display_name = "Fireworks AI"
adapter = "openai_compatible"
api_key_url = "https://app.fireworks.ai/settings/users/api-keys"
base_url = "https://api.fireworks.ai/inference/v1"
priority = 30
enabled = false
[providers.fireworks.auth]
credentials = ["env:FIREWORKS_API_KEY", "vault:FIREWORKS_API_KEY"]
# To enable Fireworks, add the following to ~/.fabro/settings.toml:
#
# [llm.providers.fireworks]
# enabled = true
#
# Then run `fabro provider login --provider fireworks` to store the API key,
# or set the FIREWORKS_API_KEY environment variable.
#
# api_id values use Fireworks account-scoped paths; dots in upstream model
# names become "p" (glm-5.2 -> glm-5p2). `GET /v1/models` only returns a
# featured subset of serverless models, so validate api_ids against
# /chat/completions, not the models list.
#
# Prompt caching is automatic prefix caching (no cache_control breakpoints);
# serverless responses report prompt_tokens_details.cached_tokens in the
# usage body. Costs below are from docs.fireworks.ai/serverless/pricing
# (standard tier), verified 2026-07-24.
[providers.fireworks.models."kimi-k2.7-code"]
api_id = "accounts/fireworks/models/kimi-k2p7-code"
display_name = "Kimi K2.7 Code"
family = "kimi-k2"
default = true
[providers.fireworks.models."kimi-k2.7-code".limits]
context_window = 262144
max_output = 32768
[providers.fireworks.models."kimi-k2.7-code".features]
tools = true
vision = true
reasoning = true
prompt_cache = true
[providers.fireworks.models."kimi-k2.7-code".costs]
input_cost_per_mtok = 0.95
output_cost_per_mtok = 4.0
cache_input_cost_per_mtok = 0.19
[providers.fireworks.models."kimi-k2.6"]
api_id = "accounts/fireworks/models/kimi-k2p6"
display_name = "Kimi K2.6"
family = "kimi-k2"
[providers.fireworks.models."kimi-k2.6".limits]
context_window = 262144
max_output = 16384
[providers.fireworks.models."kimi-k2.6".features]
tools = true
vision = false
reasoning = false
prompt_cache = true
[providers.fireworks.models."kimi-k2.6".costs]
input_cost_per_mtok = 0.95
output_cost_per_mtok = 4.0
cache_input_cost_per_mtok = 0.16
[providers.fireworks.models."deepseek-v4-pro"]
api_id = "accounts/fireworks/models/deepseek-v4-pro"
display_name = "DeepSeek V4 Pro"
family = "deepseek-v4"
[providers.fireworks.models."deepseek-v4-pro".limits]
context_window = 1048576
max_output = 16384
[providers.fireworks.models."deepseek-v4-pro".features]
tools = true
vision = false
reasoning = true
prompt_cache = true
[providers.fireworks.models."deepseek-v4-pro".costs]
input_cost_per_mtok = 1.74
output_cost_per_mtok = 3.48
cache_input_cost_per_mtok = 0.145
[providers.fireworks.models."deepseek-v4-flash"]
api_id = "accounts/fireworks/models/deepseek-v4-flash"
display_name = "DeepSeek V4 Flash"
family = "deepseek-v4"
[providers.fireworks.models."deepseek-v4-flash".limits]
context_window = 1048576
max_output = 16384
[providers.fireworks.models."deepseek-v4-flash".features]
tools = true
vision = false
reasoning = false
prompt_cache = true
[providers.fireworks.models."deepseek-v4-flash".costs]
input_cost_per_mtok = 0.14
output_cost_per_mtok = 0.28
cache_input_cost_per_mtok = 0.028
[providers.fireworks.models."glm-5.2"]
api_id = "accounts/fireworks/models/glm-5p2"
display_name = "GLM 5.2 (via Fireworks)"
family = "glm-5"
[providers.fireworks.models."glm-5.2".limits]
context_window = 1048576
max_output = 131072
[providers.fireworks.models."glm-5.2".features]
tools = true
vision = false
reasoning = true
prompt_cache = true
[providers.fireworks.models."glm-5.2".costs]
input_cost_per_mtok = 1.4
output_cost_per_mtok = 4.4
cache_input_cost_per_mtok = 0.14
[providers.fireworks.models."minimax-m2.7"]
api_id = "accounts/fireworks/models/minimax-m2p7"
display_name = "MiniMax M2.7"
family = "minimax-m2"
[providers.fireworks.models."minimax-m2.7".limits]
context_window = 196608
max_output = 16384
[providers.fireworks.models."minimax-m2.7".features]
tools = true
vision = false
reasoning = false
prompt_cache = true
[providers.fireworks.models."minimax-m2.7".costs]
input_cost_per_mtok = 0.3
output_cost_per_mtok = 1.2
cache_input_cost_per_mtok = 0.059
[providers.fireworks.models."qwen3.7-plus"]
api_id = "accounts/fireworks/models/qwen3p7-plus"
display_name = "Qwen3.7 Plus"
family = "qwen3"
[providers.fireworks.models."qwen3.7-plus".limits]
context_window = 262144
max_output = 16384
[providers.fireworks.models."qwen3.7-plus".features]
tools = true
vision = true
reasoning = false
prompt_cache = true
[providers.fireworks.models."qwen3.7-plus".costs]
input_cost_per_mtok = 0.4
output_cost_per_mtok = 1.6
cache_input_cost_per_mtok = 0.08
[providers.fireworks.models."gpt-oss-120b"]
api_id = "accounts/fireworks/models/gpt-oss-120b"
display_name = "GPT-OSS 120B"
family = "gpt-oss"
[providers.fireworks.models."gpt-oss-120b".limits]
context_window = 131072
max_output = 32768
[providers.fireworks.models."gpt-oss-120b".features]
tools = true
vision = false
reasoning = true
prompt_cache = true
[providers.fireworks.models."gpt-oss-120b".costs]
input_cost_per_mtok = 0.15
output_cost_per_mtok = 0.6
cache_input_cost_per_mtok = 0.015
[providers.fireworks.models."gpt-oss-20b"]
api_id = "accounts/fireworks/models/gpt-oss-20b"
display_name = "GPT-OSS 20B"
family = "gpt-oss"
small_default = true
probe = true
[providers.fireworks.models."gpt-oss-20b".limits]
context_window = 131072
max_output = 32768
[providers.fireworks.models."gpt-oss-20b".features]
tools = true
vision = false
reasoning = true
prompt_cache = true
[providers.fireworks.models."gpt-oss-20b".costs]
input_cost_per_mtok = 0.07
output_cost_per_mtok = 0.3
cache_input_cost_per_mtok = 0.035

4
lib/foundation/fabro-model/src/lib.rs
View file

@ -27,4 +27,6 @@ pub use model_ref::ModelHandle;
pub use model_test::ModelTestMode;
pub use provider::Provider;
pub use reasoning::ReasoningEffort;
pub use types::{Model, ModelCosts, ModelFeatures, ModelLimits, ReasoningEffortFeature};
pub use types::{
Model, ModelControls, ModelCosts, ModelFeatures, ModelLimits, ReasoningEffortFeature,
};

14
lib/foundation/fabro-model/src/types.rs
View file

@ -1,6 +1,7 @@
use serde::{Deserialize, Serialize};
use crate::ids::{ModelId, ProviderId};
use crate::reasoning::ReasoningEffort;
// --- 2.9 Model ---
@ -83,6 +84,14 @@ pub struct ModelCosts {
pub cache_input_cost_per_mtok: Option<f64>,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ModelControls {
/// Exact reasoning-effort values accepted by this provider/model offering.
/// An empty list means the request control is unsupported.
#[serde(default)]
pub reasoning_effort: Vec<ReasoningEffort>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Model {
pub id: ModelId,
@ -93,6 +102,10 @@ pub struct Model {
pub training: Option<String>,
pub knowledge_cutoff: Option<String>,
pub features: ModelFeatures,
/// Required in API responses; defaulted on deserialization so newer
/// clients tolerate older servers that predate this field.
#[serde(default)]
pub controls: ModelControls,
pub costs: ModelCosts,
pub estimated_output_tps: Option<f64>,
pub aliases: Vec<String>,
@ -236,6 +249,7 @@ mod tests {
cache_control_breakpoints: false,
sampling_params: true,
},
controls: ModelControls::default(),
costs: ModelCosts {
input_cost_per_mtok: Some(1.0),
output_cost_per_mtok: Some(2.0),

2
lib/foundation/fabro-static/src/env_vars.rs
View file

@ -48,6 +48,7 @@ impl EnvVars {
pub const BEDROCK_API_KEY: &'static str = "BEDROCK_API_KEY";
pub const BRAVE_SEARCH_API_KEY: &'static str = "BRAVE_SEARCH_API_KEY";
pub const CHATGPT_ACCOUNT_ID: &'static str = "CHATGPT_ACCOUNT_ID";
pub const FIREWORKS_API_KEY: &'static str = "FIREWORKS_API_KEY";
pub const GEMINI_API_KEY: &'static str = "GEMINI_API_KEY";
pub const GEMINI_BASE_URL: &'static str = "GEMINI_BASE_URL";
pub const GOOGLE_API_KEY: &'static str = "GOOGLE_API_KEY";
@ -195,6 +196,7 @@ mod tests {
EnvVars::BEDROCK_API_KEY,
EnvVars::BRAVE_SEARCH_API_KEY,
EnvVars::CHATGPT_ACCOUNT_ID,
EnvVars::FIREWORKS_API_KEY,
EnvVars::GEMINI_API_KEY,
EnvVars::GEMINI_BASE_URL,
EnvVars::GOOGLE_API_KEY,

2
lib/foundation/fabro-static/src/secret_registry.rs
View file

@ -21,6 +21,7 @@ const OPTIONAL_VAULT_SECRETS: &[&str] = &[
EnvVars::BRAVE_SEARCH_API_KEY,
EnvVars::FABRO_SLACK_APP_TOKEN,
EnvVars::FABRO_SLACK_BOT_TOKEN,
EnvVars::FIREWORKS_API_KEY,
EnvVars::GEMINI_API_KEY,
EnvVars::GITHUB_APP_CLIENT_SECRET,
EnvVars::GITHUB_APP_PRIVATE_KEY,
@ -91,6 +92,7 @@ mod tests {
EnvVars::ANTHROPIC_API_KEY,
EnvVars::AWS_BEARER_TOKEN_BEDROCK,
EnvVars::BEDROCK_API_KEY,
EnvVars::FIREWORKS_API_KEY,
EnvVars::GEMINI_API_KEY,
EnvVars::INCEPTION_API_KEY,
EnvVars::KIMI_API_KEY,

2
lib/foundation/fabro-types/src/lib.rs
View file

@ -19,6 +19,7 @@ pub mod manifest_path;
pub mod mcp_store;
pub mod outcome;
pub mod pair;
pub mod parallel;
pub mod principal;
pub mod pull_request;
pub mod repository;
@ -93,6 +94,7 @@ pub use pair::{
PairTranscriptWarning, RunEventDetailContent, RunEventDetailContentKind,
RunEventDetailEnvelope, RunEventDetailResponse, RunPairStatusResponse,
};
pub use parallel::ParallelBranchResult;
pub use principal::{AuthMethod, Principal, SystemActorKind, UserPrincipal};
pub use pull_request::{
CheckRun, CheckRunStatus, PullRequest, PullRequestDetails, PullRequestDetailsStatus,

14
lib/foundation/fabro-types/src/parallel.rs Normal file
View file

@ -0,0 +1,14 @@
use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use crate::StageOutcome;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ParallelBranchResult {
pub id: String,
pub status: StageOutcome,
#[serde(default)]
pub context_updates: BTreeMap<String, Value>,
}

1
lib/foundation/fabro-types/src/run_event/infra.rs
View file

@ -30,7 +30,6 @@ pub enum RunNoticeCode {
GitPushFailed,
GithubTokenFailed,
GithubTokenRefreshLimited,
ParallelBaseCheckpointFailed,
PullRequestFailed,
SandboxCleanupFailed,
SandboxGitUnavailable,

Some files were not shown because too many files have changed in this diff Show more