create-orcha 0.3.1 → 0.4.1
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 +2 -2
- package/template/orcha/AGENTS.md +57 -58
- package/template/orcha/index.ts +3 -3
- package/template/orcha/orderSupport/actions/lookupOrder/index.json +0 -1
- package/template/package.json +1 -1
- package/template/orcha/approvalAgent/evaluations/index.js +0 -5
- package/template/orcha/approvalAgent/skills/index.js +0 -5
- package/template/orcha/approvalAgent/tests/index.js +0 -5
- package/template/orcha/assistant/evaluations/index.js +0 -5
- package/template/orcha/assistant/skills/index.js +0 -5
- package/template/orcha/assistant/tests/index.js +0 -5
- package/template/orcha/orderSupport/evaluations/index.js +0 -5
- package/template/orcha/orderSupport/skills/index.js +0 -5
- package/template/orcha/orderSupport/tests/index.js +0 -5
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-orcha",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"description": "Create a complete OrchaJS project with example agents and a local playground.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"test": "node --test"
|
|
33
33
|
},
|
|
34
34
|
"engines": {
|
|
35
|
-
"node": ">=20"
|
|
35
|
+
"node": ">=18.20.8"
|
|
36
36
|
},
|
|
37
37
|
"publishConfig": {
|
|
38
38
|
"access": "public"
|
package/template/orcha/AGENTS.md
CHANGED
|
@@ -7,21 +7,26 @@ files under `.orcha/`.
|
|
|
7
7
|
## Commands
|
|
8
8
|
|
|
9
9
|
- `orcha init` creates the initial Orcha files without overwriting files.
|
|
10
|
-
- `orcha dev` validates
|
|
10
|
+
- `orcha dev` validates agent source and watches `orcha/**` for changes.
|
|
11
11
|
- `orcha playground` opens the built-in local UI and hot reloads agent source.
|
|
12
12
|
- `orcha run <agent> --input "…"` executes one registered agent.
|
|
13
13
|
- `orcha run <agent> --input-file request.json` accepts structured input.
|
|
14
14
|
- `orcha run <agent> --session <id> --input "…"` continues a session.
|
|
15
15
|
- `orcha run <agent> --session <id> --tool-results results.json` submits
|
|
16
16
|
pending client-action results.
|
|
17
|
-
- `orcha test` runs every
|
|
17
|
+
- `orcha test` runs every enabled discovered agent test.
|
|
18
18
|
- `orcha test <agent>` or `orcha test <agent>/<case>` narrows the run.
|
|
19
|
+
- `orcha migrate-storage --to sqlite|node-jsonl` copies all session histories
|
|
20
|
+
between local stores without deleting the source.
|
|
21
|
+
- `orcha export-session <agent> <sessionId> [--output <path>]` exports one
|
|
22
|
+
session from the active store as JSONL.
|
|
19
23
|
- `orcha build` creates the production Orcha bundle without calling models.
|
|
20
24
|
- Add `--json` to `run` and `test` for machine-readable output.
|
|
21
25
|
|
|
22
26
|
`run`, `test`, and playground executions use real providers and require
|
|
23
|
-
credentials. `dev` and `build` are offline.
|
|
24
|
-
`.orcha/sessions/<agentName
|
|
27
|
+
credentials. `dev` and `build` are offline. Sessions use JSONL by default
|
|
28
|
+
under `.orcha/sessions/<agentName>/`; opt-in SQLite stores all agents in
|
|
29
|
+
`.orcha/sessions/orcha-sqlite.db`.
|
|
25
30
|
|
|
26
31
|
## Registry
|
|
27
32
|
|
|
@@ -35,17 +40,16 @@ orcha.init({
|
|
|
35
40
|
anthropic: process.env.ANTHROPIC_API_KEY ?? "",
|
|
36
41
|
openai: process.env.OPENAI_API_KEY ?? "",
|
|
37
42
|
},
|
|
38
|
-
actions: { runtime: "native" },
|
|
39
43
|
agents: {
|
|
40
44
|
supportBot: "./supportBot",
|
|
41
45
|
},
|
|
42
46
|
});
|
|
43
47
|
```
|
|
44
48
|
|
|
45
|
-
Only registered
|
|
46
|
-
such as `orcha.supportBot`.
|
|
47
|
-
|
|
48
|
-
|
|
49
|
+
Only registered agents are compiled. Agent keys become runtime properties
|
|
50
|
+
such as `orcha.supportBot`. Local actions use the native Node.js runtime by
|
|
51
|
+
default. Set `actions.runtime: "sandbox"` only when isolated execution is
|
|
52
|
+
required.
|
|
49
53
|
|
|
50
54
|
`orcha.init()` fields:
|
|
51
55
|
|
|
@@ -53,9 +57,16 @@ allows action modules to execute in its Node.js process.
|
|
|
53
57
|
name.
|
|
54
58
|
- `agents` (required): runtime property names mapped to folders relative to
|
|
55
59
|
`orcha/`. At least one agent is required.
|
|
56
|
-
- `
|
|
57
|
-
|
|
58
|
-
|
|
60
|
+
- `amarsia.key` (optional): project connection key generated in Amarsia.
|
|
61
|
+
When set, Orcha syncs structural project and agent metadata only. It never
|
|
62
|
+
uploads provider credentials, environment values, prompts, instructions,
|
|
63
|
+
test inputs, or action source.
|
|
64
|
+
- `amarsia.endpoint` (optional): Amarsia API URL for project sync. Defaults to
|
|
65
|
+
`AMARSIA_API_URL` and then `https://api.amarsia.com`.
|
|
66
|
+
- `actions` (optional): overrides the native local-action runtime or configures
|
|
67
|
+
its environment and sandbox settings.
|
|
68
|
+
- `storage.strategy` (optional): `"node-jsonl"` (default) or `"sqlite"`.
|
|
69
|
+
The SQLite driver ships as an internal optional Orcha dependency.
|
|
59
70
|
- `storage.directory` (optional): session directory relative to project
|
|
60
71
|
root; defaults to `.orcha/sessions`.
|
|
61
72
|
- `root` (optional): absolute or working-directory-relative project root;
|
|
@@ -363,7 +374,6 @@ actions/
|
|
|
363
374
|
{
|
|
364
375
|
"name": "lookup_account",
|
|
365
376
|
"description": "Look up one account.",
|
|
366
|
-
"execution": "local",
|
|
367
377
|
"parameters": {
|
|
368
378
|
"type": "object",
|
|
369
379
|
"properties": {
|
|
@@ -402,8 +412,10 @@ Action `index.json` fields:
|
|
|
402
412
|
- `name` (required): model-facing tool name, 1–64 letters, numbers,
|
|
403
413
|
underscores, or hyphens. `load_skill` is reserved.
|
|
404
414
|
- `description` (required): tells the model when and why to call the action.
|
|
405
|
-
- `
|
|
406
|
-
|
|
415
|
+
- `enabled` (optional): defaults to `true`. Set to `false` to keep a WIP
|
|
416
|
+
action inactive without deleting its folder.
|
|
417
|
+
- `execution` (optional): defaults to `"local"`, which executes `index.js`.
|
|
418
|
+
Set to `"client"` to pause and delegate execution to the application.
|
|
407
419
|
- `parameters` (required): JSON Schema for model-generated arguments.
|
|
408
420
|
- `outputSchema` (optional): JSON Schema validated against local or submitted
|
|
409
421
|
client output before the model receives it.
|
|
@@ -432,7 +444,7 @@ Global local-action configuration:
|
|
|
432
444
|
|
|
433
445
|
```ts
|
|
434
446
|
actions: {
|
|
435
|
-
runtime: "sandbox", //
|
|
447
|
+
runtime: "sandbox", // optional; native is the default
|
|
436
448
|
env: {
|
|
437
449
|
BILLING_API_TOKEN: process.env.BILLING_API_TOKEN,
|
|
438
450
|
},
|
|
@@ -450,18 +462,9 @@ allowlisted `env`, guarded `fetch`, and prefixed `log`.
|
|
|
450
462
|
|
|
451
463
|
## Skills
|
|
452
464
|
|
|
453
|
-
Skills are lazy-loaded procedural instructions.
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
// skills/index.js
|
|
457
|
-
import { defineSkills } from "orchajs/skills";
|
|
458
|
-
|
|
459
|
-
export default defineSkills({
|
|
460
|
-
incidentTriage: "./incidentTriage",
|
|
461
|
-
});
|
|
462
|
-
```
|
|
463
|
-
|
|
464
|
-
Each skill folder contains `index.json` metadata and `instructions.md`.
|
|
465
|
+
Skills are lazy-loaded procedural instructions. Direct child folders under
|
|
466
|
+
`skills/` are discovered automatically. Each folder contains `index.json`
|
|
467
|
+
metadata and `instructions.md`.
|
|
465
468
|
The model receives a compact catalog and can call the internal `load_skill`
|
|
466
469
|
tool. Loaded instructions remain active for the durable session. Lifecycle
|
|
467
470
|
events are `skill.requested`, `skill.loaded`, and `skill.failed`.
|
|
@@ -471,27 +474,19 @@ Skill `index.json` fields:
|
|
|
471
474
|
- `name` (required): model-facing name, 1–64 letters, numbers, underscores,
|
|
472
475
|
or hyphens; unique within the agent.
|
|
473
476
|
- `description` (required): compact catalog description shown before loading.
|
|
477
|
+
- `enabled` (optional): defaults to `true`. Set to `false` to keep a WIP
|
|
478
|
+
skill inactive.
|
|
474
479
|
- `triggers` (optional): non-empty array of non-empty situations describing
|
|
475
480
|
when the model should load the skill.
|
|
476
481
|
|
|
477
|
-
`instructions.md` is required and cannot be empty
|
|
478
|
-
`
|
|
479
|
-
name used by the model and durable events. Unregistered folders are ignored.
|
|
482
|
+
`instructions.md` is required and cannot be empty for enabled skills.
|
|
483
|
+
`index.json.name` is the name used by the model and durable events.
|
|
480
484
|
|
|
481
485
|
## Tests
|
|
482
486
|
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
import { defineTests } from "orchajs/testing";
|
|
487
|
-
|
|
488
|
-
export default defineTests({
|
|
489
|
-
activeAccount: "./activeAccount",
|
|
490
|
-
});
|
|
491
|
-
```
|
|
492
|
-
|
|
493
|
-
Each case's `index.json` defines `input`, optional mocked action responses,
|
|
494
|
-
and `expect`. Tests run the real compiled agent and provider. Actions listed
|
|
487
|
+
Direct child folders under `tests/` are discovered automatically. Each
|
|
488
|
+
case's `index.json` defines `input`, optional mocked action responses, and
|
|
489
|
+
`expect`. Tests run the real compiled agent and provider. Actions listed
|
|
495
490
|
under `actions` are mocked; unlisted local actions execute live. Orcha reports
|
|
496
491
|
live action use in the terminal, test report, and session trace.
|
|
497
492
|
Client actions must always be mocked because no application client is attached
|
|
@@ -526,7 +521,11 @@ through action-argument assertions.
|
|
|
526
521
|
|
|
527
522
|
Test `index.json` fields:
|
|
528
523
|
|
|
524
|
+
- `name` (optional): friendly display name. The folder name remains the CLI
|
|
525
|
+
selector.
|
|
529
526
|
- `description` (optional): human-readable purpose.
|
|
527
|
+
- `enabled` (optional): defaults to `true`. Set to `false` to keep a WIP test
|
|
528
|
+
inactive.
|
|
530
529
|
- `input` (required): an inline agent input object or a path to a JSON file
|
|
531
530
|
containing that object. Relative paths resolve from the test case directory.
|
|
532
531
|
- `input.content` (required for inline input): string or multimodal content
|
|
@@ -548,15 +547,13 @@ Test `index.json` fields:
|
|
|
548
547
|
- `expect.actions` (optional): ordered expected calls. Each may assert
|
|
549
548
|
`arguments.equals` or `arguments.partial`.
|
|
550
549
|
|
|
551
|
-
The
|
|
552
|
-
`orcha test agent/testName`; its value resolves to the case folder.
|
|
550
|
+
The test folder name is the selector used by `orcha test agent/testName`.
|
|
553
551
|
|
|
554
552
|
## Evaluations
|
|
555
553
|
|
|
556
|
-
Evaluations are asynchronous LLM judges
|
|
557
|
-
`evaluations
|
|
558
|
-
|
|
559
|
-
model, metrics, and thresholds:
|
|
554
|
+
Evaluations are asynchronous LLM judges discovered from direct child folders
|
|
555
|
+
under `evaluations/`. Each folder's `index.json` defines its provider, model,
|
|
556
|
+
metrics, and thresholds:
|
|
560
557
|
|
|
561
558
|
```json
|
|
562
559
|
{
|
|
@@ -589,8 +586,8 @@ Evaluation `index.json` fields:
|
|
|
589
586
|
- `description` (optional): short human-facing summary of the evaluator.
|
|
590
587
|
- `instructions` (optional): detailed prompt supplied to the judge. When
|
|
591
588
|
omitted, `description` is used for backward compatibility.
|
|
592
|
-
- `enabled` (optional): defaults to `true`. Disabled evaluations are
|
|
593
|
-
|
|
589
|
+
- `enabled` (optional): defaults to `true`. Disabled evaluations are ignored
|
|
590
|
+
by compilation and runtime.
|
|
594
591
|
- `provider` and `model` (required): independently select the judge. The
|
|
595
592
|
provider must also exist in `orcha.init().providers`.
|
|
596
593
|
- `maxTokens` (optional): positive integer; defaults to 2000 for judges.
|
|
@@ -610,9 +607,9 @@ string, and non-empty evidence array for every configured metric.
|
|
|
610
607
|
|
|
611
608
|
## Sessions and logs
|
|
612
609
|
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
`sequence`.
|
|
610
|
+
The configured session store is the durable source of truth. JSONL stores one
|
|
611
|
+
complete event object per line; SQLite stores one event per row. Events are
|
|
612
|
+
append-only and ordered by `sequence`.
|
|
616
613
|
|
|
617
614
|
All events use this envelope:
|
|
618
615
|
|
|
@@ -974,8 +971,9 @@ number. A conversational `resume(...content)` starts a new run number.
|
|
|
974
971
|
1. `orcha/index.ts` calls `orcha.init()` with explicit agent paths.
|
|
975
972
|
2. The compiler reads each registered agent's `index.json` and
|
|
976
973
|
`instructions.md`.
|
|
977
|
-
3.
|
|
978
|
-
evaluations are
|
|
974
|
+
3. Direct child folders under `actions/`, `skills/`, `tests/`, and
|
|
975
|
+
`evaluations/` are discovered automatically. Items with `"enabled": false`
|
|
976
|
+
remain inactive.
|
|
979
977
|
4. Local action source is bundled and SHA-256 hashed. Production bundles keep
|
|
980
978
|
only provider adapters required by agents and enabled evaluations.
|
|
981
979
|
5. Invalid paths, duplicate model-facing names, missing files, unsupported
|
|
@@ -1021,7 +1019,7 @@ cause `resume()` to fail spuriously or reuse sequence numbers.
|
|
|
1021
1019
|
|
|
1022
1020
|
### Replay and context
|
|
1023
1021
|
|
|
1024
|
-
Orcha does not send raw
|
|
1022
|
+
Orcha does not send raw stored events back to the model. It projects them
|
|
1025
1023
|
into provider-neutral conversation messages. Completed and explicitly paused
|
|
1026
1024
|
conversational runs become user, assistant, and tool messages, so a new run
|
|
1027
1025
|
sees incomplete assistant text preserved by `pause()`. Lifecycle bookkeeping
|
|
@@ -1056,7 +1054,8 @@ needed for faithful continuation but are omitted from evaluation transcripts.
|
|
|
1056
1054
|
|
|
1057
1055
|
## Change rules
|
|
1058
1056
|
|
|
1059
|
-
- Register every new agent
|
|
1057
|
+
- Register every new agent and subagent explicitly. Agent-owned actions, skills,
|
|
1058
|
+
tests, and evaluations are auto-discovered; use `"enabled": false` for WIP.
|
|
1060
1059
|
- Keep runtime behavior provider-neutral.
|
|
1061
1060
|
- Mock actions when tests must avoid side effects; document intentional live
|
|
1062
1061
|
action coverage.
|
package/template/orcha/index.ts
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
import { orcha } from "orchajs";
|
|
2
2
|
|
|
3
3
|
orcha.init({
|
|
4
|
+
amarsia: process.env.AMARSIA_PROJECT_KEY
|
|
5
|
+
? { key: process.env.AMARSIA_PROJECT_KEY }
|
|
6
|
+
: undefined,
|
|
4
7
|
providers: {
|
|
5
8
|
openai: process.env.OPENAI_API_KEY ?? "",
|
|
6
9
|
},
|
|
7
|
-
actions: {
|
|
8
|
-
runtime: "native",
|
|
9
|
-
},
|
|
10
10
|
agents: {
|
|
11
11
|
approvalAgent: "./approvalAgent",
|
|
12
12
|
assistant: {
|
package/template/package.json
CHANGED