Skip to content

Commit d4bc060

Browse files
willwashburnwillwashburn
authored
Merge pull request #1003 from AgentWorkforce/codex/issue-998-spawn-provider-headless
feat(sdk): expose headless spawn facade method
2 parents 38d4255 + bc0a235 commit d4bc060

44 files changed

Lines changed: 1273 additions & 560 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Trajectory: Remove unsafe spawn patch casts
2+
3+
> **Status:** ✅ Completed
4+
> **Task:** PR-1003
5+
> **Confidence:** 93%
6+
> **Started:** May 27, 2026 at 10:17 AM
7+
> **Completed:** May 27, 2026 at 10:23 AM
8+
9+
---
10+
11+
## Summary
12+
13+
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.
14+
15+
**Approach:** Standard approach
16+
17+
---
18+
19+
## Key Decisions
20+
21+
### Typed before-spawn patch flow instead of asserting patch shape
22+
23+
- **Chose:** Typed before-spawn patch flow instead of asserting patch shape
24+
- **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.
25+
26+
---
27+
28+
## Chapters
29+
30+
### 1. Work
31+
32+
_Agent: default_
33+
34+
- 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‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
{
2+
"id": "traj_0kqt1gnfi3v8",
3+
"version": 1,
4+
"task": {
5+
"title": "Remove unsafe spawn patch casts",
6+
"source": {
7+
"system": "plain",
8+
"id": "PR-1003"
9+
}
10+
},
11+
"status": "completed",
12+
"startedAt": "2026-05-27T14:17:32.363Z",
13+
"completedAt": "2026-05-27T14:23:24.058Z",
14+
"agents": [
15+
{
16+
"name": "default",
17+
"role": "lead",
18+
"joinedAt": "2026-05-27T14:23:11.212Z"
19+
}
20+
],
21+
"chapters": [
22+
{
23+
"id": "chap_dkv8jcg4cvsh",
24+
"title": "Work",
25+
"agentName": "default",
26+
"startedAt": "2026-05-27T14:23:11.212Z",
27+
"endedAt": "2026-05-27T14:23:24.058Z",
28+
"events": [
29+
{
30+
"ts": 1779891791213,
31+
"type": "decision",
32+
"content": "Typed before-spawn patch flow instead of asserting patch shape: Typed before-spawn patch flow instead of asserting patch shape",
33+
"raw": {
34+
"question": "Typed before-spawn patch flow instead of asserting patch shape",
35+
"chosen": "Typed before-spawn patch flow instead of asserting patch shape",
36+
"alternatives": [],
37+
"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."
38+
},
39+
"significance": "high"
40+
}
41+
]
42+
}
43+
],
44+
"retrospective": {
45+
"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.",
46+
"approach": "Standard approach",
47+
"confidence": 0.93
48+
},
49+
"commits": [],
50+
"filesChanged": [],
51+
"projectId": "/Users/will/Projects/AgentWorkforce/relay",
52+
"tags": [],
53+
"_trace": {
54+
"startRef": "9a709eec38f3f8b4ed697171f8c17807e5e70fb8",
55+
"endRef": "9a709eec38f3f8b4ed697171f8c17807e5e70fb8"
56+
}
57+
}

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Trajectory: Revise AgentRelay headless facade naming
2+
3+
> **Status:** ✅ Completed
4+
> **Confidence:** 92%
5+
> **Started:** May 27, 2026 at 08:32 AM
6+
> **Completed:** May 27, 2026 at 08:36 AM
7+
8+
---
9+
10+
## Summary
11+
12+
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.
13+
14+
**Approach:** Standard approach
15+
16+
---
17+
18+
## Key Decisions
19+
20+
### Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider
21+
22+
- **Chose:** Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider
23+
- **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.
24+
25+
---
26+
27+
## Chapters
28+
29+
### 1. Work
30+
31+
_Agent: default_
32+
33+
- 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‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
{
2+
"id": "traj_33ykjz5a7avh",
3+
"version": 1,
4+
"task": {
5+
"title": "Revise AgentRelay headless facade naming"
6+
},
7+
"status": "completed",
8+
"startedAt": "2026-05-27T12:32:23.768Z",
9+
"completedAt": "2026-05-27T12:36:20.398Z",
10+
"agents": [
11+
{
12+
"name": "default",
13+
"role": "lead",
14+
"joinedAt": "2026-05-27T12:32:28.346Z"
15+
}
16+
],
17+
"chapters": [
18+
{
19+
"id": "chap_d3cnk7kkc43m",
20+
"title": "Work",
21+
"agentName": "default",
22+
"startedAt": "2026-05-27T12:32:28.346Z",
23+
"endedAt": "2026-05-27T12:36:20.398Z",
24+
"events": [
25+
{
26+
"ts": 1779885148347,
27+
"type": "decision",
28+
"content": "Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider: Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider",
29+
"raw": {
30+
"question": "Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider",
31+
"chosen": "Use cli-based AgentRelay.spawnHeadless instead of public spawnProvider",
32+
"alternatives": [],
33+
"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."
34+
},
35+
"significance": "high"
36+
}
37+
]
38+
}
39+
],
40+
"retrospective": {
41+
"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.",
42+
"approach": "Standard approach",
43+
"confidence": 0.92
44+
},
45+
"commits": [],
46+
"filesChanged": [],
47+
"projectId": "/Users/will/Projects/AgentWorkforce/relay",
48+
"tags": [],
49+
"_trace": {
50+
"startRef": "df9e4c5665d885b50219686d203671241d51bac3",
51+
"endRef": "df9e4c5665d885b50219686d203671241d51bac3"
52+
}
53+
}

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Trajectory: Surface AgentRelay provider and headless spawns
2+
3+
> **Status:** ✅ Completed
4+
> **Confidence:** 90%
5+
> **Started:** May 27, 2026 at 07:24 AM
6+
> **Completed:** May 27, 2026 at 07:24 AM
7+
8+
---
9+
10+
## Summary
11+
12+
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.
13+
14+
**Approach:** Standard approach
15+
16+
---
17+
18+
## Key Decisions
19+
20+
### Expose typed AgentRelay spawnProvider and spawnHeadless methods
21+
22+
- **Chose:** Expose typed AgentRelay spawnProvider and spawnHeadless methods
23+
- **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.
24+
25+
---
26+
27+
## Chapters
28+
29+
### 1. Work
30+
31+
_Agent: default_
32+
33+
- Expose typed AgentRelay spawnProvider and spawnHeadless methods: Expose typed AgentRelay spawnProvider and spawnHeadless methods

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

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
{
2+
"id": "traj_bvo77swtj1br",
3+
"version": 1,
4+
"task": {
5+
"title": "Surface AgentRelay provider and headless spawns"
6+
},
7+
"status": "completed",
8+
"startedAt": "2026-05-27T11:24:25.352Z",
9+
"completedAt": "2026-05-27T11:24:34.780Z",
10+
"agents": [
11+
{
12+
"name": "default",
13+
"role": "lead",
14+
"joinedAt": "2026-05-27T11:24:30.208Z"
15+
}
16+
],
17+
"chapters": [
18+
{
19+
"id": "chap_fscokieqprhr",
20+
"title": "Work",
21+
"agentName": "default",
22+
"startedAt": "2026-05-27T11:24:30.208Z",
23+
"endedAt": "2026-05-27T11:24:34.780Z",
24+
"events": [
25+
{
26+
"ts": 1779881070209,
27+
"type": "decision",
28+
"content": "Expose typed AgentRelay spawnProvider and spawnHeadless methods: Expose typed AgentRelay spawnProvider and spawnHeadless methods",
29+
"raw": {
30+
"question": "Expose typed AgentRelay spawnProvider and spawnHeadless methods",
31+
"chosen": "Expose typed AgentRelay spawnProvider and spawnHeadless methods",
32+
"alternatives": [],
33+
"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."
34+
},
35+
"significance": "high"
36+
}
37+
]
38+
}
39+
],
40+
"retrospective": {
41+
"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.",
42+
"approach": "Standard approach",
43+
"confidence": 0.9
44+
},
45+
"commits": [],
46+
"filesChanged": [],
47+
"projectId": "/Users/will/Projects/AgentWorkforce/relay",
48+
"tags": [],
49+
"_trace": {
50+
"startRef": "f904124865b9575c1def48d20e333298cc03a1f7",
51+
"endRef": "f904124865b9575c1def48d20e333298cc03a1f7"
52+
}
53+
}

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Trajectory: Rename SDK spawn provider terminology
2+
3+
> **Status:** ✅ Completed
4+
> **Confidence:** 90%
5+
> **Started:** May 27, 2026 at 08:49 AM
6+
> **Completed:** May 27, 2026 at 08:57 AM
7+
8+
---
9+
10+
## Summary
11+
12+
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.
13+
14+
**Approach:** Standard approach
15+
16+
---
17+
18+
## Key Decisions
19+
20+
### Rename SDK provider spawn vocabulary to cli/headless
21+
22+
- **Chose:** Rename SDK provider spawn vocabulary to cli/headless
23+
- **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.
24+
25+
---
26+
27+
## Chapters
28+
29+
### 1. Work
30+
31+
_Agent: default_
32+
33+
- 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‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
{
2+
"id": "traj_ei1zajpyq584",
3+
"version": 1,
4+
"task": {
5+
"title": "Rename SDK spawn provider terminology"
6+
},
7+
"status": "completed",
8+
"startedAt": "2026-05-27T12:49:51.440Z",
9+
"completedAt": "2026-05-27T12:57:01.785Z",
10+
"agents": [
11+
{
12+
"name": "default",
13+
"role": "lead",
14+
"joinedAt": "2026-05-27T12:49:55.778Z"
15+
}
16+
],
17+
"chapters": [
18+
{
19+
"id": "chap_6kshcl1sbi15",
20+
"title": "Work",
21+
"agentName": "default",
22+
"startedAt": "2026-05-27T12:49:55.778Z",
23+
"endedAt": "2026-05-27T12:57:01.785Z",
24+
"events": [
25+
{
26+
"ts": 1779886195779,
27+
"type": "decision",
28+
"content": "Rename SDK provider spawn vocabulary to cli/headless: Rename SDK provider spawn vocabulary to cli/headless",
29+
"raw": {
30+
"question": "Rename SDK provider spawn vocabulary to cli/headless",
31+
"chosen": "Rename SDK provider spawn vocabulary to cli/headless",
32+
"alternatives": [],
33+
"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."
34+
},
35+
"significance": "high"
36+
}
37+
]
38+
}
39+
],
40+
"retrospective": {
41+
"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.",
42+
"approach": "Standard approach",
43+
"confidence": 0.9
44+
},
45+
"commits": [],
46+
"filesChanged": [],
47+
"projectId": "/Users/will/Projects/AgentWorkforce/relay",
48+
"tags": [],
49+
"_trace": {
50+
"startRef": "f54552b5ac225df762bacbbad08cb66ef46ae5f7",
51+
"endRef": "f54552b5ac225df762bacbbad08cb66ef46ae5f7"
52+
}
53+
}

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Trajectory: Update web docs for spawnAgent facade
2+
3+
> **Status:** ✅ Completed
4+
> **Task:** PR-1003
5+
> **Confidence:** 90%
6+
> **Started:** May 27, 2026 at 10:47 AM
7+
> **Completed:** May 27, 2026 at 10:52 AM
8+
9+
---
10+
11+
## Summary
12+
13+
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.
14+
15+
**Approach:** Standard approach

0 commit comments

Comments
 (0)