@orchestraworks/cli 0.5.7 → 0.6.0

package/skills/orchestra-fdk/references/environment.md

@@ -219,7 +219,7 @@ the `agent` user. The worker writes a sign-in file only when none is there, so t
 **Before any cloud apply,** search `<factory>` for that marker, and for any credential in the setup script,
 in the environment's settings (`ENV`, which becomes `provisionSpec.env`), in the agents' instructions, and
 in every work-item description you write. Remove each one. Use a Secret
-instead: a gateway key, or a Secret whose `hosts` name where the edge adds it. Tell the developer why: the setup script and
+instead: a gateway key, or a Secret whose recipe's `hosts` name where the edge adds it. Tell the developer why: the setup script and
 the settings are stored as plain text and shown on every read.
 
 ### Start the local environment
@@ -318,7 +318,7 @@ The local key is never carried over. It stays on the developer's computer. In th
 Orchestra Secret, and our network edge adds it to each model call, so no machine and no person holds it:
 
 - For the gateway, `apply` creates the gateway key and its secret. The starter already declares them.
-- For a subscription token or a provider key, declare a Secret whose `hosts` name the provider's host, and a
+- For a subscription token or a provider key, declare a Secret whose recipe's `hosts` name the provider's host, and a
   rule that opens that host, as phase 2 of the orchestra-fdk skill, "The model route", says (orchestra skill,
   sections 6 and 7).
 
@@ -378,12 +378,15 @@ into `orchestra-factory-notes.md`.
    captured Windows VM does not register. The worker's own command, `worker install-machine --cloud
    azure`, adds the three parts the image must contain. The section "A team's own image" below gives the
    steps:
-   - The worker's release package, at `C:\ProgramData\sfdk\worker\package`.
-   - The worker's Windows service, `SfdkWorker`. It runs `worker.exe run --root C:\ProgramData\sfdk\worker
+   - The worker's release package, at `C:\ProgramData\orchestra\worker\package`.
+   - The worker's Windows service, `OrchestraWorker`. It runs `worker.exe run --root C:\ProgramData\orchestra\worker
      --service` as LocalSystem. It is demand-start (`Manual`), not automatic. On a failure it restarts
      three times, 2 seconds apart, and a clean stop with a non-zero exit code counts as a failure.
    - The startup task `orchestra-azure-userdata`. It runs `worker.exe boot-files --cloud azure` as SYSTEM
-     at each boot. It writes the files that the VM's startup data carries, then starts `SfdkWorker`.
+     at each boot. It writes the files that the VM's startup data carries, then starts `OrchestraWorker`.
+   - An install replaces the service an earlier release registered as `SfdkWorker`. Change your own
+     scripts that name it. On an image an earlier release built, the startup task still starts
+     `SfdkWorker`.
 
    Our image runs the same command, from `install-vm-runtime.ps1` and the image template
    `infra/packer/azure-windows-runtime.pkr.hcl`. Under a Launcher, the image needs no WinDivert, no
@@ -463,7 +466,7 @@ agent can run the team's own `docker compose up` unchanged.
    *machine endpoint*, a web address that only signed-in members of the organization can open.
 4. Write the app's own settings files (`.env.local`) into the Set up item's description, because the code
    is not on the machine when the setup script runs. Put only local or test values there. A real secret
-   becomes a Secret whose `hosts` name where the edge adds it.
+   becomes a Secret whose recipe's `hosts` name where the edge adds it.
 5. Choose the size by what CI uses for the same work. The template's sizes are fixed per agent: lg is
    32 CPU, md 16, sm 2.
 6. When the project runs containers, keep the disk at `/var/lib/docker`. The starter declares it. It keeps
@@ -650,8 +653,8 @@ failure stops the run and names the step. The team can run it again.
 - It refuses a VM that has already run as a machine, and a running worker service. Build on a new VM.
 - On Windows it creates the worker's folders for SYSTEM and the administrators only, so other accounts on
   the VM cannot add programs or read the boot files.
-- It copies the worker's package to the machine-wide root, `C:\ProgramData\sfdk\worker` or
-  `/var/lib/sfdk/worker`.
+- It copies the worker's package to the machine-wide root, `C:\ProgramData\orchestra\worker` or
+  `/var/lib/orchestra/worker`.
 - On Linux it creates the `agent` account, uid 1000, home `/home`.
 - It defines the worker's service, and the startup task that writes the boot files and starts the worker.
 - `--harness claude` preinstalls a harness. Without it, the harness installs itself on its first turn.
@@ -691,7 +694,7 @@ a Launcher machine, and the team installs their own tools.
    After each restart, run the check. Stop when it shows `"restartPending":false`:
 
    ```powershell
-   & "$env:ProgramData\sfdk\worker\package\worker.exe" check --profile launcher --output json
+   & "$env:ProgramData\orchestra\worker\package\worker.exe" check --profile launcher --output json
    ```
 
 6. Generalize with Sysprep. It takes about 4 minutes, and the VM then stops:
@@ -815,8 +818,8 @@ Tokens on a compute provider's machines:
      carries them. Tell the developer this. If it is not acceptable, use route 2 or 3, or a Secret added
      at our network edge where one stands in front.
   2. **Baked into the team's image**, at machine scope, before Sysprep or generalizing. On Windows, that
-     is the `SfdkWorker` service's `Environment` registry value. On Linux, it is a drop-in on
-     `sfdk-worker.service`.
+     is the `OrchestraWorker` service's `Environment` registry value. On Linux, it is a drop-in on
+     `orchestra-worker.service`.
   3. **The `onStartAgent` hook** writes the harness's own key file in the agent's home:
      `.claude/.credentials.json` for a Claude sign-in, `.codex/auth.json` for `codex`, or
      `.pi/agent/auth.json` for `pi`. The worker keeps a real value it finds there. The hook can read the
@@ -870,6 +873,40 @@ that need no private service.
 **Check:** the typecheck and the synth pass, and the plan is as in item 3. Go back to the orchestra-fdk
 skill's phase 4 for the apply.
 
+### Naming a credential
+
+The network edge adds a credential to a request in two cases only. A request that names none and that no
+environment default covers leaves with the headers it was sent, a placeholder included.
+
+- **The request names it.** Set the variable a tool reads its token from to a `Secret` or a `Connection`
+  in the environment's `env`. Apply writes `orchestra:secret/<id>` or `orchestra:connection/<id>`, and the
+  tool sends that reference where its token goes. The edge reads it and adds the credential, if the
+  agent may use it.
+
+  | Tool | Variable |
+  |---|---|
+  | claude, pi | `ANTHROPIC_API_KEY`, or `CLAUDE_CODE_OAUTH_TOKEN` for a subscription token |
+  | codex | `ORCHESTRA_WORKER_OPENAI_API_KEY`, which the worker writes into codex's own auth file |
+  | `gh` | `GH_TOKEN` |
+  | `glab` | `GITLAB_TOKEN`, which `glab` sends as `Private-Token` |
+  | git | `ORCHESTRA_GIT_CREDENTIAL`: the image's git credential helper answers it when the server asks |
+  | `linear`, `slack`, `teams` | `--connection-id <id>` on the command; it reads no connection |
+
+  `routeModelsViaGateway({ key })` sets `ANTHROPIC_API_KEY` and `ORCHESTRA_WORKER_OPENAI_API_KEY` to the
+  key Secret itself, so declare neither beside it.
+
+- **An environment credential covers the host.** `credentials` lists Secrets and Connections. A
+  request from the environment's machines that names none gets the first whose hosts cover its host,
+  whatever the agent. `replace` is true unless set: with `replace: false`, a request that carries its own
+  value in the credential's header keeps it and gets nothing. Adding an entry needs your own use of that
+  credential.
+
+  ```ts
+  credentials: [{ credential: githubConnection }, { credential: modelKey, replace: false }],
+  ```
+
+  With no `credentials` declared, apply leaves the live list alone; `[]` clears it.
+
 ## 7. The cloud
 
 The cloud is the fallback when no local mode can run. It is also the confirmation after the local proof:
@@ -914,7 +951,7 @@ agent's shell, its browser step hangs.
   copy it, then `umask 077 && pbpaste | tr -d '\n' > <file> && pbcopy </dev/null`. At apply, the shell
   exports it from that file into the variable a `Secret` reads. An egress rule allows `api.anthropic.com`
   and adds `Authorization: Bearer ${secret}`, removing `x-api-key`. The environment's `env` holds only
-  `CLAUDE_CODE_OAUTH_TOKEN=software-factory-egress-placeholder` and an empty `ANTHROPIC_API_KEY`, and the
+  `CLAUDE_CODE_OAUTH_TOKEN` set to the Secret, its reference, and an empty `ANTHROPIC_API_KEY`, and the
   agent's gateway setting is off. Never put the token itself in `env`. The Claude sign-in recipe in
   `references/authoring.md` shows the declaration. Copying the renewing credentials file is the fallback,
   and follows the ChatGPT sign-in steps below.

package/skills/orchestra-fdk/references/integrations/code-repo.md

@@ -4,7 +4,10 @@ Give access with a Secret the network edge adds, or with the provider's platform
 so add only the rule that adds the credential. Git over HTTPS and the REST API often take the token in
 different forms: give each its own rule, scoped by host or by path. A connection also brings events, which
 a `Trigger` turns into work. The agent installs or uses whatever git or API client it prefers. The edge adds
-the credential to its requests.
+the credential only to a request that names it, or that an environment default covers
+(`../environment.md`, "Naming a credential"). Name it in the environment's `env`: `GH_TOKEN` for `gh`,
+`GITLAB_TOKEN` for `glab`, and `ORCHESTRA_GIT_CREDENTIAL` for git, each set to the Secret or the
+Connection.
 
 Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
 
@@ -21,8 +24,25 @@ project or the profile; Azure DevOps **User settings › Personal access tokens*
 
 ## Git over HTTPS
 
-Git sends Basic auth. The edge adds it, so the agent clones `https://<host>/<path>.git` with no user name
-and no password in the address.
+Git sends Basic auth. The image's git credential helper answers the reference in `ORCHESTRA_GIT_CREDENTIAL`
+as the password when the server asks, and the edge replaces it, so the agent clones
+`https://<host>/<path>.git` with no user name and no password in the address. A default that covers the
+host adds the credential with no reference.
+
+A git token Secret stores the encoded value `base64("<user>:<token>")` and presents it as `Basic`. The
+recipe has no base64 step, so encode the pair first. `SecretValue.basicAuth(user, value)` encodes it at
+apply; to store it through the API or the console, encode it yourself:
+
+```sh
+printf 'x-access-token:%s' "$TOKEN" | base64 | tr -d '\n'
+```
+
+```ts
+new Secret(factory, "github-git", {
+  value: SecretValue.basicAuth("x-access-token", SecretValue.fromEnv("ORCHESTRA_FDK_GITHUB_TOKEN")),
+  injection: { headers: [{ name: "Authorization", value: "Basic ${secret}" }], hosts: ["github.com"] },
+});
+```
 
 - **GitHub:** the user name is `x-access-token`, and the password is the token:
   `SecretValue.basicAuth("x-access-token", SecretValue.fromEnv("ORCHESTRA_FDK_GITHUB_TOKEN"))`. The GitHub
@@ -42,8 +62,9 @@ the first declared wins for every request. So scope the API rule to `paths: ["/a
 priority, 310. The git rule at 300 takes the rest of the host.
 
 The API rule replaces the `PRIVATE-TOKEN` header. A project access token must be sent this way: sent as
-`Authorization: Bearer` beside a placeholder `PRIVATE-TOKEN`, GitLab answers 401. A personal token works the
-same way.
+`Authorization: Bearer` beside another `PRIVATE-TOKEN`, GitLab answers 401. A personal token works the
+same way. `glab` sends `GITLAB_TOKEN` as `Private-Token`, so set `GITLAB_TOKEN` to the Secret or the
+Connection, and the edge reads the reference there.
 
 With the `gitlab` connection and `Auth.oauth()`, use `.allow(gitlab, { paths: ["/api/*"], priority: 310 })`
 for the API instead, and keep the git rule. GitLab does not let the platform register the webhook. The

package/skills/orchestra-fdk/references/phases/1-discover.md

@@ -19,7 +19,7 @@ npx --package @orchestraworks/cli orchestra workflows list --all-pages --output
 npx --package @orchestraworks/cli orchestra connections list --output json
 ```
 
-A row that an apply made carries the label `sfdk.managedBy`, whose value is the factory's name.
+A row that an apply made carries the label `orchestra.managedBy`, whose value is the factory's name.
 
 1. Infer what the developer most likely wants:
    - *No agents and no pipelines:* the account is empty. Infer **a new factory**.

package/skills/orchestra-fdk/references/phases/2-plan.md

@@ -90,7 +90,7 @@ your shell, its browser step hangs. You never read or copy the value.
 
 - *Claude.* `claude setup-token` prints a long-lived token. The developer saves it in the private file as
   `ORCHESTRA_FDK_CLAUDE_CODE_OAUTH_TOKEN`. The factory stores it as a Secret, and the network edge adds it to
-  calls to `api.anthropic.com`. The machine holds only a placeholder token and an empty API key. Declare the
+  calls to `api.anthropic.com` that name it. The machine holds only the Secret's reference and an empty API key. Declare the
   Claude sign-in recipe from `../authoring.md`, "Secrets are recipes, never values". Never put the token in
   the environment's settings: they are stored and shown in plain text.
 - *Codex.* A personal access token, which begins `at-`. A ChatGPT Business or Enterprise member makes it at

package/skills/orchestra-fdk/references/troubleshooting.md

@@ -48,7 +48,8 @@ The network edge answers the agent, not you. The agent sees one of these:
   host. `details.reason` is `policy_denied` or `ambiguous_match` (two rules match with equal weight). The
   answer does not name a rule.
 - `403 egress identity missing` or `egress destination mismatch`, or `502 egress broker unavailable` or
-  `egress upstream unavailable`: a fault on the path, not the rules.
+  `egress upstream unavailable`: a fault on the path, not the rules. A `421 egress destination mismatch`
+  asks the client to send the request again on a new connection, and a browser does this by itself.
 
 To check the rules the machine has now, read `egressPolicy` in `get-diagnostics`: `defaultAction`, and each
 rule's name, priority, action, hosts and paths. Fix the rules in code and apply. Rules reach running
@@ -82,7 +83,8 @@ C, "Tokens on a compute provider's machines").
 
 - A `401` from the model provider, or "Invalid API key": the agent has no model key. Check the route the
   team chose: the environment's `env`, the image's worker service environment (on Windows, the
-  `SfdkWorker` service's `Environment` registry value), or the key file the `onStartAgent` hook writes.
+  `OrchestraWorker` service's `Environment` registry value, or `SfdkWorker` on an image an earlier
+  release built), or the key file the `onStartAgent` hook writes.
 - The image's value is a real key and `env` declares another: the image's value wins. A declared value
   replaces only our image's placeholder.
 - Never restart the worker service to load a key. A restart after the worker registered stops the
@@ -108,7 +110,7 @@ C, "Tokens on a compute provider's machines").
 - A trigger that could not start a session shows the reason on the trigger's `lastDecision`. A work item
   shows a feed note: `No session started for <agent>: ...`.
 - The model gateway answers `403` with `credits_exhausted` or `budget_exceeded`, in the model provider's
-  own error shape, with a `[sfdk]` prefix on the message.
+  own error shape, with an `[orchestra]` prefix on the message.
 - `403` with `PLAN_FEATURE_DISABLED`: the plan does not include the feature. This is not a credit problem.
 
 `maxSessionsPerMachine` is not an error. A session past it starts another machine.

package/templates/bug-fix/main.ts

@@ -68,13 +68,16 @@ const github = new Connection(factory, "github", {
   install: { permissions: ["contents:write"] },
 });
 
-// The edge adds the gateway key on the gateway's host. The runtime image's placeholder key rides x-api-key, and
-// the gateway refuses two keys that disagree, so the recipe removes it.
+// The edge adds the gateway key on the gateway's host. Claude sends the key's reference in x-api-key, and the
+// gateway refuses two keys that disagree, so the recipe removes it.
 const gatewayHost = required("ORCHESTRA_FDK_MODEL_GATEWAY_HOST");
 const gatewayKey = new Secret(factory, "model-gateway-key", {
   value: SecretValue.fromGatewayKey(new GatewayKey(factory, "model-gateway", { displayName: "__FACTORY_NAME__ bug fixing" })),
-  hosts: [gatewayHost],
-  injection: { headers: [{ name: "Authorization", value: "Bearer ${secret}" }], removeHeaders: ["x-api-key"] },
+  injection: {
+    headers: [{ name: "Authorization", value: "Bearer ${secret}" }],
+    removeHeaders: ["x-api-key"],
+    hosts: [gatewayHost],
+  },
 });
 // init-if: anthropic
 

package/templates/engineering-team/lib/environment.ts

@@ -59,9 +59,12 @@ export function declareKeys(factory: Factory): Keys {
     name: "Model gateway key",
     description: "Added to model calls at the network edge. The agents never see it.",
     value: SecretValue.fromGatewayKey(gatewayKey),
-    hosts: [DEFAULT_MODEL_GATEWAY_HOST],
-    // The runtime image's placeholder key rides x-api-key, and the gateway refuses two keys that disagree.
-    injection: { headers: [{ name: "Authorization", value: "Bearer ${secret}" }], removeHeaders: ["x-api-key"] },
+    // Claude sends the key's reference in x-api-key, and the gateway refuses two keys that disagree.
+    injection: {
+      headers: [{ name: "Authorization", value: "Bearer ${secret}" }],
+      removeHeaders: ["x-api-key"],
+      hosts: [DEFAULT_MODEL_GATEWAY_HOST],
+    },
   });
   return { modelGateway };
 }

package/templates/engineering-team/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@orchestraworks/cli": "^0.5.0"
+    "@orchestraworks/cli": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/templates/todo-factory/main.ts

@@ -66,13 +66,16 @@ const github = new Connection(factory, "github", {
   install: { permissions: ["contents:write"] },
 });
 
-// The edge adds the gateway key on the gateway's host. The runtime image's placeholder key rides x-api-key, and
-// the gateway refuses two keys that disagree, so the recipe removes it.
+// The edge adds the gateway key on the gateway's host. Claude sends the key's reference in x-api-key, and the
+// gateway refuses two keys that disagree, so the recipe removes it.
 const gatewayHost = required("ORCHESTRA_FDK_MODEL_GATEWAY_HOST");
 const gatewayKey = new Secret(factory, "model-gateway-key", {
   value: SecretValue.fromGatewayKey(new GatewayKey(factory, "model-gateway", { displayName: "todo-app bug fixing" })),
-  hosts: [gatewayHost],
-  injection: { headers: [{ name: "Authorization", value: "Bearer ${secret}" }], removeHeaders: ["x-api-key"] },
+  injection: {
+    headers: [{ name: "Authorization", value: "Bearer ${secret}" }],
+    removeHeaders: ["x-api-key"],
+    hosts: [gatewayHost],
+  },
 });
 
 // The image tag hashes the runtime image and every file under image/: a rebuilt image under an unchanged tag

package/templates/todo-factory/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@orchestraworks/cli": "^0.5.0"
+    "@orchestraworks/cli": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",