@miruzero/zgpt 0.1.0 → 0.1.1

package/src/cli.js

@@ -1,117 +1,181 @@
 #!/usr/bin/env node
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const formatter = require('./cli/formatter');
-
-const usage = () => [
-  'Zero ChatGPT CLI',
-  '',
-  'Usage:',
-  '  zgpt get <conversation-id> [--limit N|A-B] [--debug|--json]',
-  '  zgpt export <conversation-id> [--limit N|A-B] [--debug|--json] [--out <path>]',
-  '  zgpt help'
-].join('\n');
-
-const parseOptions = (argv) => {
-  const result = { json: false, debug: false, limit: null, out: null };
-  for (let index = 2; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === '--json' || arg === 'json') result.json = true;
-    else if (arg === '--debug' || arg === 'debug') result.debug = true;
-    else if (arg === '--limit' || arg === 'limit') {
-      const value = argv[++index];
-      result.limit = formatter.parseLimitSpec(value);
-      if (!result.limit) throw new Error(`Invalid limit: ${value || '(missing)'}`);
-    } else if (arg === '--out' || arg === 'out') {
-      result.out = argv[++index] || null;
-      if (!result.out) throw new Error('Export path is required after --out');
-    } else throw new Error(`Unknown option: ${arg}`);
-  }
-  if (result.json && result.debug) throw new Error('--json and --debug are mutually exclusive');
-  return result;
-};
-
-const defaultExportPath = (conversationId, options, cwd) => {
-  const safeId = String(conversationId).replace(/[^a-zA-Z0-9._-]/g, '_');
-  const suffix = options.json ? '.json' : options.debug ? '.debug.md' : '.md';
-  return path.join(cwd, 'exports', `conversation-${safeId}${suffix}`);
-};
-
-exports.run = async (argv = [], options = {}) => {
-  const stdout = options.stdout || console.log;
-  const stderr = options.stderr || console.error;
-  const command = argv[0] || 'help';
-  if (command === 'help' || command === '--help' || command === '-h') {
-    stdout(usage());
-    return 0;
-  }
-  if (!['get', 'export', 'stream-status', 'resume'].includes(command)) {
-    stderr(`Unknown command: ${command}\n\n${usage()}`);
-    return 2;
-  }
-  const conversationId = argv[1];
-  if (!conversationId) {
-    stderr(`Conversation id is required.\n\n${usage()}`);
-    return 2;
-  }
-
-  let parsed = null;
-  if (command === 'get' || command === 'export') {
-    try { parsed = parseOptions(argv); }
-    catch (error) {
-      stderr(`${error.message}\n\n${usage()}`);
-      return 2;
-    }
-  } else if (argv.length !== 2) {
-    stderr(`Unknown option for ${command}\n\n${usage()}`);
-    return 2;
-  }
-
-  try {
-    const runtime = options.runtime || require('./index');
-    if (command === 'stream-status') {
-      const state = await runtime.conversation.streamStatus(conversationId);
-      stdout(`status=${state?.status || '-'}\nconversation_id=${state?.conversation_id || conversationId}`);
-      return 0;
-    }
-    if (command === 'resume') {
-      const state = await runtime.conversation.streamStatus(conversationId);
-      if (state?.status !== 'IS_STREAMING') {
-        stdout(`status=${state?.status || '-'}\nconversation_id=${conversationId}\nresume=SKIPPED`);
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const formatter = require('./cli/formatter');
+
+const usage = () => [
+  'Zero ChatGPT CLI',
+  '',
+  'Usage:',
+  '  zgpt login',
+  '  zgpt logout',
+  '  zgpt auth-status',
+  '  zgpt conversations list [--json]',
+  '  zgpt retry <conversation-id>',
+  '  zgpt get <conversation-id> [--limit N|A-B] [--debug|--json]',
+  '  zgpt export <conversation-id> [--limit N|A-B] [--debug|--json] [--out <path>]',
+  '  zgpt help'
+].join('\n');
+
+const parseOptions = (argv) => {
+  const result = { json: false, debug: false, limit: null, out: null };
+  for (let index = 2; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json' || arg === 'json') result.json = true;
+    else if (arg === '--debug' || arg === 'debug') result.debug = true;
+    else if (arg === '--limit' || arg === 'limit') {
+      const value = argv[++index];
+      result.limit = formatter.parseLimitSpec(value);
+      if (!result.limit) throw new Error(`Invalid limit: ${value || '(missing)'}`);
+    } else if (arg === '--out' || arg === 'out') {
+      result.out = argv[++index] || null;
+      if (!result.out) throw new Error('Export path is required after --out');
+    } else throw new Error(`Unknown option: ${arg}`);
+  }
+  if (result.json && result.debug) throw new Error('--json and --debug are mutually exclusive');
+  return result;
+};
+
+const defaultExportPath = (conversationId, options, cwd) => {
+  const safeId = String(conversationId).replace(/[^a-zA-Z0-9._-]/g, '_');
+  const suffix = options.json ? '.json' : options.debug ? '.debug.md' : '.md';
+  return path.join(cwd, 'exports', `conversation-${safeId}${suffix}`);
+};
+
+exports.run = async (argv = [], options = {}) => {
+  const stdout = options.stdout || console.log;
+  const stderr = options.stderr || console.error;
+  const command = argv[0] || 'help';
+  if (command === 'help' || command === '--help' || command === '-h') {
+    stdout(usage());
+    return 0;
+  }
+  if (!['login', 'logout', 'auth-status', 'conversations', 'get', 'export', 'stream-status', 'retry', 'resume'].includes(command)) {
+    stderr(`Unknown command: ${command}\n\n${usage()}`);
+    return 2;
+  }
+  if (command === 'login' || command === 'logout' || command === 'auth-status') {
+    if (argv.length !== 1) {
+      stderr(`Unknown option for ${command}\n\n${usage()}`);
+      return 2;
+    }
+    try {
+      const runtime = options.runtime || require('./index');
+      if (command === 'login') {
+        let state;
+        if (typeof runtime.auth.login === 'function') state = await runtime.auth.login();
+        else {
+          await runtime.auth.ensure();
+          state = runtime.auth.status();
+        }
+        stdout(`status=${state?.status || '-'}\nredacted=${state?.redacted !== false}\nsource=${state?.source || '-'}\nexpires=${state?.expires || '-'}`);
+        return 0;
+      }
+      if (command === 'auth-status') {
+        const state = runtime.auth.status();
+        stdout(`status=${state?.status || '-'}\nredacted=${state?.redacted !== false}\nsource=${state?.source || '-'}\nexpires=${state?.expires || '-'}`);
+        return 0;
+      }
+      const state = await runtime.auth.logout();
+      stdout(`status=${state?.status || '-'}\nauth_removed=${Boolean(state?.authRemoved)}\nsession_removed=${Boolean(state?.sessionRemoved)}`);
+      return 0;
+    } catch (error) {
+      stderr(`${error?.code ? `${error.code}: ` : ''}${error?.message || String(error)}`);
+      return 1;
+    }
+  }
+  if (command === 'conversations') {
+    if (argv[1] !== 'list') {
+      stderr(`Usage: zgpt conversations list [--json]\n\n${usage()}`);
+      return 2;
+    }
+    let json = false;
+    for (let index = 2; index < argv.length; index += 1) {
+      const arg = argv[index];
+      if (arg === '--json' || arg === 'json') json = true;
+      else {
+        stderr(`Unknown option for conversations list: ${arg}\n\n${usage()}`);
+        return 2;
+      }
+    }
+    try {
+      const runtime = options.runtime || require('./index');
+      const items = await runtime.conversation.list();
+      if (json) {
+        stdout(formatter.json(items).trimEnd());
         return 0;
       }
-      const resumed = await runtime.conversation.resume(conversationId);
-      let text = `status=${state.status}\nconversation_id=${conversationId}\nresume=OK\nhttp_status=${resumed?.status ?? '-'}\ncontent_type=${resumed?.content_type || '-'}`;
-      if (resumed?.text) text += `\n${String(resumed.text).trimEnd()}`;
-      stdout(text);
-      return 0;
-    }
-    const conversation = await runtime.conversation.get(conversationId);
-    const rendered = parsed.json
-      ? formatter.json(conversation)
-      : formatter.markdown(conversation, { debug: parsed.debug, limit: parsed.limit });
-
-    if (command === 'get') {
-      stdout(rendered.trimEnd());
+      const runTui = options.runConversationsTui || require('./cli/conversations-tui').run;
+      return await runTui({
+        items,
+        loadItems: () => runtime.conversation.list(),
+        openConversation: (id) => runtime.conversation.get(id),
+        formatConversation: (conversation) => formatter.markdown(conversation).trimEnd(),
+        input: options.stdin || process.stdin,
+        output: options.output || process.stdout
+      });
+    } catch (error) {
+      stderr(`${error?.code ? `${error.code}: ` : ''}${error?.message || String(error)}`);
+      return 1;
+    }
+  }
+
+  const conversationId = argv[1];
+  if (!conversationId) {
+    stderr(`Conversation id is required.\n\n${usage()}`);
+    return 2;
+  }
+
+  let parsed = null;
+  if (command === 'get' || command === 'export') {
+    try { parsed = parseOptions(argv); }
+    catch (error) {
+      stderr(`${error.message}\n\n${usage()}`);
+      return 2;
+    }
+  } else if (argv.length !== 2) {
+    stderr(`Unknown option for ${command}\n\n${usage()}`);
+    return 2;
+  }
+
+  try {
+    const runtime = options.runtime || require('./index');
+    if (command === 'stream-status') {
+      const state = await runtime.conversation.streamStatus(conversationId);
+      stdout(`status=${state?.status || '-'}\nconversation_id=${state?.conversation_id || conversationId}`);
+      return 0;
+    }
+    if (command === 'retry' || command === 'resume') {
+      const recovered = await runtime.conversation.retry(conversationId);
+      stdout(`status=READY\nconversation_id=${recovered?.conversation_id || recovered?.id || conversationId}\ncurrent_node=${recovered?.current_node || '-'}`);
       return 0;
-    }
-
-    const cwd = options.cwd || process.cwd();
-    const target = parsed.out
-      ? path.resolve(cwd, parsed.out)
-      : defaultExportPath(conversationId, parsed, cwd);
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, rendered, 'utf8');
-    stdout(`exported=${target}`);
-    return 0;
-  } catch (error) {
-    stderr(`${error?.code ? `${error.code}: ` : ''}${error?.message || String(error)}`);
-    return 1;
-  }
-};
-
-if (require.main === module) {
-  exports.run(process.argv.slice(2)).then((code) => { process.exitCode = code; });
-}
+    }
+    const conversation = await runtime.conversation.get(conversationId);
+    const rendered = parsed.json
+      ? formatter.json(conversation)
+      : formatter.markdown(conversation, { debug: parsed.debug, limit: parsed.limit });
+
+    if (command === 'get') {
+      stdout(rendered.trimEnd());
+      return 0;
+    }
+
+    const cwd = options.cwd || process.cwd();
+    const target = parsed.out
+      ? path.resolve(cwd, parsed.out)
+      : defaultExportPath(conversationId, parsed, cwd);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, rendered, 'utf8');
+    stdout(`exported=${target}`);
+    return 0;
+  } catch (error) {
+    stderr(`${error?.code ? `${error.code}: ` : ''}${error?.message || String(error)}`);
+    return 1;
+  }
+};
+
+if (require.main === module) {
+  exports.run(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}

package/src/config/paths.js

@@ -9,6 +9,8 @@ exports.stateDir = (env = process.env) => path.resolve(env.ZERO_CHATGPT_STATE_DI
 exports.authFile = (env = process.env) => path.resolve(env.ZERO_CHATGPT_AUTH_FILE || path.join(exports.stateDir(env), 'auth-context.json'));
 exports.sessionFile = (env = process.env) => path.resolve(env.ZERO_CHATGPT_SESSION_FILE || path.join(exports.stateDir(env), 'session-context.json'));
 exports.tempConversationFile = (env = process.env) => path.resolve(env.ZERO_CHATGPT_TEMP_STATE_FILE || path.join(exports.stateDir(env), 'temp-conversations.json'));
+exports.conversationContextFile = (env = process.env) => path.resolve(env.ZERO_CHATGPT_CONVERSATION_CONTEXT_FILE || path.join(exports.stateDir(env), 'conversation-context.json'));
+exports.conversationRecoveryFile = (env = process.env) => path.resolve(env.ZERO_CHATGPT_RECOVERY_STATE_FILE || path.join(exports.stateDir(env), 'conversation-recovery.json'));
 exports.rateLimitDir = (env = process.env) => env.ZERO_CHATGPT_RATE_LIMIT_FILE
   ? path.dirname(path.resolve(env.ZERO_CHATGPT_RATE_LIMIT_FILE))
   : exports.stateDir(env);
@@ -16,4 +18,4 @@ exports.rateLimitFile = (env = process.env, token = 'anonymous') => {
   if (env.ZERO_CHATGPT_RATE_LIMIT_FILE) return path.resolve(env.ZERO_CHATGPT_RATE_LIMIT_FILE);
   const key = crypto.createHash('sha256').update(String(token || 'anonymous')).digest('hex').slice(0, 16);
   return path.join(exports.rateLimitDir(env), `rate-limit-${key}.json`);
-};
+};

package/src/connector/read.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const direct = require('../transport/direct/http-client');
+const context = require('../runtime-context');
 
 const requireOk = (response, target) => {
   if (!response || response.status !== 200 || !response.json) {
@@ -14,9 +15,11 @@ const requireOk = (response, target) => {
   return response.json;
 };
 
-exports.listConnectors = async ({ token, sessionHeaders, requestJson = direct.requestJson }) => {
+exports.listConnectors = async (options = {}) => {
+  options = await context.bind(options);
+  const requestJson = options.requestJson || direct.requestJson;
   const target = '/backend-api/ps/plugins/installed?limit=1000';
-  const raw = requireOk(await requestJson(target, token, sessionHeaders, { route: '/backend-api/ps/plugins/installed', headers: { connection: 'close' } }), target);
+  const raw = requireOk(await requestJson(target, options.token, options.sessionHeaders, { route: '/backend-api/ps/plugins/installed', headers: { connection: 'close' } }), target);
   const plugins = Array.isArray(raw?.plugins) ? raw.plugins : [];
   return plugins.map((plugin) => ({
     id: plugin?.id || null,
@@ -29,10 +32,13 @@ exports.listConnectors = async ({ token, sessionHeaders, requestJson = direct.re
   }));
 };
 
-exports.getConnectorActions = async ({ appId, token, sessionHeaders, requestJson = direct.requestJson }) => {
+exports.getConnectorActions = async (options = {}) => {
+  options = await context.bind(options);
+  const { appId } = options;
   if (!appId || typeof appId !== 'string') throw Object.assign(new Error('appId is required'), { code: 'BAD_ARGS' });
+  const requestJson = options.requestJson || direct.requestJson;
   const target = `/backend-api/aip/connectors/${encodeURIComponent(appId)}/actions`;
-  return requireOk(await requestJson(target, token, sessionHeaders, { route: '/backend-api/aip/connectors/{app_id}/actions', headers: { connection: 'close' } }), target);
+  return requireOk(await requestJson(target, options.token, options.sessionHeaders, { route: '/backend-api/aip/connectors/{app_id}/actions', headers: { connection: 'close' } }), target);
 };
 
 exports.resolveSystemHintSelections = async ({ message, token, sessionHeaders, listConnectors = exports.listConnectors }) => {
@@ -53,4 +59,22 @@ exports.resolveSystemHintSelections = async ({ message, token, sessionHeaders, l
     }
   }
   return { systemHints: [...hints], systemHintMentions };
+};
+
+exports.getSystemHints = async (options = {}) => {
+  options = await context.bind(options);
+  const normalizedMode = String(options.mode || 'plugins').trim();
+  if (!normalizedMode) throw Object.assign(new Error('mode is required'), { code: 'BAD_ARGS' });
+  const requestJson = options.requestJson || direct.requestJson;
+  const target = `/backend-api/system_hints?mode=${encodeURIComponent(normalizedMode)}`;
+  return requireOk(await requestJson(target, options.token, options.sessionHeaders, { route: '/backend-api/system_hints', headers: { connection: 'close' } }), target);
+};
+
+exports.getCanonicalApp = async (options = {}) => {
+  options = await context.bind(options);
+  const { appId } = options;
+  if (!appId || typeof appId !== 'string') throw Object.assign(new Error('appId is required'), { code: 'BAD_ARGS' });
+  const requestJson = options.requestJson || direct.requestJson;
+  const target = `/backend-api/ps/plugins/canonical-app/${encodeURIComponent(appId)}`;
+  return requireOk(await requestJson(target, options.token, options.sessionHeaders, { route: '/backend-api/ps/plugins/canonical-app/{app_id}', headers: { connection: 'close' } }), target);
 };

package/src/connector/write.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const direct = require('../transport/direct/http-client');
+const context = require('../runtime-context');
 
 const requireSuccess = (response, target) => {
   if (!response || response.status < 200 || response.status >= 300) {
@@ -14,13 +15,12 @@ const requireSuccess = (response, target) => {
   return response.json || { success: true };
 };
 
-exports.refreshConnectorActions = async ({ linkId, token, sessionHeaders, requestJson = direct.requestJson }) => {
-  if (!linkId || typeof linkId !== 'string') throw Object.assign(new Error('linkId is required'), { code: 'BAD_ARGS' });
+exports.refreshConnectorActions = async (options = {}) => {
+  options = await context.bind(options);
+  if (!options.linkId || typeof options.linkId !== 'string') throw Object.assign(new Error('linkId is required'), { code: 'BAD_ARGS' });
   const target = '/backend-api/aip/connectors/mcp/refresh_actions';
-  return requireSuccess(await requestJson(target, token, sessionHeaders, {
-    method: 'POST',
-    body: { link_id: linkId },
-    route: target,
-    retry: false
+  const requestJson = options.requestJson || direct.requestJson;
+  return requireSuccess(await requestJson(target, options.token, options.sessionHeaders, {
+    method: 'POST', body: { link_id: options.linkId }, route: target, retry: false
   }), target);
 };

package/src/conversation/context-config.js

@@ -0,0 +1,68 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require('../config/paths');
+
+const EMPTY = Object.freeze({
+  version: 1,
+  enabled: true,
+  attach: Object.freeze({ systemHints: [], localFunctionNames: [], systemPrompts: [] })
+});
+
+const strings = (value, name) => {
+  if (value == null) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw Object.assign(new TypeError(`${name} must be an array of strings`), { code: 'CONTEXT_CONFIG_INVALID' });
+  }
+  return [...new Set(value.map((item) => item.trim()).filter(Boolean))];
+};
+
+const normalize = (input = {}) => {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw Object.assign(new TypeError('conversation context config must be an object'), { code: 'CONTEXT_CONFIG_INVALID' });
+  }
+  const attach = input.attach == null ? {} : input.attach;
+  if (!attach || typeof attach !== 'object' || Array.isArray(attach)) {
+    throw Object.assign(new TypeError('attach must be an object'), { code: 'CONTEXT_CONFIG_INVALID' });
+  }
+  return {
+    version: 1,
+    enabled: input.enabled !== false,
+    attach: {
+      systemHints: strings(attach.systemHints, 'attach.systemHints'),
+      localFunctionNames: strings(attach.localFunctionNames, 'attach.localFunctionNames'),
+      systemPrompts: strings(attach.systemPrompts, 'attach.systemPrompts')
+    }
+  };
+};
+
+exports.get = ({ env = process.env } = {}) => {
+  const file = paths.conversationContextFile(env);
+  if (!fs.existsSync(file)) return normalize(EMPTY);
+  try { return normalize(JSON.parse(fs.readFileSync(file, 'utf8'))); }
+  catch (error) {
+    if (error?.code === 'CONTEXT_CONFIG_INVALID') throw error;
+    throw Object.assign(new Error(`invalid conversation context config: ${file}`), { code: 'CONTEXT_CONFIG_INVALID', cause: error });
+  }
+};
+
+exports.set = (config, { env = process.env } = {}) => {
+  const normalized = normalize(config);
+  const file = paths.conversationContextFile(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(normalized, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(temp, file);
+  return normalized;
+};
+
+const merge = (base, extra) => [...new Set([...(base || []), ...(extra || [])])];
+exports.merge = ({ env = process.env, systemHints = [], localFunctionNames = [], hiddenSystemMessages = [] } = {}) => {
+  const config = exports.get({ env });
+  if (!config.enabled) return { systemHints, localFunctionNames, hiddenSystemMessages };
+  return {
+    systemHints: merge(config.attach.systemHints, systemHints),
+    localFunctionNames: merge(config.attach.localFunctionNames, localFunctionNames),
+    hiddenSystemMessages: merge(config.attach.systemPrompts, hiddenSystemMessages)
+  };
+};

package/src/conversation/index.js

@@ -6,6 +6,7 @@ const paths = require('../config/paths');
 const read = require('./read');
 const write = require('./write');
 const temporary = require('./temporary');
+const recovery = require('./recovery');
 
 const sessionHeaders = (env) => {
   const file = paths.sessionFile(env);
@@ -24,7 +25,7 @@ const bindCanonicalContext = async (options = {}) => {
   const resolved = { ...options };
   const env = resolved.env || process.env;
   if (!resolved.token) {
-    const current = await auth.ensure({ env, acquireSession: false });
+    const current = await auth.ensure({ env });
     resolved.token = current.accessToken;
   }
   if (!resolved.sessionHeaders) resolved.sessionHeaders = sessionHeaders(env);
@@ -36,6 +37,7 @@ exports.get = async (id, options = {}) => read.getConversation({
   conversationId: id,
   ...(await bindCanonicalContext(options))
 });
+exports.list = async (options = {}) => read.listStandalone(await bindCanonicalContext(options));
 exports.streamStatus = async (id, options = {}) => read.getConversationStreamStatus({
   conversationId: id,
   ...(await bindCanonicalContext(options))
@@ -44,6 +46,10 @@ exports.resume = async (id, options = {}) => read.resumeConversation({
   conversationId: id,
   ...(await bindCanonicalContext(options))
 });
+exports.retry = async (id, options = {}) => recovery.retry({
+  conversationId: id,
+  ...(await bindCanonicalContext(options))
+});
 exports.send = async (id, message, options = {}) => write.sendConversation({
   conversationId: id,
   message,
@@ -59,7 +65,7 @@ exports.temp = {
     message,
     ...(await bindCanonicalContext(options))
   })
-};
-
-exports.attachments = require('./attachments');
-exports.model = require('./model');
+};
+exports.context = require('./context-config');
+exports.attachments = require('./attachments');
+exports.model = require('./model');

package/src/conversation/read.js

@@ -106,15 +106,19 @@ exports.getConversation = async ({
 
 exports.getConversationStreamStatus = async ({
   conversationId,
+  turnTraceId = null,
   token,
   sessionHeaders,
   requestJson = direct.requestJson
 }) => {
   if (!conversationId) throw new Error('conversationId is required');
   const target = `/backend-api/conversation/${encodeURIComponent(conversationId)}/stream_status`;
-  return requireOk(await requestJson(target, token, sessionHeaders, {
-    route: '/backend-api/conversation/{conversation_id}/stream_status'
-  }), target);
+  const response = await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversation/{conversation_id}/stream_status',
+    ...(turnTraceId ? { headers: { 'x-oai-turn-trace-id': turnTraceId } } : {})
+  });
+  if (response?.status === 404) return { status: 'UNAVAILABLE', conversation_id: conversationId };
+  return requireOk(response, target);
 };
 
 exports.resumeConversation = async ({
@@ -129,6 +133,9 @@ exports.resumeConversation = async ({
 }) => {
   if (!conversationId) throw new Error('conversationId is required');
   if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('offset must be a non-negative integer');
+  if (offset > 0 && !conduitToken) {
+    throw Object.assign(new Error('resume token required after stream progress'), { code: 'STREAM_RESUME_TOKEN_REQUIRED' });
+  }
   const target = '/backend-api/f/conversation/resume';
   const response = await requestText(target, token, sessionHeaders, {
     method: 'POST',

package/src/conversation/recovery-state.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require('../config/paths');
+
+const empty = () => ({ version: 1, items: {} });
+const readState = (env = process.env) => {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(paths.conversationRecoveryFile(env), 'utf8'));
+    return parsed && parsed.items && typeof parsed.items === 'object' ? parsed : empty();
+  } catch { return empty(); }
+};
+const writeState = (state, env = process.env) => {
+  const file = paths.conversationRecoveryFile(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(temp, file);
+  return file;
+};
+
+exports.get = (conversationId, env = process.env) => {
+  const value = readState(env).items[conversationId];
+  return value ? structuredClone(value) : null;
+};
+exports.save = ({ conversationId, phase = 'stream', offset = 0, resumeToken = null, turnTraceId = null, parentMessageId = null, currentNode = null }, env = process.env) => {
+  if (!conversationId) throw new TypeError('conversation recovery requires conversationId');
+  if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError('conversation recovery offset must be a non-negative integer');
+  const state = readState(env);
+  state.items[conversationId] = {
+    conversation_id: conversationId,
+    phase,
+    offset,
+    resume_token: typeof resumeToken === 'string' && resumeToken ? resumeToken : null,
+    turn_trace_id: typeof turnTraceId === 'string' && turnTraceId ? turnTraceId : null,
+    parent_message_id: typeof parentMessageId === 'string' && parentMessageId ? parentMessageId : null,
+    current_node: typeof currentNode === 'string' && currentNode ? currentNode : null,
+    updated_at: new Date().toISOString()
+  };
+  writeState(state, env);
+  return exports.get(conversationId, env);
+};
+exports.remove = (conversationId, env = process.env) => {
+  const state = readState(env);
+  const existed = Boolean(state.items[conversationId]);
+  if (!existed) return false;
+  delete state.items[conversationId];
+  writeState(state, env);
+  return true;
+};