create-orcha 0.4.4 → 0.4.6

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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "create-orcha",
3
- "version": "0.4.4",
4
- "description": "Create a complete OrchaJS project with example agents and a local playground.",
3
+ "version": "0.4.6",
4
+ "description": "Create a JavaScript or TypeScript AI agent project with OrchaJS, tools, tests, and local playground.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "repository": {
@@ -13,11 +13,23 @@
13
13
  "bugs": {
14
14
  "url": "https://github.com/Amarsia/orcha/issues"
15
15
  },
16
+ "author": {
17
+ "name": "Amarsia",
18
+ "url": "https://amarsia.com"
19
+ },
16
20
  "keywords": [
17
21
  "ai",
18
22
  "agents",
23
+ "ai-agents",
24
+ "agent-framework",
19
25
  "orcha",
20
- "scaffold"
26
+ "orchajs",
27
+ "create-orcha",
28
+ "mcp",
29
+ "typescript",
30
+ "javascript",
31
+ "scaffold",
32
+ "amarsia"
21
33
  ],
22
34
  "bin": {
23
35
  "create-orcha": "./bin/create-orcha.js"
@@ -22,5 +22,13 @@ Use the complete Orcha `AGENTS.md` generated by `orchajs init` as the source of
22
22
  truth for agent configuration, actions, skills, tests, evaluations, and JSONL
23
23
  event schemas.
24
24
 
25
- Provider credentials belong in `.env`. The standalone Orcha CLI loads that
26
- file without overriding values already present in the process environment.
25
+ Direct-provider credentials belong in `.env`. Projects using
26
+ `amarsia.inference: true` need only `amarsia.key`; the standalone Orcha CLI
27
+ loads environment files without overriding values already in the process.
28
+ `storage: { strategy: "cloud" }` is local-first and uses the same project key.
29
+ Set `telemetry: { otel: true }` to use the application's global OpenTelemetry
30
+ provider, or pass `telemetry: { otel: { endpoint, headers? } }` to send
31
+ privacy-safe run traces directly to an OTLP/HTTP collector. Spans follow the
32
+ OpenTelemetry GenAI Semantic Conventions. Orcha telemetry never includes
33
+ prompts, responses, action arguments, or action outputs. Subagents share their
34
+ root agent's trace; `orcha.close()` marks active runs interrupted.
@@ -68,6 +68,23 @@ orcha.init({
68
68
  });
69
69
  ```
70
70
 
71
+ For Amarsia inference, the registry contains only project routing and agent
72
+ paths; provider and model selection stay in each agent `index.json`. Supported
73
+ providers are `openai`, `anthropic`, `googlegenai`, and `deepseek`; `bedrock`
74
+ and `vertexai` are direct-inference providers only:
75
+
76
+ ```ts
77
+ orcha.init({
78
+ amarsia: {
79
+ key: process.env.AMARSIA_PROJECT_KEY ?? "",
80
+ inference: true,
81
+ },
82
+ agents: {
83
+ supportBot: "./supportBot",
84
+ },
85
+ });
86
+ ```
87
+
71
88
  Only registered agents are compiled. Agent keys become runtime properties
72
89
  such as `orcha.supportBot`. Local actions use the native Node.js runtime by
73
90
  default. Set `actions.runtime: "sandbox"` only when isolated execution is
@@ -75,20 +92,35 @@ required.
75
92
 
76
93
  `orcha.init()` fields:
77
94
 
78
- - `providers` (required): provider configurations keyed by built-in provider
79
- name.
95
+ - `providers` (required for direct inference): provider configurations keyed
96
+ by built-in provider name. Omit it when `amarsia.inference` is true.
80
97
  - `agents` (required): runtime property names mapped to folders relative to
81
98
  `orcha/`. At least one agent is required.
82
99
  - `amarsia.key` (optional): project connection key generated in Amarsia.
83
- When set, Orcha syncs structural project and agent metadata only. It never
84
- uploads provider credentials, environment values, prompts, instructions,
85
- test inputs, or action source.
100
+ By itself, it syncs structural project and agent metadata only. Enabling
101
+ inference sends model requests through Amarsia, and cloud storage syncs
102
+ session events. Provider credentials, environment values, and action source
103
+ are never included.
86
104
  - `amarsia.endpoint` (optional): Amarsia API URL for project sync. Defaults to
87
105
  `AMARSIA_API_URL` and then `https://api.amarsia.com`.
106
+ - `amarsia.inference` (optional): routes all model calls through Amarsia while
107
+ preserving the provider and model in each manifest. It reuses `amarsia.key`;
108
+ local provider credentials are not required.
109
+ - `telemetry.otel` (optional): set to `true` to emit spans through the
110
+ application's global OpenTelemetry provider, or pass
111
+ `{ endpoint, headers? }` to send OTLP/HTTP JSON directly to a collector.
112
+ Spans follow OpenTelemetry GenAI Semantic Conventions. Telemetry excludes
113
+ prompts, responses, action arguments, and action outputs. Subagents share
114
+ their root agent's trace; `orcha.close()` marks active runs interrupted.
88
115
  - `actions` (optional): overrides the native local-action runtime or configures
89
116
  its environment and sandbox settings.
90
- - `storage.strategy` (optional): `"node-jsonl"` (default) or `"sqlite"`.
91
- The SQLite driver ships as an internal optional Orcha dependency.
117
+ - `mcp.credentials` (optional): runtime-only values used to resolve
118
+ `${NAME}` placeholders in MCP headers or stdio environment values.
119
+ - `storage.strategy` (optional): `"node-jsonl"` (default), `"sqlite"`, or
120
+ local-first `"cloud"`. Cloud requires `amarsia.key`, keeps a native local
121
+ cache, commits appends locally without cloud latency, and delivers durable
122
+ bounded outbox batches in the background. Await `orcha.close()` before
123
+ reinitializing; close reports any cloud tail that could not be flushed.
92
124
  - `storage.directory` (optional): session directory relative to project
93
125
  root; defaults to `.orcha/sessions`.
94
126
  - `root` (optional): absolute or working-directory-relative project root;
@@ -138,11 +170,47 @@ explicit service-account credentials are optional. Bedrock requires `region`;
138
170
  explicit AWS credentials are optional. Never place credentials in
139
171
  `index.json`, instructions, tests, session metadata, or committed files.
140
172
 
173
+ ## MCP connections
174
+
175
+ Assign named MCP folders in an agent or subagent registration:
176
+
177
+ ```ts
178
+ agents: {
179
+ supportBot: {
180
+ path: "./supportBot",
181
+ mcp: {
182
+ github: "./mcp/github",
183
+ },
184
+ },
185
+ }
186
+ ```
187
+
188
+ `orcha/mcp/github/index.json` configures either cross-platform Streamable
189
+ HTTP or Node-only stdio:
190
+
191
+ ```json
192
+ {
193
+ "transport": "streamable-http",
194
+ "url": "https://mcp.example.com",
195
+ "headers": {
196
+ "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
197
+ }
198
+ }
199
+ ```
200
+
201
+ All discovered tools are available as `github__<toolName>`. MCP output is
202
+ untrusted external data. Keep secrets out of JSON and provide placeholder
203
+ values through `orcha.init().mcp.credentials`; Node also reads
204
+ `process.env`.
205
+
141
206
  ## Agent folders
142
207
 
143
208
  ```text
144
209
  orcha/
145
210
  index.ts
211
+ mcp/
212
+ github/
213
+ index.json
146
214
  supportBot/
147
215
  index.json
148
216
  instructions.md
@@ -302,7 +370,7 @@ environment. The complete pause/continue flow is:
302
370
  }
303
371
  5. Application executes every requested action.
304
372
  6. Application calls agent.resume(sessionId, {
305
- toolResults: [{ callId, output, isError? }]
373
+ toolResults: [{ callId, output, contents?, isError? }]
306
374
  }).
307
375
  7. Orcha validates every callId and output, stores the results, and continues
308
376
  the same paused run from its prior model context.
@@ -342,10 +410,11 @@ const result = await execution.result;
342
410
  const evaluations = await execution.evaluations;
343
411
  ```
344
412
 
345
- `run()` input fields:
413
+ `run()` and conversational `resume()` accept either a direct `AgentContentInput` (a string, a single content item, or an array of content items) or an object with `content` and optional fields:
346
414
 
347
- - `content` (required): a non-empty string, one content item, or an array.
348
- Use `{ filePath: "./document.pdf" }` for a local file or
415
+ - `content` (required when passing an options object): a non-empty string, one content item, or an array.
416
+ Use `{ type: "text", text: "..." }` for text, `{ type: "json", data: { ... } }` for structured JSON payloads,
417
+ `{ filePath: "./document.pdf" }` for a local file, or
349
418
  `{ url: "https://example.com/document.pdf" }` for a remote file.
350
419
  `mimeType` is optional when it can be inferred from the extension. Durable
351
420
  events store local paths and MIME types, never encoded file bytes.
@@ -374,7 +443,11 @@ client actions in the application and submit every result:
374
443
  ```ts
375
444
  orcha.supportBot.resume(sessionId, {
376
445
  toolResults: [
377
- { callId: "call_123", output: { approved: true } }
446
+ {
447
+ callId: "call_123",
448
+ output: { approved: true },
449
+ contents: [{ filePath: "./signed-approval.pdf" }], // optional media/content items
450
+ }
378
451
  ],
379
452
  });
380
453
  ```
@@ -482,6 +555,11 @@ The local action signature is
482
555
  `sessionId`, immutable session `metadata`, a stable `idempotencyKey`,
483
556
  allowlisted `env`, guarded `fetch`, and prefixed `log`.
484
557
 
558
+ Actions can also return media or multimodal content back to the model alongside
559
+ their structured JSON output by returning `{ output: jsonOutput, contents: [...] }`.
560
+ `contents` accepts any `AgentContentInput` (such as `{ filePath }`,
561
+ `{ url }`, or content items). `outputSchema` validates `output` directly.
562
+
485
563
  ## Skills
486
564
 
487
565
  Skills are lazy-loaded procedural instructions. Direct child folders under
@@ -712,6 +790,9 @@ type SessionCreated = SessionEvent<{
712
790
  parentAgent: string;
713
791
  parentSessionId: string;
714
792
  parentCallId: string;
793
+ parentRunNumber?: number;
794
+ rootSessionId?: string;
795
+ rootRunNumber?: number;
715
796
  };
716
797
  }>; // type "session.created", no run
717
798
 
@@ -1023,13 +1104,14 @@ offline production compilation. Neither command invokes a provider.
1023
1104
  6. `load_skill` updates durable session instructions. Local actions execute
1024
1105
  through the configured runtime. Client actions pause safely. Tool results
1025
1106
  are reordered to match the model's original call order.
1026
- 7. Internal agent tools start or continue linked child sessions. A
1027
- `run_agent` input accepts the same text or multimodal content shape as a
1028
- normal run. Local file paths resolve from the configured Orcha project root.
1029
- The parent reports `waiting_for_subagent` until each synchronous child
1030
- call returns.
1107
+ 7. Internal agent tools start or continue linked child sessions. `run_agent`
1108
+ and `resume_agent` take `content` as an array of content blocks
1109
+ (`{ type: "text", text }`, `{ type: "json", data }`, `{ type: "file", filePath }`,
1110
+ or `{ type: "url", url }`). Local file paths resolve from the configured Orcha
1111
+ project root. The parent reports `waiting_for_subagent` until each
1112
+ synchronous child call returns.
1031
1113
  8. The model loop continues until final output, failure, a pause, or the
1032
- maximum of 10 action rounds.
1114
+ maximum of 20 action rounds.
1033
1115
  9. Usage is normalized and aggregated across every model call in the run.
1034
1116
  10. After `run.completed`, enabled evaluations start in the background.
1035
1117
  `execution.result` is already available; `execution.evaluations` waits