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 +1 -1
- package/package.json +1 -1
- package/template/AGENTS.md +7 -5
- package/template/README.md +1 -1
- package/template/orcha/AGENTS.md +101 -30
- package/template/package.json +6 -6
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
|
-
- `
|
|
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
package/template/AGENTS.md
CHANGED
|
@@ -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 `
|
|
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 `
|
|
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 `
|
|
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
|
-
|
|
26
|
-
|
|
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.
|
package/template/README.md
CHANGED
|
@@ -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. `
|
|
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
|
|
package/template/orcha/AGENTS.md
CHANGED
|
@@ -6,21 +6,21 @@ files under `.orcha/`.
|
|
|
6
6
|
|
|
7
7
|
## Commands
|
|
8
8
|
|
|
9
|
-
- `
|
|
10
|
-
- `
|
|
11
|
-
- `
|
|
12
|
-
- `
|
|
13
|
-
- `
|
|
14
|
-
- `
|
|
15
|
-
- `
|
|
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
|
-
- `
|
|
18
|
-
- `
|
|
19
|
-
- `
|
|
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
|
-
- `
|
|
21
|
+
- `orchajs export-session <agent> <sessionId> [--output <path>]` exports one
|
|
22
22
|
session from the active store as JSONL.
|
|
23
|
-
- `
|
|
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
|
-
`
|
|
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 `
|
|
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
|
|
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
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
-
- `
|
|
91
|
-
|
|
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()`
|
|
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
|
-
{
|
|
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 `
|
|
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 `
|
|
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
|
-
`
|
|
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
|
|
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 `
|
|
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.
|
package/template/package.json
CHANGED
|
@@ -4,12 +4,12 @@
|
|
|
4
4
|
"private": true,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
7
|
-
"dev": "
|
|
8
|
-
"playground": "
|
|
9
|
-
"build": "
|
|
10
|
-
"test": "
|
|
11
|
-
"orcha:dev": "
|
|
12
|
-
"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__"
|