@shardflux/cli 0.23.1 → 0.24.1

package/dist/conversation-commands.d.ts

@@ -1,4 +1,5 @@
 import type { Ctx, Handler } from './commands.js';
+import type { CellClient, ConversationPermission, ListeningPort, MessageAttachment, PermissionDecision } from '@shardflux/sdk';
 export declare function conversationClient(ctx: Ctx): import("@shardflux/sdk").Shardflux | import("@shardflux/sdk").ShardfluxAccount;
 /** Why a conversation needs you, as one line of at most `max` characters; undefined in other states (0.18.0+). */
 export declare function questionLine(c: {
@@ -9,5 +10,34 @@ export declare function questionLine(c: {
  * prompt names it; a name someone chose stays (0.21.1+). The menu bar's AgentNaming.isRawIdentifier rule. */
 export declare function displayTitle(c: {
     title: string;
+    title_short?: string | null;
 }): string;
+/**
+ * `--file <path>` (repeatable, 0.25.0+): files for a message, read whole and checked before anything is sent. Each one
+ * keeps its file name in the conversation's computer.
+ */
+export declare function readAttachments(paths: readonly string[]): Promise<MessageAttachment[]>;
+/** A permission request's command, path or URL as one line of at most `max` characters: its first line (0.25.0+). */
+export declare function detailLine(detail: string, max?: number): string;
+/** One permission request as a list row (0.25.0+): id, state, title, detail, and the decision once answered. */
+export declare function permissionLine(p: ConversationPermission): string;
+/** `shard conversations answer` words (0.25.0+): allow, always and deny, or the API's own decision names. */
+export declare const PERMISSION_DECISIONS: Readonly<Record<string, PermissionDecision>>;
+/** --pick values as a question's answers (0.25.0+): "<question>=<option>" names the question; a bare option answers
+ * the request's only question (repeated, a multi-select one's several options). `shard needs-you answer` passes the
+ * questions of a board item. */
+export declare function pickAnswers(p: Pick<ConversationPermission, 'questions'>, picks: readonly string[]): Record<string, string | string[]>;
+/** A listening port as `conversations get` prints it: the port, its program, then its URL once exposed, else where it
+ * listens ("5173  node  https://… (exposed)", "5432  postgres  127.0.0.1 only"). */
+export declare function portLine(p: ListeningPort): string;
+/** How much of the terminal's past `conversations watch` shows before the live output: its last 256 KiB. */
+export declare const WATCH_TAIL_BYTES: number;
+/**
+ * Streams a conversation's terminal read-only from its last WATCH_TAIL_BYTES until its session exits or ctx.signal
+ * aborts (Ctrl-C), writing the terminal's bytes to stdout as they arrive. Nothing is ever typed into it, and the attach is
+ * passive: it never wakes the computer or keeps it awake while the terminal is idle (reading the terminal's size first
+ * wakes a sleeping computer, as every cell call does unless --no-wake). A host without passive attach gets an ordinary
+ * read-only attach next, from the same byte.
+ */
+export declare function watchTerminal(ctx: Ctx, cell: CellClient, ptyId: string): Promise<number>;
 export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-commands.js

@@ -1,11 +1,38 @@
-import { out, str } from "./commands.js";
-import { UsageError } from "./errors.js";
+import { randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { out, str, strs } from "./commands.js";
+import { CodedError, UsageError } from "./errors.js";
+import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENTS, PtyConnection, planAttachments } from '@shardflux/sdk';
 import { FilesMirror, humanBytes, listMirrorConversations, workspaceHub } from "./files-mirror.js";
+import { modelChoice } from "./agent-models.js";
+import { storedTitlePrefix } from "./client-settings.js";
+import { PtyOutputCursor, passiveUnavailable, sleepingAttach } from "./agent-terminal.js";
+import { progress } from "./progress.js";
+import { UUID } from "./args.js";
+import { findOrg } from "./account-scope.js";
 export function conversationClient(ctx) {
     const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
     const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
     return key || !session ? ctx.cloud() : ctx.account();
 }
+/**
+ * The client and organization of `conversations list` and `feed` (0.25.0+). Without --org: the API key's project, or
+ * signed in without a key every project the person works in. --org acts as the signed-in person when there is a sign-in
+ * (an organization id, or a slug looked up among theirs); with only an API key it is the key's own organization.
+ */
+async function listScope(ctx, values) {
+    const org = str(values.org);
+    if (org === undefined)
+        return { client: conversationClient(ctx) };
+    if (ctx.sessionSource() !== null) {
+        const account = ctx.account();
+        return { client: account, organizationId: UUID.test(org) ? org : (await findOrg(account, org)).id };
+    }
+    if (!UUID.test(org))
+        throw new UsageError(`--org with an API key takes the organization id (got "${org}").`, 'or sign in to name organizations by slug: shard auth login');
+    return { client: ctx.cloud(), organizationId: org };
+}
 /** Why a conversation needs you, as one line of at most `max` characters; undefined in other states (0.18.0+). */
 export function questionLine(c, max = 100) {
     const text = c.state === 'needs_you' ? c.question?.replace(/\s+/g, ' ').trim() : undefined;
@@ -13,7 +40,156 @@ export function questionLine(c, max = 100) {
 }
 /** A conversation's title as people read it: "New conversation" while it is still named by its generated id, before a
  * prompt names it; a name someone chose stays (0.21.1+). The menu bar's AgentNaming.isRawIdentifier rule. */
-export function displayTitle(c) { return !c.title || /^(conv[-_])?[a-z0-9]{26}$/.test(c.title) ? 'New conversation' : c.title; }
+export function displayTitle(c) {
+    // The agent's own short name for it, once it has one (APIs from 0221; CLI 0.25.0+).
+    if (c.title_short?.trim())
+        return c.title_short.trim();
+    return !c.title || /^(conv[-_])?[a-z0-9]{26}$/.test(c.title) ? 'New conversation' : c.title;
+}
+/**
+ * `--file <path>` (repeatable, 0.25.0+): files for a message, read whole and checked before anything is sent. Each one
+ * keeps its file name in the conversation's computer.
+ */
+export async function readAttachments(paths) {
+    if (paths.length > MAX_ATTACHMENTS)
+        throw new UsageError(`Attach at most ${MAX_ATTACHMENTS} files to a message.`);
+    const files = [];
+    for (const path of paths) {
+        const handle = await open(path, 'r').catch((e) => { throw new UsageError(`--file: cannot read "${path}" (${e.code ?? e.message})`); });
+        try {
+            const info = await handle.stat();
+            if (!info.isFile())
+                throw new UsageError(`--file: "${path}" is not a file.`);
+            if (info.size > MAX_ATTACHMENT_BYTES)
+                throw new UsageError(`--file: "${path}" is larger than ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MiB.`);
+            files.push({ name: basename(path), data: await handle.readFile() });
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return files;
+}
+/** The SDK's checks of a message with files (names, sizes, the text with its list), as usage errors before any request. */
+function checkMessage(text, files) {
+    try {
+        planAttachments(`conv_${'a'.repeat(26)}`, randomUUID(), text, files);
+    }
+    catch (e) {
+        if (e instanceof TypeError || e instanceof RangeError)
+            throw new UsageError(e.message);
+        throw e;
+    }
+}
+const sentLines = (r) => `${r.restored ? 'Restored\n' : ''}${(r.files ?? []).map(f => `Attached ${f.path}\n`).join('')}Message sent (${r.seq}).\n`;
+/** A permission request's command, path or URL as one line of at most `max` characters: its first line (0.25.0+). */
+export function detailLine(detail, max = 80) {
+    const line = detail.split('\n').find(l => l.trim())?.replace(/\s+/g, ' ').trim() ?? '';
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+}
+/** One permission request as a list row (0.25.0+): id, state, title, detail, and the decision once answered. */
+export function permissionLine(p) { return `${p.id}\t${p.state}\t${p.title}\t${detailLine(p.detail)}${p.decision ? `\t${p.decision}` : ''}`; }
+/** `shard conversations answer` words (0.25.0+): allow, always and deny, or the API's own decision names. */
+export const PERMISSION_DECISIONS = { allow: 'allow_once', allow_once: 'allow_once', always: 'allow_always', allow_always: 'allow_always', deny: 'deny' };
+const ANSWERED = { allow_once: 'Allowed once', allow_always: 'Always allowed', deny: 'Denied' };
+const PERMISSION_STATES = ['pending', 'answered', 'canceled'];
+/** --pick values as a question's answers (0.25.0+): "<question>=<option>" names the question; a bare option answers
+ * the request's only question (repeated, a multi-select one's several options). `shard needs-you answer` passes the
+ * questions of a board item. */
+export function pickAnswers(p, picks) {
+    const questions = p.questions ?? [];
+    if (!questions.length)
+        throw new UsageError('This request is not a question: answer it with allow, always or deny.');
+    const answers = {};
+    for (const pick of picks) {
+        const named = questions.find(q => pick.startsWith(`${q.question}=`));
+        const q = named ?? (questions.length === 1 ? questions[0] : undefined);
+        if (!q)
+            throw new UsageError(`This request asks ${questions.length} questions: --pick "<question>=<option>", e.g. --pick "${questions[0].question}=${questions[0].options[0]?.label ?? '…'}".`);
+        const label = named ? pick.slice(q.question.length + 1) : pick;
+        if (!label.trim())
+            throw new UsageError(`--pick needs an option for "${q.question}".`);
+        (answers[q.question] ??= []).push(label);
+    }
+    for (const q of questions)
+        if (!answers[q.question])
+            throw new UsageError(`Pick an answer for "${q.question}" too.`);
+    return Object.fromEntries(Object.entries(answers).map(([k, v]) => [k, v.length === 1 ? v[0] : v]));
+}
+/** A listening port as `conversations get` prints it: the port, its program, then its URL once exposed, else where it
+ * listens ("5173  node  https://… (exposed)", "5432  postgres  127.0.0.1 only"). */
+export function portLine(p) {
+    const loopback = /^127\./.test(p.address) || p.address === '::1' || p.address === 'localhost';
+    const where = p.exposed ? `${p.url ?? p.address} (exposed)` : loopback ? `${p.address} only` : `${p.address} (not exposed)`;
+    return [String(p.port), p.process, where].filter(Boolean).join('  ');
+}
+/** How much of the terminal's past `conversations watch` shows before the live output: its last 256 KiB. */
+export const WATCH_TAIL_BYTES = 256 * 1024;
+/** Why a conversation has no terminal to watch (its `pty_id` is null), with the command that shows its output. */
+function noTerminal(c) {
+    if (c.route === 'codex-cloud')
+        return `Codex Cloud runs this conversation, so its output is in its Codex thread: open it with shard agents open ${c.id}.`;
+    if (c.route !== 'terminal')
+        return `This conversation runs without a terminal (route ${c.route}): its app shows its output, and shard conversations get ${c.id} shows its state.`;
+    if (c.ended_at)
+        return `This conversation has finished: shard conversations get ${c.id} shows its result, and shard conversations resume ${c.id} continues it.`;
+    return `This conversation's terminal is starting: shard conversations get ${c.id} shows its pty_id once it runs.`;
+}
+/**
+ * Streams a conversation's terminal read-only from its last WATCH_TAIL_BYTES until its session exits or ctx.signal
+ * aborts (Ctrl-C), writing the terminal's bytes to stdout as they arrive. Nothing is ever typed into it, and the attach is
+ * passive: it never wakes the computer or keeps it awake while the terminal is idle (reading the terminal's size first
+ * wakes a sleeping computer, as every cell call does unless --no-wake). A host without passive attach gets an ordinary
+ * read-only attach next, from the same byte.
+ */
+export async function watchTerminal(ctx, cell, ptyId) {
+    const session = await cell.pty.get(ptyId);
+    const cursor = new PtyOutputCursor();
+    cursor.offset = Math.max(0, session.output_size - WATCH_TAIL_BYTES);
+    let passive = true, wrote = false;
+    try {
+        for (;;) {
+            if (ctx.signal.aborted)
+                return 0;
+            let connection;
+            try {
+                connection = await PtyConnection.attach(cell, ptyId, cursor.offset, ctx.signal, { readOnly: true, ...(passive ? { passive: true } : {}) });
+                for await (const m of connection.messages()) {
+                    const bytes = cursor.consume(m);
+                    if (bytes?.length) {
+                        ctx.io.stdout.write(bytes);
+                        wrote = true;
+                    }
+                    if (m.type === 'exit')
+                        return 0;
+                }
+                return 0;
+            }
+            catch (error) {
+                if (ctx.signal.aborted)
+                    return 0;
+                if (passive && passiveUnavailable(error)) {
+                    passive = false;
+                    continue;
+                }
+                // The computer parked under the watch: the agent is idle, and watching never wakes it.
+                if (sleepingAttach(error)) {
+                    progress(ctx, `${wrote ? '\r\n' : ''}The conversation's computer is asleep; watching ended.`);
+                    return 0;
+                }
+                throw error;
+            }
+            finally {
+                await connection?.close();
+            }
+        }
+    }
+    finally {
+        // The terminal's own modes (colours, a hidden cursor) end with the watch.
+        if (wrote && ctx.io.stdout.isTTY)
+            ctx.io.stdout.write('\x1b[0m\x1b[?25h\r\n');
+    }
+}
 export const CONVERSATION_HANDLERS = {
     async 'conversations resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${displayTitle(r.conversation)}: resumed.\n`, r); return 0; },
     async 'conversations reader'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.spaceReader(id, { signal: ctx.signal }); out(ctx, `${r.workspace.workspace_key}\n`, r); return 0; },
@@ -23,8 +199,12 @@ export const CONVERSATION_HANDLERS = {
         let cursor = str(values.cursor), next;
         if (cursor)
             seen.add(cursor);
+        const updatedAfter = str(values['updated-after']);
+        if (updatedAfter !== undefined && Number.isNaN(Date.parse(updatedAfter)))
+            throw new UsageError('--updated-after must be an RFC 3339 time, such as 2026-10-15T09:00:00Z.');
+        const { client, organizationId } = await listScope(ctx, values);
         do {
-            const page = await conversationClient(ctx).conversations.list({ projectId: str(values.project), state, parentId: str(values.parent), cursor, limit: values.limit ? Number(values.limit) : values.all ? 200 : undefined });
+            const page = await client.conversations.list({ projectId: str(values.project), organizationId, state, parentId: str(values.parent), updatedAfter, cursor, limit: values.limit ? Number(values.limit) : values.all ? 200 : undefined });
             data.push(...page.data);
             next = page.nextCursor;
             cursor = next ?? undefined;
@@ -35,14 +215,137 @@ export const CONVERSATION_HANDLERS = {
             }
         } while (values.all && cursor);
         // A conversation that needs you adds a fifth column: why (0.18.0+).
-        out(ctx, data.map(c => { const q = questionLine(c); return `${c.id}\t${displayTitle(c)}\t${c.state}\t${c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', { data, nextCursor: next });
+        out(ctx, data.map(c => { const q = questionLine(c); return `${c.id}\t${displayTitle(c)}\t${c.state}\t${c.home ? 'home' : c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', { data, nextCursor: next });
+        return 0;
+    },
+    // Each change on its own line as it happens, until interrupted: "<id>\t<title>\t<state>[\t<why>]", or with --json one
+    // object per line, {conversation, cursor} (the cursor resumes after it with --cursor). 0.25.0+.
+    async 'conversations feed'(ctx, values) {
+        const { client, organizationId } = await listScope(ctx, values);
+        let cursor = str(values.cursor);
+        for await (const c of client.conversations.watch({ projectId: str(values.project), organizationId, cursor, signal: ctx.signal, onCursor: next => { cursor = next; } })) {
+            const q = questionLine(c);
+            ctx.io.stdout.write(ctx.json ? JSON.stringify({ conversation: c, cursor }) + '\n' : `${c.id}\t${displayTitle(c)}\t${c.state}${q ? `\t${q}` : ''}\n`);
+        }
+        return 0;
+    },
+    async 'conversations get'(ctx, _values, [id]) {
+        const client = conversationClient(ctx), c = await client.conversations.get(id);
+        const q = questionLine(c, 200);
+        // needs_you with no question: its agent waits on permission requests; text output names them (0.25.0+). JSON stays the
+        // conversation. The lookup only adds to what get shows, so an API without permission requests still shows it.
+        const waits = !ctx.json && c.state === 'needs_you' && !q ? await client.conversations.permissions(c.id, { state: 'pending' }).then(p => p.data, () => []) : [];
+        // The ports processes listen on in its computer follow, one line each, once its guest reported them.
+        const ports = (c.listening_ports ?? []).map(p => `${portLine(p)}\n`).join('');
+        out(ctx, `${displayTitle(c)}\n${c.state}\n${c.home ? 'home' : c.branch}\n${q ? `${q}\n` : ''}${waits.map(p => `Waiting on: ${p.title}\n`).join('')}${ports}`, c);
+        return 0;
+    },
+    // Permission requests (0.25.0+): what the conversation's agent asked before a tool ran, oldest first; every state
+    // unless --state, --all reads every page as conversations list does.
+    async 'conversations permissions'(ctx, values, [id]) {
+        const state = str(values.state);
+        if (state !== undefined && !PERMISSION_STATES.includes(state))
+            throw new UsageError('--state must be pending, answered or canceled.');
+        const client = conversationClient(ctx), data = [], seen = new Set();
+        let cursor = str(values.cursor), next;
+        if (cursor)
+            seen.add(cursor);
+        do {
+            const page = await client.conversations.permissions(id, { state, cursor, limit: values.limit ? Number(values.limit) : values.all ? 200 : undefined });
+            data.push(...page.data);
+            next = page.nextCursor;
+            cursor = next ?? undefined;
+            if (values.all && cursor) {
+                if (seen.has(cursor) || seen.size >= 100)
+                    throw new UsageError('The permission request list repeated its cursor. Try again.');
+                seen.add(cursor);
+            }
+        } while (values.all && cursor);
+        out(ctx, data.map(p => `${permissionLine(p)}\n`).join(''), { data, nextCursor: next });
         return 0;
     },
-    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${displayTitle(c)}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
+    async 'conversations answer'(ctx, values, [id, permissionId, word]) {
+        const picks = strs(values.pick), client = conversationClient(ctx);
+        // The agent's question (0.25.0+): --pick names the answer, which the agent gets exactly as picked.
+        if (picks.length) {
+            if (word !== undefined)
+                throw new UsageError('Answer a question with --pick, or decline it with deny, not both.');
+            const p = await client.conversations.permission(id, permissionId), answers = pickAnswers(p, picks);
+            const r = await client.conversations.answerQuestion(id, permissionId, answers, { signal: ctx.signal });
+            out(ctx, `Answered: ${Object.values(r.permission.answers ?? answers).map(a => Array.isArray(a) ? a.join(', ') : a).join('; ')}\n`, r);
+            return 0;
+        }
+        const decision = word === undefined ? undefined : PERMISSION_DECISIONS[word.toLowerCase().replace(/-/g, '_')];
+        if (!decision)
+            throw new UsageError('Choose allow, always or deny (a question takes --pick <option>).');
+        const r = await client.conversations.answerPermission(id, permissionId, decision, { signal: ctx.signal });
+        out(ctx, `${ANSWERED[r.permission.decision ?? decision]}: ${r.permission.title}\n`, r);
+        return 0;
+    },
+    // Its terminal, live and read-only, from the conversation's pty_id; never typed into, never keeping the computer awake.
+    async 'conversations watch'(ctx, _values, [id]) {
+        if (ctx.json)
+            throw new UsageError(`conversations watch streams the terminal itself, so it has no --json form; shard agents logs ${id} --json returns its recent output.`);
+        const client = conversationClient(ctx), c = await client.conversations.get(id);
+        if (!c.pty_id)
+            throw new UsageError(noTerminal(c));
+        const ws = await client.workspaces.get(c.workspace_id);
+        if (ws.data.deleted_at)
+            throw new UsageError(`This conversation is saved: shard conversations resume ${c.id} continues it in a fresh VM.`);
+        const cell = ws.cell({ agentLabel: ctx.agentLabel, ...(ctx.wake ? {} : { wake: null }), transitionTimeoutMs: ctx.wakeTimeoutMs });
+        try {
+            progress(ctx, `Watching ${displayTitle(c)}, read-only. Ctrl-C stops.`);
+            return await watchTerminal(ctx, cell, c.pty_id);
+        }
+        finally {
+            cell.close();
+        }
+    },
     // A finished conversation whose VM was removed restores into a fresh one, then takes the message (APIs that do; 0.18.1+).
-    async 'conversations send'(ctx, _values, [id, text]) {
-        const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal });
-        out(ctx, `${r.restored ? 'Restored\n' : ''}Message sent (${r.seq}).\n`, r);
+    // --file (0.25.0+): the files land in the conversation's computer before the message, which lists their paths.
+    async 'conversations send'(ctx, values, [id, ...words]) {
+        const files = await readAttachments(strs(values.file)), text = words.length ? words.join(' ') : undefined;
+        if (text === undefined && !files.length)
+            throw new UsageError('missing <text> for "shard conversations send"');
+        if (files.length)
+            checkMessage(text ?? '', files);
+        const r = await conversationClient(ctx).conversations.send(id, text ?? '', { signal: ctx.signal, ...(files.length ? { files } : {}) });
+        out(ctx, sentLines(r), r);
+        return 0;
+    },
+    /**
+     * A conversation started without a folder (0.25.0+): on the machine's home (--home), or in one of the project's
+     * repositories from the project hub. With --prompt its first message follows, with any --file.
+     */
+    async 'conversations start'(ctx, values) {
+        const home = values.home === true, repo = str(values.repo), branch = str(values.branch), prompt = str(values.prompt), title = str(values.title);
+        if (home && (repo !== undefined || branch !== undefined))
+            throw new UsageError('--home starts on your machine without a repository: leave out --repo and --branch.');
+        const app = str(values.app) ?? 'claude';
+        if (app !== 'claude' && app !== 'codex')
+            throw new UsageError('Choose --app claude or codex.');
+        const choice = modelChoice(values, app);
+        if (prompt !== undefined && !prompt.trim())
+            throw new UsageError('--prompt needs text.');
+        const files = await readAttachments(strs(values.file));
+        if (files.length && prompt === undefined)
+            throw new UsageError('--file goes with the first message: add --prompt.');
+        if (prompt !== undefined)
+            checkMessage(prompt, files);
+        const projectId = str(values.project) ?? ctx.store.profile(ctx.apiUrl).project_id, titlePrefix = storedTitlePrefix(ctx.store.dir);
+        const client = conversationClient(ctx);
+        const created = await client.conversations.create({ ...(projectId ? { projectId } : {}), harness: app, route: 'terminal', mode: 'new', ...(home ? { home: true } : {}),
+            ...(repo !== undefined ? { repoRemote: repo } : {}), ...(branch !== undefined ? { base: { branch } } : {}), ...(title !== undefined ? { title } : {}), ...choice, ...(titlePrefix !== undefined ? { titlePrefix } : {}) }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+        const c = created.conversation;
+        let message;
+        try {
+            if (prompt !== undefined)
+                message = await client.conversations.send(c.id, prompt, { idempotencyKey: randomUUID(), signal: ctx.signal, ...(files.length ? { files } : {}) });
+        }
+        catch (e) {
+            throw new CodedError('initial_prompt_failed', `Started ${c.key} (${c.id}), but its first message was not sent: ${e instanceof Error ? e.message : String(e)}`, `shard conversations send ${c.id} "<message>"`, { conversation_id: c.id, workspace_key: c.key });
+        }
+        out(ctx, `${c.id}\t${c.key}\t${c.state}\n${message ? sentLines(message) : ''}`, { ...created, ...(message ? { message } : {}) });
         return 0;
     },
     async 'conversations wait'(ctx, values, [id]) {

package/dist/conversation-transcript.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `shard conversations transcript` and `shard conversations events` (0.25.0+): a conversation's stored transcript (the
+ * harness's own JSONL, byte for byte) and its event stream, read through the API without the conversation's computer.
+ */
+import type { ConversationEvent, ConversationTranscript, Shardflux } from '@shardflux/sdk';
+import type { Handler } from './commands.js';
+type ConversationsApi = Shardflux['conversations'];
+/** A stretch of transcript: the bytes [offset, next_offset) of a session's file. */
+export type TranscriptPiece = Pick<ConversationTranscript, 'session_id' | 'file' | 'offset' | 'next_offset' | 'size' | 'data'>;
+/**
+ * Reads pages from `offset` of a session (the latest when `sessionId` is undefined) until its stored end, or until
+ * `until` (a line boundary). Every page goes to `emit`; returns the last one.
+ */
+export declare function readTranscript(api: Pick<ConversationsApi, 'transcript'>, id: string, o: {
+    offset: number;
+    sessionId?: string | undefined;
+    until?: number;
+    signal: AbortSignal;
+}, emit: (page: ConversationTranscript) => void): Promise<ConversationTranscript>;
+/**
+ * Prints a followed transcript once: each event's lines after what was printed, the stored lines a reconnect or a new
+ * harness session would otherwise skip read from the API first.
+ */
+export declare class TranscriptFollower {
+    #private;
+    session: string | null;
+    offset: number;
+    constructor(api: Pick<ConversationsApi, 'transcript'>, id: string, at: {
+        session: string | null;
+        offset: number;
+    }, signal: AbortSignal, write: (p: TranscriptPiece) => void);
+    take(t: TranscriptPiece): Promise<void>;
+}
+/**
+ * The readable form of `shard conversations events`: a line per state change, transcript lines and tool call, the
+ * reply text as it streams. `end()` closes a reply still on its line.
+ */
+export declare class EventLines {
+    #private;
+    render(ev: ConversationEvent): string;
+    end(): string;
+}
+export declare const TRANSCRIPT_HANDLERS: Record<string, Handler>;
+export {};

package/dist/conversation-transcript.js

@@ -0,0 +1,206 @@
+import { out, str } from "./commands.js";
+import { conversationClient, questionLine } from "./conversation-commands.js";
+import { EXIT, UsageError } from "./errors.js";
+function byteOffset(text) {
+    if (text === undefined)
+        return 0;
+    if (!/^\d+$/.test(text) || !Number.isSafeInteger(Number(text)))
+        throw new UsageError('--offset must be a nonnegative safe integer');
+    return Number(text);
+}
+const piece = (p) => ({ session_id: p.session_id, file: p.file, offset: p.offset, next_offset: p.next_offset, size: p.size, data: p.data });
+/**
+ * Reads pages from `offset` of a session (the latest when `sessionId` is undefined) until its stored end, or until
+ * `until` (a line boundary). Every page goes to `emit`; returns the last one.
+ */
+export async function readTranscript(api, id, o, emit) {
+    const limit = (at) => (o.until === undefined ? {} : { limitBytes: o.until - at });
+    let page = await api.transcript(id, { offset: o.offset, ...(o.sessionId === undefined ? {} : { sessionId: o.sessionId }), ...limit(o.offset), signal: o.signal });
+    emit(page);
+    for (;;) {
+        const end = o.until === undefined ? page.size : Math.min(o.until, page.size);
+        if (page.next_offset >= end)
+            return page;
+        const at = page.next_offset;
+        page = await api.transcript(id, { offset: at, sessionId: page.session_id ?? o.sessionId, ...limit(at), signal: o.signal });
+        // A page that does not move on would repeat forever.
+        if (page.next_offset <= at)
+            return page;
+        emit(page);
+    }
+}
+/**
+ * Prints a followed transcript once: each event's lines after what was printed, the stored lines a reconnect or a new
+ * harness session would otherwise skip read from the API first.
+ */
+export class TranscriptFollower {
+    session;
+    offset;
+    #api;
+    #id;
+    #signal;
+    #write;
+    constructor(api, id, at, signal, write) {
+        this.#api = api;
+        this.#id = id;
+        this.session = at.session;
+        this.offset = at.offset;
+        this.#signal = signal;
+        this.#write = write;
+    }
+    #print(p) {
+        if (p.session_id !== this.session || p.next_offset <= this.offset)
+            return;
+        const bytes = Buffer.from(p.data, 'utf8');
+        const skip = Math.max(0, this.offset - p.offset);
+        const data = skip === 0 ? p.data : bytes.subarray(skip).toString('utf8');
+        this.offset = p.next_offset;
+        if (data)
+            this.#write({ ...piece(p), offset: p.offset + skip, data });
+    }
+    async take(t) {
+        if (t.session_id === null)
+            return;
+        if (t.session_id !== this.session) {
+            // A new harness session (Claude Code /clear, a new Codex thread): the rest of the earlier one, then this one.
+            if (this.session !== null)
+                await readTranscript(this.#api, this.#id, { offset: this.offset, sessionId: this.session, signal: this.#signal }, (p) => this.#print(p));
+            this.session = t.session_id;
+            this.offset = 0;
+        }
+        if (t.offset > this.offset)
+            await readTranscript(this.#api, this.#id, { offset: this.offset, sessionId: t.session_id, until: t.offset, signal: this.#signal }, (p) => this.#print(p));
+        this.#print(t);
+    }
+}
+const lineCount = (text) => text.split('\n').length - 1;
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+/**
+ * The readable form of `shard conversations events`: a line per state change, transcript lines and tool call, the
+ * reply text as it streams. `end()` closes a reply still on its line.
+ */
+export class EventLines {
+    #state;
+    #midLine = false;
+    #tools = new Map();
+    render(ev) {
+        if (ev.type === 'conversation') {
+            const c = ev.conversation;
+            if (c.state === this.#state)
+                return '';
+            this.#state = c.state;
+            const q = questionLine(c);
+            return this.#line(`state: ${c.state}${q ? ` — ${q}` : ''}`);
+        }
+        if (ev.type === 'transcript') {
+            const n = lineCount(ev.transcript.data);
+            return n ? this.#line(`transcript: +${n} line${n === 1 ? '' : 's'}`) : '';
+        }
+        return ev.delta.updates.map((u) => this.#update(u)).join('');
+    }
+    end() {
+        const close = this.#midLine ? '\n' : '';
+        this.#midLine = false;
+        return close;
+    }
+    #update(u) {
+        if (u.sessionUpdate === 'agent_message_chunk') {
+            const c = u.content;
+            if (c?.type !== 'text' || typeof c.text !== 'string' || !c.text)
+                return '';
+            this.#midLine = !c.text.endsWith('\n');
+            return c.text;
+        }
+        if (u.sessionUpdate !== 'tool_call' && u.sessionUpdate !== 'tool_call_update')
+            return '';
+        const id = typeof u.toolCallId === 'string' ? u.toolCallId : '';
+        const title = (typeof u.title === 'string' && oneLine(u.title)) || this.#tools.get(id) || 'tool';
+        if (id) {
+            this.#tools.delete(id);
+            this.#tools.set(id, title);
+            if (this.#tools.size > 1000)
+                this.#tools.delete(this.#tools.keys().next().value);
+        }
+        const status = typeof u.status === 'string' && u.status ? u.status : undefined;
+        // An update that only adds output to a call says nothing new on its line.
+        if (u.sessionUpdate === 'tool_call_update' && !status)
+            return '';
+        return this.#line(`tool: ${title}${status ? ` (${status})` : ''}`);
+    }
+    #line(text) {
+        const lead = this.#midLine ? '\n' : '';
+        this.#midLine = false;
+        return `${lead}${text}\n`;
+    }
+}
+const interrupted = (signal, err) => {
+    if (signal.aborted)
+        return EXIT.interrupted;
+    throw err;
+};
+export const TRANSCRIPT_HANDLERS = {
+    async 'conversations transcript'(ctx, values, [id]) {
+        const offset = byteOffset(str(values.offset));
+        const sessionId = str(values.session);
+        if (sessionId !== undefined && !sessionId.trim())
+            throw new UsageError('--session needs a session id');
+        const follow = values.follow === true;
+        const api = conversationClient(ctx).conversations;
+        // Stdout carries the transcript itself; with --json, one object (with --follow, one object per line).
+        const ndjson = ctx.json && follow;
+        const write = (p) => {
+            if (ndjson)
+                ctx.io.stdout.write(`${JSON.stringify(piece(p))}\n`);
+            else if (!ctx.json && p.data)
+                ctx.io.stdout.write(p.data);
+        };
+        const parts = [];
+        let last;
+        try {
+            last = await readTranscript(api, id, { offset, sessionId, signal: ctx.signal }, (p) => {
+                if (ctx.json && !follow)
+                    parts.push(p.data);
+                else if (p.data)
+                    write(p);
+            });
+        }
+        catch (err) {
+            return interrupted(ctx.signal, err);
+        }
+        if (!follow) {
+            if (ctx.json)
+                out(ctx, '', { ...last, offset, data: parts.join('') });
+            return EXIT.ok;
+        }
+        const follower = new TranscriptFollower(api, id, { session: last.session_id ?? sessionId ?? null, offset: last.next_offset }, ctx.signal, write);
+        try {
+            const events = api.events(id, { transcriptOffset: follower.offset, ...(sessionId === undefined ? {} : { sessionId }), signal: ctx.signal });
+            for await (const ev of events)
+                if (ev.type === 'transcript')
+                    await follower.take(ev.transcript);
+        }
+        catch (err) {
+            return interrupted(ctx.signal, err);
+        }
+        return ctx.signal.aborted ? EXIT.interrupted : EXIT.ok;
+    },
+    async 'conversations events'(ctx, _values, [id]) {
+        const lines = new EventLines();
+        let code = EXIT.ok;
+        try {
+            for await (const ev of conversationClient(ctx).conversations.events(id, { signal: ctx.signal })) {
+                const text = ctx.json ? `${JSON.stringify(ev)}\n` : lines.render(ev);
+                if (text)
+                    ctx.io.stdout.write(text);
+            }
+        }
+        catch (err) {
+            code = interrupted(ctx.signal, err);
+        }
+        finally {
+            if (!ctx.json)
+                ctx.io.stdout.write(lines.end());
+        }
+        return ctx.signal.aborted ? EXIT.interrupted : code;
+    },
+};