@miruzero/zgpt 0.1.0 → 0.1.1

package/docs/architecture.md

@@ -7,7 +7,7 @@
 ## Runtime
 
 ```text
-auth / session / conversation / project / connector
+auth / session / conversation / project / connector / file / memory / settings / share
                     |
                  protocol
 sentinel / proof / conduit / payload / SSE
@@ -20,6 +20,11 @@ sentinel / proof / conduit / payload / SSE
 
 Only ChatGPT runtime concerns belong in this package. Zero Core, MCP, Agent orchestration, devices, task routing, and adapter layers stay outside it.
 
+## Surface scope
+
+Only the normal ChatGPT Chat runtime is in scope. A route is eligible when it is Chat-only or when it is shared infrastructure with evidence that normal Chat uses it. Work-only and Codex-only surfaces are excluded, including routes or request variants that are only evidenced under `web_frontend=codex_webview`, `product=work_tab`, `wham`, `hermes`, `agent-deployments`, or `hosting`.
+
+Route path alone is not enough to classify a capability. Surface evidence and relevant request context are part of the contract.
 ## State
 
 Default mutable state is under `M:\Zero_ChatGPT\state`:
@@ -35,11 +40,29 @@ The state directory is the only default writer for ChatGPT runtime state.
 
 - `conversation` owns conversation lifecycle and message/stream behavior.
 - `project` owns project CRUD and project conversation grouping.
-- `connector` owns ChatGPT connector discovery, actions, refresh, and mention resolution.
+- `connector` owns ChatGPT Chat connector discovery, app metadata, system hints, actions, refresh, and mention resolution.
+- `file` owns Chat composer file reservation, file-entry creation, upload processing, and reservation finalization.
+- `memory` owns Chat memory reads used by the normal Chat surface.
+- `settings` owns normal Chat user settings and explicit user-setting mutations.
+- `share` owns normal Chat conversation share lifecycle.
 - `protocol` owns ChatGPT Web payload, Sentinel, conduit, and SSE mechanics.
 - `transport` owns HTTP, headers, retries, cooldown, and session-cookie persistence.
 - `session` owns ChatGPT session acquisition/exchange; it has no implicit browser/CDP transport.
 
+## Interrupted stream recovery
+
+conversation is the only owner of stream diagnosis and repair. Callers request an operation or retry a frozen operation; they do not choose stream_status, offsets, resume tokens, or resume endpoints.
+
+1. A normal persisted send is demand-driven. There is no background stream-status polling.
+2. If the response stream ends before terminal completion, the conversation owner records the observed conversation id, acknowledged offset, server-issued continuation token when present, turn trace, parent node, and observed current node.
+3. The owner performs at most one status diagnosis for that interruption.
+4. COMPLETE, IS_STOP_REQUESTED, and UNAVAILABLE move to canonical-state verification; they do not replay the user prompt.
+5. FAILURE is terminal for that retry attempt.
+6. IS_STREAMING may perform at most one resume request and only with a server-issued continuation token. Tokenless resume is never guessed.
+7. If resume or verification still cannot finish, the checkpoint remains frozen. A new send to that conversation is rejected until the frozen operation is resolved.
+8. conversation.retry(id) is the owner-level recovery capability. It continues from the saved phase/cursor and never resubmits the original prompt.
+9. The checkpoint is removed only after canonical conversation state proves that the current node advanced beyond the saved parent node.
+
 ## Invariants
 
 1. Direct transport is the only conversation transport.
@@ -48,4 +71,7 @@ The state directory is the only default writer for ChatGPT runtime state.
 4. Secrets are never embedded in source or diagnostics.
 5. External ChatGPT responses are validated before state mutation.
 6. This package owns only ChatGPT runtime state.
-7. No Zero Core, MCP, Agent, device, task, or adapter implementation lives here.
+7. No Zero Core, MCP, Agent, device, task, or adapter implementation lives here.
+8. No background polling or hidden retry loop is allowed; recovery work occurs only on the active demand or an explicit retry demand.
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miruzero/zgpt",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "commonjs",
   "main": "src/index.js",
   "bin": {

package/src/auth/index.js

@@ -1,87 +1,114 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const paths = require('../config/paths');
-
-const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
-const writeJson = (file, value) => { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 }); };
-const tokenExpiry = (token) => {
-  try {
-    const payload = JSON.parse(Buffer.from(String(token).split('.')[1], 'base64url').toString('utf8'));
-    return Number.isFinite(payload.exp) ? new Date(payload.exp * 1000).toISOString() : null;
-  } catch { return null; }
-};
-const isExpired = (expires) => { const at = Date.parse(expires || ''); return Number.isFinite(at) && at <= Date.now(); };
-const rawFromEnv = (env) => {
-  const token = typeof env.ZERO_CHATGPT_ACCESS_TOKEN === 'string' ? env.ZERO_CHATGPT_ACCESS_TOKEN.trim() : '';
-  if (!token) return null;
-  return { tokenName: 'env', accessToken: token, expires: tokenExpiry(token), source: 'env' };
-};
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require('../config/paths');
+
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+const writeJson = (file, value) => { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 }); };
+const tokenExpiry = (token) => {
+  try {
+    const payload = JSON.parse(Buffer.from(String(token).split('.')[1], 'base64url').toString('utf8'));
+    return Number.isFinite(payload.exp) ? new Date(payload.exp * 1000).toISOString() : null;
+  } catch { return null; }
+};
+const isExpired = (expires) => { const at = Date.parse(expires || ''); return Number.isFinite(at) && at <= Date.now(); };
+const rawFromEnv = (env) => {
+  const token = typeof env.ZERO_CHATGPT_ACCESS_TOKEN === 'string' ? env.ZERO_CHATGPT_ACCESS_TOKEN.trim() : '';
+  if (!token) return null;
+  return { tokenName: 'env', accessToken: token, expires: tokenExpiry(token), source: 'env' };
+};
 exports.file = (env = process.env) => paths.authFile(env);
 
-const rawFromFile = (env) => {
-  const file = paths.authFile(env);
-  const data = readJson(file);
-  if (!data || typeof data.accessToken !== 'string' || !data.accessToken) return null;
-  return { tokenName: data.tokenName || 'ACCESS', accessToken: data.accessToken, expires: data.expires || tokenExpiry(data.accessToken), updatedAt: data.updatedAt || null, source: 'file', file };
-};
-
-exports.status = ({ env = process.env } = {}) => {
-  const raw = rawFromEnv(env) || rawFromFile(env);
-  const file = paths.authFile(env);
-  if (!raw) return { present: false, status: fs.existsSync(file) ? 'invalid' : 'missing', redacted: true, source: 'none', file };
-  return { present: true, status: isExpired(raw.expires) ? 'expired' : 'valid', redacted: true, source: raw.source, tokenName: raw.tokenName, expires: raw.expires || null, updatedAt: raw.updatedAt || null, file: raw.file || null };
-};
-
-exports.importSession = ({ body, env = process.env, source = 'session' } = {}) => {
-  const accessToken = body?.accessToken || body?.access_token;
-  if (!accessToken || typeof accessToken !== 'string') {
-    throw Object.assign(new Error('ChatGPT session did not provide an access token'), { code: 'AUTH_REQUIRED' });
-  }
-  const expires = body?.expires || body?.expires_at || tokenExpiry(accessToken);
-  const value = {
-    tokenName: 'ACCESS',
-    accessToken,
-    expires: expires || null,
-    updatedAt: new Date().toISOString(),
-    source
-  };
-  writeJson(paths.authFile(env), value);
-  return {
-    present: true,
-    status: isExpired(value.expires) ? 'expired' : 'valid',
-    redacted: true,
-    source,
-    tokenName: value.tokenName,
-    expires: value.expires,
-    updatedAt: value.updatedAt,
-    file: paths.authFile(env)
-  };
-};
-
-exports.refresh = async ({ env = process.env, acquireSession } = {}) => {
-  const flow = typeof acquireSession === 'function' ? acquireSession : require('../session').acquire;
-  const result = await flow({ env });
-  const body = result?.body ?? result;
-  const accessToken = body?.accessToken || body?.access_token;
-  if (!accessToken || typeof accessToken !== 'string') throw Object.assign(new Error('ChatGPT session did not provide an access token'), { code: 'AUTH_REQUIRED' });
-  const value = {
-    tokenName: 'ACCESS',
-    accessToken,
-    expires: body?.expires || body?.expires_at || tokenExpiry(accessToken),
-    updatedAt: new Date().toISOString()
-  };
-  writeJson(paths.authFile(env), value);
-  return { ...value, source: 'session' };
-};
-
-exports.ensure = async ({ env = process.env, acquireSession } = {}) => {
-  const envAuth = rawFromEnv(env);
-  if (envAuth && !isExpired(envAuth.expires)) return envAuth;
-  const fileAuth = rawFromFile(env);
-  if (fileAuth && !isExpired(fileAuth.expires)) return fileAuth;
-  if (acquireSession === false) throw Object.assign(new Error('ChatGPT authentication required'), { code: 'AUTH_REQUIRED' });
-  try { return await exports.refresh({ env, ...(typeof acquireSession === 'function' ? { acquireSession } : {}) }); }
-  catch (error) { if (error?.code) throw error; throw Object.assign(new Error('ChatGPT authentication required'), { code: 'AUTH_REQUIRED', cause: error }); }
+const rawFromFile = (env) => {
+  const file = paths.authFile(env);
+  const data = readJson(file);
+  if (!data || typeof data.accessToken !== 'string' || !data.accessToken) return null;
+  return { tokenName: data.tokenName || 'ACCESS', accessToken: data.accessToken, expires: data.expires || tokenExpiry(data.accessToken), updatedAt: data.updatedAt || null, source: 'file', file };
+};
+
+exports.status = ({ env = process.env } = {}) => {
+  const raw = rawFromEnv(env) || rawFromFile(env);
+  const file = paths.authFile(env);
+  if (!raw) return { present: false, status: fs.existsSync(file) ? 'invalid' : 'missing', redacted: true, source: 'none', file };
+  return { present: true, status: isExpired(raw.expires) ? 'expired' : 'valid', redacted: true, source: raw.source, tokenName: raw.tokenName, expires: raw.expires || null, updatedAt: raw.updatedAt || null, file: raw.file || null };
+};
+
+exports.importSession = ({ body, env = process.env, source = 'session' } = {}) => {
+  const accessToken = body?.accessToken || body?.access_token;
+  if (!accessToken || typeof accessToken !== 'string') {
+    throw Object.assign(new Error('ChatGPT session did not provide an access token'), { code: 'AUTH_REQUIRED' });
+  }
+  const expires = body?.expires || body?.expires_at || tokenExpiry(accessToken);
+  const value = {
+    tokenName: 'ACCESS',
+    accessToken,
+    expires: expires || null,
+    updatedAt: new Date().toISOString(),
+    source
+  };
+  writeJson(paths.authFile(env), value);
+  return {
+    present: true,
+    status: isExpired(value.expires) ? 'expired' : 'valid',
+    redacted: true,
+    source,
+    tokenName: value.tokenName,
+    expires: value.expires,
+    updatedAt: value.updatedAt,
+    file: paths.authFile(env)
+  };
+};
+
+exports.refresh = async ({ env = process.env, acquireSession, fresh = false } = {}) => {
+  const flow = typeof acquireSession === 'function' ? acquireSession : require('../session').acquire;
+  const result = await flow({ env, fresh });
+  const body = result?.body ?? result;
+  const accessToken = body?.accessToken || body?.access_token;
+  if (!accessToken || typeof accessToken !== 'string') throw Object.assign(new Error('ChatGPT session did not provide an access token'), { code: 'AUTH_REQUIRED' });
+  const value = {
+    tokenName: 'ACCESS',
+    accessToken,
+    expires: body?.expires || body?.expires_at || tokenExpiry(accessToken),
+    updatedAt: new Date().toISOString()
+  };
+  writeJson(paths.authFile(env), value);
+  return { ...value, source: 'session' };
+};
+
+exports.login = async ({ env = process.env, acquireSession } = {}) => {
+  await exports.refresh({ env, fresh: true, ...(typeof acquireSession === 'function' ? { acquireSession } : {}) });
+  return exports.status({ env });
+};
+
+exports.logout = ({ env = process.env } = {}) => {
+  const authFile = paths.authFile(env);
+  const sessionFile = paths.sessionFile(env);
+  const remove = (file) => {
+    const existed = fs.existsSync(file);
+    if (existed) fs.rmSync(file, { force: true });
+    return existed;
+  };
+  const authRemoved = remove(authFile);
+  const sessionRemoved = remove(sessionFile);
+  const envOverridePresent = typeof env.ZERO_CHATGPT_ACCESS_TOKEN === 'string' && Boolean(env.ZERO_CHATGPT_ACCESS_TOKEN.trim());
+  return {
+    status: envOverridePresent ? 'env-active' : 'logged-out',
+    redacted: true,
+    authRemoved,
+    sessionRemoved,
+    envOverridePresent
+  };
+};
+exports.ensure = async ({ env = process.env, acquireSession } = {}) => {
+  const envAuth = rawFromEnv(env);
+  if (envAuth && !isExpired(envAuth.expires)) return envAuth;
+  const fileAuth = rawFromFile(env);
+  if (fileAuth && !isExpired(fileAuth.expires)) return fileAuth;
+  if (fileAuth && isExpired(fileAuth.expires)) {
+    try { fs.rmSync(paths.authFile(env), { force: true }); } catch {}
+  }
+  if (acquireSession === false) throw Object.assign(new Error('ChatGPT authentication required'), { code: 'AUTH_REQUIRED' });
+  try { return await exports.refresh({ env, ...(typeof acquireSession === 'function' ? { acquireSession } : {}) }); }
+  catch (error) { if (error?.code) throw error; throw Object.assign(new Error('ChatGPT authentication required'), { code: 'AUTH_REQUIRED', cause: error }); }
 };

package/src/cli/conversations-tui.js

@@ -0,0 +1,301 @@
+'use strict';
+
+const readline = require('node:readline');
+
+const ESC = '\u001b[';
+const H = '\u2500';
+const TL = '\u256d';
+const TR = '\u256e';
+const BL = '\u2570';
+const BR = '\u256f';
+const V = '\u2502';
+const ELLIPSIS = '\u2026';
+
+const MAX_PANEL_WIDTH = 108;
+const MIN_PANEL_WIDTH = 72;
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+const clean = (value) => String(value ?? '-').replace(/[\r\n\t]+/g, ' ');
+const isWide = (ch) => {
+  if (/\p{Extended_Pictographic}/u.test(ch)) return true;
+  const cp = ch.codePointAt(0);
+  return cp >= 0x1100 && (
+    cp <= 0x115f || cp === 0x2329 || cp === 0x232a
+    || (cp >= 0x2e80 && cp <= 0xa4cf)
+    || (cp >= 0xac00 && cp <= 0xd7a3)
+    || (cp >= 0xf900 && cp <= 0xfaff)
+    || (cp >= 0xfe10 && cp <= 0xfe6f)
+    || (cp >= 0xff01 && cp <= 0xff60)
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+    || (cp >= 0x20000 && cp <= 0x3fffd)
+  );
+};
+const charWidth = (ch) => {
+  const cp = ch.codePointAt(0);
+  if (/\p{Mark}/u.test(ch) || cp === 0x200d || (cp >= 0xfe00 && cp <= 0xfe0f)) return 0;
+  if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0)) return 0;
+  return isWide(ch) ? 2 : 1;
+};
+const textWidth = (value) => Array.from(clean(value)).reduce((sum, ch) => sum + charWidth(ch), 0);
+
+const fit = (value, width) => {
+  const text = clean(value);
+  if (width <= 0) return '';
+  if (textWidth(text) <= width) return text + ' '.repeat(width - textWidth(text));
+  let out = '';
+  let used = 0;
+  const limit = Math.max(1, width - 1);
+  for (const ch of Array.from(text)) {
+    const step = charWidth(ch);
+    if (used + step > limit) break;
+    out += ch;
+    used += step;
+  }
+  out += ELLIPSIS;
+  return out + ' '.repeat(Math.max(0, width - textWidth(out)));
+};
+
+const idOf = (item) => item?.id || item?.conversation_id || '-';
+const projectOf = (item) => item?.gizmo_id || item?.conversation_template_id || '-';
+const titleOf = (item) => item?.title || '(untitled)';
+const updatedOf = (item) => {
+  const raw = item?.update_time;
+  if (raw == null) return '-';
+  if (typeof raw === 'number') {
+    const milliseconds = raw < 10_000_000_000 ? raw * 1000 : raw;
+    const date = new Date(milliseconds);
+    if (!Number.isNaN(date.getTime())) return date.toISOString().replace('T', ' ').slice(0, 16);
+  }
+  return String(raw).replace('T', ' ').replace(/Z$/, '').slice(0, 16);
+};
+
+const panelWidth = (state) => {
+  const terminal = Math.max(40, Number(state?.width) || 120);
+  return Math.min(MAX_PANEL_WIDTH, Math.max(Math.min(MIN_PANEL_WIDTH, terminal - 2), terminal - 6));
+};
+
+const marginFor = (state, width) => ' '.repeat(Math.max(0, Math.floor(((Number(state?.width) || width) - width) / 2)));
+const boxed = (margin, inner, width) => `${margin}${V} ${fit(inner, width - 4)} ${V}`;
+const topBorder = (margin, width) => `${margin}${TL}${H.repeat(width - 2)}${TR}`;
+const bottomBorder = (margin, width) => `${margin}${BL}${H.repeat(width - 2)}${BR}`;
+
+exports.createState = (items = [], size = {}) => ({
+  items: Array.isArray(items) ? [...items] : [],
+  index: 0,
+  search: '',
+  searchMode: false,
+  view: 'list',
+  detailText: '',
+  detailOffset: 0,
+  status: '',
+  width: Math.max(40, Number(size.width) || 120),
+  height: Math.max(10, Number(size.height) || 30)
+});
+
+exports.visibleItems = (state) => {
+  const query = String(state?.search || '').trim().toLowerCase();
+  if (!query) return state.items;
+  return state.items.filter((item) => [idOf(item), titleOf(item), projectOf(item)]
+    .some((value) => String(value).toLowerCase().includes(query)));
+};
+
+exports.selected = (state) => {
+  const items = exports.visibleItems(state);
+  if (!items.length) return null;
+  return items[clamp(state.index, 0, items.length - 1)] || null;
+};
+
+exports.reduce = (state, key = {}) => {
+  const next = { ...state };
+  if (next.view === 'detail') {
+    if (key.name === 'escape') { next.view = 'list'; next.detailText = ''; next.detailOffset = 0; }
+    else if (key.name === 'down' || key.sequence === 'j') next.detailOffset += 1;
+    else if (key.name === 'up' || key.sequence === 'k') next.detailOffset = Math.max(0, next.detailOffset - 1);
+    return next;
+  }
+  if (next.searchMode) {
+    if (key.name === 'escape' || key.name === 'return') next.searchMode = false;
+    else if (key.name === 'backspace') next.search = Array.from(next.search).slice(0, -1).join('');
+    else if (key.ctrl && key.name === 'u') next.search = '';
+    else if (!key.ctrl && !key.meta && typeof key.sequence === 'string' && key.sequence.length === 1 && key.sequence >= ' ') next.search += key.sequence;
+    next.index = 0;
+    return next;
+  }
+  const count = exports.visibleItems(next).length;
+  if (key.name === 'down' || key.sequence === 'j') next.index = clamp(next.index + 1, 0, Math.max(0, count - 1));
+  else if (key.name === 'up' || key.sequence === 'k') next.index = clamp(next.index - 1, 0, Math.max(0, count - 1));
+  else if (key.name === 'home' || (key.sequence === 'g' && !key.shift)) next.index = 0;
+  else if (key.name === 'end' || key.sequence === 'G' || (key.name === 'g' && key.shift)) next.index = Math.max(0, count - 1);
+  else if (key.sequence === '/') next.searchMode = true;
+  else if (key.name === 'escape' && next.search) { next.search = ''; next.index = 0; }
+  return next;
+};
+
+const layout = (state) => {
+  const width = panelWidth(state);
+  const inner = width - 4;
+  const fixed = 2 + 16 + 2 + 14 + 2 + 14 + 2;
+  const title = Math.max(18, inner - fixed);
+  return { width, inner, title, updated: 16, project: 14, id: 14 };
+};
+
+const renderList = (state) => {
+  const items = exports.visibleItems(state);
+  const selectedIndex = items.length ? clamp(state.index, 0, items.length - 1) : 0;
+  const { width, inner, title, updated, project, id } = layout(state);
+  const margin = marginFor(state, width);
+  const fixedRows = 8 + (state.status ? 1 : 0);
+  const maxRows = Math.max(1, Math.min(14, state.height - fixedRows));
+  const start = clamp(selectedIndex - Math.floor(maxRows / 2), 0, Math.max(0, items.length - maxRows));
+  const end = Math.min(items.length, start + maxRows);
+  const countText = items.length === state.items.length ? `${items.length}` : `${items.length}/${state.items.length}`;
+  const header = `Zero ChatGPT  \u00b7  Conversations ${countText}`;
+  const search = state.searchMode
+    ? `\u203a ${state.search || 'Search conversations\u2026'}`
+    : state.search
+      ? `Search: ${state.search}`
+      : 'Press / to search conversations';
+
+  const lines = [
+    topBorder(margin, width),
+    boxed(margin, header, width),
+    boxed(margin, search, width),
+    boxed(margin, H.repeat(inner), width),
+    boxed(margin, `  ${fit('Title', title)}  ${fit('Updated', updated)}  ${fit('Project', project)}  ${fit('ID', id)}`, width)
+  ];
+
+  if (!items.length) {
+    lines.push(boxed(margin, '  No conversations match the current search.', width));
+  } else {
+    for (let index = start; index < end; index += 1) {
+      const item = items[index];
+      const cursor = index === selectedIndex ? '>' : ' ';
+      const row = `${cursor} ${fit(titleOf(item), title)}  ${fit(updatedOf(item), updated)}  ${fit(projectOf(item), project)}  ${fit(idOf(item), id)}`;
+      lines.push(boxed(margin, row, width));
+    }
+  }
+
+  if (state.status) lines.push(boxed(margin, state.status, width));
+  lines.push(
+    boxed(margin, H.repeat(inner), width),
+    boxed(margin, '\u2191\u2193/jk Move   Enter Open   / Search   r Refresh   q Quit', width),
+    bottomBorder(margin, width)
+  );
+
+  const available = Math.max(0, state.height - lines.length);
+  const topPad = Math.min(3, Math.max(0, Math.floor(available / 3)));
+  return [...Array(topPad).fill(''), ...lines].join('\n');
+};
+
+const renderDetail = (state) => {
+  const width = panelWidth(state);
+  const margin = marginFor(state, width);
+  const inner = width - 4;
+  const bodyRows = Math.max(1, Math.min(18, state.height - 6));
+  const source = String(state.detailText || '').split(/\r\n?/);
+  const maxOffset = Math.max(0, source.length - bodyRows);
+  const offset = clamp(state.detailOffset, 0, maxOffset);
+  const lines = [
+    topBorder(margin, width),
+    boxed(margin, `Zero ChatGPT  \u00b7  Conversation${state.status ? `  \u00b7  ${state.status}` : ''}`, width),
+    boxed(margin, H.repeat(inner), width),
+    ...source.slice(offset, offset + bodyRows).map((line) => boxed(margin, line, width)),
+    boxed(margin, H.repeat(inner), width),
+    boxed(margin, '\u2191\u2193/jk Scroll   Esc Back   q Quit', width),
+    bottomBorder(margin, width)
+  ];
+  return lines.join('\n');
+};
+
+exports.render = (state) => state.view === 'detail' ? renderDetail(state) : renderList(state);
+
+exports.run = ({
+  items = [], loadItems, openConversation, formatConversation,
+  input = process.stdin, output = process.stdout
+} = {}) => {
+  let state = exports.createState(items, { width: output.columns, height: output.rows });
+  if (!input?.isTTY || !output?.isTTY) {
+    output.write(`${exports.render(state)}\n`);
+    return Promise.resolve(0);
+  }
+
+  readline.emitKeypressEvents(input);
+  input.setRawMode?.(true);
+  input.resume?.();
+  output.write(`${ESC}?1049h${ESC}?25l`);
+
+  let busy = false;
+  let finished = false;
+  let resolveRun;
+  const result = new Promise((resolve) => { resolveRun = resolve; });
+  const syncSize = () => {
+    state.width = Math.max(40, Number(output.columns) || state.width);
+    state.height = Math.max(10, Number(output.rows) || state.height);
+  };
+  const draw = () => {
+    syncSize();
+    output.write(`${ESC}2J${ESC}H${exports.render(state)}`);
+  };
+  const onResize = () => { if (!finished) draw(); };
+
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    input.removeListener('keypress', onKey);
+    output.removeListener?.('resize', onResize);
+    input.setRawMode?.(false);
+    input.pause?.();
+    output.write(`${ESC}?25h${ESC}?1049l`);
+    resolveRun(0);
+  };
+
+  const onKey = async (_value, key = {}) => {
+    if (finished) return;
+    if ((key.ctrl && key.name === 'c') || (!state.searchMode && (key.name === 'q' || key.sequence === 'q'))) return finish();
+    if (state.searchMode) { state = exports.reduce(state, key); draw(); return; }
+
+    if (key.name === 'r' || key.sequence === 'r') {
+      if (busy || typeof loadItems !== 'function') return;
+      busy = true;
+      state.status = 'Refreshing\u2026';
+      draw();
+      try {
+        const fresh = await loadItems();
+        const search = state.search;
+        state = exports.createState(fresh, { width: output.columns, height: output.rows });
+        state.search = search;
+        state.status = `Refreshed ${state.items.length}`;
+      } catch (error) {
+        state.status = `Refresh failed: ${error?.code || error?.message || error}`;
+      } finally { busy = false; draw(); }
+      return;
+    }
+
+    if ((key.name === 'return' || key.name === 'enter') && state.view === 'list') {
+      const item = exports.selected(state);
+      if (!item || busy || typeof openConversation !== 'function') return;
+      busy = true;
+      state.status = 'Opening\u2026';
+      draw();
+      try {
+        const conversation = await openConversation(idOf(item));
+        state.view = 'detail';
+        state.detailText = typeof formatConversation === 'function' ? formatConversation(conversation) : JSON.stringify(conversation, null, 2);
+        state.detailOffset = 0;
+        state.status = '';
+      } catch (error) {
+        state.status = `Open failed: ${error?.code || error?.message || error}`;
+      } finally { busy = false; draw(); }
+      return;
+    }
+
+    state = exports.reduce(state, key);
+    state.width = Math.max(40, Number(output.columns) || state.width);
+    state.height = Math.max(10, Number(output.rows) || state.height);
+    draw();
+  };
+
+  input.on('keypress', onKey);
+  output.on?.('resize', onResize);
+  draw();
+  return result;
+};

package/src/cli/formatter.js

@@ -108,4 +108,42 @@ exports.markdown = (conversation, options = {}) => {
   return `${lines.join('\n').trimEnd()}\n`;
 };
 
-exports.json = (conversation) => `${JSON.stringify(conversation, null, 2)}\n`;
+exports.json = (conversation) => `${JSON.stringify(conversation, null, 2)}\n`;
+const terminalWidth = (value) => Array.from(String(value ?? '')).reduce((width, ch) => width + (/\p{Mark}/u.test(ch) ? 0 : 1), 0);
+const fitTerminalCell = (value, width) => {
+  const text = String(value ?? '-').replace(/[\r\n\t]+/g, ' ');
+  let out = '';
+  let used = 0;
+  for (const ch of Array.from(text)) {
+    const step = /\p{Mark}/u.test(ch) ? 0 : 1;
+    if (used + step > width) break;
+    out += ch;
+    used += step;
+  }
+  if (terminalWidth(text) > width && width > 1) {
+    while (terminalWidth(out) >= width) out = Array.from(out).slice(0, -1).join('');
+    out += '\u2026';
+    used = terminalWidth(out);
+  }
+  return out + ' '.repeat(Math.max(0, width - used));
+};
+
+exports.conversationsTable = (items = []) => {
+  const rows = Array.isArray(items) ? items : [];
+  const widths = [36, 38, 20, 18];
+  const top = '\u250c' + widths.map((w) => '\u2500'.repeat(w + 2)).join('\u252c') + '\u2510';
+  const mid = '\u251c' + widths.map((w) => '\u2500'.repeat(w + 2)).join('\u253c') + '\u2524';
+  const bottom = '\u2514' + widths.map((w) => '\u2500'.repeat(w + 2)).join('\u2534') + '\u2518';
+  const row = (cells) => '\u2502 ' + cells.map((cell, i) => fitTerminalCell(cell, widths[i])).join(' \u2502 ') + ' \u2502';
+  const lines = [`Conversations (${rows.length})`, top, row(['ID', 'Title', 'Updated', 'Project']), mid];
+  for (const item of rows) {
+    lines.push(row([
+      item?.id || item?.conversation_id || '-',
+      item?.title || '(untitled)',
+      item?.update_time ?? '-',
+      item?.gizmo_id || item?.conversation_template_id || '-'
+    ]));
+  }
+  lines.push(bottom);
+  return `${lines.join('\n')}\n`;
+};