create-orcha 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -15,6 +15,7 @@ The generated project includes:
15
15
  - a framework-free HTML, CSS, and JavaScript playground;
16
16
  - text and multimodal agent input;
17
17
  - durable sessions and chronological execution traces;
18
+ - parent agents with private durable subagents;
18
19
  - server and client actions;
19
20
  - lazy-loaded skills;
20
21
  - deterministic agent tests;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-orcha",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Create a complete OrchaJS project with example agents and a local playground.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -37,5 +37,5 @@
37
37
  "publishConfig": {
38
38
  "access": "public"
39
39
  },
40
- "orchaVersion": "^0.5.0"
40
+ "orchaVersion": "^0.6.0"
41
41
  }
@@ -23,7 +23,10 @@ to exercise the client-action pause and continuation flow.
23
23
  - Inspect model configuration, actions, skills, and evaluations.
24
24
  - Start runs from text or a complete multimodal `MessageContent[]` JSON array.
25
25
  - Start a durable run and stream cumulative output.
26
+ - Delegate order questions from `assistant` to a linked `orderSupport` child
27
+ session.
26
28
  - Continue an existing session with another message.
29
+ - Inspect parent and child session histories independently.
27
30
  - Submit results when an agent pauses for client actions.
28
31
  - Browse sessions and projected history.
29
32
  - Inspect usage, status, and canonical durable session events.
@@ -45,6 +48,6 @@ npm run orcha:test # run registered agent tests
45
48
  ```
46
49
 
47
50
  The default Node configuration stores sessions in `.orcha/sessions`. The
48
- playground accesses sessions exclusively through `agent.list()`, `agent.get()`,
49
- and `agent.events()`, so changing the storage adapter does not require UI or
50
- server changes.
51
+ playground accesses parent sessions through `agent.list()`, `agent.get()`, and
52
+ `agent.events()`, and child sessions through `agent.subagentHistory()`, so
53
+ changing the storage adapter does not require UI or server changes.
@@ -34,7 +34,7 @@ orcha.init({
34
34
  anthropic: process.env.ANTHROPIC_API_KEY ?? "",
35
35
  openai: process.env.OPENAI_API_KEY ?? "",
36
36
  },
37
- actions: { runtime: "sandbox" },
37
+ actions: { runtime: "native" },
38
38
  agents: {
39
39
  supportBot: "./supportBot",
40
40
  },
@@ -118,6 +118,8 @@ orcha/
118
118
 
119
119
  ```json
120
120
  {
121
+ "name": "Support Agent",
122
+ "description": "Resolve customer support questions using confirmed account data.",
121
123
  "provider": "anthropic",
122
124
  "model": "claude-sonnet-4-6",
123
125
  "region": "provider_managed",
@@ -133,6 +135,8 @@ instructions in `instructions.md`.
133
135
 
134
136
  Agent `index.json` fields:
135
137
 
138
+ - `name` (required): concise human-readable agent name.
139
+ - `description` (optional): what the agent does and when it should be used.
136
140
  - `provider` (required): `"anthropic"`, `"bedrock"`, `"deepseek"`,
137
141
  `"openai"`, `"googlegenai"`, or `"vertexai"`.
138
142
  - `model` (required): exact provider model identifier.
@@ -151,6 +155,49 @@ Agent `index.json` fields:
151
155
  the base system prompt. Orcha appends the compact available-skill catalog and
152
156
  the full instructions for skills already loaded in this durable session.
153
157
 
158
+ ## Subagents
159
+
160
+ Register private subagents alongside a parent in `orcha/index.ts`:
161
+
162
+ ```js
163
+ agents: {
164
+ coordinator: {
165
+ path: "./coordinator",
166
+ subagents: {
167
+ researcher: "./researcher",
168
+ },
169
+ },
170
+ researcher: "./researcher",
171
+ }
172
+ ```
173
+
174
+ Only top-level keys become `orcha.<agentName>`. In this example the
175
+ researcher is both directly accessible and available to the coordinator.
176
+ Remove its top-level entry to make it private.
177
+
178
+ A parent may configure delegation limits in its `index.json`:
179
+
180
+ ```json
181
+ {
182
+ "subagents": {
183
+ "maxPerRun": 3
184
+ }
185
+ }
186
+ ```
187
+
188
+ `maxPerRun` limits newly created child sessions in one parent run and
189
+ defaults to 10.
190
+
191
+ The parent receives a compact catalog containing each subagent's registered
192
+ name and optional description. Internal `run_agent`, `resume_agent`,
193
+ `inspect_agent` tools let it start, continue, and inspect only child sessions
194
+ initiated by its current session. A delegated agent cannot delegate again.
195
+
196
+ Subagent calls are synchronous. The parent becomes
197
+ `waiting_for_subagent` while the child runs, then receives the child's text,
198
+ pause state, client-action request, failure, or completion as a normal tool
199
+ result. The parent and child keep separate linked JSONL sessions.
200
+
154
201
  ## Core execution model
155
202
 
156
203
  An **agent** is the compiled definition: model settings, instructions, actions,
@@ -169,8 +216,12 @@ next numbered run in that session. Each run accumulates its own model usage and
169
216
  ends in exactly one of these states:
170
217
 
171
218
  - `completed`: the model produced final output.
219
+ - `waiting_for_subagent`: the parent is waiting for a synchronous child
220
+ response and continues automatically when it arrives.
172
221
  - `waiting_for_client_action`: the model requested work that only the
173
222
  application can perform. The run is paused, not completed.
223
+ - `paused`: active provider work was aborted, streamed output was preserved,
224
+ and a later `resume()` starts a new run.
174
225
  - `failed`: validation, provider, storage, or execution failed. The durable
175
226
  events remain available for diagnosis.
176
227
 
@@ -617,6 +668,12 @@ type SessionCreated = SessionEvent<{
617
668
  name?: string;
618
669
  metadata: Record<string, string | number | boolean | null>;
619
670
  variables: Record<string, string>;
671
+ lineage?: {
672
+ origin: "delegated";
673
+ parentAgent: string;
674
+ parentSessionId: string;
675
+ parentCallId: string;
676
+ };
620
677
  }>; // type "session.created", no run
621
678
 
622
679
  type SessionUpdated = SessionEvent<{
@@ -760,14 +817,49 @@ type EvaluationFailed = SessionEvent<{
760
817
  evaluatedThroughSequence: number;
761
818
  }>; // type "evaluation.failed"
762
819
 
820
+ type SubagentInitiated = SessionEvent<{
821
+ callId: string;
822
+ agent: string;
823
+ sessionId: string;
824
+ status: "running";
825
+ }>; // type "subagent.initiated"
826
+
827
+ type SubagentResumed = SessionEvent<{
828
+ callId: string;
829
+ agent: string;
830
+ sessionId: string;
831
+ status: "running";
832
+ }>; // type "subagent.resumed"
833
+
834
+ type SubagentCompletedOrPausedOrFailed = SessionEvent<{
835
+ callId: string;
836
+ agent: string;
837
+ sessionId: string;
838
+ status:
839
+ | "completed"
840
+ | "waiting_for_client_action"
841
+ | "paused"
842
+ | "failed";
843
+ output?: unknown;
844
+ usage?: Usage;
845
+ clientToolCalls?: Array<{
846
+ callId: string;
847
+ name: string;
848
+ arguments: Record<string, unknown>;
849
+ }>;
850
+ error?: ErrorData;
851
+ }>; // type "subagent.completed" | "subagent.paused" | "subagent.failed"
852
+
763
853
  type RunPaused = SessionEvent<{
764
- status: "waiting_for_client_action";
765
- clientToolCalls: Array<{
854
+ status: "waiting_for_client_action" | "paused";
855
+ clientToolCalls?: Array<{
766
856
  callId: string;
767
857
  name: string;
768
858
  arguments: Record<string, unknown>;
769
859
  }>;
770
- usage: Usage;
860
+ usage?: Usage;
861
+ output?: unknown;
862
+ durationMs?: number;
771
863
  }>; // type "run.paused"
772
864
 
773
865
  type RunCompleted = SessionEvent<{
@@ -783,6 +875,14 @@ type RunFailed = SessionEvent<{
783
875
  error: ErrorData;
784
876
  }>; // type "run.failed"
785
877
 
878
+ type SessionPaused = SessionEvent<{
879
+ status: "paused";
880
+ }>; // type "session.paused", no run
881
+
882
+ type SessionResumed = SessionEvent<{
883
+ status: "active";
884
+ }>; // type "session.resumed", no run
885
+
786
886
  type TestCompleted = SessionEvent<{
787
887
  suiteId: string;
788
888
  agent: string;
@@ -817,6 +917,12 @@ run.started
817
917
  message.created (user)
818
918
  message.created (assistant, possibly with tool_call)
819
919
  action.requested → action.completed|action.failed # local action
920
+ subagent.initiated
921
+ ...child session advances independently...
922
+ subagent.paused
923
+ subagent.resumed
924
+ ...child session advances independently...
925
+ subagent.completed|subagent.paused|subagent.failed
820
926
  message.created (tool)
821
927
  ...additional model/action rounds...
822
928
  message.created (assistant final)
@@ -866,10 +972,12 @@ offline production compilation. Neither command invokes a provider.
866
972
  6. `load_skill` updates durable session instructions. Local actions execute
867
973
  through the configured runtime. Client actions pause safely. Tool results
868
974
  are reordered to match the model's original call order.
869
- 7. The model loop continues until final output, failure, a client pause, or
870
- the maximum of 10 action rounds.
871
- 8. Usage is normalized and aggregated across every model call in the run.
872
- 9. After `run.completed`, enabled evaluations start in the background.
975
+ 7. Internal agent tools start or continue linked child sessions. The parent
976
+ reports `waiting_for_subagent` until each synchronous child call returns.
977
+ 8. The model loop continues until final output, failure, a pause, or the
978
+ maximum of 10 action rounds.
979
+ 9. Usage is normalized and aggregated across every model call in the run.
980
+ 10. After `run.completed`, enabled evaluations start in the background.
873
981
  `execution.result` is already available; `execution.evaluations` waits
874
982
  for judge completion and durable persistence.
875
983
 
@@ -880,11 +988,12 @@ cause `resume()` to fail spuriously or reuse sequence numbers.
880
988
  ### Replay and context
881
989
 
882
990
  Orcha does not send raw JSONL back to the model. It projects durable events
883
- into provider-neutral conversation messages. Completed conversational runs
884
- become user, assistant, and tool messages; lifecycle bookkeeping such as
885
- durations, test assertions, and evaluation events is excluded from model
886
- context. Reasoning text and provider replay metadata are retained where needed
887
- for faithful continuation but are omitted from evaluation transcripts.
991
+ into provider-neutral conversation messages. Completed and explicitly paused
992
+ conversational runs become user, assistant, and tool messages, so a new run
993
+ sees incomplete assistant text preserved by `pause()`. Lifecycle bookkeeping
994
+ such as durations, test assertions, and evaluation events is excluded from
995
+ model context. Reasoning text and provider replay metadata are retained where
996
+ needed for faithful continuation but are omitted from evaluation transcripts.
888
997
 
889
998
  ### Reading sessions
890
999
 
@@ -898,6 +1007,14 @@ for faithful continuation but are omitted from evaluation transcripts.
898
1007
  back in the options to keep pagination on a stable event boundary.
899
1008
  - `agent.list({ page, pageSize, status, metadata })` lists projected session
900
1009
  snapshots.
1010
+ - `agent.subagentHistory(childSessionId, { page, pageSize })` returns the
1011
+ projected history of a child owned by this parent agent. Lineage checks
1012
+ prevent access through unrelated agents.
1013
+ - `agent.pause(sessionId)` aborts active provider work for the session and
1014
+ active children, preserving streamed text as an incomplete assistant
1015
+ message. `agent.resume(sessionId)` starts a new run with `"Continue."`;
1016
+ pass content to give different instructions. Pending client actions still
1017
+ require their exact tool results.
901
1018
  - Never read storage files directly. Use these methods so applications remain
902
1019
  compatible with JSONL, SQLite, IndexedDB, remote, and future storage adapters.
903
1020
 
@@ -1,4 +1,6 @@
1
1
  {
2
+ "name": "Approval Agent",
3
+ "description": "Review purchase requests through an application-owned approval step.",
2
4
  "provider": "openai",
3
5
  "model": "gpt-5-mini",
4
6
  "region": "provider_managed",
@@ -1,7 +1,12 @@
1
1
  {
2
+ "name": "Assistant",
3
+ "description": "Answer general questions while separating confirmed facts from assumptions.",
2
4
  "provider": "openai",
3
5
  "model": "gpt-5-mini",
4
6
  "region": "provider_managed",
5
7
  "maxTokens": 4096,
6
- "outputType": "text"
8
+ "outputType": "text",
9
+ "subagents": {
10
+ "maxPerRun": 2
11
+ }
7
12
  }
@@ -2,3 +2,7 @@ You are a concise general assistant inside an Orcha playground.
2
2
 
3
3
  Answer clearly and distinguish confirmed information from assumptions. When
4
4
  information is missing, say what you would need rather than inventing it.
5
+
6
+ Use the registered order-support subagent for order lookup or delivery
7
+ questions. Give it the complete relevant task, inspect its result, and then
8
+ answer the user.
@@ -5,11 +5,16 @@ orcha.init({
5
5
  openai: process.env.OPENAI_API_KEY ?? "",
6
6
  },
7
7
  actions: {
8
- runtime: "sandbox",
8
+ runtime: "native",
9
9
  },
10
10
  agents: {
11
11
  approvalAgent: "./approvalAgent",
12
- assistant: "./assistant",
12
+ assistant: {
13
+ path: "./assistant",
14
+ subagents: {
15
+ orderSupport: "./orderSupport",
16
+ },
17
+ },
13
18
  orderSupport: "./orderSupport",
14
19
  },
15
20
  });
@@ -1,4 +1,6 @@
1
1
  {
2
+ "name": "Order Support",
3
+ "description": "Look up confirmed order data and explain its status and next step.",
2
4
  "provider": "openai",
3
5
  "model": "gpt-5-mini",
4
6
  "region": "provider_managed",
@@ -12,13 +12,14 @@ const state = {
12
12
  sessionQuery: "",
13
13
  running: false,
14
14
  rawEvents: "",
15
+ children: [],
15
16
  };
16
17
 
17
18
  const element = Object.fromEntries(
18
19
  [
19
20
  "agent-count", "agent-list", "agent-title", "agent-description",
20
21
  "agent-badges", "configuration-grid", "system-instructions", "action-count", "action-list",
21
- "skill-count", "skill-list", "evaluation-definitions",
22
+ "skill-count", "skill-list", "subagent-count", "subagent-list", "evaluation-definitions",
22
23
  "evaluation-session", "evaluation-results",
23
24
  "examples", "input-help", "prompt", "run-button", "clear-run", "run-section",
24
25
  "live-section", "live-session-label", "run-status", "live-timeline",
@@ -30,7 +31,7 @@ const element = Object.fromEntries(
30
31
  "raw-events", "copy-events", "resume-session", "refresh-sessions",
31
32
  "new-session", "session-count-side", "session-search", "session-list",
32
33
  "session-list-panel", "session-inspector", "close-session-inspector",
33
- "inspector-status", "inspector-title", "inspector-evaluations", "toast",
34
+ "inspector-status", "inspector-title", "inspector-children", "inspector-evaluations", "toast",
34
35
  ].map((id) => [camel(id), document.querySelector(`#${id}`)]),
35
36
  );
36
37
 
@@ -100,7 +101,7 @@ function renderAgentNavigation() {
100
101
  button.innerHTML = `
101
102
  <span class="agent-icon">${escapeHtml(agent.name.slice(0, 2))}</span>
102
103
  <span class="agent-copy">
103
- <strong>${escapeHtml(agent.name)}</strong>
104
+ <strong>${escapeHtml(agent.displayName || agent.name)}</strong>
104
105
  <span>${escapeHtml(agent.provider)} · ${escapeHtml(agent.model)}</span>
105
106
  </span>`;
106
107
  button.addEventListener("click", () => selectAgent(agent.name));
@@ -121,6 +122,7 @@ async function selectAgent(name) {
121
122
  state.testReports = new Map();
122
123
  state.sessionId = undefined;
123
124
  state.pendingCalls = [];
125
+ state.children = [];
124
126
  state.evaluations = [];
125
127
  state.sessionQuery = "";
126
128
  element.sessionSearch.value = "";
@@ -148,7 +150,7 @@ async function selectAgent(name) {
148
150
  function renderOverview() {
149
151
  const agent = state.agent;
150
152
  if (!agent) return;
151
- element.agentTitle.textContent = agent.name;
153
+ element.agentTitle.textContent = agent.displayName || agent.name;
152
154
  element.agentDescription.textContent =
153
155
  agent.description || "Registered Orcha agent.";
154
156
  element.agentBadges.innerHTML = [
@@ -194,6 +196,18 @@ function renderOverview() {
194
196
  skill.instructions,
195
197
  ),
196
198
  );
199
+ renderCapabilities(
200
+ element.subagentList,
201
+ element.subagentCount,
202
+ agent.subagents || [],
203
+ (subagent) => capability(
204
+ subagent.name,
205
+ subagent.description,
206
+ "subagent",
207
+ `${subagent.provider} · ${subagent.model}`,
208
+ { key: subagent.key },
209
+ ),
210
+ );
197
211
  renderEvaluationDefinitions();
198
212
  renderExamples();
199
213
  }
@@ -662,9 +676,10 @@ async function selectSession(sessionId) {
662
676
  try {
663
677
  const agent = encodeURIComponent(agentName);
664
678
  const session = encodeURIComponent(sessionId);
665
- const [snapshot, eventData] = await Promise.all([
679
+ const [snapshot, eventData, children] = await Promise.all([
666
680
  requestJson(`/api/agents/${agent}/sessions/${session}`),
667
681
  requestJson(`/api/agents/${agent}/sessions/${session}/events`),
682
+ requestJson(`/api/agents/${agent}/sessions/${session}/children`),
668
683
  ]);
669
684
  if (
670
685
  state.agent?.name !== agentName ||
@@ -672,7 +687,9 @@ async function selectSession(sessionId) {
672
687
  ) {
673
688
  return;
674
689
  }
690
+ state.children = children.items || [];
675
691
  renderSession(snapshot, eventData.events);
692
+ renderInspectorChildren();
676
693
  } catch (error) {
677
694
  if (
678
695
  state.agent?.name === agentName &&
@@ -778,6 +795,102 @@ function renderInspectorEvaluations() {
778
795
  : "No evaluation results were recorded for this session.";
779
796
  }
780
797
 
798
+ function renderInspectorChildren() {
799
+ const children = state.children || [];
800
+ element.inspectorChildren.className = children.length
801
+ ? "inspector-evaluations"
802
+ : "inspector-evaluations empty";
803
+ element.inspectorChildren.innerHTML = children.length
804
+ ? children.map((child) => `
805
+ <button class="center-session-card child-session-card" data-child-session="${escapeHtml(child.sessionId)}">
806
+ <span>
807
+ <strong>${escapeHtml(child.agent || "Subagent")}</strong>
808
+ <code>${escapeHtml(shortId(child.sessionId))}</code>
809
+ </span>
810
+ <span class="status ${escapeHtml(child.runStatus || child.status)}">${escapeHtml(child.runStatus || child.status)}</span>
811
+ </button>`).join("")
812
+ : "No child sessions were created by this session.";
813
+ for (const button of element.inspectorChildren.querySelectorAll("[data-child-session]")) {
814
+ button.addEventListener("click", () =>
815
+ selectChildSession(button.dataset.childSession),
816
+ );
817
+ }
818
+ }
819
+
820
+ async function selectChildSession(childSessionId) {
821
+ const agentName = state.agent?.name;
822
+ if (!agentName) return;
823
+ try {
824
+ const agent = encodeURIComponent(agentName);
825
+ const child = encodeURIComponent(childSessionId);
826
+ const history = await requestJson(
827
+ `/api/agents/${agent}/children/${child}/history?pageSize=100`,
828
+ );
829
+ renderChildHistory(history);
830
+ element.resumeSession.classList.add("hidden");
831
+ } catch (error) {
832
+ showToast(error.message, true);
833
+ }
834
+ }
835
+
836
+ function renderChildHistory(history) {
837
+ const title = history.name || `${history.agent} subagent`;
838
+ element.sessionTitle.textContent = title;
839
+ element.inspectorTitle.textContent = title;
840
+ element.inspectorStatus.textContent = history.runStatus || history.status;
841
+ element.inspectorStatus.className =
842
+ `status ${history.runStatus || history.status}`;
843
+ element.sessionSummary.innerHTML = [
844
+ inspectorFact("Child session ID", history.sessionId),
845
+ inspectorFact("Agent", history.agent),
846
+ inspectorFact("Parent session", history.lineage?.parentSessionId || "—"),
847
+ inspectorFact("Created", formatDate(history.createdAt)),
848
+ inspectorFact("Updated", formatDate(history.updatedAt)),
849
+ inspectorFact("Input tokens", history.usage?.inputTokens ?? "—"),
850
+ inspectorFact("Output tokens", history.usage?.outputTokens ?? "—"),
851
+ inspectorFact("Reasoning tokens", history.usage?.reasoningTokens ?? "—"),
852
+ ].join("");
853
+ element.sessionTimeline.innerHTML = history.items.length
854
+ ? history.items.map(historyCard).join("")
855
+ : '<div class="empty">No projected history.</div>';
856
+ state.rawEvents = JSON.stringify(history, null, 2);
857
+ element.rawEvents.textContent = state.rawEvents;
858
+ element.liveSection.classList.add("hidden");
859
+ state.evaluations = history.items
860
+ .filter((item) => item.type === "evaluation")
861
+ .map((item) => ({
862
+ name: item.name,
863
+ status: item.status === "completed" ? "passed" : "failed",
864
+ metrics: item.metrics || [],
865
+ durationMs: item.durationMs,
866
+ }));
867
+ renderEvaluationResults();
868
+ renderInspectorEvaluations();
869
+ element.inspectorChildren.className = "inspector-evaluations empty";
870
+ element.inspectorChildren.textContent =
871
+ "Nested subagents are not available; delegation depth is limited to one.";
872
+ showSessionInspector();
873
+ }
874
+
875
+ function historyCard(item) {
876
+ return traceCard({
877
+ type: item.type,
878
+ label:
879
+ item.type === "message"
880
+ ? item.role === "user" ? "Input" : "Output"
881
+ : item.type.replace("_", " "),
882
+ title: item.name,
883
+ status: item.status,
884
+ content: item.content ? contentText(item.content) : item.summary,
885
+ fields: [
886
+ ...(item.childSessionId ? [["Child session", item.childSessionId]] : []),
887
+ ...(typeof item.durationMs === "number"
888
+ ? [["Duration", `${item.durationMs}ms`]]
889
+ : []),
890
+ ],
891
+ });
892
+ }
893
+
781
894
  async function refreshLiveTrace(sessionId) {
782
895
  const agentName = state.agent?.name;
783
896
  if (!agentName) return;
@@ -985,6 +1098,47 @@ function executionTraceFromEvents(events) {
985
1098
  content: skill?.instructions,
986
1099
  });
987
1100
  }
1101
+ if (event.type === "subagent.initiated") {
1102
+ trace.push({
1103
+ type: "action",
1104
+ label: "Subagent initiated",
1105
+ title: event.data.agent,
1106
+ status: event.data.status,
1107
+ fields: [
1108
+ ["Session", event.data.sessionId],
1109
+ ["Call", event.data.callId],
1110
+ ],
1111
+ });
1112
+ }
1113
+ if (event.type === "subagent.resumed") {
1114
+ trace.push({
1115
+ type: "action",
1116
+ label: "Subagent resumed",
1117
+ title: event.data.agent,
1118
+ status: event.data.status,
1119
+ fields: [
1120
+ ["Session", event.data.sessionId],
1121
+ ["Call", event.data.callId],
1122
+ ],
1123
+ });
1124
+ }
1125
+ if (
1126
+ event.type === "subagent.completed" ||
1127
+ event.type === "subagent.paused" ||
1128
+ event.type === "subagent.failed"
1129
+ ) {
1130
+ trace.push({
1131
+ type: "action",
1132
+ label: event.type.replace(".", " "),
1133
+ title: event.data.agent,
1134
+ status: event.data.status,
1135
+ fields: [["Session", event.data.sessionId]],
1136
+ sections: [[
1137
+ event.data.error ? "Error" : "Result",
1138
+ JSON.stringify(event.data.error || event.data.output, null, 2),
1139
+ ]],
1140
+ });
1141
+ }
988
1142
  if (
989
1143
  event.type === "run.completed" ||
990
1144
  event.type === "run.paused" ||
@@ -58,6 +58,13 @@
58
58
  </div>
59
59
  <div id="skill-list" class="card-list"></div>
60
60
  </section>
61
+ <section class="section">
62
+ <div class="section-title">
63
+ <div><span class="overline">Delegation</span><h2>Subagents</h2></div>
64
+ <span id="subagent-count" class="count"></span>
65
+ </div>
66
+ <div id="subagent-list" class="card-list"></div>
67
+ </section>
61
68
  </div>
62
69
 
63
70
  <div id="actions-view" class="main-view">
@@ -157,8 +164,8 @@
157
164
  </section>
158
165
  <section class="section">
159
166
  <details>
160
- <summary>Raw session events</summary>
161
- <div class="raw-toolbar"><span>Storage-neutral data from agent.events()</span><button id="copy-events" class="quiet-button">Copy</button></div>
167
+ <summary>Session data</summary>
168
+ <div class="raw-toolbar"><span>Storage-neutral events or projected child history</span><button id="copy-events" class="quiet-button">Copy</button></div>
162
169
  <pre id="raw-events" class="raw-events"></pre>
163
170
  </details>
164
171
  </section>
@@ -193,6 +200,13 @@
193
200
  <span class="overline">Selected session</span>
194
201
  <h2 id="inspector-title">Session</h2>
195
202
  <div id="session-summary" class="inspector-summary"></div>
203
+ <section class="inspector-section">
204
+ <div class="inspector-section-title">
205
+ <span class="overline">Delegation</span>
206
+ <strong>Child sessions</strong>
207
+ </div>
208
+ <div id="inspector-children" class="inspector-evaluations empty">No child sessions.</div>
209
+ </section>
196
210
  <section class="inspector-section">
197
211
  <div class="inspector-section-title">
198
212
  <span class="overline">Quality</span>
@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
5
5
  import {
6
6
  orcha,
7
7
  type AgentRuntime,
8
+ type Execution,
8
9
  type MessageContent,
9
10
  type OrchaClient,
10
11
  type SessionEvent,
@@ -126,6 +127,38 @@ async function route(
126
127
  return;
127
128
  }
128
129
 
130
+ if (
131
+ method === "POST" &&
132
+ segments.length === 6 &&
133
+ segments[0] === "api" &&
134
+ segments[1] === "agents" &&
135
+ segments[3] === "sessions" &&
136
+ segments[5] === "pause"
137
+ ) {
138
+ const agent = getAgent(segments[2]);
139
+ sendJson(response, 200, await agent.pause(segments[4]));
140
+ return;
141
+ }
142
+
143
+ if (
144
+ method === "GET" &&
145
+ segments.length >= 5 &&
146
+ segments[0] === "api" &&
147
+ segments[1] === "agents" &&
148
+ segments[3] === "children"
149
+ ) {
150
+ if (segments.length === 6 && segments[5] === "history") {
151
+ sendJson(response, 200, await getAgent(segments[2]).subagentHistory(
152
+ segments[4],
153
+ {
154
+ page: positiveInteger(url.searchParams.get("page"), 1),
155
+ pageSize: positiveInteger(url.searchParams.get("pageSize"), 100),
156
+ },
157
+ ));
158
+ return;
159
+ }
160
+ }
161
+
129
162
  if (
130
163
  method === "GET" &&
131
164
  segments.length >= 5 &&
@@ -152,6 +185,10 @@ async function route(
152
185
  });
153
186
  return;
154
187
  }
188
+ if (segments.length === 6 && segments[5] === "children") {
189
+ sendJson(response, 200, await childSessionSnapshots(agent, sessionId));
190
+ return;
191
+ }
155
192
  }
156
193
 
157
194
  if (method === "GET") {
@@ -170,6 +207,48 @@ async function route(
170
207
  sendJson(response, 404, { error: "Not found." });
171
208
  }
172
209
 
210
+ async function childSessionSnapshots(
211
+ agent: AgentRuntime,
212
+ parentSessionId: string,
213
+ ) {
214
+ const history = await readAllSessionHistory(agent, parentSessionId);
215
+ const childSessionIds = [
216
+ ...new Set(
217
+ history.items.flatMap((item) =>
218
+ item.type === "subagent" && item.childSessionId
219
+ ? [item.childSessionId]
220
+ : [],
221
+ ),
222
+ ),
223
+ ];
224
+ const items = await Promise.all(
225
+ childSessionIds.map(async (childSessionId) => {
226
+ const child = await agent.subagentHistory(childSessionId, {
227
+ page: 1,
228
+ pageSize: 1,
229
+ });
230
+ const {
231
+ items: _items,
232
+ page: _page,
233
+ pageSize: _pageSize,
234
+ total: _total,
235
+ hasMore: _hasMore,
236
+ ...snapshot
237
+ } = child;
238
+ return snapshot;
239
+ }),
240
+ );
241
+ return {
242
+ items: items.sort((left, right) =>
243
+ right.updatedAt.localeCompare(left.updatedAt),
244
+ ),
245
+ page: 1,
246
+ pageSize: items.length,
247
+ total: items.length,
248
+ hasMore: false,
249
+ };
250
+ }
251
+
173
252
  async function executeAgent(
174
253
  agentName: string,
175
254
  request: IncomingMessage,
@@ -200,6 +279,13 @@ async function executeAgent(
200
279
  });
201
280
  }
202
281
 
282
+ await streamExecution(execution, response);
283
+ }
284
+
285
+ async function streamExecution(
286
+ execution: Execution,
287
+ response: ServerResponse,
288
+ ): Promise<void> {
203
289
  response.writeHead(200, {
204
290
  "content-type": "application/x-ndjson; charset=utf-8",
205
291
  "cache-control": "no-store",
@@ -241,11 +327,11 @@ function publicAgentManifest(
241
327
  manifest: ReturnType<typeof orcha.getCompiledBundle>["agents"][string],
242
328
  ) {
243
329
  return {
244
- name: manifest.name,
245
- description:
246
- playgroundConfiguration.agents?.[manifest.name]?.description,
330
+ name: manifest.key,
331
+ displayName: manifest.name,
332
+ description: manifest.description,
247
333
  examples:
248
- playgroundConfiguration.agents?.[manifest.name]?.examples ?? [],
334
+ playgroundConfiguration.agents?.[manifest.key]?.examples ?? [],
249
335
  provider: manifest.provider,
250
336
  model: manifest.model,
251
337
  region: manifest.region ?? "provider_managed",
@@ -281,6 +367,13 @@ function publicAgentManifest(
281
367
  reasoningLevel: evaluation.reasoningLevel,
282
368
  metrics: evaluation.metrics,
283
369
  })),
370
+ subagents: Object.entries(manifest.subagents).map(([key, subagent]) => ({
371
+ key,
372
+ name: subagent.name,
373
+ description: subagent.description,
374
+ provider: subagent.provider,
375
+ model: subagent.model,
376
+ })),
284
377
  };
285
378
  }
286
379
 
@@ -443,6 +536,37 @@ async function readAllSessionEvents(
443
536
  return pages.flat();
444
537
  }
445
538
 
539
+ async function readAllSessionHistory(
540
+ agent: AgentRuntime,
541
+ sessionId: string,
542
+ ) {
543
+ const pages = [];
544
+ let page = 1;
545
+ let hasMore = true;
546
+ let latest;
547
+ while (hasMore) {
548
+ latest = await agent.history(sessionId, {
549
+ page,
550
+ pageSize: 100,
551
+ });
552
+ pages.unshift(latest.items);
553
+ hasMore = latest.hasMore;
554
+ page += 1;
555
+ }
556
+ if (!latest) {
557
+ throw new Error(`Session "${sessionId}" has no history.`);
558
+ }
559
+ const items = pages.flat();
560
+ return {
561
+ ...latest,
562
+ items,
563
+ page: 1,
564
+ pageSize: items.length,
565
+ total: items.length,
566
+ hasMore: false,
567
+ };
568
+ }
569
+
446
570
  function sessionNameFromContent(content: string | MessageContent[]): string {
447
571
  const text = typeof content === "string"
448
572
  ? content