@orchestraworks/cli 0.5.7 → 0.5.8

package/README.md

@@ -20,7 +20,7 @@ The full guide to every construct, secrets, connections and troubleshooting is [
 ```bash
 npm install -g @orchestraworks/cli         # the CLI, on your path as `orchestra`
 npm install @orchestraworks/cli            # the current release
-npm install @orchestraworks/cli@0.5.7      # this exact release
+npm install @orchestraworks/cli@0.5.8      # this exact release
 ```
 
 Then `import { Factory, Agent, … } from "@orchestraworks/cli"` normally — the package `exports` entry resolves

package/dist/cli/core/auth.d.ts

@@ -14,6 +14,8 @@ export declare const AUTH_ENV: {
     /** Read after `baseUrl`: the platform writes this name into every machine. */
     readonly machineBaseUrl: "PLATFORM_BASE_URL";
     readonly token: "ORCHESTRA_API_TOKEN";
+    /** Set by the worker on each harness and hook process; the file holds a token it renews. */
+    readonly tokenFile: "ORCHESTRA_API_TOKEN_FILE";
     readonly organizationId: "ORCHESTRA_ORGANIZATION_ID";
     /** Presence is the declaration. */
     readonly edgeInjected: "SFDK_AUTH_EDGE_INJECTED";
@@ -26,7 +28,7 @@ export declare function baseUrlFromEnv(env: NodeJS.ProcessEnv): {
     readonly variable: string;
 } | undefined;
 /** Which tier of the chain supplied the authorization. */
-export type AuthProvider = "env" | "profile" | "edge";
+export type AuthProvider = "env" | "file" | "profile" | "edge";
 /**
  * The conversation the command runs in, or undefined when the variable is absent, empty or whitespace only.
  * The only reader of the variable: auth resolution and `login` both call it.
@@ -36,6 +38,9 @@ export declare function sessionIdFrom(env: NodeJS.ProcessEnv): string | undefine
  * `session` rides along under the PROFILE provider only: `token` is the bearer as of this resolution, and
  * the session is what keeps a bearer valid over time. The env provider's token has nothing to refresh it
  * with and the edge provider holds no credential at all, so for both the field's absence is structural.
+ *
+ * Under the FILE provider the worker renews the token in place, so `token` reads the file again before each
+ * request, and the token names its own organization, so no organization is resolved.
  */
 export type AuthResolution = {
     readonly provider: "env" | "profile";
@@ -44,6 +49,11 @@ export type AuthResolution = {
     readonly organizationId?: string;
     readonly session?: CredentialSession;
     readonly sessionId?: string;
+} | {
+    readonly provider: "file";
+    readonly token: () => string;
+    readonly baseUrl: string;
+    readonly sessionId?: string;
 } | {
     readonly provider: "edge";
     readonly baseUrl: string;

package/dist/cli/core/auth.js

@@ -1,8 +1,9 @@
 // Every command resolves credentials through ONE ordered chain, with strict presence-is-selection
 // precedence: `ORCHESTRA_API_TOKEN` (one opaque slot holding ANY principal's bearer — the CLI never looks inside,
-// IAM judges server-side), then the `orchestra auth login` profile, then the sandbox flag the platform DECLARES and
-// never infers (the request goes out BARE and the egress stamps the per-request agent authorization, so no
-// credential material ever enters the sandbox), then a refusal.
+// IAM judges server-side), then the agent token file the worker names in `ORCHESTRA_API_TOKEN_FILE` and renews
+// while the agent is placed, then the `orchestra auth login` profile, then the sandbox flag the platform
+// DECLARES and never infers (the request goes out BARE and the egress stamps the per-request agent
+// authorization), then a refusal.
 //
 // The precedence is purely CLIENT-side. Inside a sandbox the egress stamp REPLACES whatever the request
 // carried, so an exported token is sent, then overwritten, and the call executes as the agent.
@@ -13,6 +14,7 @@
 // Resolution is ASYNC because the profile tier renews itself. The renewal lives in
 // `core/credentialSession.ts`: this module decides WHICH credential a command uses, and the session owns
 // what happens to it over time.
+import { readFileSync } from "node:fs";
 import { CredentialSession } from "./credentialSession.js";
 import { DEFAULT_PROFILE_NAME, loadProfile as loadProfileFromDisk, } from "./profile.js";
 /**
@@ -28,6 +30,8 @@ export const AUTH_ENV = {
     /** Read after `baseUrl`: the platform writes this name into every machine. */
     machineBaseUrl: "PLATFORM_BASE_URL",
     token: "ORCHESTRA_API_TOKEN",
+    /** Set by the worker on each harness and hook process; the file holds a token it renews. */
+    tokenFile: "ORCHESTRA_API_TOKEN_FILE",
     organizationId: "ORCHESTRA_ORGANIZATION_ID",
     /** Presence is the declaration. */
     edgeInjected: "SFDK_AUTH_EDGE_INJECTED",
@@ -80,6 +84,26 @@ export class MissingBaseUrlError extends Error {
         this.name = "MissingBaseUrlError";
     }
 }
+/** The trimmed content, or undefined when the file is missing, unreadable, empty or whitespace only. */
+function tokenFromFile(path) {
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const token = content.trim();
+    return token === "" ? undefined : token;
+}
+/** A failed read mid-command keeps the last token read rather than sending the request bare. */
+function fileTokenReader(path, first) {
+    let last = first;
+    return () => {
+        last = tokenFromFile(path) ?? last;
+        return last;
+    };
+}
 /** Loopback hosts reachable over plain HTTP — the local dev-stack contract. */
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
 /**
@@ -132,12 +156,18 @@ export async function resolveAuthWithWarnings(env, flags, deps = {}) {
     const profile = (deps.loadProfile ?? loadProfileFromDisk)(flags.profile);
     const baseUrl = firstPresent(flags.baseUrl, baseUrlFromEnv(env)?.value, profile?.baseUrl);
     const envToken = firstPresent(env[AUTH_ENV.token]);
+    const tokenFilePath = firstPresent(env[AUTH_ENV.tokenFile]);
+    const fileToken = envToken === undefined && tokenFilePath !== undefined ? tokenFromFile(tokenFilePath) : undefined;
     const profileToken = firstPresent(profile?.token);
     const edgeDeclared = firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined;
     // Read before the provider split: a person may export it by hand under any provider.
     const sessionId = sessionIdFrom(env);
     const withSessionId = sessionId !== undefined ? { sessionId } : {};
-    if (envToken === undefined && profileToken === undefined && !edgeDeclared) {
+    if (envToken === undefined && fileToken === undefined && profileToken === undefined && !edgeDeclared) {
+        if (tokenFilePath !== undefined) {
+            throw new MissingCredentialsError(`no auth provider resolved: ${AUTH_ENV.tokenFile} names ${tokenFilePath}, which the worker has not ` +
+                `written yet. The worker writes it once the agent is placed on this machine; try again shortly.`);
+        }
         throw new MissingCredentialsError(`no auth provider resolved: export ${AUTH_ENV.token}, run \`orchestra auth login\`, or run inside a host ` +
             `where the platform declares ${AUTH_ENV.edgeInjected}.`);
     }
@@ -146,6 +176,17 @@ export async function resolveAuthWithWarnings(env, flags, deps = {}) {
     }
     // Refuse before ANY network access, for every provider — the bare edge send included.
     assertSecretTransport(baseUrl);
+    if (fileToken !== undefined && tokenFilePath !== undefined) {
+        return {
+            auth: {
+                provider: "file",
+                token: fileTokenReader(tokenFilePath, fileToken),
+                baseUrl,
+                ...withSessionId,
+            },
+            warnings: [],
+        };
+    }
     if (envToken === undefined && profileToken === undefined) {
         // The egress stamps the authorization and the stamped identity carries the org.
         return { auth: { provider: "edge", baseUrl, ...withSessionId }, warnings: [] };
@@ -223,6 +264,9 @@ export function platformTargetFrom(auth) {
     if (auth.provider === "edge") {
         return { baseUrl: auth.baseUrl, ...sessionId };
     }
+    if (auth.provider === "file") {
+        return { baseUrl: auth.baseUrl, token: auth.token, ...sessionId };
+    }
     return {
         baseUrl: auth.baseUrl,
         token: auth.token,

package/dist/cli/core/errors.js

@@ -182,6 +182,10 @@ function guidance(status, api, ctx) {
             case "env":
                 return (`The token in ${AUTH_ENV.token} is not accepted. Renew that token and re-export ` +
                     `${AUTH_ENV.token}; a stored login profile is not what this command used.`);
+            case "file":
+                return (`The agent token in the file ${AUTH_ENV.tokenFile} names is not accepted. The worker renews that ` +
+                    `file, so there is nothing to renew here: the token expired before the worker renewed it, or the ` +
+                    `agent's placement on this machine, the machine's state or the agent's status refused it.`);
             case "edge":
                 return (`Authorization is stamped at the egress edge (${AUTH_ENV.edgeInjected} is declared), so there is ` +
                     `no credential here to renew — the stamping path itself failed. Check the egress/identity plane.`);

package/dist/cli/core/platform-client.d.ts

@@ -50,7 +50,8 @@ export declare function withRefreshRetry(fetchApi: FetchAPI, session: Credential
  */
 export interface PlatformTarget {
     readonly baseUrl: string;
-    readonly token?: string;
+    /** The bearer, or under the file provider a reader of the worker's renewed token, called before each request. */
+    readonly token?: string | (() => string);
     readonly organizationId?: string;
     /**
      * `token` above is the bearer as of auth resolution; the session is what keeps a bearer valid, and every
@@ -73,7 +74,7 @@ export declare function createPlatformApis(target: PlatformTarget, fetchApi: Fet
 export interface RawPlatformRequest {
     baseUrl: string;
     /** Absent for the bare edge send, exactly as for a typed command. */
-    token?: string;
+    token?: string | (() => string);
     organizationId?: string;
     /** The live credentials behind `token`, when the resolution carried one. */
     session?: CredentialSession;

package/dist/cli/firstRun.d.ts

@@ -56,9 +56,9 @@ export interface FirstRunGateDeps extends InterviewDeps {
 }
 /**
  * The pre-command gate: the interview runs on a machine where a person is present and nothing is
- * configured. A credential supplied by the environment — an exported token, or the marker the platform sets
- * on a machine where the egress stamps the authorization — skips the interview and nothing else, so a
- * command's own rules are untouched either way.
+ * configured. A credential supplied by the environment — an exported token, the token file the worker
+ * names, written yet or not, or the marker the platform sets on a machine where the egress stamps the
+ * authorization — skips the interview and nothing else, so a command's own rules are untouched either way.
  *
  * The terminal is checked first, so a run with no person to ask touches neither the disk nor the network.
  */

package/dist/cli/firstRun.js

@@ -168,9 +168,9 @@ async function resolveHarnesses(flags, context) {
 }
 /**
  * The pre-command gate: the interview runs on a machine where a person is present and nothing is
- * configured. A credential supplied by the environment — an exported token, or the marker the platform sets
- * on a machine where the egress stamps the authorization — skips the interview and nothing else, so a
- * command's own rules are untouched either way.
+ * configured. A credential supplied by the environment — an exported token, the token file the worker
+ * names, written yet or not, or the marker the platform sets on a machine where the egress stamps the
+ * authorization — skips the interview and nothing else, so a command's own rules are untouched either way.
  *
  * The terminal is checked first, so a run with no person to ask touches neither the disk nor the network.
  */
@@ -179,7 +179,9 @@ export async function runFirstRunIfNeeded(flags, deps = {}) {
     if ((deps.isTTY ?? process.stdin.isTTY === true) !== true) {
         return;
     }
-    if (firstPresent(env[AUTH_ENV.token]) !== undefined || firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined) {
+    if (firstPresent(env[AUTH_ENV.token]) !== undefined ||
+        firstPresent(env[AUTH_ENV.tokenFile]) !== undefined ||
+        firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined) {
         return;
     }
     const loadProfile = deps.loadProfile ?? loadProfileFromDisk;

package/docs/REFERENCE.md

@@ -132,16 +132,28 @@ export ORCHESTRA_ORGANIZATION_ID="org_…"
 ```
 
 **The auth-provider chain** (one ordered chain for every command, presence is selection):
-`ORCHESTRA_API_TOKEN` → the `login` profile → the platform-injected machine edge flag
-(`SFDK_AUTH_EDGE_INJECTED`, which makes the CLI send the request **bare** so the egress edge
-stamps the agent's authorization — no credential ever enters the machine) → a named
-missing-credentials error. There is **no `--token` flag**: a token never appears in argv.
+`ORCHESTRA_API_TOKEN` → the file `ORCHESTRA_API_TOKEN_FILE` names → the `login` profile → the
+platform-injected machine edge flag (`SFDK_AUTH_EDGE_INJECTED`) → a named missing-credentials error.
+There is **no `--token` flag**: a token never appears in argv.
+
+- **The token file.** On an Orchestra machine, the worker writes the agent's own platform token to a
+  file and renews it before it expires. It sets `ORCHESTRA_API_TOKEN_FILE` to that file's path on each
+  agent process. The CLI reads the file again before each request, so a long `orchestra sessions wait`
+  always sends the current token. A missing, empty or unreadable file counts as absent. The worker sets
+  the path before it writes the file, so right after the agent starts, a command may report that the
+  file is not written yet.
+- **The edge flag.** On a machine behind the platform's network edge, the edge adds the agent's
+  authorization to each call to the platform. It replaces any token the request carried with a token for
+  the same agent. With the edge flag and no token, the CLI sends the request **bare**.
+- **A 401 under the token file.** The agent has nothing to renew. The token expired before the worker
+  renewed it, or the agent is no longer placed on the machine, the machine stopped, or the agent is not
+  active.
 
 **Resolved alongside the chain, per field:** the base URL (`--base-url` → `ORCHESTRA_BASE_URL`, then `PLATFORM_BASE_URL` → profile;
 `login` alone adds the built-in default as a fourth tier, because it is the command that has no profile
 to read yet — every other command needs one of the three, and says so if it has none)
-and the organization (`--org` → `ORCHESTRA_ORGANIZATION_ID` → profile; under the edge provider the organization
-rides the stamped identity server-side). Every authenticated request requires HTTPS or loopback — the
+and the organization (`--org` → `ORCHESTRA_ORGANIZATION_ID` → profile; under the token file and the edge flag
+the organization rides the agent's token server-side). Every authenticated request requires HTTPS or loopback — the
 bearer is itself a credential — with the unauthenticated `health` ping the one exemption. `diff`/`apply`
 print the resolved target org as a banner before any read/write, and warn when an exported
 `ORCHESTRA_ORGANIZATION_ID` diverges from the profile's org (so a stale export can't silently redirect writes).

package/node_modules/@orchestraworks/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/client",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Orchestra public API TypeScript client",
   "author": "Living Computers",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/cli",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "type": "module",
   "description": "The Orchestra command line.",
   "license": "Apache-2.0",
@@ -109,13 +109,13 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.3.0",
-    "@orchestraworks/client": "0.5.7",
-    "@orchestraworks/worker": "0.0.140",
+    "@orchestraworks/client": "0.5.8",
+    "@orchestraworks/worker": "0.0.141",
     "commander": "^14.0.0",
     "liquidjs": "^10.28.0"
   },
   "optionalDependencies": {
-    "@orchestraworks/local": "0.0.140"
+    "@orchestraworks/local": "0.0.141"
   },
   "bundleDependencies": [
     "@orchestraworks/client"

package/skills/orchestra/SKILL.md

@@ -549,7 +549,8 @@ names its team, and a row with none sits in Shared.
 
 <!-- Sources, on the kit's own branch: cli/src/cli/main.ts:60-160 (two jobs; nouns match API paths; standard
 verbs; --output json; --body @file.json; approval defaults; orchestra api), cli/src/cli/core/auth.ts:1-45
-(ORCHESTRA_API_TOKEN, then the login profile, then the machine's edge; ORCHESTRA_BASE_URL),
+(ORCHESTRA_API_TOKEN, then the file ORCHESTRA_API_TOKEN_FILE names, then the login profile, then the machine's
+edge; ORCHESTRA_BASE_URL),
 cli/src/cli/core/profile.ts:39-52 (profiles in ~/.config/orchestra/config.json), cli/src/generated/cli-commands.json
 (each command's answer), cli/src/cli/core/output.ts:94-113 and :143-145 (json prints the answer as it is),
 cli/src/cli/core/errors.ts:287-296 and :366-370 (the json error, on stderr), cli/src/cli/core/login.ts:361-363 (a
@@ -581,8 +582,12 @@ each part at length. What follows is only what a reader needs to run a command s
   `~/.config/orchestra/config.json`. It selects the person's organization when they have one; with several,
   name it: `orchestra auth login --org <organization>`. The browser sign-in renews itself. A token typed at the
   `--no-browser` prompt cannot renew itself, so it suits a short run only.
-- **Scripts.** `ORCHESTRA_API_TOKEN` and `ORCHESTRA_BASE_URL` in the shell are used before the profile. On an
-  Orchestra machine, the network edge signs the agent's calls, so it needs no token.
+- **Scripts.** `ORCHESTRA_API_TOKEN` and `ORCHESTRA_BASE_URL` in the shell are used before the profile.
+- **On an Orchestra machine.** The worker writes the agent's own token to a file, renews it, and names the
+  file in `ORCHESTRA_API_TOKEN_FILE`. `orchestra` reads that file before each request, so the agent needs no
+  sign-in. Where a network edge stands in front of the machine, the edge replaces that token with one for the
+  same agent. A 401 here is not fixed by `orchestra auth login`: the token expired before the worker renewed
+  it, or the agent is no longer placed on the machine.
 - **Fallback.** `orchestra api <METHOD> </path>` makes a raw call when a typed command is missing.
 
 A first look at an organization, in the order a new reader runs it:

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

@@ -1106,17 +1106,19 @@ itself a credential.
 An agent running inside a machine types the **same commands** as an operator at a workstation. There
 is no separate agent CLI, no agent-only spelling, and nothing for you to author differently:
 
-- **The agent holds no token.** Its machine is declared as edge-injected, so the CLI sends the request
-  *bare* to the platform's public HTTPS name (`PLATFORM_BASE_URL`), and the egress edge stamps the
-  authorization onto it on the way out. Credential material never enters the machine. Setting
-  `ORCHESTRA_API_TOKEN` deliberately still wins — the edge leaves an `Authorization` header the client
-  supplied alone.
+- **The agent sets no token.** The worker writes the agent's own short-lived platform token to a file,
+  renews it before it expires, and sets `ORCHESTRA_API_TOKEN_FILE` to that file's path on each agent
+  process. The CLI reads the file before each request and sends its token to the platform's public HTTPS
+  name (`PLATFORM_BASE_URL`), with no organization header, because the token names its organization.
+  The token works only while the agent is placed on that machine. A token set in `ORCHESTRA_API_TOKEN`
+  comes before the file. On a machine behind the platform's network edge, the edge replaces the
+  `Authorization` header of each call with a token for the same agent, whatever token the call carried.
 - **IAM is the only difference between principals.** The same command run by an agent and by a human
   differs only in what their grants allow; a refusal is a permission error naming the action, never
   an instruction to log in (there is nothing in a machine to log into).
 - **The factory loop works there too.** `synth`, `diff` and `apply` (and `grant`) are ordinary
   platform callers, so an agent can preview and apply a factory from inside its machine with no token
-  and no organization set — the same bare send, judged by the same IAM.
+  and no organization set — the same token file, judged by the same IAM.
 - **Triggers are runtime wiring: agents observe it, they do not author it.** Declare them in code
   (`new Trigger(factory, …)`) or have an explicitly granted principal create them. The managed
   worker role deliberately carries **no** trigger-authoring capability, so `triggers create`

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