#10748: feat: Add sessions.spawn gateway method for direct subagent spawning

## Summary This PR adds a `sessions.spawn` gateway method that allows spawning subagent sessions directly without requiring an LLM in the loop. ## Motivation Currently, spawning subagents requires using the `sessions_spawn` tool from within an agent session, which means: 1. Every spawn operation requires an LLM call (~$0.01+ per spawn) 2. External automation (systemd timers, cron scripts, CI/CD) cannot spawn subagents directly 3. Task orchestration systems must go through expensive LLM intermediaries For autonomous agent systems that need to spawn many workers (e.g., task dispatchers, build systems, test runners), this creates unnecessary cost and latency. ## Changes - **`src/gateway/protocol/schema/sessions.ts`**: Added `SessionsSpawnParamsSchema` - **`src/gateway/protocol/schema/types.ts`**: Added `SessionsSpawnParams` type - **`src/gateway/protocol/index.ts`**: Export validation and types - **`src/gateway/server-methods-list.ts`**: Added `sessions.spawn` to method list - **`src/gateway/server-methods/sessions.ts`**: Implemented the handler ## Implementation The `sessions.spawn` handler mirrors the existing `sessions_spawn` tool logic: - Validates task parameter is non-empty - Checks requester is not a subagent (forbidden) - Validates cross-agent spawning against `allowAgents` config - Resolves model and thinking level from overrides or defaults - Applies model to child session via `sessions.patch` - Triggers agent run via `callGateway('agent', ...)` - Registers subagent run for announcement routing ## Parameters | Parameter | Type | Description | |-----------|------|-------------| | `task` | string (required) | The task/prompt for the subagent | | `label` | string | Optional label for the session | | `agentId` | string | Target agent (defaults to requester's agent) | | `model` | string | Model override (e.g., `anthropic/claude-sonnet-4-5`) | | `thinking` | string | Thinking level override | | `runTimeoutSeconds` | number | Timeout for the agent run | | `cleanup` | `delete` \| `keep` | Session cleanup policy | | `channel`, `to`, `accountId`, `threadId` | string | Delivery context for announcements | | `requesterSessionKey` | string | Override requester session (defaults to main) | ## Response ```json { "ok": true, "childSessionKey": "agent:main:subagent:uuid", "runId": "uuid", "modelApplied": true, "warning": "optional model warning" } ``` ## Use Cases 1. **Task Dispatchers**: Pick tasks from a queue and spawn workers via `openclaw gateway call sessions.spawn` 2. **CI/CD Integration**: Trigger agent runs from external build systems 3. **Scheduled Jobs**: Systemd timers or cron spawning workers at /bin/bash marginal cost 4. **Cost Optimization**: Reduce per-spawn cost from ~$0.01+ to ~$0 ## Testing Tested locally by patching the compiled JS and calling: ```bash openclaw gateway call sessions.spawn --params '{"task": "echo test", "label": "test-spawn"}' ``` --- *Submitted on behalf of @DeviousCham by Fox (AI engineering partner at gr84x LLC)* <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> - Adds a new gateway RPC method `sessions.spawn` and wires it into the protocol schemas/validators and server method allowlist. - Implements `sessions.spawn` in `src/gateway/server-methods/sessions.ts` by mirroring `sessions_spawn` tool behavior: config-based allowlist checks, optional model/thinking overrides, creating a child subagent session key, and starting an `agent` run. - Registers the spawned subagent run in the subagent registry for announcement routing/cleanup, and returns `{childSessionKey, runId, modelApplied, warning}` to the caller. <h3>Confidence Score: 2/5</h3> - This PR adds useful functionality but has correctness and safety issues around requester session key handling and announcement routing context. - The handler largely mirrors the existing `sessions_spawn` tool, but it diverges in a few key places: it accepts an arbitrary `requesterSessionKey` without the alias normalization/visibility checks used elsewhere, which can affect both authorization decisions and announcement attribution; and it drops group-routing context fields that the tool forwards, which will break expected routing in group scenarios. Additionally, the new protocol schema introduces unions that are discouraged by the repo’s schema guardrails and can cause client validation incompatibilities. - src/gateway/server-methods/sessions.ts, src/gateway/protocol/schema/sessions.ts <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->