Named multi-agent / per-agent model support in the TS authoring surface

docs/SURFACE.md

@@ -255,11 +255,23 @@ No process runs between events: the handler wakes, executes to its next await, p
 
    **Project-config discovery:** starting in the flow file's directory, `flows check` walks parent directories through the filesystem root and selects the first readable `flows.json`. That nearest file is the whole project config; it is not merged with outer files. Its schema is `{ "cli"?: <non-empty string>, "executors"?: <non-empty string>[], "models"?: <trimmed model string>[], "mcp"?: <server map> }`; unknown keys, malformed model entries, and duplicates fail closed as `config_invalid`. A nearer config therefore defines a self-contained nested project boundary and prevents accidental inheritance of outer credentials, executors, or model approvals. The selected path is printed with project-level resolutions and named in refusals; if it declares no `cli` or models, outer configs remain shadowed. At gate 1, a trigger executor is considered registered only when its name is present in this author-written `executors` array; `flows check` does not yet contact a registry, broker, or RelayCron, and absence is `no_executor`.
 
-   Implementation status for issue #132: this named-agent contract currently
-   ships in the canonical declarative YAML/JSON compiler. Matching
-   `FlowHeader.agents` TypeScript types depend on the separately reviewed,
-   unmerged `@relayflows/surface` package in PR #134 and are a follow-on after
-   that package lands; this compiler slice does not duplicate that package.
+   Implementation status for issue #132: this named-agent contract ships for
+   both dialects. `@relayflows/surface`'s `FlowHeader.agents` (a
+   `Record<string, { cli, model }>`) declares the same named-agent map in
+   TypeScript; `authored-flow-agents.ts` lowers `f.agent(name, options)` by selecting
+   a declared entry by matching `name` against it (falling through to the
+   project CLI default when `name` matches nothing, so existing calls
+   that use `name` only for step-id readability are unaffected), and
+   `options.cli`/`options.model` are step-level overrides with the same
+   highest-priority resolution as the declarative dialect's inline
+   `cli`/`model` step fields. Both dialects share the same underlying
+   `FlowSpec.agents` / preflight resolution (`packages/sdk/src/preflight.ts`,
+   `compile.ts`) — this is one contract compiled from two front ends, not two
+   separate implementations.
+   Every TS header declaration is checked before the body runs, including
+   unused agents. Within one execution, successful readiness probes are reused
+   for the same CLI path, base directory, and model; overriding either field
+   checks the resulting pair. Project configuration is captured for that execution.
 7. **Two dialects, one journal.** Declarative YAML — data, fully preflightable, sage's compile target, gate 9's self-authoring output. Imperative TS — journal-memoized function, maximum ergonomics. YAML is canonical; TS is the power tool. TS preflights its declared surface (agents, helpers, tools, identity), not arbitrary control flow — declared honestly per covenant 2.
 
 ### Structured output declarations

docs/evidence/pr-sweep-0917/remediation-245-retry.md

@@ -0,0 +1,138 @@
+# PR #245 remediation retry — 2026-09-17
+
+## Daemon preparation
+
+Literal command:
+
+```sh
+cd packages/sdk && PATH=/Users/khaliqgant/.cargo/bin:$PATH npm run test:prep
+```
+
+Captured output:
+
+```text
+> @relayflows/sdk@2.0.14 test:prep
+> ( cd ../../kernel && sh ../ops/cargo.sh build ) && ( [ ! -d ../../testdata/preflight ] || find ../../testdata/preflight -name '*-cli' -type f -exec chmod +x {} + )
+
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.22s
+```
+
+Literal worktree-key derivation command:
+
+```sh
+printf %s "$PWD" | cksum
+```
+
+Captured output:
+
+```text
+1580583111 84
+```
+
+The resulting live-suite binary path is
+`/Users/khaliqgant/.relayflows-toolchain/target/1580583111/debug/relayflowd`.
+
+## Surface build and type tests
+
+Literal command:
+
+```sh
+cd packages/surface && npm run build && npm run typecheck && npm run typecheck:regressions && npm run typecheck:examples && npx vitest run tests/flow.test.ts
+```
+
+Captured output:
+
+```text
+> @relayflows/surface@2.0.14 build
+> tsc
+
+> @relayflows/surface@2.0.14 typecheck
+> tsc --noEmit
+
+> @relayflows/surface@2.0.14 typecheck:regressions
+> tsc -p ../../regressions/tsconfig.json && tsc -p tsconfig.test.json && node scripts/check-generated-helpers.mjs
+
+HELPERS_GENERATED_OK airtable.ts, asana.ts, azure-blob.ts, box.ts, calendly.ts, clickup.ts, clients.ts, cloudflare.ts, confluence.ts, daytona.ts, docker-hub.ts, dropbox.ts, fathom.ts, gcp.ts, gcs.ts, github.ts, gitlab.ts, gmail.ts, google-calendar.ts, google-drive.ts, granola.ts, hubspot.ts, index.ts, intercom.ts, jira.ts, linear.ts, mailgun.ts, mixpanel.ts, neon.ts, notion.ts, onedrive.ts, pipedrive.ts, postgres.ts, posthog.ts, providers.ts, ramp.ts, recall.ts, reddit.ts, redis.ts, s3.ts, salesforce.ts, segment.ts, sendgrid.ts, sharepoint.ts, shopify.ts, shortcut.ts, slack.ts, stripe.ts, teams.ts, telegram.ts, webhook-server.ts, x.ts, zendesk.ts
+
+> @relayflows/surface@2.0.14 typecheck:examples
+> tsc -p ../../examples/tsconfig.json
+
+ RUN  v2.1.9 /Volumes/Paris Drive/AgentWorkforce/.worktrees/flows-v2-lead-0913/pr-remediation-245/packages/surface
+
+ ✓ tests/flow.test.ts (24 tests) 5ms
+
+ Test Files  1 passed (1)
+      Tests  24 passed (24)
+   Start at  17:31:42
+   Duration  341ms (transform 88ms, setup 0ms, collect 85ms, tests 5ms, environment 0ms, prepare 87ms)
+```
+
+## SDK build and typechecks
+
+Literal command:
+
+```sh
+cd packages/sdk && npm run build && npm run typecheck && npm run typecheck:tests
+```
+
+Captured output:
+
+```text
+> @relayflows/sdk@2.0.14 build
+> tsc && node scripts/make-cli-executable.mjs
+
+> @relayflows/sdk@2.0.14 typecheck
+> tsc --noEmit && tsc -p tsconfig.type-tests.json
+
+> @relayflows/sdk@2.0.14 typecheck:tests
+> tsc -p tsconfig.tests.json
+```
+
+## Focused authored and live named-agent suites
+
+Literal command:
+
+```sh
+cd packages/sdk && RELAYFLOWD_BIN=/Users/khaliqgant/.relayflows-toolchain/target/1580583111/debug/relayflowd npx vitest run tests/authored-named-agents.test.ts tests/authored-agent-failure.test.ts tests/direct-input.test.ts tests/live-named-agents.test.ts
+```
+
+Captured output:
+
+```text
+ RUN  v2.1.9 /Volumes/Paris Drive/AgentWorkforce/.worktrees/flows-v2-lead-0913/pr-remediation-245/packages/sdk
+
+ ✓ tests/authored-agent-failure.test.ts (5 tests) 6ms
+ ✓ tests/authored-named-agents.test.ts (7 tests) 669ms
+   ✓ named agent declarations > lets a step-level cli override win over the named declaration 337ms
+   ✓ named agent declarations > does not treat an unrelated f.agent name as a named-agent selector 317ms
+ ✓ tests/live-named-agents.test.ts (1 test) 1547ms
+   ✓ named agents against a live kernel > dispatches two distinct named agents declared in the flow header 1546ms
+ ✓ tests/direct-input.test.ts (7 tests) 21820ms
+   ✓ direct .flow.ts input through the built CLI and live runtime > returns exit 3 for an authored human handoff and persists its outcome 1435ms
+   ✓ direct .flow.ts input through the built CLI and live runtime > returns exit 1 for an authored step_failed verdict and persists its outcome 858ms
+   ✓ direct .flow.ts input through the built CLI and live runtime > executes inline and file JSON input through relayflowd 2547ms
+   ✓ direct .flow.ts input through the built CLI and live runtime > refuses missing and malformed input before contacting relayflowd 2623ms
+   ✓ direct .flow.ts input through the built CLI and live runtime > surfaces the specific preflight refusal kind for an unresolved f.agent, not a generic invalid_spec 12740ms
+   ✓ direct .flow.ts input through the built CLI and live runtime > does not run the authored body before daemon availability 815ms
+   ✓ direct .flow.ts input through the built CLI and live runtime > refuses oversized file input before contacting relayflowd 800ms
+
+ Test Files  4 passed (4)
+      Tests  20 passed (20)
+   Start at  17:31:58
+   Duration  22.09s (transform 367ms, setup 0ms, collect 1.83s, tests 24.04s, environment 0ms, prepare 215ms)
+```
+
+## Diff whitespace check
+
+Literal command:
+
+```sh
+git diff --check
+```
+
+Captured output:
+
+```text
+```
+
+The command exited 0 with no output.

docs/evidence/pr-sweep-0917/remediation-245.md

@@ -0,0 +1,187 @@
+# PR #245 remediation — 2026-09-17
+
+## Remote-head guard
+
+Initial literal command:
+
+```sh
+git fetch origin main refs/pull/245/head && git ls-remote origin 'refs/pull/245/head'
+```
+
+Captured output:
+
+```text
+From github.com:AgentWorkforce/flows
+ * branch              main       -> FETCH_HEAD
+ * branch              refs/pull/245/head -> FETCH_HEAD
+   c8c68315..45417541  main       -> origin/main
+b88244113be0ca330b01871fdd0588ac483e5f59	refs/pull/245/head
+```
+
+Sweep-baseline lookup command:
+
+```sh
+rg -n --hidden --glob '!node_modules' 'PR #245|feat/ts-named-agents|b88244113be0ca330b01871fdd0588ac483e5f59' docs/evidence . 2>/dev/null || true
+```
+
+Captured matching sweep evidence:
+
+```text
+docs/evidence/pr-sweep-0917/inventory.md:30:| #245 | `b88244113be0ca330b01871fdd0588ac483e5f59` | khaliqgant | no | CONFLICTING | none | 0 | decision 13 authoring surface; **fix_required** (conflict; review FAILURE). |
+```
+
+The fetched remote head equals the sweep baseline: `b88244113be0ca330b01871fdd0588ac483e5f59`.
+
+## Rebase
+
+Literal command:
+
+```sh
+git rebase origin/main
+```
+
+Captured result:
+
+```text
+Rebasing (1/2)
+CONFLICT (content): Merge conflict in packages/relayflows/package-lock.json
+CONFLICT (content): Merge conflict in packages/relayflows/package.json
+CONFLICT (content): Merge conflict in packages/runtime-darwin-arm64/package.json
+CONFLICT (content): Merge conflict in packages/runtime-linux-x64/package.json
+CONFLICT (content): Merge conflict in packages/sdk/package-lock.json
+CONFLICT (content): Merge conflict in packages/sdk/package.json
+CONFLICT (content): Merge conflict in packages/sdk/src/authored-flow-executor.ts
+CONFLICT (content): Merge conflict in packages/sdk/src/cli/check.ts
+CONFLICT (content): Merge conflict in packages/sdk/src/cli/direct-run.ts
+CONFLICT (content): Merge conflict in packages/sdk/src/preflight.ts
+CONFLICT (content): Merge conflict in packages/surface/package-lock.json
+CONFLICT (content): Merge conflict in packages/surface/package.json
+CONFLICT (content): Merge conflict in packages/surface/src/context.ts
+CONFLICT (content): Merge conflict in packages/surface/src/flow.ts
+```
+
+Resolution retained current-main package versions and authored worker/preflight paths, then integrated the named-agent declaration map, per-step CLI/model overrides, up-front declaration preflight, and causal runtime diagnostics. Generated package locks were regenerated from the resolved manifests.
+
+## Validation
+
+Surface command (the package script first failed because `bun` is unavailable; this equivalent uses the installed Node tooling):
+
+```sh
+cd packages/surface && npm run build && npx tsc -p tsconfig.test.json && npx vitest run tests/flow.test.ts
+```
+
+Captured output:
+
+```text
+> @relayflows/surface@2.0.14 build
+> tsc
+
+ RUN  v2.1.9 /Volumes/Paris Drive/AgentWorkforce/.worktrees/flows-v2-lead-0913/pr-remediation-245/packages/surface
+
+ ✓ tests/flow.test.ts (24 tests) 5ms
+
+ Test Files  1 passed (1)
+      Tests  24 passed (24)
+```
+
+SDK command:
+
+```sh
+cd packages/sdk && npm run build && npx vitest run tests/authored-named-agents.test.ts tests/authored-agent-failure.test.ts tests/direct-input.test.ts
+```
+
+Captured output:
+
+```text
+> @relayflows/sdk@2.0.14 build
+> tsc && node scripts/make-cli-executable.mjs
+
+ RUN  v2.1.9 /Volumes/Paris Drive/AgentWorkforce/.worktrees/flows-v2-lead-0913/pr-remediation-245/packages/sdk
+
+ ✓ tests/authored-agent-failure.test.ts (5 tests) 5ms
+ ✓ tests/authored-named-agents.test.ts (7 tests) 474ms
+ ✓ tests/direct-input.test.ts (7 tests) 22781ms
+
+ Test Files  3 passed (3)
+      Tests  19 passed (19)
+```
+
+SDK typecheck command:
+
+```sh
+cd packages/sdk && npm run typecheck && npm run typecheck:tests
+```
+
+Captured output:
+
+```text
+> @relayflows/sdk@2.0.14 typecheck
+> tsc --noEmit && tsc -p tsconfig.type-tests.json
+
+> @relayflows/sdk@2.0.14 typecheck:tests
+> tsc -p tsconfig.tests.json
+```
+
+The live named-agent suite is not green in this environment. Literal command:
+
+```sh
+cd packages/sdk && npx vitest run tests/live-named-agents.test.ts
+```
+
+Captured output:
+
+```text
+ RUN  v2.1.9 /Volumes/Paris Drive/AgentWorkforce/.worktrees/flows-v2-lead-0913/pr-remediation-245/packages/sdk
+
+ FAIL  tests/live-named-agents.test.ts [ tests/live-named-agents.test.ts ]
+Error: Build this checkout's daemon and set RELAYFLOWD_BIN to it: /Volumes/Paris Drive/AgentWorkforce/.worktrees/flows-v2-lead-0913/pr-remediation-245/kernel/target/debug/relayflowd
+
+ Test Files  1 failed (1)
+      Tests  1 skipped (1)
+```
+
+Its documented preparation command also cannot run because the environment has no Rust compiler:
+
+```sh
+cd packages/sdk && npm run test:prep
+```
+
+Captured output:
+
+```text
+> @relayflows/sdk@2.0.14 test:prep
+> ( cd ../../kernel && sh ../ops/cargo.sh build ) && ( [ ! -d ../../testdata/preflight ] || find ../../testdata/preflight -name '*-cli' -type f -exec chmod +x {} + )
+
+error: could not execute process `rustc -vV` (never executed)
+
+Caused by:
+  No such file or directory (os error 2)
+```
+
+Because this required affected suite is blocked and not green, this remediation must not update the remote PR branch.
+
+## Final remote-head guard and update
+
+Final literal command (run even though no push is allowed):
+
+```sh
+git fetch origin refs/pull/245/head && git ls-remote origin 'refs/pull/245/head' && git rev-parse HEAD && git status --short --branch
+```
+
+Captured output:
+
+```text
+From github.com:AgentWorkforce/flows
+ * branch              refs/pull/245/head -> FETCH_HEAD
+b88244113be0ca330b01871fdd0588ac483e5f59	refs/pull/245/head
+2ea87580b5dd6cd1c7d420ce5961c0ccd6f5e97a
+## feat/ts-named-agents...origin/feat/ts-named-agents [ahead 88, behind 2]
+ M packages/sdk/src/authored-worker-step.ts
+ M packages/sdk/src/cli/check-typescript.ts
+ M packages/sdk/src/cli/check.ts
+ M packages/sdk/src/preflight.ts
+ M packages/surface/src/flow.ts
+?? docs/evidence/pr-sweep-0917/
+```
+
+The remote PR head still equals the sweep head. The last committed local remediation SHA and exact branch head are `2ea87580b5dd6cd1c7d420ce5961c0ccd6f5e97a`. The worktree deliberately remains uncommitted and the remote branch was not updated: the required live named-agent suite is not green in this environment.

docs/evidence/pr245/README.md

@@ -0,0 +1,38 @@
+# PR 245 verification (2026-09-10)
+
+The recorded commands and complete outputs are adjacent to this file.
+The full SDK run uses the daemon built from this checkout and the local
+surface 2.0.9 tarball. It preceded the final model-syntax regression; the later
+focused run includes that additional test. The subsequent review follow-up
+adds diagnostic-selection and failure-contract regressions; its captured
+build, typechecks, and seven-suite run are in `review-followup.txt`. The unchanged package gate verifies
+the 2.0.9 manifests and surface tarball with Bun 1.4.0; the host Bun 1.3.14
+cannot read the repository lockfile.
+
+A full-suite invocation from the repository root (`sdk-wrong-cwd.txt`) failed:
+six assertions depend on the SDK working directory, and one wrapper abort
+readiness assertion timed out. Running from `packages/sdk` produced the final
+output in `sdk-full.txt`, including that abort test. No tests were weakened.
+
+- `sdk-focused.txt`: named declarations, overrides, before-body refusal,
+  direct CLI refusal kinds, malformed model syntax, and declarative preflight.
+- `named-test-root-cwd.txt`: the new live suite also works from the repository
+  root without RELAYFLOWD_BIN; its fallback is relative to the test file.
+- `sdk-full.txt`: full SDK run; three provider/environment-dependent skips
+  are visible in the output.
+- `kernel-tests.txt`: full Rust workspace tests, including crash/resume tests.
+- `packed-consumer.txt`: the unchanged package gate, including surface tests,
+  TypeScript regressions, and the packed runtime and type consumers.
+
+The live named-agent test uses two distinct local wrapper executables, a real
+daemon, and a real SDK worker. It asserts CLI identity and model for both
+named selections, a combined override, model-only and CLI-only overrides,
+and one successful model probe per distinct pair. It does not claim to test
+provider service availability.
+
+For the negative control in `named-selection-mutated.txt`, the exact change
+was `{ agent: name }` -> `{ agent: Object.keys(namedAgents!)[0] }` in
+`packages/sdk/src/authored-flow-agents.ts`. The original bytes were saved,
+the live test was run and failed on fixer's returned identity/model, and the
+saved bytes were restored byte-for-byte before the passing run recorded in
+`named-selection-restored.txt`. Both command outputs and exits are included.