@orchestraworks/cli 0.5.2 → 0.5.4

package/dist/cli/api/tail.js

@@ -0,0 +1,564 @@
+// `orchestra sessions tail <id>`: print a conversation's items as they are saved, and what each gains later.
+//
+// It reads the public items list through its `after` cursor. While a turn is open, each read is the list's
+// waiting read, named by the open turn's prompt and set to answer once the event after the prompt's
+// recorded position is saved, so the platform paces the loop and the command never polls on a timer of its
+// own. While no turn is open there is nothing for a read to wait on, and only then does it pause, with a
+// backoff, before it reads again.
+//
+// More than the last row can change: a reply keeps growing when a message is appended behind it, and the
+// fold patches any call of the open turn by its id. So each read classifies every row from its own fields,
+// the cursor never passes a row that can still change, and the table prints what a row gains as it grows.
+import { httpStatusOf } from "../../engine/client.js";
+import { findCommand } from "../../generated/cli-commands.js";
+import { authFlagsFrom, platformTargetFrom, resolveAuthWithWarnings } from "../core/auth.js";
+import { renderError, runCommand, settleExitCode } from "../core/errors.js";
+import { defaultIo, parseOutputMode, printRedactionNotes, printWarnings, writeLines, } from "../core/output.js";
+import { createPlatformApis, REQUEST_TIMEOUT_MS } from "../core/platform-client.js";
+import { redact } from "../core/redaction.js";
+import { SETTLED_SESSION_STATUSES } from "./wait.js";
+/** Seconds. The first pause after a failed read, doubled per failure up to {@link RETRY_MAX_SECONDS}. */
+export const RETRY_FIRST_SECONDS = 0.5;
+export const RETRY_MAX_SECONDS = 8;
+/** Seconds. The pause while no turn is open, doubled per empty pass up to {@link IDLE_MAX_SECONDS}. */
+export const IDLE_FIRST_SECONDS = 1;
+/** The platform's own waiting-read budget, so an idle follow reacts no slower than a running one. */
+export const IDLE_MAX_SECONDS = 5;
+/** The list's own ceiling; a longer window is walked through the cursor. */
+const PAGE_LIMIT = 500;
+/** A prompt in these states has a turn waiting or running (`OPEN_PROMPT_STATES` on the platform). */
+const OPEN_TURN_STATES = ["QUEUED", "IN_FLIGHT"];
+const PROMPT_TYPES = ["user_message", "turn_start"];
+/** The fold appends chunks to its open run only, which is always its turn's newest output row. */
+const GROWING_TEXT_TYPES = ["agent_message", "agent_thought"];
+const FINISHED_CALL_STATUSES = ["completed", "failed"];
+export class TailUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TailUsageError";
+    }
+}
+/** Thrown out of any wait or read once the command is stopped, and answered with a clean exit. */
+class Stopped extends Error {
+}
+export async function tailCommand(id, options = {}, deps = {}) {
+    const io = deps.io ?? defaultIo;
+    const ctx = {};
+    const { signal, release } = stopSignal(deps.signal);
+    try {
+        const code = await runCommand(async () => {
+            try {
+                await follow(id, options, deps, ctx, signal);
+            }
+            catch (error) {
+                if (!signal.aborted) {
+                    throw error;
+                }
+            }
+        }, ctx, io);
+        settleExitCode(code, deps.onExitCode);
+    }
+    finally {
+        release();
+    }
+}
+/** The caller's signal when a test supplies one; otherwise one Ctrl-C aborts, and the listener is removed after. */
+function stopSignal(given) {
+    if (given !== undefined) {
+        return { signal: given, release: () => undefined };
+    }
+    const controller = new AbortController();
+    const onInterrupt = () => controller.abort();
+    process.once("SIGINT", onInterrupt);
+    return { signal: controller.signal, release: () => process.removeListener("SIGINT", onInterrupt) };
+}
+async function follow(id, options, deps, ctx, signal) {
+    const env = deps.env ?? process.env;
+    const io = deps.io ?? defaultIo;
+    const sleep = deps.sleep ?? abortableDelay;
+    const mode = parseOutputMode(options.output, (message) => new TailUsageError(message));
+    ctx.mode = mode;
+    ctx.notFound = { resource: "session", key: id };
+    const printer = new ItemPrinter(mode, sessionItemSchema(), options.reveal === true, io);
+    const { auth, warnings } = await resolveAuthWithWarnings(env, authFlagsFrom(options), deps.loadProfile !== undefined ? { loadProfile: deps.loadProfile } : {});
+    printWarnings(warnings, io);
+    ctx.provider = auth.provider;
+    ctx.baseUrl = auth.baseUrl;
+    const platformTarget = platformTargetFrom(auth);
+    const apis = createPlatformApis(platformTarget, deps.fetchApi, { warn: (lines) => printWarnings(lines, io) });
+    const organizationId = platformTarget.organizationId;
+    const scope = organizationId !== undefined ? { xOrganizationId: organizationId } : {};
+    const pause = async (seconds) => {
+        await sleep(seconds, signal);
+        if (signal.aborted) {
+            throw new Stopped();
+        }
+    };
+    const read = (call) => readWithRetry(call, signal, pause, ctx, io);
+    const readPage = (after, shape) => read((init) => apis.sessions.listSessionItemsRaw({ id, ...scope, ...(after !== undefined ? { after } : {}), ...shape }, init));
+    /**
+     * `null` when the item the read started after is gone: a queued or steered message taken off the
+     * conversation answers the cursor with a 404.
+     */
+    const readPageAfter = (after, shape) => after === undefined ? readPage(after, shape) : orGone(readPage(after, shape));
+    /** Turns some read has seen end; a read made after that holds their rows as they will stay. */
+    const endedTurns = new Set();
+    let cursor = options.after;
+    /** Every earlier cursor, newest last, to step back to when the current one is gone. */
+    const earlierCursors = [];
+    let idleSeconds = IDLE_FIRST_SECONDS;
+    let lastBounds;
+    for (;;) {
+        if (signal.aborted) {
+            throw new Stopped();
+        }
+        const readSession = () => read((init) => apis.sessions.getSessionRaw({ id, ...scope }, init));
+        let session = await readSession();
+        let openTurnId = stringOf(session["openTurnId"]);
+        let bounds;
+        let window = [];
+        let timedOut = false;
+        /** The `after` of a read that answered 404, when one did. */
+        let missing;
+        if (openTurnId !== undefined) {
+            const turnId = openTurnId;
+            const prompt = await orGone(read((init) => apis.sessions.getSessionItemRaw({ id, itemId: turnId, ...scope }, init)));
+            const page = prompt === null ? null : await orGone(readPage(cursor, (bounds = waitBoundsFor(turnId, prompt))));
+            if (page === null) {
+                // The waited prompt is gone, as an interrupted queued turn's is, or the cursor is: the session is
+                // read again, and this pass reads without bounds, whose own 404 says whether the cursor went.
+                session = await readSession();
+                openTurnId = stringOf(session["openTurnId"]);
+                bounds = undefined;
+            }
+            else {
+                window = itemsOf(page);
+                timedOut = page["waitTimedOut"] === true;
+            }
+        }
+        if (bounds === undefined) {
+            let scan = cursor;
+            for (;;) {
+                const page = await readPageAfter(scan, { limit: PAGE_LIMIT });
+                if (page === null) {
+                    missing = { after: scan };
+                    break;
+                }
+                const rows = itemsOf(page);
+                window.push(...rows);
+                const total = typeof page["total"] === "number" ? page["total"] : rows.length;
+                if (total <= rows.length || rows.length === 0) {
+                    break;
+                }
+                scan = stringOf(rows.at(-1)?.["id"]);
+            }
+        }
+        if (missing !== undefined) {
+            // A 404 on the session read here ends the follow with the usual not-found error.
+            await read((init) => apis.sessions.getSessionRaw({ id, ...scope }, init));
+            // A page boundary that went missing is read again from the cursor. A cursor that went missing steps
+            // back to the one before it, or to the start; the printer skips by id what it has already printed.
+            if (missing.after === cursor) {
+                cursor = earlierCursors.pop();
+            }
+            lastBounds = undefined;
+            continue;
+        }
+        const { states, unseenTurns } = classifyItems(window, endedTurns, openTurnId);
+        const printed = printer.show(window, states);
+        for (const [index, item] of window.entries()) {
+            if (states[index] !== "final") {
+                break;
+            }
+            const itemId = stringOf(item["id"]);
+            if (itemId !== undefined && itemId !== cursor) {
+                earlierCursors.push(cursor);
+                cursor = itemId;
+            }
+            printer.forget(item);
+        }
+        // A turn this read cannot see the prompt of is learned from its prompt now, for the next read to use.
+        for (const turnId of unseenTurns) {
+            if (turnId !== openTurnId && (await turnHasEnded(turnId))) {
+                endedTurns.add(turnId);
+            }
+        }
+        const turnChanging = states.includes("turn");
+        if (printed > 0 || bounds !== undefined) {
+            idleSeconds = IDLE_FIRST_SECONDS;
+        }
+        if (bounds !== undefined) {
+            // A read that answered at once, with the same bounds as the pass before and nothing new, is a turn
+            // whose state has not caught up with the session read: without a pause that would be a busy loop.
+            const stale = !timedOut && printed === 0 && sameBounds(bounds, lastBounds);
+            lastBounds = bounds;
+            if (stale) {
+                await pause(RETRY_FIRST_SECONDS);
+            }
+            continue;
+        }
+        lastBounds = undefined;
+        // Rows of a turn the session read did not name: the session is read again before anything settles.
+        if (turnChanging && printed > 0) {
+            continue;
+        }
+        const status = stringOf(session["status"]);
+        const settled = status !== undefined && SETTLED_SESSION_STATUSES.includes(status);
+        if (options.untilSettled === true && settled && !turnChanging) {
+            printer.flush(window, states);
+            printStatus(id, status, mode, io);
+            return;
+        }
+        await pause(idleSeconds);
+        idleSeconds = Math.min(idleSeconds * 2, IDLE_MAX_SECONDS);
+    }
+    async function turnHasEnded(turnId) {
+        try {
+            const prompt = await read((init) => apis.sessions.getSessionItemRaw({ id, itemId: turnId, ...scope }, init));
+            return !OPEN_TURN_STATES.includes(stringOf(prompt["turnState"]) ?? "");
+        }
+        catch (error) {
+            // A prompt that is gone has no turn left to write to.
+            if (httpStatusOf(error) === 404) {
+                return true;
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * The state of each row, from the row's own fields and the read it came in. One read is one snapshot, so a
+ * prompt in it that shows its turn ended means that turn's rows in the same read are as they will stay.
+ * A row of a turn whose prompt is not in the read, that no earlier read saw end, and that the session read
+ * did not name, counts as changing; its turn is returned in `unseenTurns` for the caller to look up.
+ */
+export function classifyItems(window, endedTurns, openTurnId) {
+    const openTurns = new Set();
+    for (const item of window) {
+        if (!isPrompt(item)) {
+            continue;
+        }
+        const itemId = stringOf(item["id"]);
+        if (itemId === undefined) {
+            continue;
+        }
+        if (OPEN_TURN_STATES.includes(stringOf(item["turnState"]) ?? "")) {
+            openTurns.add(itemId);
+        }
+        else {
+            endedTurns.add(itemId);
+        }
+    }
+    const unseenTurns = new Set();
+    const turnOpen = (turnId) => {
+        if (openTurns.has(turnId)) {
+            return true;
+        }
+        if (endedTurns.has(turnId)) {
+            return false;
+        }
+        if (turnId !== openTurnId) {
+            unseenTurns.add(turnId);
+        }
+        return true;
+    };
+    const newestOutput = new Map();
+    window.forEach((item, index) => {
+        const turnId = stringOf(item["turnId"]);
+        if (turnId !== undefined && !PROMPT_TYPES.includes(stringOf(item["type"]) ?? "")) {
+            newestOutput.set(turnId, index);
+        }
+    });
+    const states = window.map((item, index) => {
+        const type = stringOf(item["type"]) ?? "";
+        const turnId = stringOf(item["turnId"]);
+        if (type === "user_message" && turnId === undefined) {
+            // Queued: it may still open a turn of its own, or be taken off the conversation.
+            return "turn";
+        }
+        if (isPrompt(item)) {
+            return openTurns.has(stringOf(item["id"]) ?? "") ? "turn" : "final";
+        }
+        if (type === "user_message") {
+            // Steered into a turn: when that turn settles, the message is marked delivered, queued again as a
+            // prompt of its own, or deleted by an interrupt, so it changes until its turn's settle has run.
+            return stringOf(item["turnState"]) === "STEERED" ? "turn" : "final";
+        }
+        const open = turnId !== undefined && turnOpen(turnId);
+        if (open && (!GROWING_TEXT_TYPES.includes(type) || newestOutput.get(turnId) === index)) {
+            return "turn";
+        }
+        if (type === "background_task" && stringOf(item["taskStatus"]) === "running") {
+            return "background";
+        }
+        if (type === "tool_call" && item["taskId"] !== undefined && !FINISHED_CALL_STATUSES.includes(stringOf(item["status"]) ?? "")) {
+            return "background";
+        }
+        return "final";
+    });
+    return { states, unseenTurns };
+}
+/** A row that opened its turn: a message whose turn is its own id, or a turn the harness started. */
+function isPrompt(item) {
+    const type = stringOf(item["type"]);
+    if (type === "turn_start") {
+        return true;
+    }
+    return type === "user_message" && item["turnId"] !== undefined && item["turnId"] === item["id"];
+}
+/**
+ * Remembers what each row has printed, so nothing prints twice and nothing is lost. In the table, a reply
+ * that can still grow prints its complete lines and keeps the rest until the next line ends or the reply
+ * can no longer grow, and any other row prints its line again when the line changes. In json, a row prints
+ * once it is final.
+ */
+class ItemPrinter {
+    mode;
+    schema;
+    reveal;
+    io;
+    /** Per item id: the text a reply has printed, or the line another row has printed. */
+    shown = new Map();
+    done = new Set();
+    lastPrinted;
+    constructor(mode, schema, reveal, io) {
+        this.mode = mode;
+        this.schema = schema;
+        this.reveal = reveal;
+        this.io = io;
+    }
+    /** Returns how many rows printed something. */
+    show(window, states) {
+        let printed = 0;
+        window.forEach((item, index) => {
+            if (this.showOne(item, states[index] === "final")) {
+                printed += 1;
+            }
+        });
+        return printed;
+    }
+    /** At exit, background rows print as they stand, since nothing will print them later. */
+    flush(window, states) {
+        window.forEach((item, index) => {
+            if (states[index] === "background") {
+                this.showOne(item, true);
+            }
+        });
+    }
+    /**
+     * Once the cursor has passed a row, only a read started again from an earlier cursor returns it, and then
+     * its id in `done` keeps it from printing twice.
+     */
+    forget(item) {
+        this.shown.delete(stringOf(item["id"]) ?? "");
+    }
+    showOne(item, final) {
+        const itemId = stringOf(item["id"]) ?? "";
+        if (this.done.has(itemId)) {
+            return false;
+        }
+        const redaction = redact(item, this.schema, { reveal: this.reveal });
+        const rendered = redaction.rendered;
+        let text;
+        if (this.mode === "json") {
+            text = final ? JSON.stringify(rendered) : undefined;
+        }
+        else if (GROWING_TEXT_TYPES.includes(stringOf(rendered["type"]) ?? "")) {
+            text = this.growth(itemId, rendered, final);
+        }
+        else {
+            const line = itemLine(rendered);
+            text = this.shown.get(itemId) === line ? undefined : line;
+            this.shown.set(itemId, line);
+        }
+        if (final) {
+            this.done.add(itemId);
+        }
+        if (text === undefined) {
+            return false;
+        }
+        writeLines(this.io, "out", text);
+        printRedactionNotes(redaction, this.io);
+        this.lastPrinted = itemId;
+        return true;
+    }
+    /** The part of a reply not printed yet: whole lines while it can grow, everything once it cannot. */
+    growth(itemId, item, final) {
+        const label = itemLabel(stringOf(item["type"]) ?? "");
+        const full = contentText(item["content"]);
+        const before = this.shown.get(itemId);
+        if (before !== undefined && !full.startsWith(before)) {
+            // Rewritten rather than extended: print it whole again, so nothing is lost.
+            this.shown.set(itemId, full);
+            return `${label} (rewritten): ${full}`;
+        }
+        const from = before?.length ?? 0;
+        const upTo = final ? full.length : full.lastIndexOf("\n") + 1;
+        if (upTo <= from && !(final && before === undefined)) {
+            return undefined;
+        }
+        const part = full.slice(from, Math.max(from, upTo)).replace(/\n$/, "");
+        this.shown.set(itemId, full.slice(0, Math.max(from, upTo)));
+        if (before === undefined) {
+            return `${label}: ${part}`;
+        }
+        return this.lastPrinted === itemId ? part : `${label} (continued): ${part}`;
+    }
+}
+/**
+ * The read answers once the prompt's recorded position reaches `waitForSeq - 1`, so one past the recorded
+ * event waits for the next one. A prompt that has not started a run yet carries no attempt: its first run is
+ * attempt 1, and the read waits for that run's first event.
+ */
+export function waitBoundsFor(promptId, prompt) {
+    const attempt = typeof prompt["attempt"] === "number" && prompt["attempt"] >= 1 ? prompt["attempt"] : 1;
+    const recorded = typeof prompt["recordedSeq"] === "number" ? prompt["recordedSeq"] : 0;
+    return { waitForItem: promptId, waitForAttempt: attempt, waitForSeq: recorded + 2 };
+}
+function sameBounds(a, b) {
+    return (b !== undefined &&
+        a.waitForItem === b.waitForItem &&
+        a.waitForAttempt === b.waitForAttempt &&
+        a.waitForSeq === b.waitForSeq);
+}
+/** `null` for a read that answered 404, so the caller can tell what went missing. */
+async function orGone(pending) {
+    try {
+        return await pending;
+    }
+    catch (error) {
+        if (httpStatusOf(error) === 404) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * A 5xx and a request that never got an answer are retried with a doubling pause; every other failure, a
+ * 404 included, ends the command through the shared error report. Each request keeps the CLI's own timeout,
+ * joined with the stop signal so Ctrl-C ends a waiting read at once.
+ */
+async function readWithRetry(call, signal, pause, ctx, io) {
+    let backoff = RETRY_FIRST_SECONDS;
+    for (;;) {
+        try {
+            const response = await call({ signal: AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]) });
+            const text = await response.raw.text().catch((cause) => {
+                throw new BodyReadError(cause);
+            });
+            const body = text.trim() === "" ? undefined : JSON.parse(text);
+            return typeof body === "object" && body !== null && !Array.isArray(body) ? body : {};
+        }
+        catch (error) {
+            if (signal.aborted) {
+                throw new Stopped();
+            }
+            if (!retryable(error)) {
+                throw error;
+            }
+            const reason = (await renderError(error, ctx)).split("\n")[0].replace(/^error:\s*/, "");
+            printWarnings([`${reason} Retrying in ${backoff}s.`], io);
+            await pause(backoff);
+            backoff = Math.min(backoff * 2, RETRY_MAX_SECONDS);
+        }
+    }
+}
+/** The headers arrived and the connection dropped while the body was read. */
+class BodyReadError extends Error {
+    constructor(cause) {
+        super("the connection closed while the platform's answer was being read.", { cause });
+        this.name = "BodyReadError";
+    }
+}
+/**
+ * The generated runtime raises `ResponseError` for a status and `FetchError` for a request with no answer;
+ * a body cut off after the headers fails outside it, as {@link BodyReadError}.
+ */
+function retryable(error) {
+    const failure = error;
+    const status = failure?.response?.status;
+    if (typeof status === "number") {
+        return status >= 500;
+    }
+    return failure?.name === "FetchError" || error instanceof BodyReadError;
+}
+function sessionItemSchema() {
+    const schema = findCommand("sessions", "list-items")?.responseSchema;
+    const data = schema?.kind === "object" ? schema.fields["data"]?.schema : undefined;
+    return data?.kind === "array" ? data.items : undefined;
+}
+function itemsOf(page) {
+    const data = page["data"];
+    return Array.isArray(data)
+        ? data.filter((item) => typeof item === "object" && item !== null && !Array.isArray(item))
+        : [];
+}
+function printStatus(id, status, mode, io) {
+    io.out(mode === "json" ? JSON.stringify({ id, status }) : `session ${id}: ${status}`);
+}
+/** Messages and thoughts in full; every other item on one line, from its own fields. */
+export function itemLine(item) {
+    const type = stringOf(item["type"]) ?? "item";
+    switch (type) {
+        case "user_message":
+        case "agent_message":
+        case "agent_thought":
+            return `${itemLabel(type)}: ${contentText(item["content"])}`;
+        case "tool_call":
+            return oneLine(`tool: ${stringOf(item["title"]) ?? stringOf(item["toolCallId"]) ?? ""}${facts(item["kind"], item["status"])}`);
+        case "background_task":
+            return oneLine(`task: ${stringOf(item["description"]) ?? stringOf(item["taskId"]) ?? ""}${facts(item["taskKind"], item["taskStatus"])}`);
+        case "turn_start":
+            return "turn started";
+        default:
+            return `${type}: ${stringOf(item["id"]) ?? ""}`;
+    }
+}
+function itemLabel(type) {
+    return type === "user_message" ? "user" : type === "agent_thought" ? "thought" : "agent";
+}
+function facts(...values) {
+    const present = values.map(stringOf).filter((value) => value !== undefined);
+    return present.length === 0 ? "" : ` (${present.join(", ")})`;
+}
+/** Text blocks as they are; any other block as a bracketed marker naming what it is. */
+function contentText(content) {
+    if (!Array.isArray(content)) {
+        return "";
+    }
+    return content
+        .map((block) => {
+        const record = (typeof block === "object" && block !== null ? block : {});
+        const kind = stringOf(record["type"]) ?? "block";
+        if (kind === "text") {
+            return stringOf(record["text"]) ?? "";
+        }
+        const resource = record["resource"];
+        const uri = stringOf(record["uri"]) ?? stringOf(resource?.["uri"]);
+        return uri === undefined ? `[${kind}]` : `[${kind} ${uri}]`;
+    })
+        .join("");
+}
+function oneLine(value) {
+    return value.replace(/[\r\n\t]+/g, " ");
+}
+function stringOf(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function abortableDelay(seconds, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, seconds * 1000);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/cli/main.d.ts

@@ -12,7 +12,9 @@ import { type WorkerInstallOptions } from "./commands/worker/install.js";
 import { type WorkerRunOptions } from "./commands/worker/run.js";
 import { type InterviewFlags } from "./firstRun.js";
 import { type RawApiOptions } from "./api/raw.js";
+import { type TailCommandOptions } from "./api/tail.js";
 import { type WaitCommandOptions } from "./api/wait.js";
+import { type ComputeProviderCheckOptions } from "./api/compute-provider-check.js";
 import { type InitCommandOptions } from "./factory/init.js";
 import { type GrantCommandOptions } from "./api/grant.js";
 import { type SkillPointer } from "./core/skill-pointer.js";
@@ -32,7 +34,7 @@ import { type SynthCommandOptions } from "./factory/synth.js";
  *
  * {@link topLevelHelpText} is what `orchestra --help` actually prints — this body plus a runtime epilogue.
  */
-export declare const TOP_LEVEL_HELP = "orchestra \u2014 the Orchestra command line.\n\norchestra fdk is the software factory as code. A software factory \u2014\nagents, environments, workflows, and the credentials that power them \u2014 is\ndefined in code: versioned, reviewed, type-checked. fdk apply reconciles\nthe platform to it, like cdk or terraform.\n\nUSAGE\n  orchestra <command> [flags]\n\nThe orchestra CLI does two jobs:\n\n  1  Factory as code \u2014 where change happens.\n     Declare the factory in code; fdk synth renders the plan, fdk diff\n     previews it, fdk apply makes the platform match. Code is the source of\n     truth, so every change is version-controlled, reviewed, and type-guarded.\n\n  2  Platform commands \u2014 probe the live factory.\n     Read state, reason about what exists, trial an idea before codifying\n     it, or fall back for a one-off: orchestra <noun> <verb>.\n\n  Rule of thumb: observe with commands. Change in code.\n\nSIGN IN\n  auth login   Authenticate and save a profile (both jobs use it)\n\nFACTORY AS CODE\n  fdk init     Write a starter factory into this folder\n  fdk synth    Render the factory to a plan\n  fdk diff     Preview what apply would change\n  fdk apply    Make the platform match the code\n\nPLATFORM COMMANDS   orchestra <noun> <verb> \u2014 nouns match API paths exactly\n  Build & run      agents  environments  sessions  machines  compute-enrollments\n                   pipelines  work-items  workflows  decisions  skills\n                   files  artifacts  volumes  projects  room-tokens\n                   compute-providers\n  Events & wiring  triggers  events  deliveries  connections\n                   connection-intents  install-links  connectors  providers\n  Models           models  model-aliases  model-configs  model-providers\n                   model-provider-keys  gateway-keys\n  Credentials      secrets  api-keys\n  Organization     organizations  organization-memberships  organization-invitations\n                   users  groups  user-grants  service-accounts  roles  policies  me\n  Observability    metrics  dashboards  health\n\n  Standard verbs: list \u00B7 get \u00B7 create \u00B7 update \u00B7 delete.\n  Command endpoints keep their own verb: sessions interrupt, work-items move,\n  workflows revert.\n  Typed flows: user-grants grant (mint a user-grant and walk its consent flow) \u00B7\n               sessions wait (poll a session until it settles) \u00B7\n               artifacts preview (serve an HTML page locally).\n  Write verbs exist for trial and fallback; durable change belongs in code.\n  Writing to a factory-managed resource warns: the next apply reverts it.\n  orchestra <noun> --help lists a noun's verbs and flags.\n\nBACKUP\n  api <METHOD> </path>   Raw authenticated call (like gh api). For when a typed\n                         command is missing or wrong \u2014 needing it is a bug; file it.\n\nYOUR CODING AGENT\n  skills install         Link the two bundled skills, orchestra and orchestra-fdk,\n                         into Claude Code or Codex. Both flags are required:\n                         --harness claude|codex|both|other --scope user|project.\n\nTHIS MACHINE\n  install                Install the CLI globally, ask what this machine is, then\n                         install the worker and the harness families you choose.\n  worker run             Serve this machine: claim its identity, then register.\n  worker install         Install the worker here, taking every answer from flags.\n  worker enroll          Redeem an enrollment token, then serve this machine.\n\nRUN YOUR AGENT HERE    The local environment on this machine, and the machines it runs.\n  local up               Start it, and print the two lines a shell needs to reach it.\n  local status           Read its four checks: boot, content, turns, environment.\n  local down             Stop it, and the machines it launched.\n  outpost token          Mint an offer for a machine you already own.\n  outpost up             Enrol this machine, or this container, and hold its worker.\n  outpost down           Stop that worker and revoke its enrollment.\n  Every other command reaches it the ordinary way, by base URL.\n\nCONVENTIONS\n  --output json          On every platform command; the default is a human table.\n  --body @file.json      Full request body where flags are too coarse.\n  --file <path>          On files create and artifacts create / create-version:\n                         store the bytes at <path> and let the create name them.\n  Credential values in responses print masked; --reveal or --output-file is the\n  deliberate path.\n  fdk apply defaults to any-change: it confirms the whole pre-flight preview\n  before any write, and stays silent when nothing changes. A single platform\n  command defaults to sensitive-only \u2014 it asks for credential values and IAM only.\n  Override with --require-approval never | sensitive-only | any-change or with\n  ORCHESTRA_REQUIRE_APPROVAL; the legacy --approve-secrets is exactly never.\n  Prompts and bindings are written as prompt`\u2026` / binding`\u2026` tagged templates\n  over the typed context handle \u2014 never hand-spelled {{\u2026}} strings.\n\nEXAMPLES\n  orchestra fdk apply                                    # reconcile the factory in ./\n  orchestra secrets create --name deepseek --value-from-command-line\n  orchestra sessions list --status RUNNING --output json\n  orchestra work-items move bug-12 --stage review\n  orchestra gateway-keys create --slug ci-smoke --output-file key.json\n\nLEARN MORE\n  orchestra <command> --help \u00B7 orchestra skills install --harness <name>\n  --scope user (links the reference and setup skills into your coding agent \u2014\n  the same documents AI agents use)\n";
+export declare const TOP_LEVEL_HELP = "orchestra \u2014 the Orchestra command line.\n\norchestra fdk is the software factory as code. A software factory \u2014\nagents, environments, workflows, and the credentials that power them \u2014 is\ndefined in code: versioned, reviewed, type-checked. fdk apply reconciles\nthe platform to it, like cdk or terraform.\n\nUSAGE\n  orchestra <command> [flags]\n\nThe orchestra CLI does two jobs:\n\n  1  Factory as code \u2014 where change happens.\n     Declare the factory in code; fdk synth renders the plan, fdk diff\n     previews it, fdk apply makes the platform match. Code is the source of\n     truth, so every change is version-controlled, reviewed, and type-guarded.\n\n  2  Platform commands \u2014 probe the live factory.\n     Read state, reason about what exists, trial an idea before codifying\n     it, or fall back for a one-off: orchestra <noun> <verb>.\n\n  Rule of thumb: observe with commands. Change in code.\n\nSIGN IN\n  auth login   Authenticate and save a profile (both jobs use it)\n\nFACTORY AS CODE\n  fdk init     Write a starter factory into this folder\n  fdk synth    Render the factory to a plan\n  fdk diff     Preview what apply would change\n  fdk apply    Make the platform match the code\n\nPLATFORM COMMANDS   orchestra <noun> <verb> \u2014 nouns match API paths exactly\n  Build & run      agents  environments  sessions  machines  compute-enrollments\n                   pipelines  work-items  workflows  decisions  skills\n                   files  artifacts  volumes  projects  room-tokens\n                   compute-providers\n  Events & wiring  triggers  events  deliveries  connections\n                   connection-intents  install-links  connectors  providers\n  Models           models  model-aliases  model-configs  model-providers\n                   model-provider-keys  gateway-keys\n  Credentials      secrets  api-keys\n  Organization     organizations  organization-memberships  organization-invitations\n                   users  groups  user-grants  service-accounts  roles  policies  me\n  Observability    metrics  dashboards  health\n\n  Standard verbs: list \u00B7 get \u00B7 create \u00B7 update \u00B7 delete.\n  Command endpoints keep their own verb: sessions interrupt, work-items move,\n  workflows revert.\n  Typed flows: user-grants grant (mint a user-grant and walk its consent flow) \u00B7\n               sessions wait (poll a session until it settles) \u00B7\n               sessions tail (print a session's items as they are saved) \u00B7\n               compute-providers check (show why a Launcher fails) \u00B7\n               artifacts preview (serve an HTML page locally).\n  Write verbs exist for trial and fallback; durable change belongs in code.\n  Writing to a factory-managed resource warns: the next apply reverts it.\n  orchestra <noun> --help lists a noun's verbs and flags.\n\nBACKUP\n  api <METHOD> </path>   Raw authenticated call (like gh api). For when a typed\n                         command is missing or wrong \u2014 needing it is a bug; file it.\n\nYOUR CODING AGENT\n  skills install         Link the two bundled skills, orchestra and orchestra-fdk,\n                         into Claude Code or Codex. Both flags are required:\n                         --harness claude|codex|both|other --scope user|project.\n\nTHIS MACHINE\n  install                Install the CLI globally, ask what this machine is, then\n                         install the worker and the harness families you choose.\n  worker run             Serve this machine: claim its identity, then register.\n  worker install         Install the worker here, taking every answer from flags.\n  worker enroll          Redeem an enrollment token, then serve this machine.\n\nRUN YOUR AGENT HERE    The local environment on this machine, and the machines it runs.\n  local up               Start it, and print the two lines a shell needs to reach it.\n  local status           Read its four checks: boot, content, turns, environment.\n  local down             Stop it, and the machines it launched.\n  outpost token          Mint an offer for a machine you already own.\n  outpost up             Enrol this machine, or this container, and hold its worker.\n  outpost down           Stop that worker and revoke its enrollment.\n  Every other command reaches it the ordinary way, by base URL.\n\nCONVENTIONS\n  --output json          On every platform command; the default is a human table.\n  --body @file.json      Full request body where flags are too coarse.\n  --file <path>          On files create and artifacts create / create-version:\n                         store the bytes at <path> and let the create name them.\n  Credential values in responses print masked; --reveal or --output-file is the\n  deliberate path.\n  fdk apply defaults to any-change: it confirms the whole pre-flight preview\n  before any write, and stays silent when nothing changes. A single platform\n  command defaults to sensitive-only \u2014 it asks for credential values and IAM only.\n  Override with --require-approval never | sensitive-only | any-change or with\n  ORCHESTRA_REQUIRE_APPROVAL; the legacy --approve-secrets is exactly never.\n  Prompts and bindings are written as prompt`\u2026` / binding`\u2026` tagged templates\n  over the typed context handle \u2014 never hand-spelled {{\u2026}} strings.\n\nEXAMPLES\n  orchestra fdk apply                                    # reconcile the factory in ./\n  orchestra secrets create --name deepseek --value-from-command-line\n  orchestra sessions list --status RUNNING --output json\n  orchestra work-items move bug-12 --stage review\n  orchestra gateway-keys create --slug ci-smoke --output-file key.json\n\nLEARN MORE\n  orchestra <command> --help \u00B7 orchestra skills install --harness <name>\n  --scope user (links the reference and setup skills into your coding agent \u2014\n  the same documents AI agents use)\n";
 /**
  * A function rather than a constant because the epilogue names an ABSOLUTE PATH that differs per install and
  * can only be resolved by the running process. `buildProgram` calls it once and pins the result, so the text
@@ -76,6 +78,8 @@ export interface CommandHandlers {
     apply: (options: ApplyOptions) => void | Promise<void>;
     grant: (options: GrantCommandOptions) => void | Promise<void>;
     wait: (id: string, options: WaitCommandOptions) => void | Promise<void>;
+    tail: (id: string, options: TailCommandOptions) => void | Promise<void>;
+    computeProvidersCheck: (id: string, options: ComputeProviderCheckOptions) => void | Promise<void>;
     api: (method: string, path: string, options: RawApiOptions) => void | Promise<void>;
     skillInstall: (options: SkillInstallOptions) => void | Promise<void>;
     artifactsPreview: (file: string, options: PreviewCommandOptions) => void | Promise<void>;

package/dist/cli/main.js

@@ -30,7 +30,9 @@ import { REQUIRE_APPROVAL_ENV, requireApprovalHelp } from "./core/approval-polic
 import { AUTH_ENV, authFlagsFrom, DEFAULT_PLATFORM_BASE_URL } from "./core/auth.js";
 import { apiCommand, RAW_METHODS } from "./api/raw.js";
 import { registerPlatformCommands } from "./api/register.js";
+import { tailCommand } from "./api/tail.js";
 import { waitCommand } from "./api/wait.js";
+import { computeProviderCheckCommand } from "./api/compute-provider-check.js";
 import { APPLY_APPROVAL_DEFAULT, applyCommand } from "./factory/apply.js";
 import { diffCommand } from "./factory/diff.js";
 import { DEFAULT_TEMPLATE, initCommand, MODEL_KEY_CHOICES, OFFERED_TEMPLATES } from "./factory/init.js";
@@ -107,6 +109,8 @@ PLATFORM COMMANDS   orchestra <noun> <verb> — nouns match API paths exactly
   workflows revert.
   Typed flows: user-grants grant (mint a user-grant and walk its consent flow) ·
                sessions wait (poll a session until it settles) ·
+               sessions tail (print a session's items as they are saved) ·
+               compute-providers check (show why a Launcher fails) ·
                artifacts preview (serve an HTML page locally).
   Write verbs exist for trial and fallback; durable change belongs in code.
   Writing to a factory-managed resource warns: the next apply reverts it.
@@ -225,6 +229,8 @@ export const defaultHandlers = {
     apply: (options) => applyCommand(options),
     grant: (options) => grantCommand(options),
     wait: (id, options) => waitCommand(id, options),
+    tail: (id, options) => tailCommand(id, options),
+    computeProvidersCheck: (id, options) => computeProviderCheckCommand(id, options),
     api: (method, path, options) => apiCommand(method, path, options),
     skillInstall: (options) => skillInstallCommand(options),
     artifactsPreview: async (file, options) => {
@@ -489,6 +495,22 @@ function attachTypedFlows(program, handlers, pointer) {
         .option("--output-file <path>", "write the full raw settled resource as JSON to <path> (mode 0600)")
         .description("poll a session until it settles")
         .action((id, options) => handlers.wait(id, options));
+    // Reads the items list through its cursor and its waiting read, so a running turn paces the loop.
+    addAuthOptions(generatedNoun(program, "sessions", "tail").command("tail"))
+        .argument("<id>", "session id (session_…)")
+        .option("--after <item id>", "start after this item (default: print the items that already exist first)")
+        .option("--until-settled", "exit when the turn ends, printing the session's status")
+        .option("--output <mode>", "output mode: table (default) or json, one item per line")
+        .option("--reveal", "print credential material in full instead of masking it")
+        .description("print each item of a session as it is saved: messages and thoughts in full, tool calls as one line")
+        .addHelpText("after", "\nWith --until-settled it exits 0 once the turn has ended, whatever the status, as `sessions wait` does.\n" +
+        "Without it, it follows the session until it is stopped with Ctrl-C.\n")
+        .action((id, options) => handlers.tail(id, options));
+    addAuthOptions(generatedNoun(program, "compute-providers", "check").command("check"))
+        .argument("<id>", "compute provider id or slug")
+        .option("--output <mode>", "output mode: table (default) or json")
+        .description("read a compute provider and show why its Launcher does not work; exit 1 when it does not")
+        .action((id, options) => handlers.computeProvidersCheck(id, options));
     // A grant is never a declared resource: this mints the intent under the developer's own token and waits
     // while they finish the dance in their own authenticated browser session.
     addAuthOptions(generatedNoun(program, "user-grants", "grant").command("grant"))