@miruzero/zgpt 0.1.0

package/src/api/index.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const fs = require('node:fs');
+const auth = require('../auth');
+const paths = require('../config/paths');
+const direct = require('../transport/direct/http-client');
+const catalogData = require('./catalog.json');
+
+const catalog = Object.freeze(catalogData.entries.map((entry) => Object.freeze({ ...entry })));
+const summary = Object.freeze({ ...catalogData.summary, source: catalogData.source });
+
+const readSessionHeaders = (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 bindContext = async (entry, options) => {
+  if (entry.client === 'PublicRequest' || options.auth === false) {
+    return {
+      token: options.token ?? null,
+      sessionHeaders: options.sessionHeaders ? { ...options.sessionHeaders } : {}
+    };
+  }
+  const env = options.env || process.env;
+  let token = options.token;
+  if (!token) {
+    const current = await auth.ensure({ env, acquireSession: false });
+    token = current.accessToken;
+  }
+  const sessionHeaders = options.sessionHeaders ? { ...options.sessionHeaders } : readSessionHeaders(env);
+  return { token, sessionHeaders };
+};
+
+const missingPath = (name, route) => Object.assign(
+  new Error(`Missing path parameter ${name} for ${route}`),
+  { code: 'API_PATH_PARAMETER_REQUIRED', parameter: name, route }
+);
+
+const renderRoute = (route, options = {}) => {
+  const pathValues = Array.isArray(options.pathValues) ? options.pathValues : null;
+  const path = options.path && typeof options.path === 'object' ? options.path : {};
+  const used = Object.create(null);
+  let index = 0;
+  const rendered = route.replace(/\{([^}]+)\}/g, (_token, name) => {
+    let value;
+    if (pathValues) value = pathValues[index];
+    else if (Object.hasOwn(path, name)) {
+      const candidate = path[name];
+      if (Array.isArray(candidate)) {
+        const at = used[name] || 0;
+        value = candidate[at];
+        used[name] = at + 1;
+      } else value = candidate;
+    }
+    index += 1;
+    if (value === undefined || value === null) throw missingPath(name, route);
+    return encodeURIComponent(String(value));
+  });
+  if (pathValues && pathValues.length !== index) {
+    throw Object.assign(new Error(`Expected ${index} path values for ${route}, received ${pathValues.length}`), {
+      code: 'API_PATH_VALUE_COUNT', expected: index, received: pathValues.length, route
+    });
+  }
+  return rendered;
+};
+
+const appendQuery = (target, query) => {
+  if (!query || typeof query !== 'object') return target;
+  const params = new URLSearchParams();
+  for (const [name, input] of Object.entries(query)) {
+    const values = Array.isArray(input) ? input : [input];
+    for (const value of values) {
+      if (value === undefined || value === null) continue;
+      params.append(name, typeof value === 'object' ? JSON.stringify(value) : String(value));
+    }
+  }
+  const encoded = params.toString();
+  return encoded ? `${target}${target.includes('?') ? '&' : '?'}${encoded}` : target;
+};
+
+const byKeyEntry = new Map(catalog.map((entry) => [entry.key, entry]));
+const byNameEntry = new Map(catalog.map((entry) => [entry.name, entry]));
+const resolveEntry = (reference) => {
+  if (reference && typeof reference === 'object' && reference.key && reference.route) return reference;
+  if (typeof reference !== 'string') throw Object.assign(new Error('API route reference is required'), { code: 'API_REFERENCE_REQUIRED' });
+  const entry = byKeyEntry.get(reference) || byNameEntry.get(reference);
+  if (!entry) throw Object.assign(new Error(`Unknown ChatGPT API capability: ${reference}`), { code: 'API_CAPABILITY_UNKNOWN', reference });
+  return entry;
+};
+
+exports.catalog = catalog;
+exports.summary = summary;
+exports.list = (criteria = {}) => catalog.filter((entry) => Object.entries(criteria).every(([key, value]) => value === undefined || entry[key] === value));
+exports.find = (criteria = {}) => exports.list(criteria)[0] || null;
+
+exports.invoke = async (reference, options = {}) => {
+  const entry = resolveEntry(reference);
+  const target = appendQuery(renderRoute(entry.route, options), options.query);
+  const context = await bindContext(entry, options);
+  const responseType = options.responseType === 'text' ? 'text' : 'json';
+  const request = responseType === 'text'
+    ? (options.requestText || direct.requestText)
+    : (options.requestJson || direct.requestJson);
+  const requestOptions = {
+    method: entry.method,
+    route: entry.route,
+    retry: false,
+    ...(options.body === undefined ? {} : { body: options.body }),
+    ...(options.headers ? { headers: options.headers } : {}),
+    ...(options.onChunk ? { onChunk: options.onChunk } : {}),
+    ...(Number.isFinite(options.idleTimeoutMs) ? { idleTimeoutMs: options.idleTimeoutMs } : {}),
+    ...(options.env ? { env: options.env } : {}),
+    ...(options.sessionFile ? { sessionFile: options.sessionFile } : {})
+  };
+  const response = await request(target, context.token, context.sessionHeaders, requestOptions);
+  if (!response || response.status < 200 || response.status >= 300) {
+    const status = response?.status || null;
+    const error = new Error(`ChatGPT API request failed (${status || 'no-status'}): ${entry.method} ${target}`);
+    error.code = status === 429 ? 'RATE_LIMITED' : 'API_REQUEST_FAILED';
+    error.status = status;
+    error.target = target;
+    error.route = entry.route;
+    error.method = entry.method;
+    throw error;
+  }
+  if (options.rawResponse === true) return response;
+  if (responseType === 'text') return response.text ?? '';
+  return response.json ?? { success: true };
+};
+
+const byKey = Object.create(null);
+const functions = Object.create(null);
+const groups = Object.create(null);
+for (const entry of catalog) {
+  const fn = (options = {}) => exports.invoke(entry, options);
+  Object.defineProperty(fn, 'meta', { value: entry, enumerable: true });
+  byKey[entry.key] = fn;
+  functions[entry.name] = fn;
+  if (!groups[entry.family]) groups[entry.family] = Object.create(null);
+  groups[entry.family][entry.name] = fn;
+}
+for (const family of Object.keys(groups)) Object.freeze(groups[family]);
+exports.byKey = Object.freeze(byKey);
+exports.functions = Object.freeze(functions);
+exports.groups = Object.freeze(groups);

package/src/auth/index.js

@@ -0,0 +1,87 @@
+'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 }); }
+};

package/src/cli/formatter.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const textOf = (message) => {
+  const content = message?.content;
+  if (!content) return '(non-text)';
+  if (typeof content.content === 'string') return content.content;
+  if (typeof content.text === 'string') return content.text;
+  if (Array.isArray(content.parts)) {
+    const parts = content.parts
+      .map((part) => typeof part === 'string' ? part : part?.text)
+      .filter(Boolean);
+    if (parts.length) return parts.join('\n');
+  }
+  return '(non-text)';
+};
+
+exports.parseLimitSpec = (value) => {
+  if (/^[1-9]\d*$/.test(value || '')) return { type: 'latest', count: Number(value) };
+  const match = /^([1-9]\d*)-([1-9]\d*)$/.exec(value || '');
+  if (!match) return null;
+  const start = Number(match[1]);
+  const end = Number(match[2]);
+  return end >= start ? { type: 'range', start, end } : null;
+};
+
+const groupTurns = (messages = []) => {
+  const turns = [];
+  let current = null;
+  for (const message of messages) {
+    if (message?.author?.role === 'user') {
+      current = { number: turns.length + 1, messages: [] };
+      turns.push(current);
+    }
+    if (current) current.messages.push(message);
+  }
+  return turns;
+};
+
+const selectTurns = (turns, spec) => {
+  if (!spec) return turns;
+  if (spec.type === 'latest') return turns.slice(-spec.count);
+  return turns.slice(spec.start - 1, spec.end);
+};
+
+const debugLines = (message) => {
+  const metadata = message?.metadata || {};
+  const value = (item) => item == null ? '-' : typeof item === 'object' ? JSON.stringify(item) : String(item);
+  return [
+    '[DEBUG]',
+    `id=${message?.id || '-'}`,
+    `parent_id=${message?.parent_id || '-'}`,
+    `status=${message?.status || '-'}`,
+    `end_turn=${value(message?.end_turn)}`,
+    `content_type=${message?.content?.content_type || '-'}`,
+    `author_name=${message?.author?.name || '-'}`,
+    `recipient=${message?.recipient || '-'}`,
+    `channel=${message?.channel || '-'}`,
+    `request_id=${metadata.request_id || '-'}`,
+    `turn_id=${metadata.turn_id || '-'}`,
+    `turn_exchange_id=${metadata.turn_exchange_id || '-'}`,
+    `working_turn_id=${metadata.working_turn_id || '-'}`,
+    `model_slug=${metadata.model_slug || '-'}`,
+    `finish_details=${value(metadata.finish_details)}`
+  ];
+};
+
+const moderationLines = (conversation) => {
+  const results = Array.isArray(conversation?.moderation_results) ? conversation.moderation_results : [];
+  const lines = [];
+  for (const result of results) {
+    const metadata = result?.metadata || {};
+    lines.push('## MODERATION', `message_id=${result?.message_id || '-'}`);
+    lines.push(`blocked=${result?.blocked ?? '-'}`, `flagged=${result?.flagged ?? '-'}`);
+    lines.push(`safety_limited=${metadata.safety_limited ?? '-'}`);
+    lines.push(`protection_type=${metadata.protection_type || '-'}`);
+    lines.push(`block_reason=${metadata.safety_plugin_block_reason || result?.block_reason || '-'}`, '');
+  }
+  return lines;
+};
+
+exports.markdown = (conversation, options = {}) => {
+  const debug = options.debug === true;
+  const messages = Array.isArray(conversation?.messages) ? conversation.messages : [];
+  const turns = groupTurns(messages);
+  const selected = selectTurns(turns, options.limit || null);
+  const lines = [
+    `# ${conversation?.title || '(untitled)'}`,
+    '',
+    `conversation_id: ${conversation?.conversation_id || conversation?.id || '-'}`,
+    `project_id: ${conversation?.gizmo_id || conversation?.conversation_template_id || '-'}`,
+    `current_node: ${conversation?.current_node || '-'}`,
+    `messages: ${messages.length}`,
+    `user_turns: ${turns.length}`,
+    ''
+  ];
+
+  for (const turn of selected) {
+    lines.push(`## Turn ${turn.number}`, '');
+    for (const message of turn.messages) {
+      const role = String(message?.author?.role || 'unknown').toUpperCase();
+      if (!debug && role !== 'USER' && role !== 'ASSISTANT') continue;
+      const name = message?.author?.name ? ` (${message.author.name})` : '';
+      lines.push(`### ${role}${name}`, textOf(message), '');
+      if (debug) lines.push(...debugLines(message), '');
+    }
+  }
+  if (debug) lines.push(...moderationLines(conversation));
+  return `${lines.join('\n').trimEnd()}\n`;
+};
+
+exports.json = (conversation) => `${JSON.stringify(conversation, null, 2)}\n`;

package/src/cli.js

@@ -0,0 +1,117 @@
+#!/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`);
+        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());
+      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

@@ -0,0 +1,19 @@
+'use strict';
+
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const root = path.resolve(__dirname, '../..');
+
+exports.stateDir = (env = process.env) => path.resolve(env.ZERO_CHATGPT_STATE_DIR || path.join(root, 'state'));
+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.rateLimitDir = (env = process.env) => env.ZERO_CHATGPT_RATE_LIMIT_FILE
+  ? path.dirname(path.resolve(env.ZERO_CHATGPT_RATE_LIMIT_FILE))
+  : exports.stateDir(env);
+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/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const read = require('./read');
+const write = require('./write');
+
+Object.assign(exports, read, write);

package/src/connector/read.js

@@ -0,0 +1,56 @@
+'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;
+};
+
+exports.listConnectors = async ({ token, sessionHeaders, 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 plugins = Array.isArray(raw?.plugins) ? raw.plugins : [];
+  return plugins.map((plugin) => ({
+    id: plugin?.id || null,
+    name: plugin?.name || null,
+    displayName: plugin?.release?.display_name || plugin?.name || null,
+    shortDescription: plugin?.release?.interface?.short_description || plugin?.release?.description || null,
+    status: plugin?.status || null,
+    enabled: plugin?.enabled ?? null,
+    disabledSkillNames: Array.isArray(plugin?.disabled_skill_names) ? plugin.disabled_skill_names : []
+  }));
+};
+
+exports.getConnectorActions = async ({ appId, token, sessionHeaders, requestJson = direct.requestJson }) => {
+  if (!appId || typeof appId !== 'string') throw Object.assign(new Error('appId is required'), { code: 'BAD_ARGS' });
+  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);
+};
+
+exports.resolveSystemHintSelections = async ({ message, token, sessionHeaders, listConnectors = exports.listConnectors }) => {
+  const text = String(message || '');
+  if (!text.includes('@')) return { systemHints: [], systemHintMentions: [] };
+  const connectors = await listConnectors({ token, sessionHeaders });
+  const hints = new Set();
+  const systemHintMentions = [];
+  for (const item of connectors) {
+    if (item?.enabled === false || !item?.displayName || !item?.id?.startsWith('plugin_')) continue;
+    const mentionText = '@' + item.displayName;
+    const hint = 'plugin:' + item.id.slice('plugin_'.length);
+    let startIndex = text.indexOf(mentionText);
+    while (startIndex >= 0) {
+      hints.add(hint);
+      systemHintMentions.push({ id: hint, startIndex, endIndex: startIndex + mentionText.length });
+      startIndex = text.indexOf(mentionText, startIndex + mentionText.length);
+    }
+  }
+  return { systemHints: [...hints], systemHintMentions };
+};

package/src/connector/write.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const direct = require('../transport/direct/http-client');
+
+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.refreshConnectorActions = async ({ linkId, token, sessionHeaders, requestJson = direct.requestJson }) => {
+  if (!linkId || typeof 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
+  }), target);
+};

package/src/conversation/attachments.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const requiredString = (value, name) => {
+  if (typeof value !== 'string' || !value) throw new TypeError(`${name} is required`);
+  return value;
+};
+
+const classify = (mimeType) => {
+  if (mimeType === 'image/png') return 'image';
+  if (mimeType === 'text/plain') return 'document';
+  throw new Error(`unverified attachment mime type: ${mimeType}`);
+};
+
+exports.normalizeReservation = (input) => {
+  if (!input || input.eligible !== true) throw new Error('upload reservation is not eligible');
+  const fileId = requiredString(input.reservation_id, 'reservation_id');
+  const uploadUrl = requiredString(input.upload_url, 'upload_url');
+  const uploadUrlExpiresAt = requiredString(input.upload_url_expires_at, 'upload_url_expires_at');
+  const reservationExpiresAt = requiredString(input.reservation_expires_at, 'reservation_expires_at');
+  new URL(uploadUrl);
+  if (Number.isNaN(Date.parse(uploadUrlExpiresAt))) throw new TypeError('invalid upload_url_expires_at');
+  if (Number.isNaN(Date.parse(reservationExpiresAt))) throw new TypeError('invalid reservation_expires_at');
+  return { fileId, uploadUrl, uploadUrlExpiresAt, reservationExpiresAt };
+};
+
+exports.sanitizeReservationForLog = (input) => {
+  const normalized = exports.normalizeReservation(input);
+  const url = new URL(normalized.uploadUrl);
+  return {
+    ...normalized,
+    uploadUrl: `${url.origin}${url.pathname}${url.search ? '?<redacted>' : ''}`
+  };
+};
+
+exports.buildProcessPayload = ({ fileId, name, mimeType, temporary = false }) => {
+  const kind = classify(mimeType);
+  return {
+    entry_surface: 'chat_composer',
+    file_id: requiredString(fileId, 'fileId'),
+    file_name: requiredString(name, 'name'),
+    index_for_retrieval: kind === 'document',
+    library_persistence_mode: 'opportunistic',
+    metadata: {
+      is_temporary_chat: Boolean(temporary),
+      store_in_library: false,
+      is_project_thread: false
+    },
+    mime_type: mimeType,
+    use_case: kind === 'image' ? 'multimodal' : 'my_files'
+  };
+};
+
+const projectAttachment = ({ fileId, name, mimeType, size, width, height }) => {
+  const kind = classify(mimeType);
+  requiredString(fileId, 'fileId');
+  requiredString(name, 'name');
+  if (kind === 'image') {
+    return {
+      kind,
+      part: {
+        asset_pointer: `sediment://${fileId}`,
+        content_type: 'image_asset_pointer',
+        height,
+        size_bytes: size,
+        width
+      },
+      attachment: { id: fileId, mime_type: mimeType, name, size, width, height }
+    };
+  }
+  return {
+    kind,
+    attachment: { id: fileId, is_big_paste: true, mime_type: mimeType, name, size }
+  };
+};
+
+exports.project = projectAttachment;
+exports.projectAttachment = projectAttachment;