@sixb/cli-core 0.1.10 → 0.2.1

package/src/commands/history.ts

@@ -0,0 +1,204 @@
+import type { ApiClient } from "../api-client"
+import {
+  integerInRange,
+  isHelp,
+  nonNegativeInteger,
+  parseCommandArgs,
+  requestsHelp,
+} from "../arguments"
+import { CliError, EXIT_API, fail, writeText } from "../output"
+import { CLI_LIMITS } from "../policies"
+import { GROUP_HELP } from "./metadata"
+import { idSegment } from "./shared"
+
+/** In a page, longer text is cut: `sixb history <seq>` prints a message whole. */
+const PAGE_TEXT_CHARS = 4_000
+const PAGE_TOOL_CHARS = 1_000
+
+interface StoredMessage {
+  readonly id?: string
+  readonly seq: number
+  readonly role: string
+  readonly createdAt?: string
+  readonly authorPrincipal?: { readonly type: string; readonly id: string }
+  readonly parts: readonly Record<string, unknown>[]
+}
+
+interface MessagePage {
+  readonly messages: readonly StoredMessage[]
+  readonly authors: readonly { readonly id: string; readonly displayName?: string }[]
+  readonly hasMore: boolean
+  readonly total: number
+}
+
+/**
+ * Read the run's conversation as text, oldest first, compacted turns included: what was said,
+ * the files sent, and each tool call with its result. Reasoning stays out.
+ */
+export async function history(api: ApiClient, args: readonly string[]): Promise<void> {
+  if (isHelp(args[0]) || requestsHelp(args)) return writeText(GROUP_HELP.history)
+
+  const { positionals, options } = parseCommandArgs(
+    args,
+    { "--offset": "string", "--limit": "string" },
+    "history",
+    [0, 1]
+  )
+  const threadId = process.env.SIXB_THREAD_ID
+  if (!threadId) fail("This run has no conversation to read: SIXB_THREAD_ID is not set.")
+  const path = `/api/agent-threads/${idSegment(threadId)}/messages`
+
+  const seq = positionals[0]
+  if (seq !== undefined) {
+    const wanted = integerInRange("<seq>", seq, 1, Number.MAX_SAFE_INTEGER)
+    const page = messagePage(
+      await api.get(path, { order: "asc", offset: String(wanted - 1), limit: "1" })
+    )
+    const message = page.messages[0]
+    if (message?.seq !== wanted) {
+      throw new CliError(
+        { code: "not_found", message: `The conversation has no message #${wanted}.` },
+        EXIT_API
+      )
+    }
+    return writeText(renderMessage(message, page, { whole: true }))
+  }
+
+  const offset = nonNegativeInteger("--offset", options["--offset"] ?? "0")
+  const limit = integerInRange(
+    "--limit",
+    options["--limit"] ?? String(CLI_LIMITS.history.default),
+    1,
+    CLI_LIMITS.history.maximum
+  )
+  const page = messagePage(
+    await api.get(path, { order: "asc", offset: String(offset), limit: String(limit) })
+  )
+
+  const shown = page.messages.map((message) => renderMessage(message, page, { whole: false }))
+  const end = offset + page.messages.length
+  const footer =
+    page.messages.length === 0
+      ? `No messages from offset ${offset}: the conversation has ${page.total}.`
+      : page.hasMore
+        ? `Messages ${offset + 1}–${end} of ${page.total}. Next: sixb history --offset ${end}`
+        : `Messages ${offset + 1}–${end} of ${page.total}: the end of the conversation.`
+  writeText([...shown, footer].join("\n\n"))
+}
+
+function renderMessage(
+  message: StoredMessage,
+  page: MessagePage,
+  options: { readonly whole: boolean }
+): string {
+  const author = message.authorPrincipal
+    ? page.authors.find((person) => person.id === message.authorPrincipal?.id)?.displayName
+    : undefined
+  const heading = [`#${message.seq} ${message.role}`, author, message.createdAt]
+    .filter(Boolean)
+    .join(" · ")
+  const bounds = {
+    seq: message.seq,
+    textChars: options.whole ? Number.POSITIVE_INFINITY : PAGE_TEXT_CHARS,
+    toolChars: options.whole ? Number.POSITIVE_INFINITY : PAGE_TOOL_CHARS,
+  }
+
+  return [
+    `── ${heading}`,
+    ...message.parts.flatMap((part, index) => [
+      ...renderPart(part, bounds),
+      ...renderOutputFile(part, message, index),
+    ]),
+  ].join("\n")
+}
+
+/**
+ * Where a call's whole output is, when it was too large for the context and its part keeps a
+ * bounded copy: in the sandbox while the conversation still shows the call, which every run
+ * writes back, and through the message's file route whatever happened since.
+ */
+function renderOutputFile(
+  part: Record<string, unknown>,
+  message: StoredMessage,
+  index: number
+): string[] {
+  const file = part.type === "tool-call" ? record(part.outputFile) : undefined
+  const fileRef = record(file?.fileRef)
+  if (typeof file?.path !== "string" || typeof fileRef?.sizeBytes !== "number") return []
+
+  const contextDir = process.env.SIXB_CONTEXT_DIR
+  const path = contextDir ? `${contextDir.replace(/\/$/, "")}/${file.path}` : file.path
+  const apiBaseUrl = process.env.SIXB_API_BASE_URL
+  const threadId = process.env.SIXB_THREAD_ID
+  const download =
+    apiBaseUrl && threadId && message.id
+      ? `; else: sixb files download url ${apiBaseUrl.replace(/\/$/, "")}/api/agent-threads/${idSegment(threadId)}/messages/${idSegment(message.id)}/files/content?path=${encodeURIComponent(`/parts/${index}/outputFile/fileRef`)} --output <file>`
+      : ""
+  return [
+    `  [whole output, ${fileRef.sizeBytes.toLocaleString("en-US")} bytes: ${path}, written back to the sandbox at each run while the conversation shows this call${download}]`,
+  ]
+}
+
+function renderPart(
+  part: Record<string, unknown>,
+  bounds: { readonly seq: number; readonly textChars: number; readonly toolChars: number }
+): string[] {
+  const cut = (value: string, max: number) =>
+    value.length <= max
+      ? value
+      : `${value.slice(0, max)}… [${(value.length - max).toLocaleString("en-US")} more characters: sixb history ${bounds.seq}]`
+
+  switch (part.type) {
+    case "text":
+      return typeof part.text === "string" && part.text.trim()
+        ? [cut(part.text, bounds.textChars)]
+        : []
+    case "file": {
+      const file = record(part.fileRef)
+      const name = file?.fileName ?? file?.logicalPath ?? file?.blobId
+      return [`[file ${String(name)}${file?.mediaType ? `, ${String(file.mediaType)}` : ""}]`]
+    }
+    case "tool-call": {
+      const input = cut(JSON.stringify(part.input ?? {}), bounds.toolChars)
+      const outcome =
+        part.state === "output-error"
+          ? `error: ${cut(String(part.errorText ?? ""), bounds.toolChars)}`
+          : part.state === "output-available"
+            ? cut(
+                typeof part.output === "string" ? part.output : JSON.stringify(part.output),
+                bounds.toolChars
+              )
+            : String(part.state ?? "")
+      return [`[${String(part.toolName)}] ${input}`, `→ ${outcome}`]
+    }
+    case "continuation":
+      return ["[asked to continue]"]
+    case "approval-outcome":
+      return [`[approval ${String(part.status)}]`]
+    // Reasoning, provider state and step marks are not part of what was said.
+    default:
+      return []
+  }
+}
+
+function messagePage(value: unknown): MessagePage {
+  const page = record(value)
+  if (!page || !Array.isArray(page.messages) || typeof page.total !== "number") {
+    throw new CliError(
+      { code: "invalid_api_response", message: "The Sixb API returned an invalid message page." },
+      EXIT_API
+    )
+  }
+  return {
+    messages: page.messages as StoredMessage[],
+    authors: Array.isArray(page.authors) ? (page.authors as MessagePage["authors"]) : [],
+    hasMore: page.hasMore === true,
+    total: page.total,
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}

package/src/commands/metadata.ts

@@ -204,6 +204,13 @@ optionally under filters; k bounds the ranked matches and results carry a score.
 export const GROUP_HELP = {
   status: "Usage: sixb status",
   context: "Usage: sixb context",
+  history: `Usage:
+  sixb history [--offset <n>] [--limit <1-${CLI_LIMITS.history.maximum}>]
+  sixb history <seq>
+
+Prints this conversation's messages as text, oldest first, including those summarized when it
+was compacted: what was said, the files sent, and each tool call with its result. A page holds
+${CLI_LIMITS.history.default} messages by default and cuts long text; \`sixb history <seq>\` prints one message whole.`,
   project: "Usage: sixb project show",
   ontology: `Usage:
   sixb ontology list [--full]

package/src/generated/sixb.mjs

@@ -167,6 +167,7 @@ var CLI_LIMITS = {
   telemetryHistory: { default: 100, maximum: 1000 },
   linkPage: { default: 100, maximum: 1000 },
   users: { default: 20, maximum: 200 },
+  history: { default: 20, maximum: 100 },
   datasetVersions: { default: 20, maximum: 100 },
   datasetRows: { default: 100, maximum: 1000 },
   inspect: {
@@ -372,6 +373,13 @@ optionally under filters; k bounds the ranked matches and results carry a score.
 var GROUP_HELP = {
   status: "Usage: sixb status",
   context: "Usage: sixb context",
+  history: `Usage:
+  sixb history [--offset <n>] [--limit <1-${CLI_LIMITS.history.maximum}>]
+  sixb history <seq>
+
+Prints this conversation's messages as text, oldest first, including those summarized when it
+was compacted: what was said, the files sent, and each tool call with its result. A page holds
+${CLI_LIMITS.history.default} messages by default and cuts long text; \`sixb history <seq>\` prints one message whole.`,
   project: "Usage: sixb project show",
   ontology: `Usage:
   sixb ontology list [--full]
@@ -1976,6 +1984,107 @@ async function dispatch(api, command, args) {
   }
 }
 
+// src/commands/history.ts
+var PAGE_TEXT_CHARS = 4000;
+var PAGE_TOOL_CHARS = 1000;
+async function history(api, args) {
+  if (isHelp(args[0]) || requestsHelp(args))
+    return writeText(GROUP_HELP.history);
+  const { positionals, options } = parseCommandArgs(args, { "--offset": "string", "--limit": "string" }, "history", [0, 1]);
+  const threadId = process.env.SIXB_THREAD_ID;
+  if (!threadId)
+    fail("This run has no conversation to read: SIXB_THREAD_ID is not set.");
+  const path = `/api/agent-threads/${idSegment(threadId)}/messages`;
+  const seq = positionals[0];
+  if (seq !== undefined) {
+    const wanted = integerInRange("<seq>", seq, 1, Number.MAX_SAFE_INTEGER);
+    const page = messagePage(await api.get(path, { order: "asc", offset: String(wanted - 1), limit: "1" }));
+    const message = page.messages[0];
+    if (message?.seq !== wanted) {
+      throw new CliError({ code: "not_found", message: `The conversation has no message #${wanted}.` }, EXIT_API);
+    }
+    return writeText(renderMessage(message, page, { whole: true }));
+  }
+  const offset = nonNegativeInteger("--offset", options["--offset"] ?? "0");
+  const limit = integerInRange("--limit", options["--limit"] ?? String(CLI_LIMITS.history.default), 1, CLI_LIMITS.history.maximum);
+  const page = messagePage(await api.get(path, { order: "asc", offset: String(offset), limit: String(limit) }));
+  const shown = page.messages.map((message) => renderMessage(message, page, { whole: false }));
+  const end = offset + page.messages.length;
+  const footer = page.messages.length === 0 ? `No messages from offset ${offset}: the conversation has ${page.total}.` : page.hasMore ? `Messages ${offset + 1}–${end} of ${page.total}. Next: sixb history --offset ${end}` : `Messages ${offset + 1}–${end} of ${page.total}: the end of the conversation.`;
+  writeText([...shown, footer].join(`
+
+`));
+}
+function renderMessage(message, page, options) {
+  const author = message.authorPrincipal ? page.authors.find((person) => person.id === message.authorPrincipal?.id)?.displayName : undefined;
+  const heading = [`#${message.seq} ${message.role}`, author, message.createdAt].filter(Boolean).join(" · ");
+  const bounds = {
+    seq: message.seq,
+    textChars: options.whole ? Number.POSITIVE_INFINITY : PAGE_TEXT_CHARS,
+    toolChars: options.whole ? Number.POSITIVE_INFINITY : PAGE_TOOL_CHARS
+  };
+  return [
+    `── ${heading}`,
+    ...message.parts.flatMap((part, index) => [
+      ...renderPart(part, bounds),
+      ...renderOutputFile(part, message, index)
+    ])
+  ].join(`
+`);
+}
+function renderOutputFile(part, message, index) {
+  const file = part.type === "tool-call" ? record(part.outputFile) : undefined;
+  const fileRef = record(file?.fileRef);
+  if (typeof file?.path !== "string" || typeof fileRef?.sizeBytes !== "number")
+    return [];
+  const contextDir = process.env.SIXB_CONTEXT_DIR;
+  const path = contextDir ? `${contextDir.replace(/\/$/, "")}/${file.path}` : file.path;
+  const apiBaseUrl = process.env.SIXB_API_BASE_URL;
+  const threadId = process.env.SIXB_THREAD_ID;
+  const download = apiBaseUrl && threadId && message.id ? `; else: sixb files download url ${apiBaseUrl.replace(/\/$/, "")}/api/agent-threads/${idSegment(threadId)}/messages/${idSegment(message.id)}/files/content?path=${encodeURIComponent(`/parts/${index}/outputFile/fileRef`)} --output <file>` : "";
+  return [
+    `  [whole output, ${fileRef.sizeBytes.toLocaleString("en-US")} bytes: ${path}, written back to the sandbox at each run while the conversation shows this call${download}]`
+  ];
+}
+function renderPart(part, bounds) {
+  const cut = (value, max) => value.length <= max ? value : `${value.slice(0, max)}… [${(value.length - max).toLocaleString("en-US")} more characters: sixb history ${bounds.seq}]`;
+  switch (part.type) {
+    case "text":
+      return typeof part.text === "string" && part.text.trim() ? [cut(part.text, bounds.textChars)] : [];
+    case "file": {
+      const file = record(part.fileRef);
+      const name = file?.fileName ?? file?.logicalPath ?? file?.blobId;
+      return [`[file ${String(name)}${file?.mediaType ? `, ${String(file.mediaType)}` : ""}]`];
+    }
+    case "tool-call": {
+      const input = cut(JSON.stringify(part.input ?? {}), bounds.toolChars);
+      const outcome = part.state === "output-error" ? `error: ${cut(String(part.errorText ?? ""), bounds.toolChars)}` : part.state === "output-available" ? cut(typeof part.output === "string" ? part.output : JSON.stringify(part.output), bounds.toolChars) : String(part.state ?? "");
+      return [`[${String(part.toolName)}] ${input}`, `→ ${outcome}`];
+    }
+    case "continuation":
+      return ["[asked to continue]"];
+    case "approval-outcome":
+      return [`[approval ${String(part.status)}]`];
+    default:
+      return [];
+  }
+}
+function messagePage(value) {
+  const page = record(value);
+  if (!page || !Array.isArray(page.messages) || typeof page.total !== "number") {
+    throw new CliError({ code: "invalid_api_response", message: "The Sixb API returned an invalid message page." }, EXIT_API);
+  }
+  return {
+    messages: page.messages,
+    authors: Array.isArray(page.authors) ? page.authors : [],
+    hasMore: page.hasMore === true,
+    total: page.total
+  };
+}
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+
 // src/commands/memory.ts
 import { lstat, mkdir as mkdir2, readdir, readFile as readFile3, rm as rm2, writeFile } from "node:fs/promises";
 import { dirname as dirname3, join as join3 } from "node:path";
@@ -2529,6 +2638,8 @@ async function main(args) {
     return context(rest);
   if (command === "memory")
     return memory(rest, sandboxMode());
+  if (command === "history")
+    return history(createInstanceApiClient(sandboxMode()), rest);
   if (!isInstanceCommand(command))
     fail(`Unknown command '${command}'. Run 'sixb --help'.`);
   await runInstanceCli({ args, mode: sandboxMode() });

package/src/main.ts

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 
 // The `sixb` a sandbox runs: the API commands people run, plus the run's own (`status`,
-// `context`, `memory`). `bun run generate:sandbox-cli` bundles it into generated/sixb.mjs.
+// `context`, `memory`, `history`). `bun run generate:sandbox-cli` bundles it into generated/sixb.mjs.
 import { isHelp } from "./arguments"
 import { isInstanceCommand } from "./commands"
+import { history } from "./commands/history"
 import { memory } from "./commands/memory"
 import { renderInstanceHelp } from "./commands/metadata"
 import { context, status } from "./commands/system"
 import { fail, INSTANCE_CLI_VERSION, reportError, writeText } from "./output"
-import { runInstanceCli } from "./run"
+import { createInstanceApiClient, runInstanceCli } from "./run"
 
 async function main(args: readonly string[]): Promise<void> {
   const [command, ...rest] = args
@@ -19,6 +20,7 @@ async function main(args: readonly string[]): Promise<void> {
   if (command === "status") return status(rest, sandboxMode())
   if (command === "context") return context(rest)
   if (command === "memory") return memory(rest, sandboxMode())
+  if (command === "history") return history(createInstanceApiClient(sandboxMode()), rest)
   if (!isInstanceCommand(command)) fail(`Unknown command '${command}'. Run 'sixb --help'.`)
 
   await runInstanceCli({ args, mode: sandboxMode() })

package/src/policies.ts

@@ -8,6 +8,8 @@ export const CLI_LIMITS = {
   linkPage: { default: 100, maximum: 1_000 },
   /** The server lists at most 200 members per page. */
   users: { default: 20, maximum: 200 },
+  /** A page of a conversation's messages, as `sixb history` prints them. */
+  history: { default: 20, maximum: 100 },
   /** The server's dataset bounds: 100 versions and 1,000 rows per page. */
   datasetVersions: { default: 20, maximum: 100 },
   datasetRows: { default: 100, maximum: 1_000 },

package/src/sandbox-cli-assets.d.ts

@@ -0,0 +1,10 @@
+// What `sandbox-cli.ts` imports as text. Bun's loader reads them; the type checker needs telling.
+declare module "*/bin/sixb" {
+  const text: string
+  export default text
+}
+
+declare module "*/generated/sixb.mjs" {
+  const text: string
+  export default text
+}

package/src/sandbox-cli.ts

@@ -1,4 +1,6 @@
-import { readFile } from "node:fs/promises"
+/// <reference path="./sandbox-cli-assets.d.ts" />
+import launcher from "./bin/sixb" with { type: "text" }
+import bundle from "./generated/sixb.mjs" with { type: "text" }
 
 /** The `sixb` a sandbox installs: a shell launcher and the bundle it runs on Bun or Node. */
 export interface SandboxCliAssets {
@@ -6,13 +8,9 @@ export interface SandboxCliAssets {
   readonly artifact: Uint8Array
 }
 
-let cachedAssets: Promise<SandboxCliAssets> | undefined
+const assets: SandboxCliAssets = { launcher, artifact: new TextEncoder().encode(bundle) }
 
-/** Read from beside this module: `src/` in the workspace, `dist/` once built. */
-export function loadSandboxCliAssets(): Promise<SandboxCliAssets> {
-  cachedAssets ??= Promise.all([
-    readFile(new URL("./bin/sixb", import.meta.url), "utf8"),
-    readFile(new URL("./generated/sixb.mjs", import.meta.url)),
-  ]).then(([launcher, artifact]) => ({ launcher, artifact }))
-  return cachedAssets
+/** Part of this module, so that a program compiled to one file carries them too. */
+export async function loadSandboxCliAssets(): Promise<SandboxCliAssets> {
+  return assets
 }

package/dist/bin/sixb

@@ -1,26 +0,0 @@
-#!/usr/bin/env sh
-
-set -eu
-
-script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-artifact="$script_dir/../lib/sixb.mjs"
-if [ ! -f "$artifact" ]; then
-  artifact="$script_dir/../generated/sixb.mjs"
-fi
-if [ ! -f "$artifact" ]; then
-  printf '%s\n' '{"error":{"code":"runtime_unavailable","message":"The Sixb CLI artifact is missing."}}' >&2
-  exit 2
-fi
-
-bun_path=$(command -v bun || true)
-if [ -n "$bun_path" ]; then
-  exec "$bun_path" "$artifact" "$@"
-fi
-
-node_path=$(command -v node || true)
-if [ -n "$node_path" ]; then
-  exec "$node_path" "$artifact" "$@"
-fi
-
-printf '%s\n' '{"error":{"code":"runtime_unavailable","message":"The Sixb CLI requires Bun or Node.js."}}' >&2
-exit 2