primitive-admin 1.2.0-alpha.0 → 1.2.0-alpha.10

package/dist/src/commands/agent-sessions.js

@@ -0,0 +1,792 @@
+import { createHash } from "crypto";
+import { readFileSync, writeFileSync } from "fs";
+import { basename, resolve as resolvePath } from "path";
+import { lookup as mimeLookup } from "mime-types";
+import { ulid } from "ulid";
+import { ApiClient } from "../lib/api-client.js";
+import { resolveAppId } from "../lib/config.js";
+import { error, formatDate, formatDuration, formatTable, info, json, keyValue, result, success, } from "../lib/output.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, } from "../lib/list-options.js";
+import { normalizeCliListEnvelope } from "../lib/paginate.js";
+import { describeRecordsFailure } from "./documents.js";
+/**
+ * `primitive agent-sessions` — inspect and delete agent sessions (#3809,
+ * design-docs/agents.md §D7). A data noun: `list` one user's sessions, `get`
+ * one session's binding, status, active turn and — for app owners and admins —
+ * the session object's state, and `delete` a session with its document.
+ * `transcript`, `steps` and `artifacts` read the conversation's rows by
+ * session ID, and `upload` and `download` move a session's files (#4589);
+ * none takes a document ID. The rows never hold the system prompt or a
+ * turn's context, so those stay visible only through `get` to app owners and
+ * admins. `primitive sessions` is sign-in sessions.
+ */
+/** The `object` keys `get` prints as sections; any other key is printed as JSON. */
+const OBJECT_SECTIONS = new Set([
+    "pending",
+    "deletedAt",
+    "initializing",
+    "turn",
+    "lastTurn",
+    "queue",
+    "leaseUntil",
+    "alarmAt",
+    "calls",
+]);
+const ROWS_NOTE = `
+The conversation itself (messages, parts, steps) lives in the session's
+document. Read it by session ID with:
+  $ primitive agent-sessions transcript <session-id>
+  $ primitive agent-sessions steps <session-id>
+  $ primitive agent-sessions artifacts <session-id>
+or as raw rows, by the session's document ID:
+  $ primitive documents records query <document-id> PrimitiveMessage
+  $ primitive documents records query <document-id> PrimitivePart
+  $ primitive documents records query <document-id> PrimitiveStep
+  $ primitive documents records query <document-id> PrimitiveSession
+`;
+/** Who `transcript`, `steps` and `artifacts` answer: the session document's own readers. */
+const READERS_NOTE = `The rows are read under the session document's own permissions: every
+member of the session reads them, and so does a console admin of the app. An
+app owner or admin who is not in the session can \`get\` it but is refused
+here (403) unless granted the document.
+`;
+const list = (values) => Array.isArray(values) && values.length > 0 ? values.map(String).join(", ") : "-";
+/**
+ * Delete one agent session: confirm unless `yes`, then one `DELETE`. Answers
+ * whether it was deleted or the prompt was declined; a refusal throws (the
+ * prompt's non-TTY refusal included, before any request).
+ */
+export async function deleteAgentSessionAction(options, deps) {
+    if (!options.yes) {
+        const ok = await deps.confirm(`Delete agent session ${options.sessionId} and its document? This cannot be undone.`);
+        if (!ok)
+            return "cancelled";
+    }
+    const answer = await deps.client.deleteAgentSession(options.appId, options.sessionId);
+    deps.print(options.json ? JSON.stringify(answer, null, 2) : `Agent session ${options.sessionId} deleted.`);
+    return "deleted";
+}
+/** The active turn, as `get` prints it. */
+function printTurn(turn) {
+    if (!turn) {
+        result("Turn", "none");
+        return;
+    }
+    result("Turn", turn.turnId);
+    result("  Phase", turn.phase);
+    result("  Rounds", turn.rounds);
+    result("  Initiator", turn.initiatorUserId);
+    result("  Started", turn.startedAt ? formatDate(turn.startedAt) : null);
+    result("  Answered by", turn.answeredBy);
+    if (turn.pause) {
+        result("  Waiting on", `${list(turn.pause.callIds)} (until ${formatDate(turn.pause.expiresAt)})`);
+    }
+    if (turn.pending)
+        result("  Pending", turn.pending.kind);
+}
+/** The session object's state, for app owners and admins. */
+function printObject(object) {
+    console.log("");
+    console.log("Session object");
+    result("Deleted at", object.deletedAt ? formatDate(object.deletedAt) : null);
+    result("Initializing", object.initializing ? formatDate(object.initializing) : null);
+    result("Pending changes", Array.isArray(object.pending) ? object.pending.length : 0);
+    const queue = Array.isArray(object.queue) ? object.queue : [];
+    result("Queue", queue.length > 0
+        ? queue
+            .map((entry) => {
+            const count = Array.isArray(entry?.messageIds) ? entry.messageIds.length : 0;
+            return `${entry?.userId} (${count} message${count === 1 ? "" : "s"})`;
+        })
+            .join(", ")
+        : "empty");
+    result("Lease until", object.leaseUntil ? formatDate(object.leaseUntil) : null);
+    result("Alarm at", object.alarmAt ? formatDate(object.alarmAt) : null);
+    const last = object.lastTurn;
+    if (last) {
+        result("Last turn", last.turnId);
+        result("  Outcome", `${last.outcome}${last.code ? ` (${last.code})` : ""}`);
+        result("  Started", last.startedAt ? formatDate(last.startedAt) : null);
+        result("  Ended", last.endedAt ? formatDate(last.endedAt) : null);
+        result("  Rounds", last.rounds);
+    }
+    else {
+        result("Last turn", "none");
+    }
+    const calls = Array.isArray(object.calls) ? object.calls : [];
+    if (calls.length > 0) {
+        console.log("");
+        console.log(formatTable(calls.map((call) => ({ ...call, endedBy: call.endedBy ?? (call.discarded ? "discarded" : "-") })), [
+            { header: "CALL", key: "callId" },
+            { header: "TOOL", key: "toolName" },
+            { header: "STATE", key: "state" },
+            { header: "ATTEMPTS", key: "attempts" },
+            { header: "ENDED BY", key: "endedBy" },
+        ]));
+    }
+    // The configuration pinned at the active turn's start, else the last turn's.
+    const pinned = object.turn ?? last;
+    if (typeof pinned?.systemPrompt === "string") {
+        console.log("");
+        console.log("Pinned system prompt:");
+        console.log(pinned.systemPrompt);
+    }
+    if (Array.isArray(pinned?.tools) && pinned.tools.length > 0) {
+        console.log("");
+        console.log("Pinned tools:");
+        for (const tool of pinned.tools) {
+            const how = [tool.runs, tool.runs === "server" ? tool.invoke ?? "request" : undefined].filter(Boolean).join(", ");
+            console.log(`  ${tool.name}${how ? ` (${how})` : ""}`);
+        }
+    }
+    // Keys this CLI does not know yet, as they came.
+    for (const [key, value] of Object.entries(object)) {
+        if (OBJECT_SECTIONS.has(key))
+            continue;
+        console.log("");
+        console.log(`${key}:`);
+        console.log(JSON.stringify(value, null, 2));
+    }
+}
+/** A part's JSON columns: stored as text, printed as the values they hold. */
+const PART_JSON_COLUMNS = ["input", "output", "artifact", "providerMetadata", "data"];
+/** A step's JSON columns. */
+const STEP_JSON_COLUMNS = ["historySelection"];
+/** At most this many message ids in one parts filter: the records route's `$in` cap. */
+export const PARTS_BATCH_SIZE = 1000;
+/**
+ * At most this many bytes of encoded filter in one parts request. The filter
+ * rides in the query string and Cloudflare refuses a URL over 16 KB, so this
+ * leaves room for the path, the sort, the limit and a continuation cursor.
+ */
+export const PARTS_FILTER_MAX_BYTES = 8 * 1024;
+/** Parts asked for per request: the records route's maximum `limit`. */
+const PARTS_PAGE_LIMIT = 10_000;
+/** The most parts requests one transcript page makes before it fails. */
+export const MAX_PARTS_REQUESTS = 64;
+/**
+ * A session row with its JSON columns decoded from their stored text. A
+ * column whose text is not JSON is left as that text.
+ */
+export function decodeSessionRow(row, columns = PART_JSON_COLUMNS) {
+    const decoded = { ...row };
+    for (const column of columns) {
+        const text = decoded[column];
+        if (typeof text !== "string")
+            continue;
+        try {
+            decoded[column] = JSON.parse(text);
+        }
+        catch {
+            // Not JSON: kept as it came.
+        }
+    }
+    return decoded;
+}
+/** A text's length once encoded into the query string, as the api client sends it. */
+const queryBytes = (text) => new URLSearchParams({ q: text }).toString().length - "q=".length;
+/** The parts filter around its ids, `{"messageId":{"$in":[]}}`, encoded. */
+const PARTS_FILTER_FRAME_BYTES = queryBytes(JSON.stringify({ messageId: { $in: [] } }));
+const ID_SEPARATOR_BYTES = queryBytes(",");
+/**
+ * Message ids in order, in batches one parts filter can carry: at most
+ * `maxIds` ids (the `$in` cap) and at most `maxFilterBytes` of encoded filter
+ * (the URL budget). An id too long for the budget alone gets a batch of its own.
+ */
+export function batchMessageIds(ids, { maxIds = PARTS_BATCH_SIZE, maxFilterBytes = PARTS_FILTER_MAX_BYTES } = {}) {
+    const batches = [];
+    let batch = [];
+    let bytes = PARTS_FILTER_FRAME_BYTES;
+    for (const id of ids) {
+        const idBytes = queryBytes(JSON.stringify(id));
+        if (batch.length > 0 && (batch.length >= maxIds || bytes + ID_SEPARATOR_BYTES + idBytes > maxFilterBytes)) {
+            batches.push(batch);
+            batch = [];
+            bytes = PARTS_FILTER_FRAME_BYTES;
+        }
+        bytes += (batch.length > 0 ? ID_SEPARATOR_BYTES : 0) + idBytes;
+        batch.push(id);
+    }
+    if (batch.length > 0)
+        batches.push(batch);
+    return batches;
+}
+/**
+ * The page's messages in their order, each with a `parts` array of its parts
+ * by `seq`, whatever order the parts arrived in.
+ */
+export function joinTranscriptPage(messages, parts) {
+    const byMessage = new Map();
+    for (const part of parts) {
+        const own = byMessage.get(part.messageId);
+        if (own)
+            own.push(part);
+        else
+            byMessage.set(part.messageId, [part]);
+    }
+    return messages.map((message) => ({
+        ...message,
+        parts: [...(byMessage.get(message.id) ?? [])].sort((a, b) => Number(a.seq) - Number(b.seq)),
+    }));
+}
+/** Where a tool call's artifact lives: on a blob, inline on the row, or nowhere. */
+export function artifactOf(part) {
+    if (typeof part.artifactBlobId === "string" && part.artifactBlobId) {
+        return { kind: "blob", blobId: part.artifactBlobId };
+    }
+    if (part.artifact !== undefined && part.artifact !== null)
+        return { kind: "inline", value: part.artifact };
+    return { kind: "none" };
+}
+function artifactLabel(part) {
+    const artifact = artifactOf(part);
+    return artifact.kind === "blob" ? `blob ${artifact.blobId}` : artifact.kind === "inline" ? "inline" : "-";
+}
+/** A decoded value on one line: text as it is, anything else as compact JSON. */
+const compact = (value) => (typeof value === "string" ? value : JSON.stringify(value));
+const present = (value) => value !== undefined && value !== null && value !== "";
+function formatPart(part) {
+    switch (part.kind) {
+        case "text":
+        case "reasoning":
+            return [`  [${part.kind}] ${String(part.text ?? "").replace(/\n/g, "\n    ")}`];
+        case "tool_call": {
+            const lines = [`  [tool_call] ${part.toolName} (${part.toolCallId}) ${part.state}`];
+            if (present(part.input))
+                lines.push(`    input: ${compact(part.input)}`);
+            if (present(part.output))
+                lines.push(`    output: ${compact(part.output)}`);
+            if (artifactOf(part).kind !== "none")
+                lines.push(`    artifact: ${artifactLabel(part)}`);
+            if (present(part.errorCode) || present(part.errorText)) {
+                lines.push(`    error: ${[part.errorCode, part.errorText].filter(present).join(" ")}`);
+            }
+            return lines;
+        }
+        case "file":
+            return [`  [file] ${part.filename} ${part.mediaType} ${part.sizeBytes} bytes blob ${part.blobId}`];
+        case "event":
+            return [`  [event] ${part.eventKind}${present(part.data) ? ` ${compact(part.data)}` : ""}`];
+        default:
+            // A kind this CLI does not know yet, as it came.
+            return [`  [${part.kind}] ${JSON.stringify(part)}`];
+    }
+}
+/** One transcript message as `transcript` prints it: a header, then a line per part. */
+export function formatTranscriptMessage(message) {
+    const header = [
+        `#${message.seq}`,
+        message.authorKind,
+        message.authorUserId,
+        formatDate(message.createdAt),
+        message.turnId ? `turn ${message.turnId}` : undefined,
+    ]
+        .filter(present)
+        .join(" ");
+    return [header, ...(Array.isArray(message.parts) ? message.parts : []).flatMap(formatPart)];
+}
+async function sessionDocumentId(client, appId, sessionId) {
+    const session = await client.getAgentSession(appId, sessionId);
+    return session.documentId;
+}
+function envelopeOf(page, items) {
+    return { items, hasMore: page.hasMore, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) };
+}
+/**
+ * One page of a session's conversation, oldest first: the session's messages
+ * by `seq`, each with every one of its parts. The parts are read in batches
+ * of message ids, each followed through its cursor, so a printed message is
+ * never missing a part; a page that needs more than `MAX_PARTS_REQUESTS`
+ * parts requests fails instead.
+ */
+export async function transcriptAction(options, client) {
+    const documentId = await sessionDocumentId(client, options.appId, options.sessionId);
+    const page = await client.queryDocumentRecords(options.appId, documentId, "PrimitiveMessage", {
+        ...(options.turnId ? { filter: { turnId: options.turnId } } : {}),
+        sort: { seq: 1 },
+        limit: options.limit,
+        cursor: options.cursor,
+    });
+    const ids = page.items.map((message) => message.id);
+    const parts = [];
+    let requests = 0;
+    for (const batch of batchMessageIds(ids)) {
+        let cursor;
+        do {
+            if (requests >= MAX_PARTS_REQUESTS) {
+                throw new Error(`Transcript page too large to assemble (${ids.length} messages, more than ${MAX_PARTS_REQUESTS} parts requests); use a smaller --limit.`);
+            }
+            requests++;
+            const answer = await client.queryDocumentRecords(options.appId, documentId, "PrimitivePart", {
+                filter: { messageId: { $in: batch } },
+                sort: { seq: 1 },
+                limit: PARTS_PAGE_LIMIT,
+                cursor,
+            });
+            parts.push(...answer.items.map((part) => decodeSessionRow(part)));
+            cursor = answer.hasMore ? answer.nextCursor : undefined;
+        } while (cursor);
+    }
+    return envelopeOf(page, joinTranscriptPage(page.items, parts));
+}
+/** One page of a session's steps, oldest first. */
+async function stepsAction(options, client) {
+    const documentId = await sessionDocumentId(client, options.appId, options.sessionId);
+    const page = await client.queryDocumentRecords(options.appId, documentId, "PrimitiveStep", {
+        ...(options.turnId ? { filter: { turnId: options.turnId } } : {}),
+        sort: { startedAt: 1 },
+        limit: options.limit,
+        cursor: options.cursor,
+    });
+    return envelopeOf(page, page.items.map((step) => decodeSessionRow(step, STEP_JSON_COLUMNS)));
+}
+/** One page of a session's tool calls, oldest first. */
+async function toolCallsAction(options, client) {
+    const documentId = await sessionDocumentId(client, options.appId, options.sessionId);
+    const page = await client.queryDocumentRecords(options.appId, documentId, "PrimitivePart", {
+        filter: { kind: "tool_call" },
+        sort: { createdAt: 1 },
+        limit: options.limit,
+        cursor: options.cursor,
+    });
+    return envelopeOf(page, page.items.map((part) => decodeSessionRow(part)));
+}
+/**
+ * One tool call's artifact: `found: false` when the session has no tool call
+ * part by that id, else its value — read from the session's attachment when
+ * the artifact is a blob, `null` when the call has none.
+ */
+export async function readArtifactAction(options, client) {
+    const documentId = await sessionDocumentId(client, options.appId, options.sessionId);
+    const page = await client.queryDocumentRecords(options.appId, documentId, "PrimitivePart", {
+        filter: { id: options.partId, kind: "tool_call" },
+        limit: 1,
+    });
+    const [part] = page.items;
+    if (!part)
+        return { found: false };
+    const artifact = artifactOf(decodeSessionRow(part));
+    if (artifact.kind === "none")
+        return { found: true, value: null };
+    if (artifact.kind === "inline")
+        return { found: true, value: artifact.value };
+    const bytes = await client.downloadAgentSessionAttachment(options.appId, options.sessionId, artifact.blobId);
+    return { found: true, value: JSON.parse(bytes.toString("utf8")) };
+}
+/**
+ * Upload one file to a session: read it, then one `PUT` on the session's
+ * attachment route with the size and base64 SHA-256 the route checks. The
+ * blob ID defaults to a fresh ULID, the filename to the file's basename and
+ * the content type to the filename's MIME type. An unreadable file fails
+ * before any request.
+ */
+export async function uploadAttachmentAction(options, client) {
+    let data;
+    try {
+        data = readFileSync(resolvePath(options.filePath));
+    }
+    catch (err) {
+        throw new Error(`Failed to read file: ${err?.message ?? String(err)}`);
+    }
+    const blobId = options.blobId || ulid();
+    const filename = options.filename || basename(options.filePath) || "upload";
+    const contentType = options.contentType || mimeLookup(filename) || "application/octet-stream";
+    const sha256 = createHash("sha256").update(data).digest("base64");
+    const answer = await client.uploadAgentSessionAttachment(options.appId, options.sessionId, blobId, data, {
+        filename,
+        contentType,
+        sha256,
+    });
+    return { answer, blobId, filename, contentType, numBytes: data.length };
+}
+/**
+ * Download one of a session's files: the bytes go to `output` with a success
+ * line, or to stdout alone. A refusal throws with nothing written.
+ */
+export async function downloadAttachmentAction(options, deps) {
+    const data = await deps.client.downloadAgentSessionAttachment(options.appId, options.sessionId, options.blobId);
+    if (options.output) {
+        deps.writeFile(resolvePath(options.output), data);
+        deps.print(`Downloaded to ${options.output} (${data.length} bytes)`);
+    }
+    else {
+        deps.writeStdout(data);
+    }
+    return data;
+}
+/** The step table's display row. */
+function stepCells(step) {
+    const providerModel = [step.provider, step.model].filter(present).join("/");
+    return {
+        ...step,
+        providerModel: providerModel || step.toolName || step.functionName || "-",
+        tokens: present(step.totalTokens) ? step.totalTokens : "-",
+        costCell: present(step.cost) ? step.cost : "-",
+        errorCell: step.errorCode || "-",
+    };
+}
+export function registerAgentSessionsCommands(program) {
+    const agentSessions = program
+        .command("agent-sessions")
+        .description("Inspect agent sessions, read their conversations, move their files, and delete them")
+        .addHelpText("after", `
+An agent session is one conversation with an agent, created by a server
+function (ctx.agents.createSession). App owners and admins list any user's
+sessions, get any session — including the session object's state: each
+turn's pinned system prompt and tools, the queue and the call ledger — and
+delete any session. Members read their own sessions' transcript, steps and
+artifacts, and the owner and participants upload files to them. This is not
+\`primitive sessions\`, which lists sign-in sessions.
+${ROWS_NOTE}
+Examples:
+  $ primitive agent-sessions list --user-id 01HXY...
+  $ primitive agent-sessions list --user-id 01HXY... --agent advisor --json
+  $ primitive agent-sessions get 01HXZ...
+  $ primitive agent-sessions transcript 01HXZ... --limit 20
+  $ primitive agent-sessions steps 01HXZ... --turn 01HXT...
+  $ primitive agent-sessions artifacts 01HXZ...
+  $ primitive agent-sessions artifacts 01HXZ... 01HXP... --json
+  $ primitive agent-sessions upload 01HXZ... ./receipt.png
+  $ primitive agent-sessions download 01HXZ... 01HXB... --output ./receipt.png
+  $ primitive agent-sessions delete 01HXZ... --yes
+`);
+    agentSessions
+        .command("list")
+        .description("List one user's agent sessions, newest first")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        // Required, but checked in the action (the `sessions list` precedent).
+        .option("--user-id <user-id>", "List sessions this user owns or belongs to")
+        .option("--agent <key>", "Only this agent's sessions")
+        .option("--scope <scope>", "Only sessions created with exactly this scope")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        const userId = options.userId;
+        if (!userId) {
+            error("required option '--user-id <user-id>' not specified");
+            process.exit(1);
+        }
+        const limit = parsePageLimit(options.limit);
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const page = normalizeCliListEnvelope(await client.listAgentSessions(resolvedAppId, {
+                userId,
+                agent: options.agent,
+                scope: options.scope,
+                limit,
+                cursor: options.cursor,
+            }));
+            if (options.json) {
+                json(page);
+                return;
+            }
+            if (page.items.length === 0) {
+                printEmptyPage(page, "agent sessions");
+                return;
+            }
+            console.log(formatTable(page.items, [
+                { header: "SESSION", key: "sessionId" },
+                { header: "AGENT", key: "agentKey" },
+                { header: "SCOPE", key: "scope" },
+                { header: "ROLE", key: "role" },
+                { header: "TITLE", key: "title", flex: true },
+                // The listed user's unread dot (#4256): activity they have not marked read.
+                { header: "UNREAD", key: "hasUnread", format: (value) => (value === true ? "•" : "-") },
+                { header: "LAST ACTIVITY", key: "lastActivityAt", format: formatDate },
+                { header: "DOCUMENT", key: "documentId" },
+            ]));
+            printPageHint(page);
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+    agentSessions
+        .command("get")
+        .description("Show an agent session: its binding, status, members, active turn and object state")
+        .argument("<session-id>", "Session ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output the server's answer as JSON")
+        .addHelpText("after", `
+App owners and admins also see the session object's state: the active and
+last turn with the system prompt and tools pinned at the turn's start, the
+queue, the lease, the next alarm and the server tool calls (never their
+input). Keys this CLI does not know are printed as JSON.
+${ROWS_NOTE}`)
+        .action(async (sessionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const session = await client.getAgentSession(resolvedAppId, sessionId);
+            if (options.json) {
+                json(session);
+                return;
+            }
+            result("Session ID", session.sessionId);
+            result("Agent", session.agentKey);
+            result("Document ID", session.documentId);
+            result("Owner", session.ownerUserId);
+            result("Created", formatDate(session.createdAt));
+            result("Status", session.status);
+            result("Title", session.title);
+            result("Scope", session.scope);
+            result("Last activity", session.lastActivityAt ? formatDate(session.lastActivityAt) : null);
+            result("Unread", session.hasUnread === true ? "yes" : "no");
+            result("Last read", session.lastReadAt ? formatDate(session.lastReadAt) : null);
+            result("Viewers", list(session.members?.viewers));
+            result("Participants", list(session.members?.participants));
+            result("Your role", session.role);
+            printTurn(session.turn);
+            if (session.object && typeof session.object === "object")
+                printObject(session.object);
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+    agentSessions
+        .command("transcript")
+        .description("Show one page of a session's conversation: its messages, oldest first, with their parts")
+        .argument("<session-id>", "Session ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--turn <turn-id>", "Only this turn's messages")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Each message prints with its parts: text, reasoning, tool calls (input, output
+and where the artifact lives), files and events. --json prints the one list
+envelope, each message with a \`parts\` array and the JSON columns decoded.
+
+${READERS_NOTE}`)
+        .action(async (sessionId, options) => {
+        const limit = parsePageLimit(options.limit);
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const page = await transcriptAction({ appId: resolvedAppId, sessionId, limit, cursor: options.cursor, turnId: options.turn }, new ApiClient());
+            if (options.json) {
+                json(page);
+                return;
+            }
+            if (page.items.length === 0) {
+                printEmptyPage(page, "messages");
+                return;
+            }
+            for (const message of page.items)
+                console.log(formatTranscriptMessage(message).join("\n"));
+            printPageHint(page);
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+    agentSessions
+        .command("steps")
+        .description("Show one page of a session's turn steps, oldest first: model, tool, context and history calls")
+        .argument("<session-id>", "Session ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--turn <turn-id>", "Only this turn's steps")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `\n${READERS_NOTE}`)
+        .action(async (sessionId, options) => {
+        const limit = parsePageLimit(options.limit);
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const page = await stepsAction({ appId: resolvedAppId, sessionId, limit, cursor: options.cursor, turnId: options.turn }, new ApiClient());
+            if (options.json) {
+                json(page);
+                return;
+            }
+            if (page.items.length === 0) {
+                printEmptyPage(page, "steps");
+                return;
+            }
+            console.log(formatTable(page.items.map(stepCells), [
+                { header: "TURN", key: "turnId" },
+                { header: "SEQ", key: "seq" },
+                { header: "KIND", key: "kind" },
+                { header: "STATUS", key: "status" },
+                { header: "STARTED", key: "startedAt", format: formatDate },
+                { header: "DURATION", key: "durationMs", format: formatDuration },
+                { header: "PROVIDER/MODEL", key: "providerModel" },
+                { header: "TOKENS", key: "tokens" },
+                { header: "COST", key: "costCell" },
+                { header: "ERROR", key: "errorCell" },
+            ]));
+            printPageHint(page);
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+    agentSessions
+        .command("artifacts")
+        .description("List a session's tool calls and where their artifacts live, or print one call's artifact")
+        .argument("<session-id>", "Session ID")
+        .argument("[part-id]", "A tool call's part ID: print its artifact")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Without a part ID, one page of the session's tool calls, oldest first; the
+ARTIFACT column says whether each artifact is inline, on a blob, or absent.
+With a part ID (the PART column), the artifact's value as JSON, read from the
+session's attachments when it is a blob.
+
+${READERS_NOTE}`)
+        .action(async (sessionId, partId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (partId !== undefined) {
+            try {
+                const read = await readArtifactAction({ appId: resolvedAppId, sessionId, partId }, new ApiClient());
+                if (!read.found) {
+                    error(`No tool call part ${partId} in session ${sessionId}`);
+                    process.exit(1);
+                }
+                if (read.value === null && !options.json) {
+                    info("This call has no artifact.");
+                    return;
+                }
+                json(read.value);
+            }
+            catch (err) {
+                error(describeRecordsFailure(err));
+                process.exit(1);
+            }
+            return;
+        }
+        const limit = parsePageLimit(options.limit);
+        try {
+            const page = await toolCallsAction({ appId: resolvedAppId, sessionId, limit, cursor: options.cursor }, new ApiClient());
+            if (options.json) {
+                json(page);
+                return;
+            }
+            if (page.items.length === 0) {
+                printEmptyPage(page, "tool calls");
+                return;
+            }
+            console.log(formatTable(page.items.map((part) => ({ ...part, artifactCell: artifactLabel(part) })), [
+                { header: "PART", key: "id" },
+                { header: "CALL", key: "toolCallId" },
+                { header: "TOOL", key: "toolName" },
+                { header: "STATE", key: "state" },
+                { header: "MESSAGE", key: "messageId" },
+                { header: "ARTIFACT", key: "artifactCell" },
+            ]));
+            printPageHint(page);
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+    agentSessions
+        .command("upload")
+        .description("Upload a file to a session, for a message to reference")
+        .argument("<session-id>", "Session ID")
+        .argument("<file-path>", "Path to the file to upload")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--blob-id <id>", "Blob ID to upload under (a new ULID if not specified)")
+        .option("--filename <name>", "Filename to store (the file's own name if not specified)")
+        .option("--content-type <type>", "Content type (from the filename's extension if not specified)")
+        .option("--json", "Output the server's answer as JSON")
+        .addHelpText("after", `
+The session's owner and participants upload. Uploading the same bytes under
+the same blob ID again succeeds without sending them; different bytes under
+an existing ID are refused. A message carries the file by its blob ID.
+`)
+        .action(async (sessionId, filePath, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const done = await uploadAttachmentAction({
+                appId: resolvedAppId,
+                sessionId,
+                filePath,
+                blobId: options.blobId,
+                filename: options.filename,
+                contentType: options.contentType,
+            }, new ApiClient());
+            if (options.json) {
+                json(done.answer);
+                return;
+            }
+            const blobId = done.answer?.blobId ?? done.blobId;
+            const filename = done.answer?.filename ?? done.filename;
+            success(`${done.answer?.bytesTransferred === 0 ? "Already uploaded" : "Uploaded"} ${filename} to session ${sessionId}.`);
+            keyValue("Blob ID", blobId);
+            keyValue("Filename", filename);
+            keyValue("Content Type", done.answer?.contentType ?? done.contentType);
+            keyValue("Size", `${done.answer?.numBytes ?? done.numBytes} bytes`);
+            info(`Reference it in a message as files: [{ blobId: "${blobId}" }].`);
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+    agentSessions
+        .command("download")
+        .description("Download one of a session's files: an upload or a tool call's artifact blob")
+        .argument("<session-id>", "Session ID")
+        .argument("<blob-id>", "Blob ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--output <path>", "Output file path (defaults to stdout)")
+        .addHelpText("after", `
+Every member of the session and every app owner and admin downloads. Without
+--output the bytes are written to stdout unchanged.
+`)
+        .action(async (sessionId, blobId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            await downloadAttachmentAction({ appId: resolvedAppId, sessionId, blobId, output: options.output }, {
+                client: new ApiClient(),
+                writeFile: (path, data) => writeFileSync(path, data),
+                writeStdout: (data) => process.stdout.write(data),
+                print: success,
+            });
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+    agentSessions
+        .command("delete")
+        .description("Delete an agent session and its document")
+        .argument("<session-id>", "Session ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+The session's owner, app owners and admins delete; the document and its rows
+go with it. Deleting a session that is already deleted succeeds again.
+`)
+        .action(async (sessionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        try {
+            const outcome = await deleteAgentSessionAction({ appId: resolvedAppId, sessionId, yes: options.yes === true, json: options.json === true }, {
+                client: new ApiClient(),
+                confirm: confirmPrompt,
+                print: (line) => (options.json ? console.log(line) : success(line)),
+            });
+            if (outcome === "cancelled")
+                info("Cancelled.");
+        }
+        catch (err) {
+            error(describeRecordsFailure(err));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=agent-sessions.js.map