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.
- package/LICENSE +21 -0
- package/README.md +32 -0
- package/bin/create-orcha.js +177 -0
- package/package.json +41 -0
- package/template/.env.example +2 -0
- package/template/AGENTS.md +30 -0
- package/template/README.md +50 -0
- package/template/orcha/AGENTS.md +913 -0
- package/template/orcha/approvalAgent/actions/requestHumanApproval/index.json +25 -0
- package/template/orcha/approvalAgent/evaluations/approvalQuality/index.json +22 -0
- package/template/orcha/approvalAgent/evaluations/index.js +5 -0
- package/template/orcha/approvalAgent/index.json +7 -0
- package/template/orcha/approvalAgent/instructions.md +5 -0
- package/template/orcha/approvalAgent/skills/index.js +5 -0
- package/template/orcha/approvalAgent/skills/purchaseReview/index.json +8 -0
- package/template/orcha/approvalAgent/skills/purchaseReview/instructions.md +5 -0
- package/template/orcha/approvalAgent/tests/approvedPurchase/index.json +36 -0
- package/template/orcha/approvalAgent/tests/index.js +5 -0
- package/template/orcha/assistant/evaluations/index.js +5 -0
- package/template/orcha/assistant/evaluations/responseQuality/index.json +22 -0
- package/template/orcha/assistant/index.json +7 -0
- package/template/orcha/assistant/instructions.md +4 -0
- package/template/orcha/assistant/skills/index.js +5 -0
- package/template/orcha/assistant/skills/technicalExplanation/index.json +8 -0
- package/template/orcha/assistant/skills/technicalExplanation/instructions.md +6 -0
- package/template/orcha/assistant/tests/explainsIdempotency/index.json +15 -0
- package/template/orcha/assistant/tests/index.js +5 -0
- package/template/orcha/index.ts +15 -0
- package/template/orcha/orderSupport/actions/lookupOrder/index.js +25 -0
- package/template/orcha/orderSupport/actions/lookupOrder/index.json +29 -0
- package/template/orcha/orderSupport/evaluations/index.js +5 -0
- package/template/orcha/orderSupport/evaluations/supportQuality/index.json +22 -0
- package/template/orcha/orderSupport/index.json +7 -0
- package/template/orcha/orderSupport/instructions.md +5 -0
- package/template/orcha/orderSupport/skills/delayedOrderHandling/index.json +8 -0
- package/template/orcha/orderSupport/skills/delayedOrderHandling/instructions.md +6 -0
- package/template/orcha/orderSupport/skills/index.js +5 -0
- package/template/orcha/orderSupport/tests/delayedOrder/index.json +37 -0
- package/template/orcha/orderSupport/tests/index.js +5 -0
- package/template/package.json +25 -0
- package/template/playground.json +49 -0
- package/template/public/app.js +1234 -0
- package/template/public/index.html +210 -0
- package/template/public/orcha-logo.svg +4 -0
- package/template/public/styles.css +548 -0
- package/template/scripts/build.mjs +20 -0
- package/template/src/server.ts +478 -0
- 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,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.
|