feat(sdk): expose headless spawn facade method

.agentworkforce/trajectories/completed/2026-05/traj_0kqt1gnfi3v8/summary.md

@@ -0,0 +1,34 @@
+# Trajectory: Remove unsafe spawn patch casts
+
+> **Status:** ✅ Completed
+> **Task:** PR-1003
+> **Confidence:** 93%
+> **Started:** May 27, 2026 at 10:17 AM
+> **Completed:** May 27, 2026 at 10:23 AM
+
+---
+
+## Summary
+
+Removed unsafe before-spawn patch assertions by preserving concrete spawn input types through runBeforeSpawn and applying allowed SpawnPatch fields explicitly; validated SDK check, lifecycle hook tests, formatting, diff check, and build.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Typed before-spawn patch flow instead of asserting patch shape
+
+- **Chose:** Typed before-spawn patch flow instead of asserting patch shape
+- **Reasoning:** The lifecycle hook return is SDK user code, not a broker response, so the safer fix is to preserve the concrete SpawnPtyInput or SpawnCliInput generic through runBeforeSpawn and apply only the allowed SpawnPatch fields without type assertions.
+
+---
+
+## Chapters
+
+### 1. Work
+
+_Agent: default_
+
+- Typed before-spawn patch flow instead of asserting patch shape: Typed before-spawn patch flow instead of asserting patch shape

.agentworkforce/trajectories/completed/2026-05/traj_0kqt1gnfi3v8/trajectory.json

@@ -0,0 +1,57 @@
+{
+  "id": "traj_0kqt1gnfi3v8",
+  "version": 1,
+  "task": {
+    "title": "Remove unsafe spawn patch casts",
+    "source": {
+      "system": "plain",
+      "id": "PR-1003"
+    }
+  },
+  "status": "completed",
+  "startedAt": "2026-05-27T14:17:32.363Z",
+  "completedAt": "2026-05-27T14:23:24.058Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-05-27T14:23:11.212Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_dkv8jcg4cvsh",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-05-27T14:23:11.212Z",
+      "endedAt": "2026-05-27T14:23:24.058Z",
+      "events": [
+        {
+          "ts": 1779891791213,
+          "type": "decision",
+          "content": "Typed before-spawn patch flow instead of asserting patch shape: Typed before-spawn patch flow instead of asserting patch shape",
+          "raw": {
+            "question": "Typed before-spawn patch flow instead of asserting patch shape",
+            "chosen": "Typed before-spawn patch flow instead of asserting patch shape",
+            "alternatives": [],
+            "reasoning": "The lifecycle hook return is SDK user code, not a broker response, so the safer fix is to preserve the concrete SpawnPtyInput or SpawnCliInput generic through runBeforeSpawn and apply only the allowed SpawnPatch fields without type assertions."
+          },
+          "significance": "high"
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Removed unsafe before-spawn patch assertions by preserving concrete spawn input types through runBeforeSpawn and applying allowed SpawnPatch fields explicitly; validated SDK check, lifecycle hook tests, formatting, diff check, and build.",
+    "approach": "Standard approach",
+    "confidence": 0.93
+  },
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/will/Projects/AgentWorkforce/relay",
+  "tags": [],
+  "_trace": {
+    "startRef": "9a709eec38f3f8b4ed697171f8c17807e5e70fb8",
+    "endRef": "9a709eec38f3f8b4ed697171f8c17807e5e70fb8"
+  }
+}

.agentworkforce/trajectories/completed/2026-05/traj_33ykjz5a7avh/summary.md

@@ -0,0 +1,33 @@
+# Trajectory: Revise AgentRelay headless facade naming
+
+> **Status:** ✅ Completed
+> **Confidence:** 92%
+> **Started:** May 27, 2026 at 08:32 AM
+> **Completed:** May 27, 2026 at 08:36 AM
+
+---
+
+## Summary
+
+Revised the PR API to avoid exposing provider terminology at the AgentRelay facade: removed public AgentRelay.spawnProvider, changed spawnHeadless to accept cli, routed headless property spawners through the same helper, and updated docs/tests/changelog.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider
+
+- **Chose:** Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider
+- **Reasoning:** The high-level facade should present runtime choice as spawnPty versus spawnHeadless. Provider is a lower-level client implementation detail and reads poorly at the recipe layer where callers already resolve a CLI/harness plan.
+
+---
+
+## Chapters
+
+### 1. Work
+
+_Agent: default_
+
+- Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider: Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider

.agentworkforce/trajectories/completed/2026-05/traj_33ykjz5a7avh/trajectory.json

@@ -0,0 +1,53 @@
+{
+  "id": "traj_33ykjz5a7avh",
+  "version": 1,
+  "task": {
+    "title": "Revise AgentRelay headless facade naming"
+  },
+  "status": "completed",
+  "startedAt": "2026-05-27T12:32:23.768Z",
+  "completedAt": "2026-05-27T12:36:20.398Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-05-27T12:32:28.346Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_d3cnk7kkc43m",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-05-27T12:32:28.346Z",
+      "endedAt": "2026-05-27T12:36:20.398Z",
+      "events": [
+        {
+          "ts": 1779885148347,
+          "type": "decision",
+          "content": "Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider: Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider",
+          "raw": {
+            "question": "Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider",
+            "chosen": "Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider",
+            "alternatives": [],
+            "reasoning": "The high-level facade should present runtime choice as spawnPty versus spawnHeadless. Provider is a lower-level client implementation detail and reads poorly at the recipe layer where callers already resolve a CLI/harness plan."
+          },
+          "significance": "high"
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Revised the PR API to avoid exposing provider terminology at the AgentRelay facade: removed public AgentRelay.spawnProvider, changed spawnHeadless to accept cli, routed headless property spawners through the same helper, and updated docs/tests/changelog.",
+    "approach": "Standard approach",
+    "confidence": 0.92
+  },
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/will/Projects/AgentWorkforce/relay",
+  "tags": [],
+  "_trace": {
+    "startRef": "df9e4c5665d885b50219686d203671241d51bac3",
+    "endRef": "df9e4c5665d885b50219686d203671241d51bac3"
+  }
+}

.agentworkforce/trajectories/completed/2026-05/traj_bvo77swtj1br/summary.md

@@ -0,0 +1,33 @@
+# Trajectory: Surface AgentRelay provider and headless spawns
+
+> **Status:** ✅ Completed
+> **Confidence:** 90%
+> **Started:** May 27, 2026 at 07:24 AM
+> **Completed:** May 27, 2026 at 07:24 AM
+
+---
+
+## Summary
+
+Added high-level AgentRelay.spawnProvider and AgentRelay.spawnHeadless facade methods, widened SpawnHeadlessInput for harness-backed provider metadata, documented the API, updated the changelog, and verified with SDK typecheck, build, formatting, and focused Vitest coverage.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Expose typed AgentRelay spawnProvider and spawnHeadless methods
+
+- **Chose:** Expose typed AgentRelay spawnProvider and spawnHeadless methods
+- **Reasoning:** Issue 998 needs provider-backed and headless app-server agents to use the high-level facade lifecycle hooks, result contracts, channel handles, and harness resolution instead of dropping to AgentRelayClient.
+
+---
+
+## Chapters
+
+### 1. Work
+
+_Agent: default_
+
+- Expose typed AgentRelay spawnProvider and spawnHeadless methods: Expose typed AgentRelay spawnProvider and spawnHeadless methods

.agentworkforce/trajectories/completed/2026-05/traj_bvo77swtj1br/trajectory.json

@@ -0,0 +1,53 @@
+{
+  "id": "traj_bvo77swtj1br",
+  "version": 1,
+  "task": {
+    "title": "Surface AgentRelay provider and headless spawns"
+  },
+  "status": "completed",
+  "startedAt": "2026-05-27T11:24:25.352Z",
+  "completedAt": "2026-05-27T11:24:34.780Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-05-27T11:24:30.208Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_fscokieqprhr",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-05-27T11:24:30.208Z",
+      "endedAt": "2026-05-27T11:24:34.780Z",
+      "events": [
+        {
+          "ts": 1779881070209,
+          "type": "decision",
+          "content": "Expose typed AgentRelay spawnProvider and spawnHeadless methods: Expose typed AgentRelay spawnProvider and spawnHeadless methods",
+          "raw": {
+            "question": "Expose typed AgentRelay spawnProvider and spawnHeadless methods",
+            "chosen": "Expose typed AgentRelay spawnProvider and spawnHeadless methods",
+            "alternatives": [],
+            "reasoning": "Issue 998 needs provider-backed and headless app-server agents to use the high-level facade lifecycle hooks, result contracts, channel handles, and harness resolution instead of dropping to AgentRelayClient."
+          },
+          "significance": "high"
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Added high-level AgentRelay.spawnProvider and AgentRelay.spawnHeadless facade methods, widened SpawnHeadlessInput for harness-backed provider metadata, documented the API, updated the changelog, and verified with SDK typecheck, build, formatting, and focused Vitest coverage.",
+    "approach": "Standard approach",
+    "confidence": 0.9
+  },
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/will/Projects/AgentWorkforce/relay",
+  "tags": [],
+  "_trace": {
+    "startRef": "f904124865b9575c1def48d20e333298cc03a1f7",
+    "endRef": "f904124865b9575c1def48d20e333298cc03a1f7"
+  }
+}

.agentworkforce/trajectories/completed/2026-05/traj_ei1zajpyq584/summary.md

@@ -0,0 +1,33 @@
+# Trajectory: Rename SDK spawn provider terminology
+
+> **Status:** ✅ Completed
+> **Confidence:** 90%
+> **Started:** May 27, 2026 at 08:49 AM
+> **Completed:** May 27, 2026 at 08:57 AM
+
+---
+
+## Summary
+
+Renamed the SDK spawn API from provider terminology to CLI terminology for the major release: AgentRelayClient.spawnProvider -> spawnCli, SpawnProviderInput -> SpawnCliInput, SpawnHeadlessInput.provider -> cli, lifecycle kind provider -> cli/headless, with docs, changelog migration notes, gateway type update, and tests.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Rename SDK provider spawn vocabulary to cli/headless
+
+- **Chose:** Rename SDK provider spawn vocabulary to cli/headless
+- **Reasoning:** The broker payload already uses cli, and provider is stale terminology now that harness configs represent the execution harness. Because this is a major release, the SDK can remove the legacy SpawnProviderInput/spawnProvider surface instead of layering aliases.
+
+---
+
+## Chapters
+
+### 1. Work
+
+_Agent: default_
+
+- Rename SDK provider spawn vocabulary to cli/headless: Rename SDK provider spawn vocabulary to cli/headless

.agentworkforce/trajectories/completed/2026-05/traj_ei1zajpyq584/trajectory.json

@@ -0,0 +1,53 @@
+{
+  "id": "traj_ei1zajpyq584",
+  "version": 1,
+  "task": {
+    "title": "Rename SDK spawn provider terminology"
+  },
+  "status": "completed",
+  "startedAt": "2026-05-27T12:49:51.440Z",
+  "completedAt": "2026-05-27T12:57:01.785Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-05-27T12:49:55.778Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_6kshcl1sbi15",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-05-27T12:49:55.778Z",
+      "endedAt": "2026-05-27T12:57:01.785Z",
+      "events": [
+        {
+          "ts": 1779886195779,
+          "type": "decision",
+          "content": "Rename SDK provider spawn vocabulary to cli/headless: Rename SDK provider spawn vocabulary to cli/headless",
+          "raw": {
+            "question": "Rename SDK provider spawn vocabulary to cli/headless",
+            "chosen": "Rename SDK provider spawn vocabulary to cli/headless",
+            "alternatives": [],
+            "reasoning": "The broker payload already uses cli, and provider is stale terminology now that harness configs represent the execution harness. Because this is a major release, the SDK can remove the legacy SpawnProviderInput/spawnProvider surface instead of layering aliases."
+          },
+          "significance": "high"
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Renamed the SDK spawn API from provider terminology to CLI terminology for the major release: AgentRelayClient.spawnProvider -> spawnCli, SpawnProviderInput -> SpawnCliInput, SpawnHeadlessInput.provider -> cli, lifecycle kind provider -> cli/headless, with docs, changelog migration notes, gateway type update, and tests.",
+    "approach": "Standard approach",
+    "confidence": 0.9
+  },
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/will/Projects/AgentWorkforce/relay",
+  "tags": [],
+  "_trace": {
+    "startRef": "f54552b5ac225df762bacbbad08cb66ef46ae5f7",
+    "endRef": "f54552b5ac225df762bacbbad08cb66ef46ae5f7"
+  }
+}

.agentworkforce/trajectories/completed/2026-05/traj_eowdep73c8oz/summary.md

@@ -0,0 +1,15 @@
+# Trajectory: Update web docs for spawnAgent facade
+
+> **Status:** ✅ Completed
+> **Task:** PR-1003
+> **Confidence:** 90%
+> **Started:** May 27, 2026 at 10:47 AM
+> **Completed:** May 27, 2026 at 10:52 AM
+
+---
+
+## Summary
+
+Updated web and README examples to use the TypeScript spawnAgent facade while leaving Python SDK examples on the Python API. Validated formatting, diff whitespace, and web build.
+
+**Approach:** Standard approach