Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .agents/plans/19-maintainability/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Maintainability after Flow 10

Preserve Session v5, host-observed validation, independent review, exact-artifact
qualification, and resumable publication. Reduce the places a maintainer must
change to preserve those guarantees.

## First change

- Share Node, package-pinned Bun, and frozen dependency installation through
`.github/actions/setup-project`. Ordinary CI, scheduled evals, and weekly
compatibility use the same setup. Jobs keep their names, runners, triggers,
permissions, checks, and checkout policy.
- Keep conditional patch qualification, Bun-only auditing, and publication's
registry/npm setup explicit. A shared action should not need a collection of
switches for these different contracts.
- Build tool status metadata once on a fresh response object. Remove forwarding
error and reviewer wrappers and the repeated validation coordinator argument.
Keep schema parsing, mutation cancellation, reviewer-only writes, and exact
completion replay at their existing boundaries.

## Next changes, in order

1. Move duplicated candidate preparation from the two release jobs into one
tested command. Keep historical release rules and immutable artifact checks
intact; compare every supported version's old and new commands before landing.
2. Give auto-drive presentation/timing a separate owner from execution authority.
Then separate native hook registration from lifecycle decisions. Extract one
cohesive responsibility at a time, without adding a second state ledger or
passing the entire coordinator into each module.
3. Make qualification status a single read-only command derived from existing
matrix, canary, archive, and publication records. Report the next unmet gate
and whether it is offline or requires an approved model dispatch. Preserve
failed attempts and original accounting; do not infer success from exit codes.
4. Consolidate maintainer instructions around those commands. Keep historical
evidence immutable and link it rather than copying operating receipts into
additional status files.

Each follow-up should remove duplicated policy or reduce independent mutable
state, retain the original behavioral controls, and pass normal CI. File moves
alone, larger line limits, broader test timeouts, and removed safety checks do
not count as simplification. Runtime changes still follow release qualification;
this maintenance PR neither publishes a version nor starts paid evaluations.
16 changes: 16 additions & 0 deletions .github/actions/setup-project/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
name: Set up Flow project
description: Install the CI Node runtime, package-pinned Bun, and locked dependencies.
runs:
using: composite
steps:
- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 26
- name: Set up Bun
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version-file: package.json
- name: Install dependencies
shell: bash
run: bun install --frozen-lockfile
42 changes: 6 additions & 36 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -66,18 +66,8 @@ jobs:
with:
fetch-depth: 0

- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 26

- name: Set up Bun
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: 1.4.0

- name: Install dependencies
run: bun install --frozen-lockfile
- name: Set up project toolchain
uses: ./.github/actions/setup-project

- name: Run checks
run: bun run check
Expand Down Expand Up @@ -142,18 +132,8 @@ jobs:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 26

- name: Set up Bun
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: 1.4.0

- name: Install dependencies
run: bun install --frozen-lockfile
- name: Set up project toolchain
uses: ./.github/actions/setup-project

- name: Run platform filesystem checks
run: bun test tests/workspace-persistence.test.ts tests/source-identity.test.ts tests/flow-leadership.test.ts tests/test-results.test.ts tests/validation-capture.test.ts
Expand All @@ -164,18 +144,8 @@ jobs:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 26

- name: Set up Bun
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: 1.4.0

- name: Install dependencies
run: bun install --frozen-lockfile
- name: Set up project toolchain
uses: ./.github/actions/setup-project

- name: Run live OpenCode smoke
run: bun run smoke:live
Expand Down
14 changes: 2 additions & 12 deletions .github/workflows/evals.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,18 +49,8 @@ jobs:
# the job only reads the checkout, runs the eval, and uploads an artifact.
persist-credentials: false

- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 26

- name: Set up Bun
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: 1.4.0

- name: Install dependencies
run: bun install --frozen-lockfile
- name: Set up project toolchain
uses: ./.github/actions/setup-project

# Absent credentials are a configuration state, not a failure: a fork and a
# freshly cloned repository both have none, and failing the schedule there
Expand Down
14 changes: 2 additions & 12 deletions .github/workflows/opencode-compatibility.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,8 @@ jobs:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 26

- name: Set up Bun
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: 1.4.0

- name: Install dependencies
run: bun install --frozen-lockfile
- name: Set up project toolchain
uses: ./.github/actions/setup-project

- name: Resolve the latest OpenCode 2 release
run: |
Expand Down
102 changes: 32 additions & 70 deletions src/platform/opencode/tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -82,10 +82,6 @@ type ToolOptions = Readonly<{
| undefined;
}>;

function toolError(error: unknown): FlowToolResponse {
return errorResponse(error);
}

function bestEffort<Value>(read: () => Value): Value | undefined {
try {
return read();
Expand All @@ -100,56 +96,44 @@ function withAutoContext(
view?: string,
sessionID?: string,
): FlowToolResponse {
let workflowData = response.workflowData;
const reviewer =
options.readReviewerConfiguration?.() ?? options.reviewerConfiguration;
if (reviewer) {
workflowData = {
...workflowData,
reviewerConfiguration: flowReviewerStatus(reviewer),
};
}
workflowData = {
...workflowData,
const workflowData: Record<string, unknown> = {
...response.workflowData,
...(reviewer
? { reviewerConfiguration: flowReviewerStatus(reviewer) }
: {}),
modelConfiguration: flowModelStatus(
options.readPlanningModel?.(),
sessionID ? options.readCodingModel?.(sessionID) : undefined,
reviewer,
),
};
if (options.runtimeIdentity)
workflowData = {
...workflowData,
runtimeIdentity: options.runtimeIdentity,
};
workflowData.runtimeIdentity = options.runtimeIdentity;
const timing =
view === "detail"
? bestEffort(() => options.autoTimingSnapshot?.())
: undefined;
if (timing) workflowData = { ...workflowData, autoTiming: timing };
if (timing) workflowData.autoTiming = timing;
const continuation = sessionID
? bestEffort(() => options.autoContinuationSnapshot?.(sessionID))
: undefined;
if (continuation) workflowData = { ...workflowData, autoDrive: continuation };
if (continuation) workflowData.autoDrive = continuation;
const support = bestEffort(() => options.autoContinuationSupport?.());
if (support === "supported" || support === "unsupported") {
workflowData = {
...workflowData,
autoContinuation: {
scope: "current-plugin-process",
support,
...(support === "unsupported"
? {
reason: "host-request-attribution-unavailable",
recovery: "Drive each feature with /flow-run.",
}
: {}),
},
workflowData.autoContinuation = {
scope: "current-plugin-process",
support,
...(support === "unsupported"
? {
reason: "host-request-attribution-unavailable",
recovery: "Drive each feature with /flow-run.",
}
: {}),
};
}
return workflowData === response.workflowData
? response
: { ...response, workflowData };
return { ...response, workflowData };
}

export function createTools(options: ToolOptions): FlowTools {
Expand All @@ -169,27 +153,15 @@ export function createTools(options: ToolOptions): FlowTools {
),
);
} catch (error) {
return toolError(error);
return errorResponse(error);
}
}

function executeMutation<T extends FlowToolResponse>(
context: FlowToolContext,
validation: ValidationCaptureCoordinator,
handler: (flow: WorkspaceFlowService) => Promise<T>,
): Promise<FlowToolResponse> {
validation.cancel(context.sessionID);
return execute(context, handler);
}

function executeReviewerMutation<T extends FlowToolResponse>(
context: FlowToolContext,
handler: (flow: WorkspaceFlowService) => Promise<T>,
replayHandler: (flow: WorkspaceFlowService) => Promise<T>,
): Promise<FlowToolResponse> {
if (context.agent !== "flow-reviewer") {
return execute(context, replayHandler);
}
options.validation.cancel(context.sessionID);
return execute(context, handler);
}

Expand Down Expand Up @@ -247,15 +219,15 @@ export function createTools(options: ToolOptions): FlowTools {
description: "Create or replace the active draft plan.",
schema: PlanSaveInputSchema,
execute: (args, context) =>
executeMutation(context, options.validation, (workspace) =>
executeMutation(context, (workspace) =>
workspace.planSave(args, requestAuthority(context.sessionID)),
),
}),
flow_plan_approve: defineFlowTool({
description: "Approve the current draft plan.",
schema: PlanApproveInputSchema,
execute: (args, context) =>
executeMutation(context, options.validation, (workspace) =>
executeMutation(context, (workspace) =>
workspace.planApprove(args, requestAuthority(context.sessionID)),
),
}),
Expand All @@ -264,17 +236,13 @@ export function createTools(options: ToolOptions): FlowTools {
"Record a same-goal reversible prerequisite repair after a failed canonical gate, without an amendment count limit. This does not change the approved plan or bypass review.",
schema: PlanAmendInputSchema,
execute: (args, context) =>
executeMutation(context, options.validation, (workspace) =>
workspace.planAmend(args),
),
executeMutation(context, (workspace) => workspace.planAmend(args)),
}),
flow_run_start: defineFlowTool({
description: "Start one runnable approved feature.",
schema: RunStartInputSchema,
execute: (args, context) =>
executeMutation(context, options.validation, (workspace) =>
workspace.runStart(args),
),
executeMutation(context, (workspace) => workspace.runStart(args)),
}),
flow_validation_start: defineFlowTool({
description:
Expand Down Expand Up @@ -308,7 +276,7 @@ export function createTools(options: ToolOptions): FlowTools {
},
};
} catch (error) {
return toolError(error);
return errorResponse(error);
}
},
}),
Expand All @@ -317,37 +285,31 @@ export function createTools(options: ToolOptions): FlowTools {
"Create one independent review assignment using current applicable validation.",
schema: ReviewStartInputSchema,
execute: (args, context) =>
executeMutation(context, options.validation, (workspace) =>
workspace.reviewStart(args),
),
executeMutation(context, (workspace) => workspace.reviewStart(args)),
}),
flow_feature_complete: defineFlowTool({
description:
"Submit a pending review result; only the reviewer may create a new completion, while exact accepted requests remain replayable for an active Session v5 workflow.",
schema: FeatureCompleteInputSchema,
execute: (args, context) =>
executeReviewerMutation(
context,
(workspace) => workspace.featureComplete(args),
(workspace) => workspace.featureCompleteReplay(args),
execute(context, (workspace) =>
context.agent === "flow-reviewer"
? workspace.featureComplete(args)
: workspace.featureCompleteReplay(args),
),
}),
flow_feature_reset: defineFlowTool({
description:
"Reset dependents and optionally start one exact next run atomically.",
schema: FeatureResetInputSchema,
execute: (args, context) =>
executeMutation(context, options.validation, (workspace) =>
workspace.featureReset(args),
),
executeMutation(context, (workspace) => workspace.featureReset(args)),
}),
flow_session_close: defineFlowTool({
description: "Close and archive a session in one convergent operation.",
schema: SessionCloseInputSchema,
execute: (args, context) =>
executeMutation(context, options.validation, (workspace) =>
workspace.sessionClose(args),
),
executeMutation(context, (workspace) => workspace.sessionClose(args)),
}),
};
}
Expand Down
Loading
Loading