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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-orcha",
3
- "version": "0.3.1",
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"
@@ -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 the registry and watches `orcha/**` for changes.
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 registered agent test.
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. Session logs are JSONL files under
24
- `.orcha/sessions/<agentName>/ses_<timestamp>_<uuid>.jsonl`.
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 folders are compiled. Agent keys become runtime properties
46
- such as `orcha.supportBot`. Use `actions.runtime: "sandbox"` for isolated
47
- local action execution or `"native"` when the application intentionally
48
- allows action modules to execute in its Node.js process.
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
- - `actions` (required only when a registered agent has local actions):
57
- selects the local execution runtime and its environment/sandbox settings.
58
- - `storage.strategy` (optional): currently only `"node-jsonl"`.
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
- - `execution` (required): `"local"` executes `index.js`; `"client"`
406
- pauses the run and delegates execution to the application.
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", // required when any registered action is local
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. Register only intended skills:
454
-
455
- ```js
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. The key in
478
- `skills/index.js` is only a registration label; `index.json.name` is the
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
- Register tests in `tests/index.js`:
484
-
485
- ```js
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 registration key in `tests/index.js` is the test selector used by
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 registered in
557
- `evaluations/index.js` with `defineEvaluations` from
558
- `orchajs/evaluations`. Each folder's `index.json` defines its provider,
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
- compiled but do not run.
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
- JSONL is the durable source of truth. Each line is one complete JSON object;
614
- never treat the file as one JSON array. Events are append-only and ordered by
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. Every directory under `actions/` is compiled. Skills, tests, and
978
- evaluations are included only through their local `index.js` registry.
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 JSONL back to the model. It projects durable events
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, skill, test, and evaluation explicitly.
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.
@@ -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: {
@@ -1,7 +1,6 @@
1
1
  {
2
2
  "name": "lookup_order",
3
3
  "description": "Look up the latest confirmed state of an order.",
4
- "execution": "local",
5
4
  "parameters": {
6
5
  "type": "object",
7
6
  "properties": {
@@ -15,6 +15,6 @@
15
15
  "orchajs": "__ORCHA_VERSION__"
16
16
  },
17
17
  "engines": {
18
- "node": ">=20.12"
18
+ "node": ">=18.20.8"
19
19
  }
20
20
  }
@@ -1,5 +0,0 @@
1
- import { defineEvaluations } from "orchajs/evaluations";
2
-
3
- export default defineEvaluations({
4
- approvalQuality: "./approvalQuality",
5
- });
@@ -1,5 +0,0 @@
1
- import { defineSkills } from "orchajs/skills";
2
-
3
- export default defineSkills({
4
- purchaseReview: "./purchaseReview",
5
- });
@@ -1,5 +0,0 @@
1
- import { defineTests } from "orchajs/testing";
2
-
3
- export default defineTests({
4
- approvedPurchase: "./approvedPurchase",
5
- });
@@ -1,5 +0,0 @@
1
- import { defineEvaluations } from "orchajs/evaluations";
2
-
3
- export default defineEvaluations({
4
- responseQuality: "./responseQuality",
5
- });
@@ -1,5 +0,0 @@
1
- import { defineSkills } from "orchajs/skills";
2
-
3
- export default defineSkills({
4
- technicalExplanation: "./technicalExplanation",
5
- });
@@ -1,5 +0,0 @@
1
- import { defineTests } from "orchajs/testing";
2
-
3
- export default defineTests({
4
- explainsIdempotency: "./explainsIdempotency",
5
- });
@@ -1,5 +0,0 @@
1
- import { defineEvaluations } from "orchajs/evaluations";
2
-
3
- export default defineEvaluations({
4
- supportQuality: "./supportQuality",
5
- });
@@ -1,5 +0,0 @@
1
- import { defineSkills } from "orchajs/skills";
2
-
3
- export default defineSkills({
4
- delayedOrderHandling: "./delayedOrderHandling",
5
- });
@@ -1,5 +0,0 @@
1
- import { defineTests } from "orchajs/testing";
2
-
3
- export default defineTests({
4
- delayedOrder: "./delayedOrder",
5
- });