create-orcha 0.1.6 → 0.2.0

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
@@ -1,7 +1,7 @@
1
1
  # create-orcha
2
2
 
3
- Create a complete OrchaJS application with example agents and a lightweight
4
- local playground.
3
+ Create a complete OrchaJS project with example agents and the built-in local
4
+ playground.
5
5
 
6
6
  ```bash
7
7
  npm create orcha@latest my-agent-app
@@ -11,8 +11,8 @@ npm install
11
11
 
12
12
  The generated project includes:
13
13
 
14
- - a Node.js and TypeScript application;
15
- - a framework-free HTML, CSS, and JavaScript playground;
14
+ - an Orcha agent registry with example agents;
15
+ - `orcha 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;
@@ -20,7 +20,7 @@ The generated project includes:
20
20
  - lazy-loaded skills;
21
21
  - deterministic agent tests;
22
22
  - model-graded evaluations;
23
- - production build and start commands.
23
+ - a production agent build command that excludes playground assets.
24
24
 
25
25
  ## Options
26
26
 
@@ -157,7 +157,7 @@ async function createProject(options) {
157
157
  console.log(" cp .env.example .env");
158
158
  console.log(" # Add OPENAI_API_KEY to .env");
159
159
  console.log(" npm run dev");
160
- console.log("\nThen open http://127.0.0.1:4310");
160
+ console.log("\nThen open http://localhost:4310");
161
161
  }
162
162
 
163
163
  async function main() {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-orcha",
3
- "version": "0.1.6",
3
+ "version": "0.2.0",
4
4
  "description": "Create a complete OrchaJS project with example agents and a local playground.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -1,30 +1,20 @@
1
- # Playground development guide
1
+ # Orcha project guide
2
2
 
3
- This is a dependency-light local interface for Orcha. Keep the browser
4
- framework-free and the server bound to localhost.
3
+ This project uses Orcha's built-in local playground. Application-specific
4
+ frontend or server code is not required.
5
5
 
6
6
  ## Architecture
7
7
 
8
8
  - `orcha/` contains registered agent source.
9
- - `src/server.ts` owns Orcha and exposes local API routes.
10
- - `public/` contains static HTML, CSS, and JavaScript.
11
9
  - `.orcha/sessions/` is the default Node JSONL storage directory and must not
12
- be committed. Application code must access sessions through agent methods,
13
- never through storage files.
14
-
15
- The execution endpoint streams newline-delimited JSON. Preserve the sequence:
16
- streaming snapshots, final result, then asynchronous evaluations. Client action
17
- results must be submitted with the exact returned `callId`.
10
+ be committed.
11
+ - `npm run dev` starts `orcha playground`, which watches `orcha/**`.
12
+ - `npm run build` creates only the production agent bundle; it does not include
13
+ the playground React application.
18
14
 
19
15
  Use the complete Orcha `AGENTS.md` generated by `orcha init` as the source of
20
16
  truth for agent configuration, actions, skills, tests, evaluations, and JSONL
21
17
  event schemas.
22
18
 
23
- ## Constraints
24
-
25
- - Do not add a frontend framework for basic interface work.
26
- - Do not expose provider credentials or action source to the browser.
27
- - Do not allow arbitrary filesystem paths through API routes.
28
- - Validate session ownership before serving raw logs.
29
- - Keep provider calls and filesystem access in the Node server.
30
- - Keep generated projects understandable without special infrastructure.
19
+ Provider credentials belong in `.env`. The standalone Orcha CLI loads that
20
+ file without overriding values already present in the process environment.
@@ -1,7 +1,7 @@
1
1
  # __PROJECT_NAME__
2
2
 
3
- A complete OrchaJS starter with example agents and a lightweight local
4
- playground for running them and inspecting their durable sessions.
3
+ A complete OrchaJS starter with example agents and the built-in local
4
+ playground for inspecting, testing, and running them.
5
5
 
6
6
  ## Get started
7
7
 
@@ -11,9 +11,7 @@ cp .env.example .env
11
11
  npm run dev
12
12
  ```
13
13
 
14
- The included Node.js scripts load `.env` before starting the application.
15
-
16
- Open [http://127.0.0.1:4310](http://127.0.0.1:4310).
14
+ Open [http://localhost:4310](http://localhost:4310).
17
15
 
18
16
  Try the general `assistant`, ask `orderSupport` about `ord_1001`, `ord_1002`,
19
17
  or an unknown order identifier, or ask `approvalAgent` to approve a purchase
@@ -31,26 +29,25 @@ to exercise the client-action pause and continuation flow.
31
29
  - Inspect parent and child session histories independently.
32
30
  - Submit results when an agent pauses for client actions.
33
31
  - Browse sessions and projected history.
34
- - Inspect usage, status, and canonical durable session events.
32
+ - Inspect usage, status, and chronological durable session traces.
35
33
  - Wait for and display asynchronous evaluations when configured.
36
34
  - Run the selected agent's registered model-backed tests with one click.
37
35
 
38
- The browser has no direct filesystem or provider access. A localhost-only Node
39
- server owns Orcha and exposes a small JSON/NDJSON API. There is no frontend
40
- framework, database, authentication layer, or hosted dependency.
36
+ The browser has no direct filesystem or provider access. `orcha playground`
37
+ binds to localhost, loads `.env`, watches `orcha/**`, and reports invalid edits
38
+ in the interface.
41
39
 
42
40
  ## Commands
43
41
 
44
42
  ```bash
45
- npm run dev # local server with file watching
46
- npm run build # production bundle
47
- npm start # run the production bundle
43
+ npm run dev # built-in playground with hot reload
44
+ npm run build # production agent bundle only
45
+ npm test # run all registered agent tests
48
46
  npm run orcha:dev # validate and watch the Orcha registry
49
47
  npm run orcha:test # run registered agent tests
50
48
  ```
51
49
 
52
50
  The default Node configuration stores sessions in
53
51
  `.orcha/sessions/<agentName>/ses_<timestamp>_<uuid>.jsonl`. The
54
- playground accesses parent sessions through `agent.list()`, `agent.get()`, and
55
- `agent.events()`, and child sessions through `agent.subagentHistory()`, so
56
- changing the storage adapter does not require UI or server changes.
52
+ playground accesses sessions through storage-neutral agent APIs, so changing
53
+ the storage adapter does not require generated application code.
@@ -8,6 +8,7 @@ files under `.orcha/`.
8
8
 
9
9
  - `orcha init` creates the initial Orcha files without overwriting files.
10
10
  - `orcha dev` validates the registry and watches `orcha/**` for changes.
11
+ - `orcha playground` opens the built-in local UI and hot reloads agent source.
11
12
  - `orcha run <agent> --input "…"` executes one registered agent.
12
13
  - `orcha run <agent> --input-file request.json` accepts structured input.
13
14
  - `orcha run <agent> --session <id> --input "…"` continues a session.
@@ -18,8 +19,8 @@ files under `.orcha/`.
18
19
  - `orcha build` creates the production Orcha bundle without calling models.
19
20
  - Add `--json` to `run` and `test` for machine-readable output.
20
21
 
21
- `run` and `test` use real providers and require credentials. `dev` and
22
- `build` are offline. Session logs are JSONL files under
22
+ `run`, `test`, and playground executions use real providers and require
23
+ credentials. `dev` and `build` are offline. Session logs are JSONL files under
23
24
  `.orcha/sessions/<agentName>/ses_<timestamp>_<uuid>.jsonl`.
24
25
 
25
26
  ## Registry
@@ -1024,6 +1025,8 @@ needed for faithful continuation but are omitted from evaluation transcripts.
1024
1025
  - `agent.subagentHistory(childSessionId, { page, pageSize })` returns the
1025
1026
  projected history of a child owned by this parent agent. Lineage checks
1026
1027
  prevent access through unrelated agents.
1028
+ - `agent.subagentEvents(childSessionId, { page, pageSize })` returns that
1029
+ owned child's canonical events for full transcript and debugging interfaces.
1027
1030
  - `agent.pause(sessionId)` aborts active provider work for the session and
1028
1031
  active children, preserving streamed text as an incomplete assistant
1029
1032
  message. `agent.resume(sessionId)` starts a new run with `"Continue."`;
@@ -4,22 +4,17 @@
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "scripts": {
7
- "dev": "node --env-file=.env --import tsx --watch src/server.ts",
8
- "build": "node scripts/build.mjs",
9
- "start": "node --env-file=.env dist/server.js",
7
+ "dev": "orcha playground",
8
+ "playground": "orcha playground",
9
+ "build": "orcha build",
10
+ "test": "orcha test",
10
11
  "orcha:dev": "orcha dev",
11
12
  "orcha:test": "orcha test"
12
13
  },
13
14
  "dependencies": {
14
15
  "orchajs": "__ORCHA_VERSION__"
15
16
  },
16
- "devDependencies": {
17
- "@types/node": "^24.3.1",
18
- "esbuild": "^0.25.9",
19
- "tsx": "^4.20.5",
20
- "typescript": "^5.9.2"
21
- },
22
17
  "engines": {
23
- "node": ">=20"
18
+ "node": ">=20.12"
24
19
  }
25
20
  }
@@ -1,49 +0,0 @@
1
- {
2
- "agents": {
3
- "approvalAgent": {
4
- "description": "Review purchase requests through an application-owned human approval step.",
5
- "examples": [
6
- {
7
- "label": "Request purchase approval",
8
- "content": "Request approval for a 1250 USD annual observability subscription needed by the platform team."
9
- }
10
- ]
11
- },
12
- "assistant": {
13
- "description": "Answer general questions while keeping confirmed facts separate from assumptions.",
14
- "examples": [
15
- {
16
- "label": "Explain a technical concept",
17
- "content": "Explain idempotency in APIs with one practical example."
18
- },
19
- {
20
- "label": "Multimodal content",
21
- "content": [
22
- {
23
- "type": "text",
24
- "text": "Describe the important information in this image."
25
- },
26
- {
27
- "type": "image",
28
- "mimeType": "image/png",
29
- "fileUri": "https://raw.githubusercontent.com/github/explore/main/topics/nodejs/nodejs.png"
30
- }
31
- ]
32
- }
33
- ]
34
- },
35
- "orderSupport": {
36
- "description": "Look up confirmed order data and explain its status and operational next step.",
37
- "examples": [
38
- {
39
- "label": "Track an in-transit order",
40
- "content": "Where is order ord_1001?"
41
- },
42
- {
43
- "label": "Investigate a delayed order",
44
- "content": "Order ord_1002 has not arrived. What happened and what happens next?"
45
- }
46
- ]
47
- }
48
- }
49
- }