@orchestraworks/local 0.0.134 → 0.0.136

package/README.md

@@ -1,38 +1,32 @@
-# The local environment
-
-One Go program serves the one-agent subset of the platform API on a developer's own machine, so a real
-instance of their agent runs against it before anything reaches the cloud. This tree is that program,
-and it is also the `@orchestraworks/local` npm package: the launcher on the path, and one per-platform
-package carrying the binary for the machine it is installed on.
-
-It is always its own process. `worker run` starts none of it, and it refuses to start inside a machine:
-a machine's job is to be the thing under test, never to serve the platform it claims against.
-
-## The tree
-
-| path | what it holds |
-|---|---|
-| `cmd/orchestra-local/` | the one binary: `serve`, `bootstrap`, `version` |
-| `api/` | the subset the stack serves — agents, environments, skills, files, artifacts, sessions with their items, enrollment — and the refusal every other route answers with |
-| `identity/` | the binding document's four identity exchanges, and the enrollment offers this run mints and redeems itself |
-| `listen/` | the four listeners: the developer's loopback plain http, the machine-facing https on this run's own certificate, the authority beside it, and the broker |
-| `broker/` | the embedded NATS with the work stream every machine's consumer pulls from, so nothing else has to run |
-| `store/` | the run folder under the CLI's config directory, its SQLite file, and the record naming the current run |
-| `objectstore/` | the presigned GET and PUT the worker understands, and the bytes behind a broker-delivered locator |
-| `machine/` | the bus side: the register answered, each machine's consumer kept, the placement commands stored and their answers taken |
-| `launch/` | the three machine kinds: the Docker launch, the image inspection and the check inside it, admission, the bootstrap set and the model key |
-| `manifest/` | the manifest the platform composes, every byte-carrying item a presigned locator |
-| `session/` | the turn: sessions and items, one open turn per session, the interrupt and the set-only claim |
-| `fold/` | the item fold and the transcript, in the console's own item vocabulary |
-| `bin/orchestra-local.js` | the npm launcher: it runs the binary out of the per-platform package installed for this machine, stays in front of it, and forwards the signal it is ended with. Its own tests sit beside it and are not packed |
-| `npm/<platform>/` | the four per-platform packages, one per release target, each carrying one binary |
-
-## Building it
+# @orchestraworks/local
 
+The local environment runs one real instance of your agent on your own computer, so you can try it before anything reaches the cloud.
+
+## Install
+
+The Orchestra CLI installs this package as an optional dependency. To install it alone:
+
+```bash
+npm install -g @orchestraworks/local
 ```
-make build     # one static binary per release package, into npm/<platform>/
-go test ./...  # the module's own suite
+
+## Quick start
+
+The machines it starts run in Docker, so Docker must be running. Use the CLI to start, check and stop the local environment:
+
+```bash
+npm install -g @orchestraworks/cli
+orchestra local up        # start it and print the two lines a shell needs to reach it
+orchestra local status    # read the four checks: boot, content, turns and environment
+orchestra local down      # stop it and the machines it started
 ```
 
-The stack is published at the worker's version rather than at the CLI's: the worker version an image
-carries is what the stack refuses an image for not carrying, so the two move together.
+## For coding agents
+
+- `orchestra local --help` lists the commands. `orchestra local <command> --help` gives their flags.
+- `skills/orchestra-fdk/references/authoring.md` in `@orchestraworks/cli` explains how to run an agent here before the cloud.
+- [docs/REFERENCE.md](docs/REFERENCE.md): what each part of this program does, and how to build it.
+
+## License
+
+Apache License 2.0. The full text is in [LICENSE](LICENSE).

package/docs/REFERENCE.md

@@ -0,0 +1,40 @@
+# The local environment: the full reference
+
+The short introduction is the package [README](../README.md). Paths below are relative to the `local/` folder.
+
+One Go program serves the one-agent subset of the platform API on a developer's own machine, so a real
+instance of their agent runs against it before anything reaches the cloud. This tree is that program,
+and it is also the `@orchestraworks/local` npm package: the launcher on the path, and one per-platform
+package carrying the binary for the machine it is installed on.
+
+It is always its own process. `worker run` starts none of it, and it refuses to start inside a machine:
+a machine's job is to be the thing under test, never to serve the platform it claims against.
+
+## The tree
+
+| path | what it holds |
+|---|---|
+| `cmd/orchestra-local/` | the one binary: `serve`, `bootstrap`, `version` |
+| `api/` | the subset the stack serves — agents, environments, skills, files, artifacts, sessions with their items, enrollment — and the refusal every other route answers with |
+| `identity/` | the binding document's four identity exchanges, and the enrollment offers this run mints and redeems itself |
+| `listen/` | the four listeners: the developer's loopback plain http, the machine-facing https on this run's own certificate, the authority beside it, and the broker |
+| `broker/` | the embedded NATS with the work stream every machine's consumer pulls from, so nothing else has to run |
+| `store/` | the run folder under the CLI's config directory, its SQLite file, and the record naming the current run |
+| `objectstore/` | the presigned GET and PUT the worker understands, and the bytes behind a broker-delivered locator |
+| `machine/` | the bus side: the register answered, each machine's consumer kept, the placement commands stored and their answers taken |
+| `launch/` | the three machine kinds: the Docker launch, the image inspection and the check inside it, admission, the bootstrap set and the model key |
+| `manifest/` | the manifest the platform composes, every byte-carrying item a presigned locator |
+| `session/` | the turn: sessions and items, one open turn per session, the interrupt and the set-only claim |
+| `fold/` | the item fold and the transcript, in the console's own item vocabulary |
+| `bin/orchestra-local.js` | the npm launcher: it runs the binary out of the per-platform package installed for this machine, stays in front of it, and forwards the signal it is ended with. Its own tests sit beside it and are not packed |
+| `npm/<platform>/` | the four per-platform packages, one per release target, each carrying one binary |
+
+## Building it
+
+```
+make build     # one static binary per release package, into npm/<platform>/
+go test ./...  # the module's own suite
+```
+
+The stack is published at the worker's version rather than at the CLI's: the worker version an image
+carries is what the stack refuses an image for not carrying, so the two move together.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@orchestraworks/local",
-  "version": "0.0.134",
+  "version": "0.0.136",
   "type": "module",
-  "description": "The Software Factory local environment: one process a developer runs a real instance of their agent against on their own machine.",
+  "description": "Run your Orchestra agent on your own computer.",
   "license": "Apache-2.0",
   "author": "Living Computers",
   "homepage": "https://orchestraworks.ai",
@@ -18,12 +18,13 @@
   },
   "files": [
     "bin",
-    "README.md"
+    "README.md",
+    "docs/REFERENCE.md"
   ],
   "optionalDependencies": {
-    "@orchestraworks/local-linux-x64": "0.0.134",
-    "@orchestraworks/local-linux-arm64": "0.0.134",
-    "@orchestraworks/local-darwin-x64": "0.0.134",
-    "@orchestraworks/local-darwin-arm64": "0.0.134"
+    "@orchestraworks/local-linux-x64": "0.0.136",
+    "@orchestraworks/local-linux-arm64": "0.0.136",
+    "@orchestraworks/local-darwin-x64": "0.0.136",
+    "@orchestraworks/local-darwin-arm64": "0.0.136"
   }
 }