@miruzero/zgpt 0.1.0

package/src/conversation/index.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('node:fs');
+const auth = require('../auth');
+const paths = require('../config/paths');
+const read = require('./read');
+const write = require('./write');
+const temporary = require('./temporary');
+
+const sessionHeaders = (env) => {
+  const file = paths.sessionFile(env);
+  let state;
+  try { state = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch {
+    throw Object.assign(new Error('ChatGPT session context required'), { code: 'SESSION_REQUIRED' });
+  }
+  if (!state?.headers || typeof state.headers !== 'object' || Array.isArray(state.headers)) {
+    throw Object.assign(new Error('ChatGPT session context required'), { code: 'SESSION_REQUIRED' });
+  }
+  return { ...state.headers };
+};
+
+const bindCanonicalContext = async (options = {}) => {
+  const resolved = { ...options };
+  const env = resolved.env || process.env;
+  if (!resolved.token) {
+    const current = await auth.ensure({ env, acquireSession: false });
+    resolved.token = current.accessToken;
+  }
+  if (!resolved.sessionHeaders) resolved.sessionHeaders = sessionHeaders(env);
+  return resolved;
+};
+
+Object.assign(exports, read, write);
+exports.get = async (id, options = {}) => read.getConversation({
+  conversationId: id,
+  ...(await bindCanonicalContext(options))
+});
+exports.streamStatus = async (id, options = {}) => read.getConversationStreamStatus({
+  conversationId: id,
+  ...(await bindCanonicalContext(options))
+});
+exports.resume = async (id, options = {}) => read.resumeConversation({
+  conversationId: id,
+  ...(await bindCanonicalContext(options))
+});
+exports.send = async (id, message, options = {}) => write.sendConversation({
+  conversationId: id,
+  message,
+  ...(await bindCanonicalContext(options))
+});
+exports.temp = {
+  new: async (message, options = {}) => temporary.createConversation({
+    message,
+    ...(await bindCanonicalContext(options))
+  }),
+  send: async (id, message, options = {}) => temporary.sendConversation({
+    conversationId: id,
+    message,
+    ...(await bindCanonicalContext(options))
+  })
+};
+
+exports.attachments = require('./attachments');
+exports.model = require('./model');

package/src/conversation/model.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const direct = require('../transport/direct/http-client');
+
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+let state = { models: [], defaultModelSlug: null, refreshedAt: 0 };
+
+const clone = (value) => value == null ? value : structuredClone(value);
+const cookieString = (headers = {}) => headers.Cookie || headers.cookie || '';
+const parseCookies = (headers = {}) => {
+  const out = new Map();
+  for (const pair of String(cookieString(headers)).split(';')) {
+    const index = pair.indexOf('=');
+    if (index <= 0) continue;
+    out.set(pair.slice(0, index).trim(), pair.slice(index + 1).trim());
+  }
+  return out;
+};
+const parseJsonCookie = (cookies, name) => {
+  const raw = cookies.get(name);
+  if (!raw) return null;
+  try { return JSON.parse(decodeURIComponent(raw)); }
+  catch { return null; }
+};
+
+const sessionPreference = (headers = {}) => {
+  const cookies = parseCookies(headers);
+  const last = parseJsonCookie(cookies, 'oai-last-model-config');
+  if (typeof last?.model === 'string' && last.model) {
+    return { model: last.model, thinkingEffort: typeof last.effort === 'string' ? last.effort : null };
+  }
+  const tpp = parseJsonCookie(cookies, 'oai-tpp-model-settings');
+  const model = tpp?.modelSettings?.lastUsedModelSlug;
+  if (typeof model === 'string' && model) {
+    return { model, thinkingEffort: typeof tpp?.thinkingEffort === 'string' ? tpp.thinkingEffort : null };
+  }
+  return { model: null, thinkingEffort: null };
+};
+
+const normalizeModel = (item) => {
+  const id = typeof item?.slug === 'string' && item.slug.trim()
+    ? item.slug.trim()
+    : typeof item?.id === 'string' && item.id.trim()
+      ? item.id.trim()
+      : null;
+  return id ? { ...clone(item), id, slug: item.slug || id, backendModel: id } : null;
+};
+const allowedEfforts = (model) => (Array.isArray(model?.thinking_efforts) ? model.thinking_efforts : [])
+  .map((item) => typeof item === 'string' ? item : item?.thinking_effort)
+  .filter((item) => typeof item === 'string' && item);
+const validEffort = (model, effort) => {
+  if (!effort) return null;
+  const allowed = allowedEfforts(model);
+  return allowed.length === 0 || allowed.includes(effort) ? effort : null;
+};
+
+exports.clearCache = () => { state = { models: [], defaultModelSlug: null, refreshedAt: 0 }; };
+exports.list = () => state.models.map(clone);
+exports.get = (id) => clone(state.models.find((item) => item.id === id) || null);
+exports.sessionPreference = sessionPreference;
+
+exports.refresh = async ({
+  token,
+  sessionHeaders = {},
+  requestJson = direct.requestJson,
+  cacheTtlMs = DEFAULT_CACHE_TTL_MS,
+  force = false
+} = {}) => {
+  const fresh = state.models.length && (Date.now() - state.refreshedAt) < Math.max(0, cacheTtlMs);
+  if (!force && fresh) return { refreshed: false, cached: true, count: state.models.length, defaultModelSlug: state.defaultModelSlug };
+  if (!token || typeof requestJson !== 'function') throw Object.assign(new Error('ChatGPT model catalog context required'), { code: 'MODEL_CONTEXT_REQUIRED' });
+  const target = '/backend-api/models';
+  const response = await requestJson(target, token, sessionHeaders, { route: target, retry: false });
+  if (response?.status !== 200 || !Array.isArray(response.json?.models) || response.json.models.length === 0) {
+    throw Object.assign(new Error(`ChatGPT model catalog request failed (${response?.status || 'invalid'})`), { code: 'MODEL_CATALOG_UNAVAILABLE', status: response?.status || null });
+  }
+  const models = response.json.models.map(normalizeModel).filter(Boolean);
+  if (!models.length) throw Object.assign(new Error('ChatGPT model catalog is empty'), { code: 'MODEL_CATALOG_EMPTY' });
+  state = {
+    models,
+    defaultModelSlug: typeof response.json.default_model_slug === 'string' ? response.json.default_model_slug : null,
+    refreshedAt: Date.now()
+  };
+  return { refreshed: true, cached: false, count: models.length, defaultModelSlug: state.defaultModelSlug };
+};
+
+exports.resolve = async ({
+  requestedModel = 'auto',
+  requestedThinkingEffort = null,
+  initDefaultModel = null,
+  token,
+  sessionHeaders = {},
+  requestJson = direct.requestJson,
+  cacheTtlMs = DEFAULT_CACHE_TTL_MS
+} = {}) => {
+  await exports.refresh({ token, sessionHeaders, requestJson, cacheTtlMs });
+  const requested = requestedModel && requestedModel !== 'auto' ? exports.get(requestedModel) : null;
+  const preference = sessionPreference(sessionHeaders);
+  const preferred = preference.model ? exports.get(preference.model) : null;
+  const initialized = initDefaultModel ? exports.get(initDefaultModel) : null;
+  const catalogDefault = state.defaultModelSlug ? exports.get(state.defaultModelSlug) : null;
+  const selected = requested || preferred || initialized || catalogDefault || exports.list()[0] || null;
+  if (!selected) throw Object.assign(new Error('No ChatGPT model is available'), { code: 'MODEL_NOT_FOUND' });
+  const source = requested ? 'requested' : preferred ? 'session-last-used' : initialized ? 'conversation-init' : catalogDefault ? 'catalog-default' : 'catalog-first';
+  const preferredEffort = source === 'session-last-used' ? preference.thinkingEffort : null;
+  const efforts = allowedEfforts(selected);
+  const thinkingEffort = validEffort(selected, requestedThinkingEffort)
+    || validEffort(selected, preferredEffort)
+    || (efforts.length ? efforts[0] : null);
+  return {
+    model: selected.id,
+    thinkingEffort,
+    source,
+    requestedValid: Boolean(requested),
+    catalogModel: selected
+  };
+};

package/src/conversation/read.js

@@ -0,0 +1,378 @@
+'use strict';
+
+const direct = require('../transport/direct/http-client');
+
+const requireOk = (response, target) => {
+  if (!response || response.status !== 200 || !response.json) {
+    const error = new Error(`ChatGPT request failed (${response?.status || 'no-status'}): ${target}`);
+    error.status = response?.status || null;
+    error.target = target;
+    error.retryAfterMs = direct.parseRetryAfterMs(response?.headers || {});
+    if (error.status === 429) error.code = 'RATE_LIMITED';
+    throw error;
+  }
+  return response.json;
+};
+
+const requireSuccess = (response, target) => {
+  if (!response || response.status < 200 || response.status >= 300) {
+    const error = new Error(`ChatGPT request failed (${response?.status || 'no-status'}): ${target}`);
+    error.status = response?.status || null;
+    error.target = target;
+    error.retryAfterMs = direct.parseRetryAfterMs(response?.headers || {});
+    if (error.status === 429) error.code = 'RATE_LIMITED';
+    throw error;
+  }
+  return response.json || { success: true };
+};
+
+exports.listConversationPage = async ({
+  token,
+  sessionHeaders,
+  offset = 0,
+  limit = 50,
+  requestJson = direct.requestJson,
+  onProgress = () => {}
+}) => {
+  const target = `/backend-api/conversations?offset=${offset}&limit=${limit}&order=updated&is_archived=false&is_starred=false`;
+  const page = requireOk(await requestJson(target, token, sessionHeaders), target);
+  const items = Array.isArray(page.items) ? page.items : [];
+  const totalValue = Number(page.total);
+  const total = Number.isFinite(totalValue) ? totalValue : items.length;
+  const pageLimit = Number(page.limit) || limit;
+  const pageOffset = Number(page.offset) || offset;
+  const nextOffset = items.length > 0 && pageOffset + pageLimit < total
+    ? pageOffset + pageLimit
+    : null;
+  onProgress({ type: 'conversation-page', count: items.length, pageCount: items.length, offset: pageOffset, total });
+  return { items, total, limit: pageLimit, offset: pageOffset, nextOffset };
+};
+
+exports.listStandalone = async ({
+  token,
+  sessionHeaders,
+  requestJson = direct.requestJson,
+  onProgress = () => {}
+}) => {
+  const items = [];
+  let offset = 0;
+  const limit = 50;
+
+  for (let pageNumber = 0; pageNumber < 1000; pageNumber += 1) {
+    const target = `/backend-api/conversations?offset=${offset}&limit=${limit}&order=updated&is_archived=false&is_starred=false`;
+    const page = requireOk(await requestJson(target, token, sessionHeaders), target);
+    const pageItems = Array.isArray(page.items) ? page.items : [];
+    items.push(...pageItems);
+    onProgress({ type: 'conversation-page', count: items.length, pageCount: pageItems.length, offset });
+
+    const total = Number(page.total);
+    const pageLimit = Number(page.limit) || limit;
+    offset += pageLimit;
+    if (!Number.isFinite(total) || offset >= total || pageItems.length === 0) return items;
+  }
+  throw Object.assign(new Error('conversation pagination exceeded 1000 pages'), { code: 'PAGINATION_LIMIT' });
+};
+exports.searchGlobal = async ({
+  query,
+  cursor = null,
+  limit = 20,
+  source = 'conversation',
+  token,
+  sessionHeaders,
+  requestJson = direct.requestJson
+}) => {
+  const normalized = String(query || '').trim();
+  if (!normalized) throw new Error('query is required');
+  const params = new URLSearchParams({ query: normalized, limit: String(limit) });
+  if (cursor) params.set('cursor', cursor);
+  if (source) params.set('sources', source);
+  const target = `/backend-api/global/search?${params.toString()}`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/global/search'
+  }), target);
+};
+exports.getConversation = async ({
+  conversationId,
+  token,
+  sessionHeaders,
+  requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  const target = `/backend-api/conversations/${encodeURIComponent(conversationId)}`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversations/{conversation_id}'
+  }), target);
+};
+
+exports.getConversationStreamStatus = async ({
+  conversationId,
+  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);
+};
+
+exports.resumeConversation = async ({
+  conversationId,
+  offset = 0,
+  conduitToken = null,
+  turnTraceId = null,
+  onChunk = null,
+  token,
+  sessionHeaders,
+  requestText = direct.requestText
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('offset must be a non-negative integer');
+  const target = '/backend-api/f/conversation/resume';
+  const response = await requestText(target, token, sessionHeaders, {
+    method: 'POST',
+    body: { conversation_id: conversationId, offset },
+    route: target,
+    headers: {
+      accept: 'text/event-stream',
+      origin: sessionHeaders?.origin || sessionHeaders?.Origin || 'https://chatgpt.com',
+      'x-openai-web-frontend': sessionHeaders?.['x-openai-web-frontend'] || 'core_web',
+      ...(conduitToken ? { 'x-conduit-token': conduitToken } : {}),
+      ...(turnTraceId ? { 'x-oai-turn-trace-id': turnTraceId } : {})
+    },
+    retry: false,
+    idleTimeoutMs: 60_000,
+    onChunk
+  });
+  if (!response || response.status < 200 || response.status >= 300) {
+    const error = new Error(`ChatGPT request failed (${response?.status || 'no-status'}): ${target}`);
+    error.status = response?.status || null;
+    error.target = target;
+    error.body = response?.text || null;
+    throw error;
+  }
+  return {
+    conversation_id: conversationId,
+    status: response.status,
+    content_type: response.contentType || null,
+    text: response.text || ''
+  };
+};
+
+exports.getConversationMessagesPage = async ({
+  conversationId, before, numTurns = 10, includeHasVersions = true,
+  token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  if (!before) throw new Error('before is required');
+  const params = new URLSearchParams({
+    before: String(before),
+    include_has_versions: includeHasVersions ? 'true' : 'false',
+    num_turns: String(numTurns)
+  });
+  const target = `/backend-api/conversations/${encodeURIComponent(conversationId)}/messages?${params}`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversations/{conversation_id}/messages'
+  }), target);
+};
+exports.findConversationMessage = async ({
+  conversationId, messageId, numTurns = 10, includeHasVersions = true,
+  token, sessionHeaders, requestJson = direct.requestJson,
+  getConversation = exports.getConversation, getMessagesPage = exports.getConversationMessagesPage
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  if (!messageId) throw new Error('messageId is required');
+  const current = await getConversation({ conversationId, token, sessionHeaders, requestJson });
+  let pagesScanned = 1;
+  let nodesScanned = Array.isArray(current?.messages) ? current.messages.length : 0;
+  const currentMatch = Array.isArray(current?.messages) ? current.messages.find((item) => item?.id === messageId) : null;
+  if (currentMatch) return { found: true, conversation_id: conversationId, message_id: messageId, source: 'current_window', page_info: current?.page_info || null, message: currentMatch, pages_scanned: pagesScanned, nodes_scanned: nodesScanned };
+  let pageInfo = current?.page_info || {};
+  let before = pageInfo.start_cursor || null;
+  let hasPrevious = pageInfo.has_previous_page === true;
+  const seen = new Set();
+  while (hasPrevious && before) {
+    if (seen.has(before)) throw Object.assign(new Error('conversation history cursor stalled'), { code: 'PAGINATION_STALLED' });
+    seen.add(before);
+    const page = await getMessagesPage({ conversationId, before, numTurns, includeHasVersions, token, sessionHeaders, requestJson });
+    pagesScanned += 1;
+    const messages = Array.isArray(page?.messages) ? page.messages : [];
+    nodesScanned += messages.length;
+    const match = messages.find((item) => item?.id === messageId);
+    if (match) return { found: true, conversation_id: conversationId, message_id: messageId, source: 'historical_page', before, page_info: page?.page_info || null, message: match, pages_scanned: pagesScanned, nodes_scanned: nodesScanned };
+    pageInfo = page?.page_info || {};
+    hasPrevious = pageInfo.has_previous_page === true;
+    const nextBefore = pageInfo.start_cursor || null;
+    if (hasPrevious && (!nextBefore || nextBefore === before)) throw Object.assign(new Error('conversation history cursor stalled'), { code: 'PAGINATION_STALLED' });
+    before = nextBefore;
+  }
+  return { found: false, conversation_id: conversationId, message_id: messageId, source: null, page_info: pageInfo, message: null, pages_scanned: pagesScanned, nodes_scanned: nodesScanned };
+};
+
+exports.getConversationHistory = async ({
+  conversationId, numTurns = 10, includeHasVersions = true,
+  token, sessionHeaders, requestJson = direct.requestJson,
+  getConversation = exports.getConversation, getMessagesPage = exports.getConversationMessagesPage
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  const current = await getConversation({ conversationId, token, sessionHeaders, requestJson });
+  const pages = [{ ...current, kind: 'current_window', before: null }];
+  let messageCount = Array.isArray(current?.messages) ? current.messages.length : 0;
+  let pageInfo = current?.page_info || {};
+  let before = pageInfo.start_cursor || null;
+  let hasPrevious = pageInfo.has_previous_page === true;
+  const seen = new Set();
+  while (hasPrevious && before) {
+    if (seen.has(before)) throw Object.assign(new Error('conversation history cursor stalled'), { code: 'PAGINATION_STALLED' });
+    seen.add(before);
+    const page = await getMessagesPage({ conversationId, before, numTurns, includeHasVersions, token, sessionHeaders, requestJson });
+    pages.push({ ...page, kind: 'historical_page', before });
+    messageCount += Array.isArray(page?.messages) ? page.messages.length : 0;
+    pageInfo = page?.page_info || {};
+    hasPrevious = pageInfo.has_previous_page === true;
+    const nextBefore = pageInfo.start_cursor || null;
+    if (hasPrevious && (!nextBefore || nextBefore === before)) throw Object.assign(new Error('conversation history cursor stalled'), { code: 'PAGINATION_STALLED' });
+    before = nextBefore;
+  }
+  return {
+    conversation_id: current?.conversation_id || current?.id || conversationId,
+    title: current?.title || null,
+    project_id: current?.gizmo_id || current?.conversation_template_id || null,
+    current_node: current?.current_node || null,
+    complete: true,
+    direction: 'current_to_older',
+    page_count: pages.length,
+    message_count: messageCount,
+    pages
+  };
+};
+
+exports.getConversationThread = async ({
+  conversationId, includeFullConversation = false,
+  token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  const query = includeFullConversation ? '?include_full_conversation=true' : '';
+  const target = `/backend-api/conversation/${encodeURIComponent(conversationId)}${query}`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversation/{conversation_id}'
+  }), target);
+};
+
+exports.getConversationMessageSupplements = async ({
+  conversationId, token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  const target = `/backend-api/conversations/${encodeURIComponent(conversationId)}/message_supplements`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversations/{conversation_id}/message_supplements'
+  }), target);
+};
+
+exports.getConversationTextdocs = async ({
+  conversationId, token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  const target = `/backend-api/conversation/${encodeURIComponent(conversationId)}/textdocs`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversation/{conversation_id}/textdocs'
+  }), target);
+};
+
+exports.checkConversationUrlSafety = async ({
+  conversationId, url, historyAndTrainingDisabled = false,
+  token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  if (!url) throw new Error('url is required');
+  const params = new URLSearchParams({
+    url: String(url),
+    history_and_training_disabled: historyAndTrainingDisabled ? 'true' : 'false'
+  });
+  const target = `/backend-api/conversation/${encodeURIComponent(conversationId)}/url_safe?${params}`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversation/{conversation_id}/url_safe'
+  }), target);
+};
+
+exports.getVoiceFeedbackOptions = async ({
+  token, sessionHeaders, requestJson = direct.requestJson
+} = {}) => {
+  const target = '/backend-api/conversation/voice/feedback-options';
+  return requireOk(await requestJson(target, token, sessionHeaders, { route: target }), target);
+};
+
+exports.listConversationFilesPage = async ({
+  conversationId, cursor = null, limit = 200,
+  token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  const safeLimit = Math.max(1, Math.min(200, Number.parseInt(limit, 10) || 200));
+  const params = new URLSearchParams();
+  if (cursor) params.set('cursor', String(cursor));
+  params.set('limit', String(safeLimit));
+  const target = `/backend-api/conversations/${encodeURIComponent(conversationId)}/files?${params}`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversations/{conversation_id}/files'
+  }), target);
+};
+
+exports.listConversationFiles = async ({
+  conversationId, limit = 200, maxPages = 1000,
+  token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  const files = [];
+  const seenFiles = new Set();
+  const seenCursors = new Set();
+  let cursor = null;
+  const pageLimit = Math.max(1, Math.min(1000, Number.parseInt(maxPages, 10) || 1000));
+  for (let page = 0; page < pageLimit; page += 1) {
+    const result = await exports.listConversationFilesPage({ conversationId, cursor, limit, token, sessionHeaders, requestJson });
+    for (const file of Array.isArray(result?.items) ? result.items : []) {
+      const id = file?.file_id;
+      if (id && seenFiles.has(id)) continue;
+      if (id) seenFiles.add(id);
+      files.push(file);
+    }
+    const next = result?.cursor ?? null;
+    if (!next || seenCursors.has(next)) return files;
+    seenCursors.add(next);
+    cursor = next;
+  }
+  throw Object.assign(new Error(`conversation file pagination exceeded ${pageLimit} pages`), { code: 'PAGINATION_LIMIT' });
+};
+
+exports.searchConversations = async ({
+  query, cursor = null, token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  const normalized = String(query || '').trim();
+  if (!normalized) throw new Error('query is required');
+  const params = new URLSearchParams({ query: normalized });
+  if (cursor) params.set('cursor', String(cursor));
+  const target = `/backend-api/conversations/search?${params}`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversations/search'
+  }), target);
+};
+
+exports.requestInterpreterDownload = async ({
+  conversationId, messageId, sandboxPath, downloadIntent = null,
+  projectId = null, ownerUserId = null, requestSource = null,
+  token, sessionHeaders, requestJson = direct.requestJson
+}) => {
+  if (!conversationId) throw new Error('conversationId is required');
+  if (!messageId) throw new Error('messageId is required');
+  if (!sandboxPath) throw new Error('sandboxPath is required');
+  const params = new URLSearchParams({ message_id: String(messageId), sandbox_path: String(sandboxPath) });
+  if (downloadIntent !== null && downloadIntent !== undefined) params.set('download_intent', String(downloadIntent));
+  const headers = {};
+  if (projectId) headers['chatgpt-project-id'] = String(projectId);
+  if (ownerUserId) headers['chatgpt-conv-owner-id'] = String(ownerUserId);
+  if (requestSource) headers['x-chatgpt-sandbox-download-source'] = String(requestSource);
+  const target = `/backend-api/conversation/${encodeURIComponent(conversationId)}/interpreter/download?${params}`;
+  return requireOk(await requestJson(target, token, sessionHeaders, {
+    route: '/backend-api/conversation/{conversation_id}/interpreter/download', headers
+  }), target);
+};

package/src/conversation/temp-state.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require('../config/paths');
+
+const readState = (env = process.env) => {
+  const file = paths.tempConversationFile(env);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && parsed.items && typeof parsed.items === 'object'
+      ? parsed
+      : { version: 1, items: {} };
+  } catch {
+    return { version: 1, items: {} };
+  }
+};
+
+const writeState = (state, env = process.env) => {
+  const file = paths.tempConversationFile(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(state, null, 2)}
+`, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(temp, file);
+  return file;
+};
+
+exports.get = (conversationId, env = process.env) => readState(env).items[conversationId] || null;
+exports.save = ({ conversationId, currentNode, env = process.env }) => {
+  if (!conversationId || !currentNode) throw new TypeError('temporary conversation cursor requires conversationId and currentNode');
+  const state = readState(env);
+  state.items[conversationId] = { current_node: currentNode, updated_at: new Date().toISOString() };
+  writeState(state, env);
+  return { conversation_id: conversationId, current_node: currentNode };
+};
+exports.remove = (conversationId, env = process.env) => {
+  const state = readState(env);
+  const existed = Boolean(state.items[conversationId]);
+  delete state.items[conversationId];
+  writeState(state, env);
+  return existed;
+};

package/src/conversation/temporary.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const write = require('./write');
+const tempState = require('./temp-state');
+
+const VALID_PERSONALIZATION = new Set(['inherit', 'on', 'off']);
+
+exports.resolvePersonalization = (mode = 'inherit', nativeValue = undefined) => {
+  if (!VALID_PERSONALIZATION.has(mode)) {
+    throw new TypeError(`invalid personalization mode: ${mode}`);
+  }
+  if (mode === 'on') return true;
+  if (mode === 'off') return false;
+  return typeof nativeValue === 'boolean' ? nativeValue : undefined;
+};
+
+exports.createConversation = async ({
+  message,
+  personalization = 'inherit',
+  nativePersonalization = undefined,
+  env = process.env,
+  ...options
+}) => {
+  const result = await write.createConversation({
+    ...options,
+    message,
+    temporaryChat: true,
+    historyAndTrainingDisabled: true,
+    isDoNotRemember: false,
+    temporaryChatRequestsPersonalization: exports.resolvePersonalization(personalization, nativePersonalization)
+  });
+  tempState.save({ conversationId: result.conversation_id, currentNode: result.current_node, env });
+  return result;
+};
+
+exports.sendConversation = async ({
+  conversationId,
+  message,
+  env = process.env,
+  parentMessageId = null,
+  ...options
+}) => {
+  const cursor = parentMessageId ? { current_node: parentMessageId } : tempState.get(conversationId, env);
+  if (!cursor?.current_node) {
+    throw Object.assign(new Error(`temporary conversation cursor not found: ${conversationId}`), { code: 'TEMP_STATE_NOT_FOUND' });
+  }
+  const result = await write.sendConversation({
+    ...options,
+    conversationId,
+    message,
+    parentMessageId: cursor.current_node,
+    temporaryChat: true,
+    historyAndTrainingDisabled: true,
+    isDoNotRemember: false,
+    temporaryChatRequestsPersonalization: null
+  });
+  tempState.save({ conversationId, currentNode: result.current_node, env });
+  return result;
+};