@relayflows/sdk 2.0.30 → 2.0.32

package/dist/cli/cli-probe.js

@@ -0,0 +1,166 @@
+import { accessSync, constants } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { execFile, spawnSync } from 'node:child_process';
+import { agentEnvironment, brokerEnvironment } from '../communication/environment.js';
+import { adapterIdentification, authenticationProbe, cliAdapterKind, displayInvocation, modelReadinessProbe } from '../cli-adapter.js';
+import { MODEL_ENV } from '../worker-cli.js';
+import { CliProbeError } from '../preflight.js';
+/** One decision sequence; checking uses synchronous I/O, live flows yield the loop. */
+export function probeCli(...args) {
+    return driveSync(probeSequence(...args));
+}
+export async function probeCliAsync(...args) {
+    const sequence = probeSequence(...args);
+    let next = sequence.next();
+    while (!next.done)
+        next = sequence.next(await runProbeAsync(next.value));
+    return next.value;
+}
+export function resolveExecutable(command, directory) {
+    return driveSync(executableSequence(command, directory));
+}
+function driveSync(sequence) {
+    let next = sequence.next();
+    while (!next.done) {
+        const request = next.value;
+        const result = spawnSync(request.executable, request.invocation.args, {
+            ...probeOptions(request),
+            // Preserve the old synchronous probe contract: provider CLIs must not
+            // inherit a readable stdin that can block auth/identify probes.
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const failure = classifySpawnFailure(result.error, result.signal, request.invocation.timeoutMs);
+        if (failure !== undefined)
+            throw failure;
+        next = sequence.next({ status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' });
+    }
+    return next.value;
+}
+function probeOptions({ directory, invocation, environment }) {
+    const env = { ...environment };
+    delete env[MODEL_ENV];
+    if (invocation.modelEnv !== undefined)
+        env[MODEL_ENV] = invocation.modelEnv;
+    return { cwd: directory, encoding: 'utf8', timeout: invocation.timeoutMs,
+        maxBuffer: 1024 * 1024, env };
+}
+function runProbeAsync(request) {
+    return new Promise((resolve, reject) => {
+        const child = execFile(request.executable, request.invocation.args, probeOptions(request), (error, stdout, stderr) => {
+            // Numeric exit codes are probe results; launch, timeout, signal and buffer
+            // errors are failures to collect a fact, just as in the synchronous driver.
+            if (error?.killed && typeof error.code !== 'string')
+                return reject(new CliProbeError(`timeout:${request.invocation.timeoutMs}ms`));
+            const failure = classifySpawnFailure(error !== null && typeof error.code !== 'number' && error.signal == null ? error : undefined, error?.signal ?? null, request.invocation.timeoutMs);
+            if (failure !== undefined)
+                return reject(failure);
+            resolve({ status: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
+                stdout, stderr });
+        });
+        child.stdin?.end();
+    });
+}
+function* probeSequence(cli, directory, model, execution) {
+    const executable = yield* executableSequence(cli, directory);
+    if (executable === undefined)
+        return { exists: false, authenticated: false };
+    const kind = cliAdapterKind(executable);
+    // Relay owns interactive CLI launch/injection. Its generic PTY path is not
+    // the headless wrapper protocol; do not demand that protocol from Gemini,
+    // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
+    if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
+        return { exists: true, supported: true, authenticated: 'unverified' };
+    }
+    const environment = execution === 'managed'
+        ? { ...brokerEnvironment(process.env), ...agentEnvironment(executable) } : process.env;
+    const probe = (invocation) => ({ executable, directory, invocation, environment });
+    const identification = adapterIdentification(kind);
+    const identified = yield probe(identification.invocation);
+    if (identified.status !== 0
+        || (identification.expectedStdout !== undefined
+            && identified.stdout.trim() !== identification.expectedStdout)) {
+        return { exists: true, supported: false, authenticated: false };
+    }
+    const auth = authenticationProbe(kind);
+    const authCommand = displayInvocation(cli, auth);
+    if (model === undefined) {
+        return {
+            exists: true,
+            supported: true,
+            authenticated: (yield probe(auth)).status === 0,
+            authCommand,
+        };
+    }
+    const scoped = modelReadinessProbe(kind, model);
+    const modelCommand = displayInvocation(cli, scoped);
+    // A successful real provider round trip (or identified wrapper probe)
+    // proves both auth and exact-model access. On failure, run the adapter's
+    // actual auth command solely to classify auth vs model access truthfully.
+    if ((yield probe(scoped)).status === 0) {
+        return {
+            exists: true,
+            supported: true,
+            authenticated: true,
+            modelAvailable: true,
+            authCommand,
+            modelCommand,
+        };
+    }
+    const authProbe = yield probe(auth);
+    const authenticated = authProbe.status === 0;
+    return {
+        exists: true,
+        supported: true,
+        authenticated,
+        modelAvailable: false,
+        authCommand,
+        modelCommand,
+        // Only on failure: on success there is nothing to explain, and the output
+        // is the most identity-bearing thing this function touches.
+        ...(authenticated
+            ? {}
+            : {
+                authExitCode: authProbe.status,
+                authFailureDetail: redactProbeOutput(`${authProbe.stderr}${authProbe.stdout}`).trim().slice(0, 500),
+            }),
+    };
+}
+/**
+ * Redact anything that looks like a credential or an account identifier.
+ *
+ * `auth status` output is diagnostic, but it is also the one place an account
+ * email, org id or token fragment can appear. The point of surfacing it is to
+ * say WHY a probe failed, which survives redaction; leaking an identity into a
+ * refusal message that gets pasted into issues does not.
+ */
+function redactProbeOutput(text) {
+    return text
+        .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '<redacted-email>')
+        .replace(/\b(sk|pk|oat|rt)[-_][A-Za-z0-9._-]{8,}/gi, '<redacted-token>')
+        .replace(/\b[A-Fa-f0-9]{32,}\b/g, '<redacted-hex>');
+}
+function* executableSequence(command, directory) {
+    if (command.includes('/') || isAbsolute(command)) {
+        const path = isAbsolute(command) ? command : resolve(directory, command);
+        try {
+            accessSync(path, constants.X_OK);
+            return path;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const result = yield { executable: 'which', directory: process.cwd(),
+        invocation: { args: [command], timeoutMs: 5_000 }, environment: process.env };
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
+function classifySpawnFailure(error, signal, timeoutMs) {
+    if (error !== undefined) {
+        const detail = error.code === 'ETIMEDOUT'
+            ? `timeout:${timeoutMs}ms`
+            : 'spawn_failed';
+        return new CliProbeError(detail);
+    }
+    return signal === null ? undefined : new CliProbeError(`signal:${signal}`);
+}
+//# sourceMappingURL=cli-probe.js.map

package/dist/cli/cli-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-probe.js","sourceRoot":"","sources":["../../src/cli/cli-probe.ts"],"names":[],"mappings":"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"}

package/dist/cli/cloud-format.d.ts

@@ -0,0 +1,9 @@
+export declare function thousands(value: number): string;
+export declare function dollars(value: number): string;
+/** Agent- and flow-authored names cannot inject terminal control sequences. */
+export declare function safe(text: string): string;
+export declare function errorLines(text: string, indent: string): string[];
+/** ISO-8601 to the second: a list column, not a timestamp to do arithmetic on. */
+export declare function instant(value: string | null): string;
+export declare function ago(value: string | null, now: number): string;
+//# sourceMappingURL=cloud-format.d.ts.map

package/dist/cli/cloud-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-format.d.ts","sourceRoot":"","sources":["../../src/cli/cloud-format.ts"],"names":[],"mappings":"AAYA,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,+EAA+E;AAC/E,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzC;AAoBD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBjE;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAIpD;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI7D"}

package/dist/cli/cloud-format.js

@@ -0,0 +1,77 @@
+// The cells every hosted-run page is built from.
+//
+// Moved out of `cli/cloud-read.ts` verbatim when the live views (`--watch`,
+// `--follow`) needed the same formatting: the run list, the status page and
+// the watched page must render a count, a cost and an instant identically, or
+// a reader would have to learn which verb they were looking at first.
+//
+// Depends on nothing in `cli/` but `formatDuration`, so every other Cloud CLI
+// module can import it without an import cycle.
+import { formatDuration } from './status.js';
+export function thousands(value) {
+    return String(value).replace(/\B(?=(\d{3})+(?!\d))/gu, ',');
+}
+export function dollars(value) {
+    return `$${value.toFixed(6).replace(/0+$/u, '').replace(/\.$/u, '')}`;
+}
+/** Agent- and flow-authored names cannot inject terminal control sequences. */
+export function safe(text) {
+    return text.replace(/[\u0000-\u001F\u007F-\u009F]/gu, '?');
+}
+/**
+ * Render a run's `error` as readable lines rather than one control-char smear.
+ *
+ * Cloud stores the runner's terminal output in this field, newlines and all, so
+ * passing it through `safe()` alone turns a 200-line tail into a single line of
+ * `?` separators. Long runs are dominated by lease renewals — one line every
+ * 10s for the life of every agent step, differing only in the deadline — which
+ * are worth counting, not reading.
+ *
+ * Collapsing is deliberately narrow: two adjacent lines merge only when they
+ * are character-for-character identical once a trailing integer is masked. A
+ * shared prefix is NOT line identity — runner lines put the step name, reason
+ * or message after a long fixed prefix, so collapsing on a prefix would hide
+ * distinct diagnostics behind a similarity count. The final line never
+ * collapses into an earlier one, because that is where the failure is.
+ */
+const TRAILING_NUMBER = /\d+(?=\D{0,2}$)/u;
+export function errorLines(text, indent) {
+    const raw = text.split(/\r\n|\r|\n/u).map((line) => line.trimEnd()).filter((line) => line !== '');
+    if (raw.length === 0)
+        return [];
+    const key = (line) => line.replace(TRAILING_NUMBER, '#');
+    const collapsed = [];
+    raw.forEach((line, index) => {
+        const previous = collapsed.at(-1);
+        const isLast = index === raw.length - 1;
+        if (previous !== undefined && !isLast && key(previous.line) === key(line))
+            previous.count += 1;
+        else
+            collapsed.push({ line, count: 1 });
+    });
+    const rendered = collapsed.map(({ line, count }) => count === 1 ? safe(line) : `${safe(line)}  (${count} times, differing only in a number)`);
+    const HEAD = 2;
+    const TAIL = 12;
+    if (rendered.length <= HEAD + TAIL + 1)
+        return rendered.map((line) => `${indent}${line}`);
+    const elided = rendered.length - HEAD - TAIL;
+    return [
+        ...rendered.slice(0, HEAD),
+        `… ${elided} more line${elided === 1 ? '' : 's'} (full text: --json)`,
+        ...rendered.slice(-TAIL),
+    ].map((line) => `${indent}${line}`);
+}
+/** ISO-8601 to the second: a list column, not a timestamp to do arithmetic on. */
+export function instant(value) {
+    if (value === null)
+        return 'unknown';
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString().replace(/\.\d{3}Z$/u, 'Z') : 'unknown';
+}
+export function ago(value, now) {
+    if (value === null)
+        return 'unknown';
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? `${formatDuration(now - parsed)} ago` : 'unknown';
+}
+//# sourceMappingURL=cloud-format.js.map

package/dist/cli/cloud-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-format.js","sourceRoot":"","sources":["../../src/cli/cloud-format.ts"],"names":[],"mappings":"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"}

package/dist/cli/cloud-live.d.ts

@@ -0,0 +1,39 @@
+import { type CloudReadOptions } from './cloud-refusal.js';
+import type { CliIo } from '../cli.js';
+export interface CloudLiveOptions extends CloudReadOptions {
+    /** Milliseconds between polls. Injected by tests; 1..60000, as the waiter accepts. */
+    pollIntervalMs?: number;
+    /** Injected by tests so no suite sleeps; production uses the abortable sleep. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Redraw the hosted status page until the run is terminal, then leave the
+ * final page up and exit with the run's outcome.
+ *
+ * The detail and the step rows are two requests against two projections, so
+ * the page is a pair of reads and not an atomic snapshot: a step row can lag
+ * the header it is drawn under by one poll. That is a property of the API, and
+ * this view reports what each read said rather than reconciling them.
+ */
+export declare function runCloudStatusWatch(args: {
+    runId?: string;
+    json: boolean;
+}, io: CliIo, options?: CloudLiveOptions): Promise<0 | 1 | 2>;
+/**
+ * Append the hosted runner log until the run is terminal and its log is drained.
+ *
+ * The route serves the log from an offset, but this client does not page it:
+ * the offsets are byte counts and the content is a JavaScript string, and
+ * subtracting one from the other silently loses text the moment a log contains
+ * a non-ASCII character — which the runner's own transition lines do. Until
+ * the byte-range contract can be checked against the server, each poll reads
+ * the whole log and prints the part that is new, refusing outright if what it
+ * already showed is no longer a prefix of what Cloud serves. That costs a full
+ * read per poll and holds the log in memory; it cannot duplicate or drop a line.
+ */
+export declare function runCloudLogsFollow(args: {
+    runId: string;
+    step: string | undefined;
+    json: boolean;
+}, io: CliIo, options?: CloudLiveOptions): Promise<0 | 1 | 2>;
+//# sourceMappingURL=cloud-live.d.ts.map

package/dist/cli/cloud-live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-live.d.ts","sourceRoot":"","sources":["../../src/cli/cloud-live.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAsD,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG/G,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAMvC,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AA2CD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,EACvC,EAAE,EAAE,KAAK,EACT,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CA+CpB;AAuGD;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,EAChE,EAAE,EAAE,KAAK,EACT,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAkGpB"}

package/dist/cli/cloud-live.js

@@ -0,0 +1,325 @@
+// `flows status --cloud --watch` and `flows logs <run> --follow`: the two
+// hosted reads that keep reading.
+//
+// The one-shot verbs (cli/cloud-read.ts) answer "what did that run do". These
+// two answer "what is it doing", by asking again until the run is over. Three
+// properties separate them from a loop around the one-shot reads:
+//
+//  1. **The exit code is the run's.** A finished page is not evidence that the
+//     run succeeded; `getCloudRunDetailLive` validates the same record
+//     `flows run --wait` blocks on, so `--watch` and `--follow` exit 0 only on
+//     an attested `completed`/`success`, 1 on an attested failure or a
+//     cancellation, and refuse a terminal record that attests neither.
+//  2. **A frame is whole or absent.** The page is rendered, then the abort is
+//     checked, then the whole page leaves in one `io.stdout` call. A Ctrl-C
+//     mid-poll ends the command with a refusal and no half-drawn screen.
+//  3. **Nothing is invented while waiting.** A failed poll leaves the previous
+//     page and the consumed log exactly where they were; it never clears the
+//     screen to show an error, and never re-prints a line it has shown.
+//
+// Cancellation is the caller's: `runCli` hands these functions the signal it
+// owns for the verb's duration, and nothing here installs a process handler.
+// Aborting stops the observation, not the hosted run — the refusal says so.
+import { canonicalize } from '../canonical.js';
+import { getCloudRunDetailLive, getCloudRunLog, getCloudRunSteps, } from '../cloud-read.js';
+import { isCloudRunActive } from '../cloud-run-record.js';
+import { endsWithOpenCredentialHeader, openCredentialStart, openSecretStart, redact } from '../redact.js';
+import { thousands } from './cloud-format.js';
+import { fail, isTransientRead, refusalFor, RUN_ID_REQUIRED } from './cloud-refusal.js';
+import { renderCloudStatus, scrubRun, scrubSteps } from './cloud-status-view.js';
+import { sleepInterruptible } from './interruptible-sleep.js';
+/** The cadence `waitForCloudFlowRun` polls at; not a user flag on either verb. */
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const MAX_BACKOFF_MS = 30_000;
+/** Clears the screen only for a terminal; a redirected page must stay text. */
+function clearSequence(io) {
+    return io.tty === true ? '\u001b[2J\u001b[H' : '';
+}
+/** The same delay schedule as `waitForCloudFlowRun`: ×2 per failure, capped. */
+function delayFor(failures, interval) {
+    return failures === 0 ? interval : Math.min(interval * 2 ** (failures - 1), MAX_BACKOFF_MS);
+}
+/** The hosted `flows run --wait` mapping: only an attested success is 0. */
+function exitFor(state) {
+    return state.status === 'completed' ? 0 : 1;
+}
+function aborted(verb, runId, json, io) {
+    fail({
+        code: 'observation_aborted', exit: 1,
+        message: `Stopped ${verb} run ${runId}; the hosted run has not been cancelled.`,
+    }, json, io);
+    return 1;
+}
+/**
+ * Has the caller cancelled?
+ *
+ * A function rather than `signal?.aborted` at each site on purpose: `aborted`
+ * is a readonly property, so an inline check narrows the signal's type for the
+ * rest of the block and the compiler then calls every later check dead — which
+ * is exactly backwards for a value that changes under an await.
+ */
+function isAborted(signal) {
+    return signal !== undefined && signal.aborted;
+}
+function invalidInterval(interval) {
+    return !Number.isSafeInteger(interval) || interval < 1 || interval > 60_000;
+}
+// -------------------------------------------------- flows status --cloud --watch
+/**
+ * Redraw the hosted status page until the run is terminal, then leave the
+ * final page up and exit with the run's outcome.
+ *
+ * The detail and the step rows are two requests against two projections, so
+ * the page is a pair of reads and not an atomic snapshot: a step row can lag
+ * the header it is drawn under by one poll. That is a property of the API, and
+ * this view reports what each read said rather than reconciling them.
+ */
+export async function runCloudStatusWatch(args, io, options = {}) {
+    const env = options.env ?? process.env;
+    const clock = options.now ?? Date.now;
+    const signal = options.signal;
+    const interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const sleep = options.sleep ?? sleepInterruptible;
+    if (args.runId === undefined || args.runId.length === 0)
+        return fail(RUN_ID_REQUIRED, args.json, io);
+    const runId = args.runId;
+    if (invalidInterval(interval)) {
+        return fail({ code: 'cloud_configuration', exit: 2, message: 'pollIntervalMs must be an integer from 1 to 60000.' }, args.json, io);
+    }
+    let failures = 0;
+    for (;;) {
+        if (isAborted(signal))
+            return aborted('watching', runId, args.json, io);
+        let live;
+        let steps;
+        try {
+            live = await getCloudRunDetailLive(runId, options);
+            if (isAborted(signal))
+                return aborted('watching', runId, args.json, io);
+            steps = await getCloudRunSteps(runId, options);
+        }
+        catch (error) {
+            if (isAborted(signal))
+                return aborted('watching', runId, args.json, io);
+            if (!isTransientRead(error))
+                return fail(refusalFor(error, `run ${runId}`, env), args.json, io);
+            // The previous page stays exactly as it was: a poll that did not
+            // complete is not news about the run.
+            failures = Math.min(failures + 1, 16);
+            await sleep(delayFor(failures, interval), signal);
+            continue;
+        }
+        failures = 0;
+        const run = scrubRun(live.detail, env);
+        const scrubbed = scrubSteps(steps, env);
+        const terminal = !isCloudRunActive(live.state.status);
+        // Rendered before the abort check and emitted after it, in one call: an
+        // interrupt between two lines of a frame would leave a torn page.
+        const page = args.json ? '' : `${clearSequence(io)}${renderCloudStatus(run, scrubbed, clock()).join('\n')}`;
+        if (isAborted(signal))
+            return aborted('watching', runId, args.json, io);
+        if (!args.json)
+            io.stdout(page);
+        if (terminal) {
+            if (args.json)
+                io.stdout(canonicalize({ v: 1, ok: true, run, steps: scrubbed, now_ms: clock() }));
+            return exitFor(live.state);
+        }
+        await sleep(interval, signal);
+    }
+}
+/**
+ * Print `text` as lines.
+ *
+ * Splitting is on `\n` only, and one trailing `\r` per line is dropped: a
+ * CRLF log printed with its carriage returns intact makes a terminal overwrite
+ * each line it just drew. A final newline ends the last line rather than
+ * starting an empty one. Blank lines and repeated identical lines are
+ * preserved — they are the log.
+ */
+function writeLines(text, state, io) {
+    const lines = text.split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    for (const line of lines) {
+        io.stdout(line.replace(/\r$/u, ''));
+        state.emitted = true;
+    }
+}
+/** The last line boundary at or before `at`: 0, or the index after a newline. */
+function lineBoundaryAtOrBefore(text, at) {
+    return at <= 0 ? 0 : text.lastIndexOf('\n', at - 1) + 1;
+}
+/**
+ * Release every line the log has settled on, redacted as one block.
+ *
+ * Four things hold a line back. `openSecretStart` marks where a secret value
+ * has begun and not ended, so nothing at or past it can be shown until the
+ * next poll completes it. `openCredentialStart` marks a trailing credential
+ * header — `authorization:`, `Bearer`, a callback-token name, or an
+ * unterminated credential JSON field — whose value may only arrive on a later
+ * poll; releasing the header first would leave the value without the context
+ * the redactor needs. A block is never ended on a bare credential header even
+ * when more text follows, because the redactor folds the header's newline
+ * into its own match — the block-prefix check cannot see that the header's
+ * value lives on the next line. And a candidate block is released only when
+ * redacting it alone gives the same text as the front of the whole redacted
+ * remainder: if the cut fell inside something the redactor would have caught —
+ * the second line of a private key — the two disagree, and the cut moves back
+ * a line and is tried again.
+ *
+ * A poll that can release nothing prints nothing; the bytes are not lost, they
+ * are held until a later poll or the drain flush can redact them whole.
+ */
+function releaseLines(state, io, env) {
+    const raw = state.consumed;
+    if (state.released >= raw.length)
+        return;
+    const remainder = redact(raw.slice(state.released), env);
+    let cut = lineBoundaryAtOrBefore(raw, Math.min(openSecretStart(raw, env), openCredentialStart(raw)));
+    while (cut > state.released) {
+        if (endsWithOpenCredentialHeader(raw.slice(state.released, cut))) {
+            // A bare credential header as the released block's last line strands
+            // the value that starts on the next line — redact needs them together.
+            // Shrink until the header is inside the held remainder; it releases
+            // with its value line once that line is complete.
+            cut = lineBoundaryAtOrBefore(raw, cut - 1);
+            continue;
+        }
+        const block = redact(raw.slice(state.released, cut), env);
+        if (remainder.startsWith(block)) {
+            writeLines(block, state, io);
+            state.released = cut;
+            return;
+        }
+        cut = lineBoundaryAtOrBefore(raw, cut - 1);
+    }
+}
+/**
+ * Has Cloud finished publishing this log?
+ *
+ * Three facts, all required. The run being over does not mean the last bytes
+ * have been written; `done` alone does not mean the run is over (the route can
+ * report a completed *upload* of a log the run is still adding to); and a
+ * `done` envelope that carries fewer bytes than it advertises has not served
+ * the tail. Stopping on any one of them alone would truncate the output, which
+ * is the one thing a follow must not do.
+ */
+function logDrained(log, terminal, content) {
+    return terminal && log.done && Buffer.byteLength(content, 'utf8') >= log.total_size;
+}
+/**
+ * Append the hosted runner log until the run is terminal and its log is drained.
+ *
+ * The route serves the log from an offset, but this client does not page it:
+ * the offsets are byte counts and the content is a JavaScript string, and
+ * subtracting one from the other silently loses text the moment a log contains
+ * a non-ASCII character — which the runner's own transition lines do. Until
+ * the byte-range contract can be checked against the server, each poll reads
+ * the whole log and prints the part that is new, refusing outright if what it
+ * already showed is no longer a prefix of what Cloud serves. That costs a full
+ * read per poll and holds the log in memory; it cannot duplicate or drop a line.
+ */
+export async function runCloudLogsFollow(args, io, options = {}) {
+    const env = options.env ?? process.env;
+    const signal = options.signal;
+    const interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const sleep = options.sleep ?? sleepInterruptible;
+    const runId = args.runId;
+    // Refused before any request: a step transcript is not an append-only stream
+    // this verb can follow. A retry replaces it, and the rendered form is built
+    // from the whole JSONL — attempt markers, session header, result footer —
+    // rather than a line at a time.
+    if (args.step !== undefined) {
+        return fail({
+            code: 'invalid_invocation', exit: 2,
+            message: '`flows logs --follow` follows the runner log, which is append-only; it cannot follow a step '
+                + 'transcript. Follow the run with `flows logs <run-id> --follow`, or read the step transcript once '
+                + 'with `flows logs <run-id> --step <name>`.',
+        }, args.json, io);
+    }
+    if (invalidInterval(interval)) {
+        return fail({ code: 'cloud_configuration', exit: 2, message: 'pollIntervalMs must be an integer from 1 to 60000.' }, args.json, io);
+    }
+    const state = { consumed: '', released: 0, emitted: false };
+    let header = false;
+    let failures = 0;
+    // A snapshot that satisfies every drain fact can still predate terminality:
+    // `done` can describe an upload finished while the run kept writing, and the
+    // log route can keep serving that snapshot past the terminal transition.
+    // The read that ends the follow has to postdate the terminal observation —
+    // which on the first sighting it cannot — so a terminal run always gets one
+    // more poll before its log counts as drained.
+    let terminalObserved = false;
+    for (;;) {
+        if (isAborted(signal))
+            return aborted('following', runId, args.json, io);
+        let outcome;
+        let log;
+        try {
+            // The run record first: a log read that follows a terminal status can
+            // only be missing bytes Cloud had not published yet, never bytes written
+            // after the check.
+            const live = await getCloudRunDetailLive(runId, options);
+            if (isAborted(signal))
+                return aborted('following', runId, args.json, io);
+            log = await getCloudRunLog(runId, undefined, options);
+            outcome = live.state;
+        }
+        catch (error) {
+            if (isAborted(signal))
+                return aborted('following', runId, args.json, io);
+            if (!isTransientRead(error))
+                return fail(refusalFor(error, `run ${runId}`, env), args.json, io);
+            failures = Math.min(failures + 1, 16);
+            await sleep(delayFor(failures, interval), signal);
+            continue;
+        }
+        failures = 0;
+        if (isAborted(signal))
+            return aborted('following', runId, args.json, io);
+        if (!log.content.startsWith(state.consumed)) {
+            return fail({
+                code: 'cloud_log_rewritten', exit: 1,
+                message: `Cloud's runner log for run ${runId} no longer begins with the ${thousands(state.consumed.length)} `
+                    + 'characters already shown, so following it would skip or repeat output. Read it whole with '
+                    + `\`flows logs ${runId}\`.`,
+            }, args.json, io);
+        }
+        state.consumed = log.content;
+        const terminal = !isCloudRunActive(outcome.status);
+        const drained = terminalObserved && logDrained(log, terminal, log.content);
+        terminalObserved ||= terminal;
+        if (!args.json) {
+            if (!header) {
+                io.stdout(`LOG ${runId}  runner  following  ${thousands(log.total_size)} bytes so far`);
+                header = true;
+            }
+            releaseLines(state, io, env);
+        }
+        if (!drained) {
+            await sleep(interval, signal);
+            continue;
+        }
+        // Drained: the last line may have no newline, and this is the only moment
+        // at which printing it cannot cut a line in half.
+        if (args.json) {
+            io.stdout(canonicalize({
+                v: 1, ok: true, run_id: runId, step: null,
+                bytes: log.offset, total_bytes: log.total_size, done: log.done,
+                content: redact(log.content, env),
+            }));
+            return exitFor(outcome);
+        }
+        if (state.released < state.consumed.length) {
+            writeLines(redact(state.consumed.slice(state.released), env), state, io);
+            state.released = state.consumed.length;
+        }
+        if (!state.emitted)
+            io.stdout('  (empty)');
+        io.stdout(`${outcome.status.toUpperCase()} ${runId} completionReason: `
+            + `${'completionReason' in outcome ? outcome.completionReason : 'unavailable'}`);
+        return exitFor(outcome);
+    }
+}
+//# sourceMappingURL=cloud-live.js.map