[factory] Accept a persona in relay spawn and relayflow steps, via the SDK — not a CLI shell-out

[khaliqgant]

Note: this body was rewritten after the original claim was falsified. The comments below preserve how it got here — the first version asserted personas could not be launched non-interactively at all, which is false. Read this body, not the opening comment.

The gap

A persona can be launched three ways today, and only one of them takes a persona.

Surface	Takes a persona?
agentworkforce agent <persona> (interactive TTY)	yes
Agent Relay spawn action	no — cli + free-text task + target_node
Relayflow steps	no — { name, cli, role, preset } (see relayflows/workflows/ci/fix-mcp-spawn.yaml)

So anything placed on a fleet node, or run as a workflow step, is a hand-written prompt rather than a persona.

Why that loses more than convenience

A persona is not a prompt. nango-integrations declares agentsMdContent, skills (each with a source that gets installed), mcpServers, harness, model, and harnessSettings. Pasting its text into a task string carries one of those. The spawned agent has no skills installed and no MCP server — it works from memory of a workflow the persona exists to enforce.

And it fails silently. Nothing errors. The agent runs, sounds correct, and is missing its tools. A wrong path that works badly is worse than one that fails.

The practical consequence: every remote agent is a fresh, unversioned approximation of a capability that already exists in a reviewed file, and improvements to that file never reach the fleet.

The capability already exists — this is a caller problem

@agentworkforce/deploy exports a real programmatic entrypoint:

export async function deploy(opts: DeployOptions, resolvers?: DeployResolvers): Promise<DeployResult>

plus preflightPersona, the mode launchers (devLauncher / sandboxLauncher / cloudLauncher), ModeLaunchHandle / ModeLaunchInput / ModeLauncher, and createBufferedIO. It validates declared persona inputs up front with typed errors rather than failing inside a child process.

@agentworkforce/local-surface already composes that into Agent Relay: defineWorkforcePersonaNode(options): FleetNodeDefinition, whose launchPersonaRunner calls deploy() with mode: 'dev', detach: true, bridged: true, noPrompt: true (local-surface/src/index.ts:145). The bridged flag exists specifically so the persona survives a non-interactive parent whose stdin ends.

So non-interactive, in-process persona launch is built, deliberate, and already wired to @agent-relay/fleet. What is missing is that spawn and relayflow steps do not reach for it.

Constraint — SDK surfaces only

Do not implement this by shelling out to agentworkforce agent. pear/src/main/broker.ts:2991 does exactly that, and it is not the pattern to copy. Shelling out:

• makes a CLI binary a runtime dependency of every calling host — unacceptable for an arbitrary fleet node or cloud sandbox;
• couples two release trains across a process boundary with no type checking (relayfile mount recently rejected --workspace / --local-dir, flags its own help text advertised);
• forces stdout scraping for state — pear parses readiness out of log lines with personaHarnessReadyFromOutput;
• drives a TTY-oriented command from a daemon.

Notably pear already depends on @agentworkforce/deploy and shells out anyway. The library is there; the caller reaches past it.

What done looks like

1. Agent Relay spawn accepts a persona (name or path) as an alternative to cli + task, resolved through the same registry agentworkforce uses (built-in / cwd / personal / configured dirs). harness and model come from the persona spec. A task supplied alongside layers the concrete assignment over the persona's standing instructions.
2. Relayflow steps accept a persona in place of cli + role, with the same resolution.
3. Both go through @agentworkforce/deploy / local-surface in process. No agentworkforce binary required on the node, no output parsing.
4. Launch is deduped and verified. Borrow the discipline from pear even though not its mechanism: coalesce concurrent launches of the same persona (personaSpawnRequestKey keys on project + persona; a fleet needs the node-scoped equivalent), and confirm broker registration and harness readiness before reporting success, releasing the agent if either fails. A launched process is not a running persona.
5. Discoverability. Nothing today points a caller from spawn toward defineWorkforcePersonaNode. Whatever ships, make the working path findable from the wrong one.

Cross-repo

The persona resolution and SDK live here (workforce). The spawn action lives in relay. Relayflow step schema lives in relayflows. Expect changes in more than one repo; do not merge anything — the merge gate is the principal's.

[khaliqgant]

Correcting this issue — the main claim was wrong

I filed this saying a persona cannot be launched by anything other than a human at a TTY. That is false, and I should have checked the packages in this repo before asserting it.

@agentworkforce/local-surface already exports defineWorkforcePersonaNode(options): FleetNodeDefinition — and that FleetNodeDefinition is imported from @agent-relay/fleet. A persona already runs as an Agent Relay fleet node.

Internally it calls launchPersonaRunner → deployPersona with mode: 'dev', detach: true, bridged: true, noPrompt: true (packages/local-surface/src/index.ts:145). The bridged flag exists precisely so the persona survives a non-interactive parent whose stdin ends. So a fully non-interactive, programmatic persona launch is not only possible, it is deliberately built for and commented as such.

There is also a whole persona SDK surface I overlooked: @agentworkforce/persona-kit, @agentworkforce/personas-core, and per-persona packs published to npm — including @agentworkforce/persona-nango-integrations@0.1.9, which exports the very persona JSON I hand-copied into a prompt.

So the loss I described was self-inflicted. I reached for relay's raw spawn action and pasted persona text into a task string, when the persona could have been run as a fleet node with its skills, MCP servers, harness and model intact.

What remains genuinely missing — narrower, and worth keeping

Relay's spawn action still takes only cli + free-text task + target_node. It has no persona parameter, and does not resolve the persona registry (built-in / cwd / personal / configured dirs) that agentworkforce agent uses.

That matters because spawn is the ergonomic path — it is what an orchestrating agent reaches for, and what I reached for. defineWorkforcePersonaNode requires standing up a fleet node definition with a channel and workspace connection; it is the right tool for a long-lived persona-backed node, not for "run this persona on that box for this task."

So the remaining ask is narrower than the title suggests:

1. spawn should accept a persona (name or path) resolved through the same registry, as an alternative to cli + task, with task layering the concrete assignment over the persona's standing instructions.
2. Discoverability. Nothing pointed me from spawn toward defineWorkforcePersonaNode, and the failure mode is silent: pasting persona text into a task produces an agent that runs, sounds correct, and is missing its skills and MCP servers. Nothing errors. A wrong path that works badly is worse than one that fails.

Retitling would be fair — the accurate framing is "relay spawn has no persona parameter, and the working path via defineWorkforcePersonaNode is undiscoverable from it", not "personas cannot be spawned".

Also raised by Khaliq and belonging with this: a relayflow step should be able to name a persona too. Workflows in relayflows declare agents as { name, cli, role, preset } (e.g. workflows/ci/fix-mcp-spawn.yaml) — free text and a CLI choice, with the same loss. Three launch surfaces exist — interactive CLI, relay spawn, relayflow steps — and only the first takes a persona.

[khaliqgant]

pear already does this, end to end — so this is a port, not a design problem

Khaliq pointed out it works in pear. It does, and the implementation is small and readable: pear/src/main/broker.ts, spawnPersona() at :2991 and spawnPersonaOnce() at :3003.

The whole mechanism:

1. Resolve the CLI — resolveAgentWorkforceCommand(cwd), which throws a specific error if absent: "AgentWorkforce CLI not found — install it to launch personas".
2. Discover — agentworkforce list --json → persona summaries.
3. Resolve one — agentworkforce show <personaId> --json → the spec, from which pear reads only id, description, harness, tags.
4. Launch — delegate to agentworkforce agent <persona>.
5. Verify it stuck — verifyPersonaBrokerRegistration(), then verifyPersonaHarnessReady(), and releaseUnreadyPersona() if either fails.

So agentworkforce list --json and show <id> --json already exist as machine-readable resolution primitives. The registry lookup I described as missing is a solved problem with a JSON interface.

The comment at broker.ts:3009 is the key insight and deserves quoting, because it removes most of the imagined work:

"The actual spawn is delegated to the workforce CLI (agent <persona>), which reads the full inherited persona itself, stages skills, materializes sidecars in its sandbox mount, and injects relaycast MCP from the broker env."

A caller does not have to understand a persona to launch one. It resolves the harness, shells out, and the CLI does skills, sidecars and MCP wiring itself. That is precisely the loss I hit by pasting persona text into a task — and pear avoids it by not trying to reconstruct the persona at all.

What this changes about the ask

The remaining gap is genuinely narrow: relay's spawn action needs the same three steps pear already performs — resolve via show --json, take harness from the spec, delegate to agentworkforce agent <persona> on the target node. Not new capability; the same call from a different caller.

Two things worth lifting from pear rather than reinventing:

• Spawn coalescing. personaSpawnRequestKey(projectId, personaId) keys in-flight dedup by project + persona, so concurrent requests for the same persona coalesce into one launch. A fleet will need the node-scoped equivalent.
• Readiness verification, and the release on failure. Pear does not treat a launched process as a running persona: it confirms broker registration and harness readiness, and releases the agent if either fails. Given how much of today was spent on records that claimed liveness while nothing was running, that verify-then-release discipline is the part most worth copying.

The one prerequisite pear enforces and a fleet node must too: the AgentWorkforce CLI has to be installed on the host doing the launching.

[khaliqgant]

Correction from Khaliq, and it overrides my last comment: delegating to another CLI is not acceptable. Use the SDK surface.

I posted pear's spawnPersona() as the pattern to copy. Do not copy it. Pear shells out to agentworkforce agent <persona>, and shelling out is the wrong boundary here regardless of how neatly it is written.

Khaliq's rule, stated plainly: we should always be using SDK surfaces.

Why the shell-out is the wrong answer, not just a less tidy one

• It makes a CLI binary a runtime dependency of every fleet node. Pear enforces this and even has the error for it — "AgentWorkforce CLI not found — install it to launch personas." Acceptable in a desktop app the user installed; not acceptable as a precondition for placing work on an arbitrary node, including a cloud sandbox.
• It couples two release trains through a process boundary with no type checking. A CLI whose flags or JSON shape shift breaks the caller at runtime, and only at runtime. We hit exactly this today: relayfile mount rejected --workspace/--local-dir flags its own help text advertised.
• It launders errors through exit codes and stdout parsing. Pear has to scrape output for readiness (personaHarnessReadyFromOutput, personaHarnessFailedFromOutput). That is a parser against another program's log format, and it is precisely the "check the output rather than the effect" pattern that produced several wrong answers today.
• agentworkforce agent is TTY-oriented. It drops into an interactive harness session; there is no headless form. Driving an interactive command from a daemon is fragile by construction.

The SDK surface already exists

@agentworkforce/deploy exports a real programmatic entrypoint:

export async function deploy(
  opts: DeployOptions,
  resolvers: DeployResolvers = {}
): Promise<DeployResult>

plus preflightPersona, the three mode launchers (devLauncher, sandboxLauncher, cloudLauncher), ModeLaunchHandle, ModeLaunchInput, ModeLauncher, and createTerminalIO / createBufferedIO for controlling IO instead of scraping it. It validates declared persona inputs up front and throws typed errors — "Unknown input 'x'; persona declares: …" — rather than failing somewhere inside a child process.

And @agentworkforce/local-surface already composes exactly that into Agent Relay: defineWorkforcePersonaNode(options): FleetNodeDefinition, whose launchPersonaRunner calls deploy() with mode: 'dev', detach: true, bridged: true, noPrompt: true (local-surface/src/index.ts:145). That is the library path, in-process, no CLI, and it is already wired to @agent-relay/fleet.

Notably pear already depends on @agentworkforce/deploy@^4.1.16 and shells out anyway. So this is not a missing capability — it is a caller reaching for the wrong surface, which is the same mistake I made when I pasted persona text into a relay task.

The ask, restated

Relay spawn — and relayflow steps — should accept a persona and launch it through @agentworkforce/deploy / local-surface, in process. No agentworkforce binary on the node, no stdout scraping, no interactive command driven by a daemon.

What is still worth taking from pear is the discipline, not the mechanism: dedup concurrent launches of the same persona, and verify registration and harness readiness before calling it running, releasing it if either fails. A launched process is not a running persona — today produced a long list of records asserting liveness with nothing behind them.