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 +15 -3
- package/template/AGENTS.md +10 -2
- package/template/orcha/AGENTS.md +100 -18
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-orcha",
|
|
3
|
-
"version": "0.4.
|
|
4
|
-
"description": "Create a
|
|
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
|
-
"
|
|
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"
|
package/template/AGENTS.md
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
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.
|
package/template/orcha/AGENTS.md
CHANGED
|
@@ -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
|
|
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.
|
|
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
|
-
- `
|
|
91
|
-
|
|
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()`
|
|
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 `{
|
|
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
|
-
{
|
|
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.
|
|
1027
|
-
`
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
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
|
|
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
|