@ljw1004/opencode-trace 0.1.1 → 0.1.3

package/README.md

@@ -15,3 +15,5 @@ Add the package to your OpenCode config:
 ```
 
 Restart OpenCode and you'll see each transcript stored in `~/opencode-trace`.
+
+That installation path by default uses `@latest`, which opencode currently does't refresh when latest changes. You can force a refresh with `rm -rf ~/.cache/opencode/packages/@ljw1004/opencode-trace@latest`

package/index.ts

@@ -75,7 +75,7 @@ function extractPromptFromRequestBody(v: Record<string, unknown>): string | unde
     return undefined
   }
   const content = (v: unknown): string | undefined => {
-    if (typeof v === "string") return v
+    if (typeof v === "string") return usable(v)
     if (!Array.isArray(v)) return undefined
     for (const part of v) {
       const found = text(part)
@@ -97,35 +97,42 @@ function extractPromptFromRequestBody(v: Record<string, unknown>): string | unde
 }
 
 /**
- * Appends one row to the session logfile.
- * If this is the first row for the session, also chooses the filename and writes the html preamble.
- * Side effects: may create directories, create a logfile, mutate `files`, and append to disk.
+ * Appends one row to the session logfile. If logging fails, them skips silently.
+ * Session logfiles are like `~/opencode-trace/2024.6.10 15.30.45 why is the sky blue.html`
+ * In the vanishingly rare case of filename collision (because a user asked two different sessions
+ * the same prompt at the exact same second) then there'll be a clash, and that's the user's fault:
+ * we tradeoff theoretical perfection for user convenience in the common case.
  */
-function write(id: string, name: string, row: Record<string, unknown>): void {
-  const prev = files.get(id)
-  const d = new Date()
-  const file = prev ?? path.join(
-    root,
-    `${d.getFullYear()}.${d.getMonth() + 1}.${d.getDate()} ${d.getHours()}.${d.getMinutes()}.${d.getSeconds()} ${name}.html`,
-  )
-  mkdirSync(root, { recursive: true })
-  if (!existsSync(file)) {
-    const html = PREAMBLE.replace(
-      "// {viewer.js}",
-      readFileSync(new URL("./viewer.js", import.meta.url), "utf8"),
-    )
-    appendFileSync(
-      file,
-      html,
+function writeNoThrow(id: string, name: string, row: Record<string, unknown>): void {
+  try {
+    const prev = files.get(id)
+    const d = new Date()
+    const file = prev ?? path.join(
+      root,
+      `${d.getFullYear()}.${d.getMonth() + 1}.${d.getDate()} ${d.getHours()}.${d.getMinutes()}.${d.getSeconds()} ${name}.html`,
     )
+    mkdirSync(root, { recursive: true })
+    if (!existsSync(file)) {
+      const html = PREAMBLE.replace(
+        "// {viewer.js}",
+        () => readFileSync(new URL("./viewer.js", import.meta.url), "utf8"),
+      )
+      appendFileSync(
+        file,
+        html,
+      )
+    }
+    files.set(id, file)
+    appendFileSync(file, `${JSON.stringify(row).replace(/-->/g, "--\\u003e")}\n`)
+  } catch {
+    // Intentionally swallow tracing I/O failures so plugin logging can't crash OpenCode.
   }
-  files.set(id, file)
-  appendFileSync(file, `${JSON.stringify(row).replace(/-->/g, "--\\u003e")}\n`)
 }
 
 /**
- * Given two json values, returns a bool for whether they are identical, plus a representation
- * of the difference intended for humans to read.
+ * Given two json values, returns a bool for whether they are identical, plus a
+ * (lossy) representation of the difference intended for humans to read, which
+ * still roughly captures the shape even of unchanged objects.
  *
  * The representation always has the same type as `next`.
  *
@@ -465,7 +472,7 @@ async function tracedFetch(
 
   const req = new Request(input, init)
   const session = req.headers.get("x-opencode-session") ?? req.headers.get("x-session-affinity") ?? req.headers.get("session_id") ?? undefined;
-  if (session === undefined) return orig!(input,init);
+  if (session === undefined) return orig!(req);
 
   const text = await req.clone().text().catch(() => "")
   const raw = ((): Record<string, unknown> => {
@@ -478,6 +485,10 @@ async function tracedFetch(
   })()
   const title = isRecord(raw) && typeof raw._body !== "string" ? extractPromptFromRequestBody(raw) : undefined
   const purpose = isRecord(raw) && Array.isArray(raw.tools) && raw.tools.length > 0 ? '' : '[meta]';
+  // The purpose field is "[meta]" for LLM requests that appear to be not part of the conversation, e.g. "generate a title".
+  // I tried a bunch of heuristics, and this one "no tools" was the one that worked best across a variety of models.
+  // We calculate it here based on the request, and store it on both request and response, since otherwise
+  // there are no reliable indicators on the response jsonl for our viewer to key off.
   const seq = (ids.get(session) ?? 0) + 1
   ids.set(session, seq)
   const common = { _id: seq, _purpose: purpose, _url: req.url }
@@ -493,7 +504,7 @@ async function tracedFetch(
   const requestNext = raw as object
   const [requestRow] = delta(prevs.get(requestKey), requestNext)
   prevs.set(requestKey, requestNext)
-  write(session, name, {
+  writeNoThrow(session, name, {
     ...(requestRow as Record<string, unknown>),
     ...common,
     _kind: "request",
@@ -501,7 +512,7 @@ async function tracedFetch(
   })
 
   const res = await orig!(req).catch((err) => {
-    write(session, name, {
+    writeNoThrow(session, name, {
       ...common,
       _kind: "error",
       _ts: now(),
@@ -526,7 +537,7 @@ async function tracedFetch(
       const responseKey = `${session}\n${req.method}\n${req.url}\nresponse\n${purpose}`
       const [responseRow] = delta(prevs.get(responseKey), responseNext)
       prevs.set(responseKey, responseNext)
-      write(session, name, {
+      writeNoThrow(session, name, {
         ...(responseRow as Record<string, unknown>),
         ...common,
         _kind: "response",
@@ -534,7 +545,7 @@ async function tracedFetch(
       })
     })
     .catch((err) => {
-      write(session, name, {
+      writeNoThrow(session, name, {
         ...common,
         _kind: "error",
         _ts: now(),
@@ -544,35 +555,24 @@ async function tracedFetch(
   return res
 }
 
-export default {
-  id: "ljw.opencode-trace",
-  async server(): Promise<object> {
-    // OpenCode loads this module with dynamic import() when plugin state is initialized for
-    // an instance/directory. In current OpenCode this module import is normally cached, so
-    // top-level state like `orig`, `files`, and `prevs` survives repeated hook initialization.
-    //
-    // OpenCode then calls `server()` when it initializes this plugin's server hooks for that
-    // instance. That can happen more than once per process across instance reload/dispose, so
-    // the fetch patch must be guarded even though the module itself is usually only loaded once.
-    if (!orig) {
-      orig = globalThis.fetch.bind(globalThis)
-      globalThis.fetch = tracedFetch
-    }
-    return {}
-  },
-}
+/* Plugin model:
+ * - This module is loaded with dynamic import() when plugin state is initialized for an instance/directory.
+ *   The module import is normally cached, so our top-level state like `orig` survives repeated hook initialization
+ * - Opencode calls `default.server()` when it initializes this plugin's server hooks for that instance.
+ *   This can happen more than once per process across instance reload/dispose, which is why our fetch()
+ *   patch is guarded even though the module itself is loaded only once.
+ * - Opencode v1.3 has a single unified process for both TUI and server, so its plugin entrypoint `default` is just a function.
+ * - Opencode v1.4 has two separate entrypoints, `default.tui()` and `default.server()`
+ */
+const main: (() => Promise<object>) & {id?: unknown, server?: unknown} = async () => {
+  if (!orig) {
+    orig = globalThis.fetch.bind(globalThis);
+    globalThis.fetch = tracedFetch;
+  }
+  return {};
+};
 
-// For opencode versions prior to 1.4, it doesn't get picked up automatically from the plugins
-// directory so you have to add this to your ~/.config/opencode/opencode.json
-//  "plugin": [
-//    "file:///path/to/.config/opencode/plugins/index.ts"
-//  ]
-//
-// And it uses a different default export:
-// export default async function opencodeTracePlugin() {
-//   if (!orig) {
-//     orig = globalThis.fetch.bind(globalThis);
-//     globalThis.fetch = tracedFetch;
-//   }
-//   return {}
-// }
+const entrypoint = main; // opencode v1.3 expects default export to be a function
+entrypoint.id = "ljw1004.opencode-trace";
+entrypoint.server = main; // opencode v1.4 expects default export to be an object, with server() being what executes
+export default entrypoint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ljw1004/opencode-trace",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "OpenCode plugin that saves raw json LLM request+responses as jsonl in ~/opencode-trace, with built-in HTML interactive viewer",
   "license": "MIT",
   "type": "module",

package/viewer.js

@@ -32,6 +32,7 @@ function fromHTML(html) {
  * Escapes string for safe insertion into HTML
  */
 function esc(s) {
+  s = String(s ?? '');
   return s
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -51,7 +52,7 @@ function ts(data) {
  * Puts a string onto a single line and truncates to 80 chars, for display in INLINE part of a node
  */
 function short(s) {
-  return s.replace(/\n/g, ' ').slice(0, 80);
+  return String(s ?? '').replace(/\n/g, ' ').slice(0, 80);
 }
 
 /**
@@ -63,10 +64,10 @@ function contentText(contents) {
   if (!Array.isArray(contents)) return JSON.stringify(contents ?? '');
   let r = [];
   for (const c of contents ?? []) {
-    if (c.type === 'input_text') r.push(c.text);
-    else if (c.type === 'output_text') r.push(c.text);
-    else if (c.type === 'text') r.push(c.text);
-    else r.push(`[${c.type}]`);
+    const type = c && typeof c === 'object' ? c.type : undefined;
+    const text = c && typeof c === 'object' ? c.text : c;
+    if (type === 'input_text' || type === 'output_text' || type === 'text') r.push(String(text ?? ''));
+    else r.push(`[${String(type ?? '?')}]`);
   }
   return r.join('\n');
 }
@@ -91,7 +92,7 @@ function renderPayload(elements) {
     } else if (e.type === 'input_text' || e.type === 'output_text' || e.type === 'text') {
       payload.push({
         [TITLE]: `${payload.length}: ${e.type}: `,
-        [INLINE]: esc(short(e.text)),
+        [INLINE]: esc(short(String(e.text ?? ''))),
         body: e.text,
       });
 
@@ -131,13 +132,15 @@ function renderPayload(elements) {
 
 /**
  * Renders a node in the tree.
- * If it looks like a REQUEST or RESPONSE payload (has ._kind property) then renders it conveniently.
+ * If it looks like a REQUEST or RESPONSE payload (has ._kind property) then pretty-prints it.
+ * The goal of this pretty-printing is not to be 100% faithful; instead it's solely to surface
+ * to the users some of the most important lines, for their attention.
  * Otherwise, renders primtives, objects, arrays in the obvious way.
  */
 function render(data, label) {
   const deltaField = (key) => data[key] ?? data[`${key}+`] ?? data[`${key}-`] ?? data[`*${key}`];
-  const id = data?._id !== undefined ? ` #${data._id}` : '';
-  const purpose = data?._purpose ? ` ${data._purpose}` : '';
+  const id = data?._id !== undefined ? ` #${esc(String(data._id))}` : '';
+  const purpose = data?._purpose ? ` ${esc(String(data._purpose))}` : '';
   if (data?.[TITLE] !== undefined) {
     return data;
   } else if (data?._kind === 'request') {
@@ -162,7 +165,7 @@ function render(data, label) {
     const raw = {...data};
     return {
       [TITLE]: `[${esc(ts(data))}] <b>ERROR${id}${purpose}</b> `,
-      [INLINE]: esc(short(data._error ?? '')),
+      [INLINE]: esc(short(data._error)),
       body: [
         data._error ?? '???',
         ...(data._stack ? [{[TITLE]: 'stack', body: data._stack}] : []),