feat(flows): select per-node models and session config options - #844

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

Codex review: blocked before merge.

What this changes

This PR adds per-node model and ordered session-option selection to ACP flows, with run defaults and persistent-session replay.

Example: A Codex flow node requests modelId gpt-6-luna and reasoning_effort medium.

• Before: Flow nodes cannot declare these selections before their first prompt.
• After: The runtime selects the model, applies medium effort, and then prompts; later nodes sharing the handle inherit those settings.

Review scores

Product

Kind: Feature · Worth it: Needs a maintainer decision · Fix scope: Complete
User problem: Flow authors cannot choose a node's model and adapter options before its first turn.
Reason: The capability has clear workflow value and follows the earlier compatibility direction, but the new persistent-handle contract lacks recorded approval.

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep this PR open: it adds a capability missing from main and resolves the previous compatibility finding; the persistent-handle settings contract still needs a maintainer decision.

Priority: P2
Reviewed head: 034221c0fe8e7d5357519a58d466bbc9fb6a0e95
Owner decision: Required. See Decision needed.

Decision needed

• Question: Should a persistent flow handle pin its first effective settings, inherit omitted selections, and reject later conflicting explicit selections?
• Recommendation: Approve settings pinned per handle: Keep the proposed inheritance, conflict checks, and replay contract; flows needing different settings use distinct handles.
• Why: The earlier maintainer discussion supports a distinct validated model field, but neither it nor discussion on this PR settles pinning versus changing settings between turns.

Before merge

• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

None.

Tests

• Low-value test test/cli-flags.test.ts: Remove the added helper-level description assertions: they repeat the supplied description and pin incidental wording, while CLI integration coverage exercises repeatable option parsing.

flowchart TD
A[Flow definition and CLI defaults] --> B[Flow runner]
B --> C[Session settings and binding]
C --> D[Shared session configuration]
D --> E[ACP adapter]
E --> F[Prompt result]
C --> G[Run bundle]
F --> G

Reviewed October 16, 2026, 3:06 PM ET / 19:06 UTC (Revision 7).

Real-adapter proof on head 18c2a9487d7dce8931e3283332678c505f688c7b, using the built CLI with the official @agentclientprotocol/codex-acp 1.1.14 adapter. HOME and CODEX_HOME point to a scratch directory, and the adapter runs in a sandbox that mounts only the auth file (read-only).

Flow (proof.flow.mjs) — one isolated node, then two persistent nodes on the same handle; the third declares no settings:

import { acp, defineFlow } from "acpx/flows";
const settings = { model: "gpt-6-luna", configOptions: [{ configId: "reasoning_effort", value: "medium" }] };
export default defineFlow({
  name: "node-settings-proof",
  startAt: "isolated",
  nodes: {
    isolated: acp({ ...settings, session: { isolated: true }, prompt: () => "Reply with exactly: ONE" }),
    first: acp({ ...settings, session: { handle: "pinned" }, prompt: () => "Reply with exactly: TWO" }),
    reconnect: acp({ session: { handle: "pinned" }, prompt: () => "Reply with exactly: THREE" }),
  },
  edges: [{ from: "isolated", to: "first" }, { from: "first", to: "reconnect" }],
});

$ node dist/cli.js --cwd "$SCRATCH/workspace" --deny-all --format json --timeout 180 flow run proof.flow.mjs --default-agent codex
exit 0
"status":"completed", "outputs":{"isolated":"ONE","first":"TWO","reconnect":"THREE"}

The adapter's defaults are gpt-6.1-sol at low effort. The run requests gpt-6-luna at medium.

Isolated node: first turn. Excerpt from sessions/isolated-*/events.ndjson: non-update messages only, config catalogs trimmed to model and reasoning_effort, prompt receipts reduced to stopReason and _meta.quota.model_usage[].model.

{"id": 1, "method": "session/new", "params": {"_meta": {"claudeCode": {"options": {"model": "gpt-6-luna"}}}}}
{"id": 1, "result": {"configOptions": [{"id": "model", "currentValue": "gpt-6.1-sol"}, {"id": "reasoning_effort", "currentValue": "low"}]}}
{"id": 2, "method": "session/set_config_option", "params": {"sessionId": "01a0f398-3e9b-78d0-bb61-5a09207862a7", "configId": "model", "value": "gpt-6-luna"}}
{"id": 2, "result": {"configOptions": [{"id": "model", "currentValue": "gpt-6-luna"}, {"id": "reasoning_effort", "currentValue": "low"}]}}
{"id": 3, "method": "session/set_config_option", "params": {"sessionId": "01a0f398-3e9b-78d0-bb61-5a09207862a7", "configId": "reasoning_effort", "value": "medium"}}
{"id": 3, "result": {"configOptions": [{"id": "model", "currentValue": "gpt-6-luna"}, {"id": "reasoning_effort", "currentValue": "medium"}]}}
{"id": 4, "method": "session/prompt", "params": {"sessionId": "01a0f398-3e9b-78d0-bb61-5a09207862a7", "prompt": [{"type": "text", "text": "Reply with exactly: ONE"}]}}
{"id": 4, "result": {"stopReason": "end_turn", "model_usage": ["gpt-6-luna"]}}

Persistent handle pinned: first turn and reconnect. Excerpt from sessions/pinned-*/events.ndjson, using the same filter. As documented, the controls sent when the persistent session was created are not in events.ndjson; binding.json (below) records them. The node reconnect declares no settings. It resumes the same ACP session, which comes back at the adapter defaults, restores the pinned model and effort, and only then prompts:

{"id": 4, "method": "session/prompt", "params": {"sessionId": "01a0f398-5544-7ab0-940b-32d48aaa916f", "prompt": [{"type": "text", "text": "Reply with exactly: TWO"}]}}
{"id": 4, "result": {"stopReason": "end_turn", "model_usage": ["gpt-6-luna"]}}
{"id": 1, "method": "session/resume", "params": {"sessionId": "01a0f398-5544-7ab0-940b-32d48aaa916f", "_meta": {"claudeCode": {"options": {"model": "gpt-6-luna"}}}}}
{"id": 1, "result": {"configOptions": [{"id": "model", "currentValue": "gpt-6.1-sol"}, {"id": "reasoning_effort", "currentValue": "low"}]}}
{"id": 2, "method": "session/set_config_option", "params": {"sessionId": "01a0f398-5544-7ab0-940b-32d48aaa916f", "configId": "model", "value": "gpt-6-luna"}}
{"id": 2, "result": {"configOptions": [{"id": "model", "currentValue": "gpt-6-luna"}, {"id": "reasoning_effort", "currentValue": "low"}]}}
{"id": 3, "method": "session/set_config_option", "params": {"sessionId": "01a0f398-5544-7ab0-940b-32d48aaa916f", "configId": "reasoning_effort", "value": "medium"}}
{"id": 3, "result": {"configOptions": [{"id": "model", "currentValue": "gpt-6-luna"}, {"id": "reasoning_effort", "currentValue": "medium"}]}}
{"id": 4, "method": "session/prompt", "params": {"sessionId": "01a0f398-5544-7ab0-940b-32d48aaa916f", "prompt": [{"type": "text", "text": "Reply with exactly: THREE"}]}}
{"id": 4, "result": {"stopReason": "end_turn", "model_usage": ["gpt-6-luna"]}}

sessions/pinned-*/binding.json (settings fields):

{
  "handle": "pinned",
  "acpSessionId": "01a0f398-5544-7ab0-940b-32d48aaa916f",
  "requestedSettings": { "model": "gpt-6-luna", "configOptions": [{ "configId": "reasoning_effort", "value": "medium" }] },
  "acceptedSettings": {
    "model": { "requested": "gpt-6-luna", "applied": true, "accepted": "gpt-6-luna" },
    "configOptions": [{ "configId": "reasoning_effort", "value": "medium", "acceptedValue": "medium", "reported": true }]
  }
}

In the two excerpts, every prompt runs on gpt-6-luna, and each prompt is preceded by an adapter-reported reasoning_effort of medium where the adapter default is low. That covers the first turns (the isolated session and the persistent session's creation controls, recorded in binding.json) and the resumed session. This adapter's prompt receipt reports the model but not the effort, so effort evidence is the adapter's config-option reply.

On the persistent-handle contract and global --model: a conflict requires a node to set model or configOptions explicitly, and those fields do not exist on main. With global --model only, every node on a handle resolves the same requested model, so no existing flow can hit the new conflict error. The only visible change for those runs is the additive requestedSettings / acceptedSettings keys in the bundle. Pinning was chosen so that a reconnect has one well-defined state to restore; a different configuration uses a different session.handle.

_{@superbiche · contributor · drafted with Claude Opus 5.5.}

On the option-value finding: ACP session config options are select (the value is one of the IDs the adapter advertises, like medium or gpt-6-luna) or boolean. The schema has no free-text option type, so a value cannot carry a secret. main already stores the same values in plain text: session records keep them in acpx.desired_config_options, fed by exec --config-option (#533), and bundle events.ndjson records the raw session/set_config_option messages. The new fields repeat values acpx already stores. I'd rather not add redaction for catalog IDs; if you want the flow JSON result slimmer, I can drop the settings fields from stdout and keep them in the bundle.

@clawsweeper re-review

_{@superbiche · contributor · drafted with Claude Opus 5.5, reviewed before posting; the voice and decisions are mine.}

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/36766682993
• Updated: 2026-09-30T19:35:21.211Z

@clawsweeper re-review

Please review current head 034221c0fe8e7d5357519a58d466bbc9fb6a0e95; the existing checklist still names 9aecae5. This revision preserves legacy model metadata, adds explicit modelId selection and upgrade regressions, and resolves the merge conflict. All current CI jobs pass. The PR body retains the evidence limits; the persistent-handle pinning contract still needs a maintainer decision.

_{@superbiche · contributor · drafted with GPT-6.1 Sol.}

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/38952656564
• Updated: 2026-10-16T19:08:41.922Z

Landed as ba09c49.

Approved per-node model/configuration selection and first-settings pinning for persistent handles. Integrated main with only a changelog conflict repair, preserving the reviewed feature patch and contributor ancestry. Reviewed head 72a84bc; full code and docs CI passed all 12 jobs: https://github.com/openclaw/acpx/actions/runs/41210298168.

Thanks @superbiche!