create-orcha 0.4.3 → 0.4.5

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
@@ -12,7 +12,7 @@ npm install
12
12
  The generated project includes:
13
13
 
14
14
  - an Orcha agent registry with example agents;
15
- - `orcha playground` for a hot-reloading local interface;
15
+ - `orchajs playground` for a hot-reloading local interface;
16
16
  - text and multimodal agent input;
17
17
  - durable sessions and chronological execution traces;
18
18
  - parent agents with private durable subagents;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-orcha",
3
- "version": "0.4.3",
3
+ "version": "0.4.5",
4
4
  "description": "Create a complete OrchaJS project with example agents and a local playground.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -8,19 +8,21 @@ frontend or server code is not required.
8
8
  - `orcha/` contains registered agent source.
9
9
  - `.orcha/sessions/` is the default Node JSONL storage directory and must not
10
10
  be committed.
11
- - `npm run dev` starts `orcha playground`, which watches `orcha/**`.
11
+ - `npm run dev` starts `orchajs playground`, which watches `orcha/**`.
12
12
  - `npm run build` creates `.orcha/dist/bundle.js` and
13
13
  `.orcha/dist/manifest.json`; it does not include the playground React
14
14
  application.
15
15
 
16
16
  When another tool packages an unbundled production application, explicitly
17
- include `.orcha/dist/**`. A successful `orcha build` does not guarantee that a
17
+ include `.orcha/dist/**`. A successful `orchajs build` does not guarantee that a
18
18
  later packager copied generated files. Inspect the final ZIP or container and
19
19
  confirm that `.orcha/dist/manifest.json` is present.
20
20
 
21
- Use the complete Orcha `AGENTS.md` generated by `orcha init` as the source of
21
+ 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.
@@ -33,7 +33,7 @@ to exercise the client-action pause and continuation flow.
33
33
  - Wait for and display asynchronous evaluations when configured.
34
34
  - Run the selected agent's registered model-backed tests with one click.
35
35
 
36
- The browser has no direct filesystem or provider access. `orcha playground`
36
+ The browser has no direct filesystem or provider access. `orchajs playground`
37
37
  binds to localhost, loads `.env`, watches `orcha/**`, and reports invalid edits
38
38
  in the interface.
39
39
 
@@ -6,21 +6,21 @@ files under `.orcha/`.
6
6
 
7
7
  ## Commands
8
8
 
9
- - `orcha init` creates the initial Orcha files without overwriting files.
10
- - `orcha dev` validates agent source and watches `orcha/**` for changes.
11
- - `orcha playground` opens the built-in local UI and hot reloads agent source.
12
- - `orcha run <agent> --input "…"` executes one registered agent.
13
- - `orcha run <agent> --input-file request.json` accepts structured input.
14
- - `orcha run <agent> --session <id> --input "…"` continues a session.
15
- - `orcha run <agent> --session <id> --tool-results results.json` submits
9
+ - `orchajs init` creates the initial Orcha files without overwriting files.
10
+ - `orchajs dev` validates agent source and watches `orcha/**` for changes.
11
+ - `orchajs playground` opens the built-in local UI and hot reloads agent source.
12
+ - `orchajs run <agent> --input "…"` executes one registered agent.
13
+ - `orchajs run <agent> --input-file request.json` accepts structured input.
14
+ - `orchajs run <agent> --session <id> --input "…"` continues a session.
15
+ - `orchajs run <agent> --session <id> --tool-results results.json` submits
16
16
  pending client-action results.
17
- - `orcha test` runs every enabled discovered agent test.
18
- - `orcha test <agent>` or `orcha test <agent>/<case>` narrows the run.
19
- - `orcha migrate-storage --to sqlite|node-jsonl` copies all session histories
17
+ - `orchajs test` runs every enabled discovered agent test.
18
+ - `orchajs test <agent>` or `orchajs test <agent>/<case>` narrows the run.
19
+ - `orchajs migrate-storage --to sqlite|node-jsonl` copies all session histories
20
20
  between local stores without deleting the source.
21
- - `orcha export-session <agent> <sessionId> [--output <path>]` exports one
21
+ - `orchajs export-session <agent> <sessionId> [--output <path>]` exports one
22
22
  session from the active store as JSONL.
23
- - `orcha build` creates the production Orcha bundle without calling models.
23
+ - `orchajs build` creates the production Orcha bundle without calling models.
24
24
  - Add `--json` to `run` and `test` for machine-readable output.
25
25
 
26
26
  `run`, `test`, and playground executions use real providers and require
@@ -30,7 +30,7 @@ under `.orcha/sessions/<agentName>/`; opt-in SQLite stores all agents in
30
30
 
31
31
  ## Production deployment
32
32
 
33
- `orcha build` writes `.orcha/dist/bundle.js` for bundler integrations and
33
+ `orchajs build` writes `.orcha/dist/bundle.js` for bundler integrations and
34
34
  `.orcha/dist/manifest.json` for unbundled production runtimes. If deployment
35
35
  uses plain `tsc`, `serverless-plugin-typescript`, or another packager that
36
36
  does not use `orchajs/esbuild`, explicitly include `.orcha/dist/**` in the
@@ -46,7 +46,7 @@ package:
46
46
  - ".orcha/dist/**"
47
47
  ```
48
48
 
49
- Do not assume that a successful `orcha build` means the generated files were
49
+ Do not assume that a successful `orchajs build` means the generated files were
50
50
  copied by a later packaging tool. Inspect the final ZIP or container image and
51
51
  confirm that `.orcha/dist/manifest.json` is present.
52
52
 
@@ -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,29 @@ 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.
88
109
  - `actions` (optional): overrides the native local-action runtime or configures
89
110
  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.
111
+ - `mcp.credentials` (optional): runtime-only values used to resolve
112
+ `${NAME}` placeholders in MCP headers or stdio environment values.
113
+ - `storage.strategy` (optional): `"node-jsonl"` (default), `"sqlite"`, or
114
+ local-first `"cloud"`. Cloud requires `amarsia.key`, keeps a native local
115
+ cache, commits appends locally without cloud latency, and delivers durable
116
+ bounded outbox batches in the background. Await `orcha.close()` before
117
+ reinitializing; close reports any cloud tail that could not be flushed.
92
118
  - `storage.directory` (optional): session directory relative to project
93
119
  root; defaults to `.orcha/sessions`.
94
120
  - `root` (optional): absolute or working-directory-relative project root;
@@ -138,11 +164,47 @@ explicit service-account credentials are optional. Bedrock requires `region`;
138
164
  explicit AWS credentials are optional. Never place credentials in
139
165
  `index.json`, instructions, tests, session metadata, or committed files.
140
166
 
167
+ ## MCP connections
168
+
169
+ Assign named MCP folders in an agent or subagent registration:
170
+
171
+ ```ts
172
+ agents: {
173
+ supportBot: {
174
+ path: "./supportBot",
175
+ mcp: {
176
+ github: "./mcp/github",
177
+ },
178
+ },
179
+ }
180
+ ```
181
+
182
+ `orcha/mcp/github/index.json` configures either cross-platform Streamable
183
+ HTTP or Node-only stdio:
184
+
185
+ ```json
186
+ {
187
+ "transport": "streamable-http",
188
+ "url": "https://mcp.example.com",
189
+ "headers": {
190
+ "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
191
+ }
192
+ }
193
+ ```
194
+
195
+ All discovered tools are available as `github__<toolName>`. MCP output is
196
+ untrusted external data. Keep secrets out of JSON and provide placeholder
197
+ values through `orcha.init().mcp.credentials`; Node also reads
198
+ `process.env`.
199
+
141
200
  ## Agent folders
142
201
 
143
202
  ```text
144
203
  orcha/
145
204
  index.ts
205
+ mcp/
206
+ github/
207
+ index.json
146
208
  supportBot/
147
209
  index.json
148
210
  instructions.md
@@ -302,7 +364,7 @@ environment. The complete pause/continue flow is:
302
364
  }
303
365
  5. Application executes every requested action.
304
366
  6. Application calls agent.resume(sessionId, {
305
- toolResults: [{ callId, output, isError? }]
367
+ toolResults: [{ callId, output, contents?, isError? }]
306
368
  }).
307
369
  7. Orcha validates every callId and output, stores the results, and continues
308
370
  the same paused run from its prior model context.
@@ -342,9 +404,9 @@ const result = await execution.result;
342
404
  const evaluations = await execution.evaluations;
343
405
  ```
344
406
 
345
- `run()` input fields:
407
+ `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
408
 
347
- - `content` (required): a non-empty string, one content item, or an array.
409
+ - `content` (required when passing an options object): a non-empty string, one content item, or an array.
348
410
  Use `{ filePath: "./document.pdf" }` for a local file or
349
411
  `{ url: "https://example.com/document.pdf" }` for a remote file.
350
412
  `mimeType` is optional when it can be inferred from the extension. Durable
@@ -374,7 +436,11 @@ client actions in the application and submit every result:
374
436
  ```ts
375
437
  orcha.supportBot.resume(sessionId, {
376
438
  toolResults: [
377
- { callId: "call_123", output: { approved: true } }
439
+ {
440
+ callId: "call_123",
441
+ output: { approved: true },
442
+ contents: [{ filePath: "./signed-approval.pdf" }], // optional media/content items
443
+ }
378
444
  ],
379
445
  });
380
446
  ```
@@ -482,6 +548,11 @@ The local action signature is
482
548
  `sessionId`, immutable session `metadata`, a stable `idempotencyKey`,
483
549
  allowlisted `env`, guarded `fetch`, and prefixed `log`.
484
550
 
551
+ Actions can also return media or multimodal content back to the model alongside
552
+ their structured JSON output by returning `{ output: jsonOutput, contents: [...] }`.
553
+ `contents` accepts any `AgentContentInput` (such as `{ filePath }`,
554
+ `{ url }`, or content items). `outputSchema` validates `output` directly.
555
+
485
556
  ## Skills
486
557
 
487
558
  Skills are lazy-loaded procedural instructions. Direct child folders under
@@ -569,7 +640,7 @@ Test `index.json` fields:
569
640
  - `expect.actions` (optional): ordered expected calls. Each may assert
570
641
  `arguments.equals` or `arguments.partial`.
571
642
 
572
- The test folder name is the selector used by `orcha test agent/testName`.
643
+ The test folder name is the selector used by `orchajs test agent/testName`.
573
644
 
574
645
  ## Evaluations
575
646
 
@@ -597,7 +668,7 @@ metrics, and thresholds:
597
668
 
598
669
  `execution.result` does not wait for judges. Await
599
670
  `execution.evaluations` when results must finish before process exit.
600
- Evaluations always finish during `orcha test`; judge errors and missed
671
+ Evaluations always finish during `orchajs test`; judge errors and missed
601
672
  thresholds fail the test. Lifecycle events are `evaluation.requested`,
602
673
  `evaluation.completed`, and `evaluation.failed`.
603
674
 
@@ -1003,7 +1074,7 @@ number. A conversational `resume(...content)` starts a new run number.
1003
1074
  Concrete action arguments and outputs are validated against their schemas
1004
1075
  when the action is used.
1005
1076
 
1006
- `orcha dev` repeats validation when files change. `orcha build` performs
1077
+ `orchajs dev` repeats validation when files change. `orchajs build` performs
1007
1078
  offline production compilation. Neither command invokes a provider.
1008
1079
 
1009
1080
  ### Run lifecycle
@@ -1029,7 +1100,7 @@ offline production compilation. Neither command invokes a provider.
1029
1100
  The parent reports `waiting_for_subagent` until each synchronous child
1030
1101
  call returns.
1031
1102
  8. The model loop continues until final output, failure, a pause, or the
1032
- maximum of 10 action rounds.
1103
+ maximum of 20 action rounds.
1033
1104
  9. Usage is normalized and aggregated across every model call in the run.
1034
1105
  10. After `run.completed`, enabled evaluations start in the background.
1035
1106
  `execution.result` is already available; `execution.evaluations` waits
@@ -1082,7 +1153,7 @@ needed for faithful continuation but are omitted from evaluation transcripts.
1082
1153
  - Mock actions when tests must avoid side effects; document intentional live
1083
1154
  action coverage.
1084
1155
  - Do not commit `.orcha/`; it contains generated output and session data.
1085
- - Run `orcha dev` after filesystem changes and `orcha test` when behavior
1156
+ - Run `orchajs dev` after filesystem changes and `orchajs test` when behavior
1086
1157
  changes.
1087
1158
  - Do not weaken assertions to match incorrect behavior. Remove an assertion
1088
1159
  only when it is stricter than the documented agent contract.
@@ -4,12 +4,12 @@
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "scripts": {
7
- "dev": "orcha playground",
8
- "playground": "orcha playground",
9
- "build": "orcha build",
10
- "test": "orcha test",
11
- "orcha:dev": "orcha dev",
12
- "orcha:test": "orcha test"
7
+ "dev": "orchajs playground",
8
+ "playground": "orchajs playground",
9
+ "build": "orchajs build",
10
+ "test": "orchajs test",
11
+ "orcha:dev": "orchajs dev",
12
+ "orcha:test": "orchajs test"
13
13
  },
14
14
  "dependencies": {
15
15
  "orchajs": "__ORCHA_VERSION__"