create-orcha 0.1.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.
Files changed (48) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +32 -0
  3. package/bin/create-orcha.js +177 -0
  4. package/package.json +41 -0
  5. package/template/.env.example +2 -0
  6. package/template/AGENTS.md +30 -0
  7. package/template/README.md +50 -0
  8. package/template/orcha/AGENTS.md +913 -0
  9. package/template/orcha/approvalAgent/actions/requestHumanApproval/index.json +25 -0
  10. package/template/orcha/approvalAgent/evaluations/approvalQuality/index.json +22 -0
  11. package/template/orcha/approvalAgent/evaluations/index.js +5 -0
  12. package/template/orcha/approvalAgent/index.json +7 -0
  13. package/template/orcha/approvalAgent/instructions.md +5 -0
  14. package/template/orcha/approvalAgent/skills/index.js +5 -0
  15. package/template/orcha/approvalAgent/skills/purchaseReview/index.json +8 -0
  16. package/template/orcha/approvalAgent/skills/purchaseReview/instructions.md +5 -0
  17. package/template/orcha/approvalAgent/tests/approvedPurchase/index.json +36 -0
  18. package/template/orcha/approvalAgent/tests/index.js +5 -0
  19. package/template/orcha/assistant/evaluations/index.js +5 -0
  20. package/template/orcha/assistant/evaluations/responseQuality/index.json +22 -0
  21. package/template/orcha/assistant/index.json +7 -0
  22. package/template/orcha/assistant/instructions.md +4 -0
  23. package/template/orcha/assistant/skills/index.js +5 -0
  24. package/template/orcha/assistant/skills/technicalExplanation/index.json +8 -0
  25. package/template/orcha/assistant/skills/technicalExplanation/instructions.md +6 -0
  26. package/template/orcha/assistant/tests/explainsIdempotency/index.json +15 -0
  27. package/template/orcha/assistant/tests/index.js +5 -0
  28. package/template/orcha/index.ts +15 -0
  29. package/template/orcha/orderSupport/actions/lookupOrder/index.js +25 -0
  30. package/template/orcha/orderSupport/actions/lookupOrder/index.json +29 -0
  31. package/template/orcha/orderSupport/evaluations/index.js +5 -0
  32. package/template/orcha/orderSupport/evaluations/supportQuality/index.json +22 -0
  33. package/template/orcha/orderSupport/index.json +7 -0
  34. package/template/orcha/orderSupport/instructions.md +5 -0
  35. package/template/orcha/orderSupport/skills/delayedOrderHandling/index.json +8 -0
  36. package/template/orcha/orderSupport/skills/delayedOrderHandling/instructions.md +6 -0
  37. package/template/orcha/orderSupport/skills/index.js +5 -0
  38. package/template/orcha/orderSupport/tests/delayedOrder/index.json +37 -0
  39. package/template/orcha/orderSupport/tests/index.js +5 -0
  40. package/template/package.json +25 -0
  41. package/template/playground.json +49 -0
  42. package/template/public/app.js +1234 -0
  43. package/template/public/index.html +210 -0
  44. package/template/public/orcha-logo.svg +4 -0
  45. package/template/public/styles.css +548 -0
  46. package/template/scripts/build.mjs +20 -0
  47. package/template/src/server.ts +478 -0
  48. package/template/tsconfig.json +12 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Amarsia
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,32 @@
1
+ # create-orcha
2
+
3
+ Create a complete OrchaJS application with example agents and a lightweight
4
+ local playground.
5
+
6
+ ```bash
7
+ npm create orcha@latest my-agent-app
8
+ cd my-agent-app
9
+ npm install
10
+ ```
11
+
12
+ The generated project includes:
13
+
14
+ - a Node.js and TypeScript application;
15
+ - a framework-free HTML, CSS, and JavaScript playground;
16
+ - text and multimodal agent input;
17
+ - durable sessions and chronological execution traces;
18
+ - server and client actions;
19
+ - lazy-loaded skills;
20
+ - deterministic agent tests;
21
+ - model-graded evaluations;
22
+ - production build and start commands.
23
+
24
+ ## Options
25
+
26
+ ```text
27
+ --no-git Do not initialize a Git repository
28
+ -h, --help Show help
29
+ ```
30
+
31
+ The CLI only writes project source files. It does not install dependencies or
32
+ generate `node_modules`, and it never overwrites a non-empty directory.
@@ -0,0 +1,177 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { existsSync } from "node:fs";
4
+ import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
5
+ import { dirname, join, parse, resolve } from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+ import { spawnSync } from "node:child_process";
8
+
9
+ const packageDirectory = resolve(dirname(fileURLToPath(import.meta.url)), "..");
10
+ const templateDirectory = join(packageDirectory, "template");
11
+
12
+ const HELP = `Create a complete OrchaJS project.
13
+
14
+ Usage:
15
+ create-orcha <project-directory> [options]
16
+
17
+ Options:
18
+ --no-git Do not initialize a Git repository
19
+ -h, --help Show this help
20
+
21
+ Examples:
22
+ npm create orcha@latest my-agent-app
23
+ npx create-orcha my-agent-app
24
+ create-orcha .
25
+ `;
26
+
27
+ function parseArguments(arguments_) {
28
+ const options = { git: true };
29
+ const positional = [];
30
+
31
+ for (const argument of arguments_) {
32
+ if (argument === "-h" || argument === "--help") {
33
+ options.help = true;
34
+ } else if (argument === "--no-git") {
35
+ options.git = false;
36
+ } else if (argument.startsWith("-")) {
37
+ throw new Error(`Unknown option: ${argument}`);
38
+ } else {
39
+ positional.push(argument);
40
+ }
41
+ }
42
+
43
+ if (positional.length > 1) {
44
+ throw new Error("Provide exactly one project directory.");
45
+ }
46
+
47
+ return { ...options, projectDirectory: positional[0] };
48
+ }
49
+
50
+ function packageNameFromDirectory(directory) {
51
+ const name = parse(directory).base
52
+ .trim()
53
+ .toLowerCase()
54
+ .replace(/[^a-z0-9._-]+/g, "-")
55
+ .replace(/^[._-]+|[._-]+$/g, "");
56
+
57
+ if (!name) {
58
+ throw new Error("The project directory must produce a valid npm package name.");
59
+ }
60
+
61
+ return name;
62
+ }
63
+
64
+ async function assertWritableTarget(targetDirectory) {
65
+ if (!existsSync(targetDirectory)) {
66
+ return false;
67
+ }
68
+
69
+ const entries = await readdir(targetDirectory);
70
+ if (entries.length > 0) {
71
+ throw new Error(`Target directory is not empty: ${targetDirectory}`);
72
+ }
73
+
74
+ return true;
75
+ }
76
+
77
+ function run(command, arguments_, cwd, quiet = false) {
78
+ return spawnSync(command, arguments_, {
79
+ cwd,
80
+ encoding: "utf8",
81
+ stdio: quiet ? "pipe" : "inherit",
82
+ });
83
+ }
84
+
85
+ function isInsideGitRepository(directory) {
86
+ const result = run("git", ["-C", directory, "rev-parse", "--is-inside-work-tree"], directory, true);
87
+ return result.status === 0 && result.stdout.trim() === "true";
88
+ }
89
+
90
+ function initializeGit(targetDirectory) {
91
+ if (isInsideGitRepository(dirname(targetDirectory))) {
92
+ return false;
93
+ }
94
+
95
+ const result = run("git", ["init"], targetDirectory, true);
96
+ return result.status === 0;
97
+ }
98
+
99
+ async function configureProject(targetDirectory, projectName, orchaVersion) {
100
+ const packagePath = join(targetDirectory, "package.json");
101
+ const readmePath = join(targetDirectory, "README.md");
102
+ const packageTemplate = await readFile(packagePath, "utf8");
103
+ const readmeTemplate = await readFile(readmePath, "utf8");
104
+
105
+ await Promise.all([
106
+ writeFile(
107
+ packagePath,
108
+ `${packageTemplate
109
+ .replaceAll("__PROJECT_NAME__", projectName)
110
+ .replaceAll("__ORCHA_VERSION__", orchaVersion)
111
+ .trim()}\n`,
112
+ ),
113
+ writeFile(readmePath, readmeTemplate.replaceAll("__PROJECT_NAME__", projectName)),
114
+ ]);
115
+ }
116
+
117
+ async function createProject(options) {
118
+ if (!options.projectDirectory) {
119
+ throw new Error(`Missing project directory.\n\n${HELP}`);
120
+ }
121
+
122
+ const targetDirectory = resolve(options.projectDirectory);
123
+ if (targetDirectory === parse(targetDirectory).root) {
124
+ throw new Error("Refusing to create a project at the filesystem root.");
125
+ }
126
+
127
+ const targetExisted = await assertWritableTarget(targetDirectory);
128
+ const projectName = packageNameFromDirectory(targetDirectory);
129
+ const packageMetadata = JSON.parse(
130
+ await readFile(join(packageDirectory, "package.json"), "utf8"),
131
+ );
132
+
133
+ await mkdir(targetDirectory, { recursive: true });
134
+
135
+ try {
136
+ await cp(templateDirectory, targetDirectory, { recursive: true });
137
+ await configureProject(targetDirectory, projectName, packageMetadata.orchaVersion);
138
+ } catch (error) {
139
+ if (!targetExisted) {
140
+ await rm(targetDirectory, { recursive: true, force: true });
141
+ }
142
+ throw error;
143
+ }
144
+
145
+ const initializedGit = options.git && initializeGit(targetDirectory);
146
+ const relativeTarget = resolve(".") === targetDirectory ? "." : options.projectDirectory;
147
+
148
+ console.log(`\nCreated ${projectName} at ${targetDirectory}`);
149
+ if (initializedGit) {
150
+ console.log("Initialized an empty Git repository.");
151
+ }
152
+ console.log("\nNext steps:");
153
+ if (relativeTarget !== ".") {
154
+ console.log(` cd ${relativeTarget}`);
155
+ }
156
+ console.log(" npm install");
157
+ console.log(" cp .env.example .env");
158
+ console.log(" # Add OPENAI_API_KEY to .env");
159
+ console.log(" npm run dev");
160
+ console.log("\nThen open http://127.0.0.1:4310");
161
+ }
162
+
163
+ async function main() {
164
+ try {
165
+ const options = parseArguments(process.argv.slice(2));
166
+ if (options.help) {
167
+ console.log(HELP);
168
+ return;
169
+ }
170
+ await createProject(options);
171
+ } catch (error) {
172
+ console.error(`\ncreate-orcha: ${error instanceof Error ? error.message : String(error)}`);
173
+ process.exitCode = 1;
174
+ }
175
+ }
176
+
177
+ await main();
package/package.json ADDED
@@ -0,0 +1,41 @@
1
+ {
2
+ "name": "create-orcha",
3
+ "version": "0.1.0",
4
+ "description": "Create a complete OrchaJS project with example agents and a local playground.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/Amarsia/orcha.git",
10
+ "directory": "packages/create-orcha"
11
+ },
12
+ "homepage": "https://orcha.sh",
13
+ "bugs": {
14
+ "url": "https://github.com/Amarsia/orcha/issues"
15
+ },
16
+ "keywords": [
17
+ "ai",
18
+ "agents",
19
+ "orcha",
20
+ "scaffold"
21
+ ],
22
+ "bin": {
23
+ "create-orcha": "./bin/create-orcha.js"
24
+ },
25
+ "files": [
26
+ "bin",
27
+ "template",
28
+ "README.md",
29
+ "LICENSE"
30
+ ],
31
+ "scripts": {
32
+ "test": "node --test"
33
+ },
34
+ "engines": {
35
+ "node": ">=20"
36
+ },
37
+ "publishConfig": {
38
+ "access": "public"
39
+ },
40
+ "orchaVersion": "^0.5.0"
41
+ }
@@ -0,0 +1,2 @@
1
+ OPENAI_API_KEY=
2
+ PORT=4310
@@ -0,0 +1,30 @@
1
+ # Playground development guide
2
+
3
+ This is a dependency-light local interface for Orcha. Keep the browser
4
+ framework-free and the server bound to localhost.
5
+
6
+ ## Architecture
7
+
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
+ - `.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`.
18
+
19
+ Use the complete Orcha `AGENTS.md` generated by `orcha init` as the source of
20
+ truth for agent configuration, actions, skills, tests, evaluations, and JSONL
21
+ event schemas.
22
+
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.
@@ -0,0 +1,50 @@
1
+ # __PROJECT_NAME__
2
+
3
+ A complete OrchaJS starter with example agents and a lightweight local
4
+ playground for running them and inspecting their durable sessions.
5
+
6
+ ## Get started
7
+
8
+ ```bash
9
+ cp .env.example .env
10
+ # Add OPENAI_API_KEY to .env
11
+ npm run dev
12
+ ```
13
+
14
+ Open [http://127.0.0.1:4310](http://127.0.0.1:4310).
15
+
16
+ Try the general `assistant`, ask `orderSupport` about `ord_1001`, `ord_1002`,
17
+ or an unknown order identifier, or ask `approvalAgent` to approve a purchase
18
+ to exercise the client-action pause and continuation flow.
19
+
20
+ ## Included workflows
21
+
22
+ - List registered agents and their capabilities.
23
+ - Inspect model configuration, actions, skills, and evaluations.
24
+ - Start runs from text or a complete multimodal `MessageContent[]` JSON array.
25
+ - Start a durable run and stream cumulative output.
26
+ - Continue an existing session with another message.
27
+ - Submit results when an agent pauses for client actions.
28
+ - Browse sessions and projected history.
29
+ - Inspect usage, status, and canonical durable session events.
30
+ - Wait for and display asynchronous evaluations when configured.
31
+ - Run the selected agent's registered model-backed tests with one click.
32
+
33
+ The browser has no direct filesystem or provider access. A localhost-only Node
34
+ server owns Orcha and exposes a small JSON/NDJSON API. There is no frontend
35
+ framework, database, authentication layer, or hosted dependency.
36
+
37
+ ## Commands
38
+
39
+ ```bash
40
+ npm run dev # local server with file watching
41
+ npm run build # production bundle
42
+ npm start # run the production bundle
43
+ npm run orcha:dev # validate and watch the Orcha registry
44
+ npm run orcha:test # run registered agent tests
45
+ ```
46
+
47
+ The default Node configuration stores sessions in `.orcha/sessions`. The
48
+ playground accesses sessions exclusively through `agent.list()`, `agent.get()`,
49
+ and `agent.events()`, so changing the storage adapter does not require UI or
50
+ server changes.