@shardflux/cli 0.1.0 → 0.3.0

package/dist/format.d.ts

@@ -3,7 +3,7 @@
  * `--json` output is the API's own objects (see README "JSON output"), so
  * these functions only shape what people read.
  */
-import type { AgentSession, FileList, Operation, WorkspaceView } from '@shardflux/sdk';
+import type { AgentSession, DraftState, FileList, Operation, Secret, SecretAccessEvent, SecretVersion, TemplateBuild, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateSummary, WorkspaceChange, WorkspaceSecretBindings, WorkspaceView } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
 export declare function json(value: unknown): string;
 export declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): string;
@@ -14,6 +14,8 @@ export declare function time(iso: string | null | undefined): string;
 export declare function pairs(obj: Record<string, unknown> | null | undefined): string;
 export declare function operationSummary(op: Operation | null | undefined): string;
 export declare const WORKSPACE_HEADERS: readonly ["ID", "KEY", "STATE", "DESIRED", "TEMPLATE", "OPERATION", "CREATED"];
+/** Observed state plus what sets the workspace apart: session, draft or test instance, and how it ended. */
+export declare function workspaceState(w: WorkspaceView): string;
 export declare function workspaceRow(w: WorkspaceView): string[];
 export declare function workspaceTable(ws: readonly WorkspaceView[]): string;
 export declare function isReady(w: WorkspaceView): boolean;
@@ -23,6 +25,12 @@ export declare function operationTable(ops: readonly Operation[]): string;
 export declare function operationDetail(op: Operation): string;
 export declare function sessionTable(sessions: readonly AgentSession[]): string;
 export declare function fileTable(list: FileList): string;
+export declare function secretTable(rows: readonly Secret[]): string;
+/** Secret metadata; there is no value to show (values are write-only). */
+export declare function secretDetail(s: Secret): string;
+export declare function secretVersionTable(rows: readonly SecretVersion[]): string;
+export declare function secretAccessTable(rows: readonly SecretAccessEvent[]): string;
+export declare function bindingsText(b: WorkspaceSecretBindings): string;
 /**
  * The usage summary (GET /v1/organizations/{id}/usage/summary): plan, period, measurement
  * freshness, then meters and allowances as tables. Columns absent from the response are omitted.
@@ -30,3 +38,14 @@ export declare function fileTable(list: FileList): string;
 export declare function usageText(summary: unknown): string;
 /** One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. */
 export declare function errorText(e: ErrorInfo, hint?: string): string;
+export declare function templateTable(rows: readonly TemplateSummary[]): string;
+/** Permission bits as the four-digit octal `ls -l` users read (e.g. 0755). */
+export declare function octal(mode: number): string;
+export declare function templateFileTable(rows: readonly TemplateFileEntry[]): string;
+export declare function templateEntryText(e: TemplateFileEntry): string;
+export declare function diffTable(rows: readonly TemplateDiffEntry[]): string;
+export declare function diffSummaryText(summary: unknown): string;
+export declare function changesTable(rows: readonly WorkspaceChange[]): string;
+export declare function draftText(d: TemplateDraft): string;
+export declare function draftStateTable(rows: readonly DraftState[]): string;
+export declare function buildText(b: TemplateBuild): string;

package/dist/format.js

@@ -44,8 +44,21 @@ export function operationSummary(op) {
     return `${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}`;
 }
 export const WORKSPACE_HEADERS = ['ID', 'KEY', 'STATE', 'DESIRED', 'TEMPLATE', 'OPERATION', 'CREATED'];
+/** Observed state plus what sets the workspace apart: session, draft or test instance, and how it ended. */
+export function workspaceState(w) {
+    const tags = [];
+    if (w.purpose === 'template_draft')
+        tags.push('draft');
+    else if (w.purpose === 'template_test')
+        tags.push('test instance');
+    else if (w.lifetime === 'session')
+        tags.push('session');
+    if (w.deleted_at)
+        tags.push(w.ended_reason ? `ended: ${w.ended_reason}` : 'deleted');
+    return tags.length ? `${w.observed_state} (${tags.join(', ')})` : w.observed_state;
+}
 export function workspaceRow(w) {
-    const state = w.deleted_at ? `${w.observed_state} (deleted)` : w.observed_state;
+    const state = workspaceState(w);
     return [w.id, w.workspace_key, state, w.desired_state, `${w.template.slug}@${w.template.version}`, operationSummary(w.active_operation), time(w.created_at)];
 }
 export function workspaceTable(ws) {
@@ -69,6 +82,15 @@ export function workspaceDetail(w) {
         ['operation', w.active_operation ? `${operationSummary(w.active_operation)} ${w.active_operation.id}` : '-'],
         ['pending', w.pending_reason ?? '-'],
         ['forked from', w.forked_from_workspace_id ?? '-'],
+        ...(w.lifetime !== undefined
+            ? [
+                ['lifetime', w.lifetime === 'session' ? `session (ends after ${w.idle_timeout_seconds ?? '-'} s idle, or on close)` : 'persistent'],
+                ['purpose', w.purpose],
+                ['disk layout', w.disk_layout],
+                ...(w.origin ? [['origin', w.origin.kind === 'fork' ? `fork of ${w.origin.workspace_id}` : `draft state ${w.origin.checkpoint_id ?? '(capturing)'} of ${w.origin.draft_workspace_id}`]] : []),
+                ...(w.ended_reason ? [['ended', w.ended_reason]] : []),
+            ]
+            : []),
         ['created', time(w.created_at)],
         ['deleted', time(w.deleted_at)],
     ]);
@@ -97,6 +119,38 @@ export function sessionTable(sessions) {
 export function fileTable(list) {
     return table(['TYPE', 'SIZE', 'MODIFIED', 'NAME'], list.entries.map((e) => [e.type, String(e.size), time(e.modified_at), e.name]));
 }
+export function secretTable(rows) {
+    return table(['ID', 'NAME', 'SCOPE', 'VERSION', 'TOOLS', 'UPDATED', 'DELETED'], rows.map((s) => [s.id, s.name, s.scope, String(s.current_version), s.permissions.allowed_tools.join(','), time(s.updated_at), time(s.deleted_at)]));
+}
+const idList = (ids, all) => (ids === null ? all : ids.length ? ids.join(', ') : '(none)');
+/** Secret metadata; there is no value to show (values are write-only). */
+export function secretDetail(s) {
+    return kv([
+        ['id', s.id],
+        ['name', s.name],
+        ['scope', s.scope === 'project' ? `project ${s.project_id ?? '-'}` : `organization ${s.organization_id}`],
+        ['description', s.description || '-'],
+        ['version', String(s.current_version)],
+        ['tools', s.permissions.allowed_tools.join(', ')],
+        ...(s.scope === 'organization' ? [['projects', idList(s.permissions.allowed_project_ids, '(every project)')]] : []),
+        ['workspaces', idList(s.permissions.allowed_workspace_ids, '(any)')],
+        ['created', `${time(s.created_at)} by ${s.created_by.type}:${s.created_by.id}`],
+        ['updated', time(s.updated_at)],
+        ['rotated', time(s.rotated_at)],
+        ['deleted', time(s.deleted_at)],
+    ]);
+}
+export function secretVersionTable(rows) {
+    return table(['VERSION', 'STATE', 'CREATED', 'BY', 'DESTROYED', 'REASON'], rows.map((v) => [String(v.version), v.state, time(v.created_at), `${v.created_by.type}:${v.created_by.id}`, time(v.destroyed_at), v.destroyed_reason ?? '-']));
+}
+export function secretAccessTable(rows) {
+    return table(['TIME', 'OUTCOME', 'REASON', 'TOOL', 'VERSION', 'WORKSPACE', 'PRINCIPAL', 'REQUEST'], rows.map((e) => [time(e.created_at), e.outcome, e.reason ?? '-', e.tool, e.secret_version === null ? '-' : String(e.secret_version), e.workspace_id, `${e.principal.type}:${e.principal.id}`, e.request_id ?? '-']));
+}
+export function bindingsText(b) {
+    if (b.secrets.length === 0)
+        return 'No secrets are bound to this workspace.\n';
+    return table(['NAME', 'STATUS', 'SCOPE', 'SECRET'], b.secrets.map((s) => [s.name, s.status, s.scope ?? '-', s.secret_id ?? '-']));
+}
 function isObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -175,3 +229,80 @@ export function errorText(e, hint) {
         : '';
     return `error: ${e.message}${reason} [${meta.join(' ')}]\n${issues}${hint ? `hint: ${hint}\n` : ''}`;
 }
+// ---- Templates v2 (contracts §19) ---------------------------------------------------------------
+export function templateTable(rows) {
+    return table(['SLUG', 'OWNER', 'OPEN VERSION', 'LAYOUTS', 'FILES', 'DRAFT', 'ARCHIVED'], rows.map((t) => {
+        const v = t.open_version;
+        return [
+            t.slug,
+            t.owner,
+            v ? `v${v.version}` : '-',
+            v?.disk_layouts?.join(',') ?? '-',
+            v?.files ? v.files.state : '-',
+            t.draft ? `${t.draft.workspace_key} (${t.draft.observed_state})` : '-',
+            time(t.archived_at),
+        ];
+    }));
+}
+/** Permission bits as the four-digit octal `ls -l` users read (e.g. 0755). */
+export function octal(mode) {
+    return mode.toString(8).padStart(4, '0');
+}
+export function templateFileTable(rows) {
+    return table(['TYPE', 'MODE', 'OWNER', 'SIZE', 'NAME'], rows.map((e) => [e.type, octal(e.mode), `${e.uid}:${e.gid}`, e.type === 'dir' ? `${e.child_count ?? 0} entries` : String(e.size_bytes), e.link_target ? `${e.name} -> ${e.link_target}` : e.name]));
+}
+export function templateEntryText(e) {
+    return kv([
+        ['path', e.path],
+        ['type', e.type],
+        ['size', `${e.size_bytes} bytes`],
+        ['mode', octal(e.mode)],
+        ['owner', `${e.uid}:${e.gid}`],
+        ['sha256', e.sha256 ?? '-'],
+        ['link target', e.link_target ?? '-'],
+        ['hardlink of', e.hardlink_of ?? '-'],
+        ...(e.type === 'dir' ? [['entries', String(e.child_count ?? 0)]] : []),
+    ]);
+}
+function side(x) {
+    if (!x)
+        return '-';
+    return `${x.type} ${x.type === 'symlink' ? `-> ${x.link_target ?? '?'}` : `${x.size_bytes} B`} ${octal(x.mode)} ${x.uid}:${x.gid}`;
+}
+export function diffTable(rows) {
+    return table(['CHANGE', 'BEFORE', 'AFTER', 'PATH'], rows.map((d) => [d.change, side(d.before), side(d.after), d.path]));
+}
+export function diffSummaryText(summary) {
+    if (typeof summary !== 'object' || summary === null)
+        return '';
+    const s = summary;
+    return `added ${s.added}, removed ${s.removed}, changed ${s.changed}, type changed ${s.type_changed}, metadata ${s.metadata}; +${s.bytes_added} / -${s.bytes_removed} bytes\n`;
+}
+export function changesTable(rows) {
+    return table(['CHANGE', 'TYPE', 'SIZE', 'MODE', 'PATH'], rows.map((c) => [c.change, c.type, String(c.size_bytes), c.mode, c.link_target ? `${c.path} -> ${c.link_target}` : c.path]));
+}
+export function draftText(d) {
+    const w = d.workspace;
+    return kv([
+        ['workspace', `${w.workspace_key} (${w.id})`],
+        ['state', `${w.observed_state} (desired ${w.desired_state})`],
+        ['base version', `${d.base_version.slug} v${d.base_version.version} (${d.base_version.id})`],
+        ['states', String(d.states_count)],
+        ['latest state', d.latest_state ? `${d.latest_state.checkpoint_id}${d.latest_state.label ? ` "${d.latest_state.label}"` : ''} ${time(d.latest_state.captured_at)}` : '-'],
+        ['test instances', `${d.test_instances_live} live`],
+        ['created', `${time(d.created_at)} by ${d.created_by.type}${d.created_by.id ? `:${d.created_by.id}` : ''}`],
+    ]);
+}
+export function draftStateTable(rows) {
+    return table(['STATE', 'LABEL', 'CAPTURED', 'BYTES', 'TEST INSTANCES'], rows.map((st) => [st.checkpoint_id, st.label ?? '-', time(st.captured_at), st.bytes === null ? '-' : String(st.bytes), String(st.test_instances)]));
+}
+export function buildText(b) {
+    return kv([
+        ['build', b.id],
+        ['template', `${b.template.slug} v${b.target_version ?? '?'}`],
+        ['state', `${b.state}${b.failure ? ` (${b.failure.code}: ${b.failure.message})` : ''}`],
+        ['registration', b.registration.state],
+        ['source', b.source_kind === 'workspace' ? `workspace ${b.source_workspace_id ?? '-'}${b.source_checkpoint_id ? ` checkpoint ${b.source_checkpoint_id}` : ''}` : 'recipe'],
+        ['version', b.template_version ? `${b.template_version.id}${b.template_version.published ? ' (published)' : ' (unpublished)'}` : '-'],
+    ]) + (b.state === 'published' || b.state === 'failed' || b.state === 'canceled' ? '' : `the build continues server side (--wait follows it; GET /v1/organizations/${b.organization_id}/template-builds/${b.id} reports it)\n`);
+}

package/dist/http.d.ts

@@ -9,5 +9,10 @@
  * 6.28) and `Connection: close` do not stall. A fresh connection per request
  * costs one TCP/TLS handshake, which is negligible for these call rates.
  * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ *
+ * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
+ * held by the server for up to 20 s). The SDK passes the caller's signal to its
+ * held polls itself, but not to the held open (`workspaces.open()` with `wait`
+ * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
  */
-export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch): typeof fetch;
+export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch, signal?: AbortSignal): typeof fetch;

package/dist/http.js

@@ -9,13 +9,22 @@
  * 6.28) and `Connection: close` do not stall. A fresh connection per request
  * costs one TCP/TLS handshake, which is negligible for these call rates.
  * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ *
+ * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
+ * held by the server for up to 20 s). The SDK passes the caller's signal to its
+ * held polls itself, but not to the held open (`workspaces.open()` with `wait`
+ * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
  */
-export function makeFetch(env, base = fetch) {
-    if (env.SHARDFLUX_HTTP_KEEPALIVE === '1')
-        return base;
+export function makeFetch(env, base = fetch, signal) {
+    const keepAlive = env.SHARDFLUX_HTTP_KEEPALIVE === '1';
     return (input, init) => {
         const headers = new Headers(init?.headers);
-        headers.set('connection', 'close');
-        return base(input, { ...init, headers });
+        const held = signal !== undefined && /\bwait\s*=/i.test(headers.get('prefer') ?? '');
+        if (keepAlive && !held)
+            return base(input, init);
+        if (!keepAlive)
+            headers.set('connection', 'close');
+        const s = held && signal ? (init?.signal ? AbortSignal.any([init.signal, signal]) : signal) : init?.signal;
+        return base(input, { ...init, headers, ...(s ? { signal: s } : {}) });
     };
 }

package/dist/index.d.ts

@@ -3,10 +3,11 @@
  * The executable is src/bin.ts; `run()` drives the same code in-process.
  */
 export { run, abortableSleep } from './main.js';
-export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, topHelp } from './args.js';
+export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, resolveWake, resolveWakeTimeout, topHelp } from './args.js';
 export type { CommandSpec, OptionSpec, Parsed, PositionalSpec, Values } from './args.js';
 export { HANDLERS, execExitCode, resolveWorkspace } from './commands.js';
 export type { Ctx, Handler, Io, Writer } from './commands.js';
 export { EXIT, AuthConfigError, InterruptedError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from './errors.js';
 export type { ErrorInfo } from './errors.js';
 export { errorText, json, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
+export { TimingRecorder, timingJson, timingText } from './timing.js';

package/dist/index.js

@@ -3,7 +3,8 @@
  * The executable is src/bin.ts; `run()` drives the same code in-process.
  */
 export { run, abortableSleep } from "./main.js";
-export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, topHelp } from "./args.js";
+export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, resolveWake, resolveWakeTimeout, topHelp } from "./args.js";
 export { HANDLERS, execExitCode, resolveWorkspace } from "./commands.js";
 export { EXIT, AuthConfigError, InterruptedError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
 export { errorText, json, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
+export { TimingRecorder, timingJson, timingText } from "./timing.js";

package/dist/main.js

@@ -5,11 +5,12 @@
  * the whole CLI can be driven by tests; bin.ts wires it to the real process.
  */
 import { SDK_VERSION, Shardflux } from '@shardflux/sdk';
-import { CLI_VERSION, parseCommandLine, resolveApiUrl } from "./args.js";
+import { CLI_VERSION, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { HANDLERS } from "./commands.js";
 import { AuthConfigError, EXIT, InterruptedError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
 import { errorText, json } from "./format.js";
 import { makeFetch } from "./http.js";
+import { TimingRecorder, timingJson, timingText } from "./timing.js";
 const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
 // Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
 const isLabel = (s) => s.length >= 1 && s.length <= 100 && ![...s].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
@@ -44,6 +45,9 @@ export async function run(argv, io, opts = {}) {
     const signal = opts.signal ?? new AbortController().signal;
     const rawKey = io.env.SHARDFLUX_API_KEY;
     const wantsJson = argv.slice(0, argv.includes('--') ? argv.indexOf('--') : argv.length).includes('--json');
+    // Every traced SDK call of the command (open, waited lifecycle calls, waits, wakes) reports here; --timing prints it.
+    const traces = new TimingRecorder();
+    let showTiming = false;
     const report = (err) => {
         const code = exitCodeFor(err, signal.aborted);
         const info = describeError(err);
@@ -52,7 +56,11 @@ export async function run(argv, io, opts = {}) {
             info.message = 'Interrupted.';
         }
         info.message = redact(info.message, rawKey);
-        io.stderr.write(redact(wantsJson ? json({ error: info }) : errorText(info, hintFor(info)), rawKey));
+        // --timing on a failure: the failed call's timing (err.timing, else the last recorded), before the error; with
+        // --json a `timing` field next to `error`.
+        const timing = showTiming ? traces.forError(err) : null;
+        const text = wantsJson ? json(showTiming ? { error: info, timing: timingJson(timing) } : { error: info }) : `${timing ? timingText(timing) : ''}${errorText(info, hintFor(info))}`;
+        io.stderr.write(redact(text, rawKey));
         return code;
     };
     let parsed;
@@ -76,13 +84,20 @@ export async function run(argv, io, opts = {}) {
         const agentLabel = parsed.global.agentLabel ?? io.env.SHARDFLUX_AGENT_LABEL ?? 'cli';
         if (!isLabel(agentLabel))
             throw new UsageError('--agent-label must be 1-100 printable characters');
+        const wake = resolveWake(parsed.global.wake, io.env.SHARDFLUX_NO_WAKE);
+        const wakeTimeoutMs = resolveWakeTimeout(parsed.global.wakeTimeout, io.env.SHARDFLUX_WAKE_TIMEOUT_MS);
+        showTiming = parsed.values.timing === true;
         let cloud;
         ctx = {
             io,
             json: parsed.global.json,
             apiUrl,
             agentLabel,
+            wake,
+            wakeTimeoutMs,
             signal,
+            timing: showTiming,
+            traces,
             cloud() {
                 if (cloud)
                     return cloud;
@@ -91,7 +106,14 @@ export async function run(argv, io, opts = {}) {
                     throw new AuthConfigError('SHARDFLUX_API_KEY is not set.');
                 if (!KEY_SHAPE.test(key))
                     throw new AuthConfigError('SHARDFLUX_API_KEY is not a Shardflux project key (expected sfk_<key id>_<secret>).');
-                cloud = new Shardflux({ apiKey: key, baseUrl: apiUrl, userAgent: `shard-cli/${CLI_VERSION} shardflux-sdk-ts/${SDK_VERSION}`, fetch: makeFetch(io.env), sleep: abortableSleep(signal) });
+                cloud = new Shardflux({
+                    apiKey: key,
+                    baseUrl: apiUrl,
+                    userAgent: `shard-cli/${CLI_VERSION} shardflux-sdk-ts/${SDK_VERSION}`,
+                    fetch: makeFetch(io.env, fetch, signal),
+                    sleep: abortableSleep(signal),
+                    onProgress: traces.listener,
+                });
                 return cloud;
             },
         };
@@ -116,5 +138,8 @@ export async function run(argv, io, opts = {}) {
         return report(new InterruptedError('Interrupted.'));
     if ('err' in outcome)
         return report(outcome.err);
+    // With --json the handler put the timing into its output; otherwise it follows the output, on stderr.
+    if (showTiming && !ctx.json && traces.last)
+        io.stderr.write(timingText(traces.last));
     return outcome.code;
 }

package/dist/timing.d.ts

@@ -0,0 +1,17 @@
+import type { LifecycleTiming, ProgressListener } from '@shardflux/sdk';
+export declare class TimingRecorder {
+    /** The timing of the last traced call that ended (token fetches are not lifecycle calls and are skipped). */
+    last: LifecycleTiming | null;
+    /** The operation the command's traced calls last observed: named when Ctrl-C interrupts a wait. */
+    operationId: string | null;
+    readonly listener: ProgressListener;
+    /**
+     * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
+     * carries the token fetch's timing, which is not a lifecycle call: then only a wake (if any) counts.
+     */
+    forError(err: unknown): LifecycleTiming | null;
+}
+/** The human form (stderr): formatTiming() of the SDK, one block. */
+export declare function timingText(t: LifecycleTiming): string;
+/** The `--json` form: the SDK's LifecycleTiming with the CLI's snake_case keys (the rest of its JSON is the API's). */
+export declare function timingJson(t: LifecycleTiming | null): Record<string, unknown> | null;

package/dist/timing.js

@@ -0,0 +1,65 @@
+/**
+ * `--timing`: where the time of a command's lifecycle call went, as @shardflux/sdk measures it (0.6.0+). The CLI
+ * does no timing of its own: the SDK traces open(), waited lifecycle calls, waitForOperation() and wakes, and emits
+ * each trace's LifecycleTiming in a `done` progress event (also on `err.timing` when the call fails). The recorder
+ * listens on the client (every traced call of the command), so a timing exists for failures too, including ones that
+ * carry no `timing` (network errors, Ctrl-C).
+ */
+import { formatTiming } from '@shardflux/sdk';
+export class TimingRecorder {
+    /** The timing of the last traced call that ended (token fetches are not lifecycle calls and are skipped). */
+    last = null;
+    /** The operation the command's traced calls last observed: named when Ctrl-C interrupts a wait. */
+    operationId = null;
+    listener = (e) => {
+        if (e.action === 'token' || e.action === 'tool')
+            return;
+        if (e.operationId)
+            this.operationId = e.operationId;
+        if (e.type === 'done')
+            this.last = e.timing;
+    };
+    /**
+     * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
+     * carries the token fetch's timing, which is not a lifecycle call: then only a wake (if any) counts.
+     */
+    forError(err) {
+        const own = typeof err === 'object' && err !== null ? err.timing : undefined;
+        return own && own.action !== 'token' ? own : this.last;
+    }
+}
+/** The human form (stderr): formatTiming() of the SDK, one block. */
+export function timingText(t) {
+    return `${formatTiming(t)}\n`;
+}
+/** The `--json` form: the SDK's LifecycleTiming with the CLI's snake_case keys (the rest of its JSON is the API's). */
+export function timingJson(t) {
+    if (!t)
+        return null;
+    const s = t.server;
+    return {
+        action: t.action,
+        outcome: t.outcome,
+        workspace_id: t.workspaceId,
+        operation_id: t.operationId,
+        total_ms: t.totalMs,
+        phases: t.phases.map((p) => ({ phase: p.phase, reason: p.reason, operation_id: p.operationId, start_ms: p.startMs, duration_ms: p.durationMs })),
+        retries: t.retries.map((r) => ({ at_ms: r.atMs, request: r.request, attempt: r.attempt, cause: r.cause, delay_ms: r.delayMs })),
+        server: s
+            ? {
+                operation_id: s.operationId,
+                kind: s.kind,
+                state: s.state,
+                queued_ms: s.queuedMs,
+                run_ms: s.runMs,
+                total_ms: s.totalMs,
+                start_path: s.startPath,
+                warm_fallback: s.warmFallback,
+                resume_path: s.resumePath,
+                boot_to_ready_ms: s.bootToReadyMs,
+                host_timings_ms: s.hostTimingsMs,
+            }
+            : null,
+        outside_server_ms: t.outsideServerMs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "shard: the Shardflux command line. Open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
@@ -32,13 +32,14 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@shardflux/sdk": "^0.5.0"
+    "@shardflux/sdk": "^0.6.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",