@miruzero/zgpt 0.1.3 → 0.1.5

package/src/api/discovered.json

@@ -0,0 +1,165 @@
+{
+  "source": "2026-10-11 local OSSGPT, OSSGPT1 and Chrome extension evidence; supplemental to historical catalog",
+  "entries": [
+    {
+      "key": "GET /api/auth/session",
+      "method": "GET",
+      "route": "/api/auth/session",
+      "name": "getWebAuthSession",
+      "family": "auth",
+      "client": "Request",
+      "evidence": [
+        "CAPTURE_OSSGPT1"
+      ],
+      "captureCount": 2,
+      "statuses": {
+        "200": 2
+      },
+      "scope": "WEB_AUTH",
+      "verification": "CAPTURED_SUCCESS"
+    },
+    {
+      "key": "GET /backend-api/aura/identity",
+      "method": "GET",
+      "route": "/backend-api/aura/identity",
+      "name": "getAuraIdentity",
+      "family": "profile",
+      "client": "Request",
+      "evidence": [
+        "EXTENSION_BACKGROUND_FETCH"
+      ],
+      "captureCount": 0,
+      "statuses": {},
+      "scope": "CHATGPT_BROWSER_EXTENSION",
+      "verification": "STATIC_CALLSITE"
+    },
+    {
+      "key": "GET /backend-api/diag",
+      "method": "GET",
+      "route": "/backend-api/diag",
+      "name": "getWebDiagnostics",
+      "family": "diag",
+      "client": "Request",
+      "evidence": [
+        "CAPTURE_OSSGPT1"
+      ],
+      "captureCount": 2,
+      "statuses": {
+        "200": 2
+      },
+      "scope": "WEB_DIAGNOSTICS",
+      "verification": "CAPTURED_SUCCESS"
+    },
+    {
+      "key": "GET /backend-api/hosting/sites/{id}/access",
+      "method": "GET",
+      "route": "/backend-api/hosting/sites/{id}/access",
+      "name": "getHostingSiteAccess",
+      "family": "hosting",
+      "client": "Request",
+      "evidence": [
+        "STATIC_OSSGPT"
+      ],
+      "captureCount": 0,
+      "statuses": {},
+      "scope": "WORK_HOSTING",
+      "verification": "STATIC_CALLSITE"
+    },
+    {
+      "key": "GET /backend-api/models/",
+      "method": "GET",
+      "route": "/backend-api/models/",
+      "name": "getModelsTrailingSlash",
+      "family": "models",
+      "client": "Request",
+      "evidence": [
+        "CAPTURE_OSSGPT1"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "307": 1
+      },
+      "scope": "CHATGPT_WEB_REDIRECT_ALIAS",
+      "verification": "CAPTURED_REDIRECT_ONLY"
+    },
+    {
+      "key": "GET /public-api/conversation_limit",
+      "method": "GET",
+      "route": "/public-api/conversation_limit",
+      "name": "getPublicConversationLimitActualPath",
+      "family": "public-request",
+      "client": "PublicRequest",
+      "evidence": [
+        "CAPTURE_OSSGPT"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "scope": "CHATGPT_WEB_PUBLIC",
+      "verification": "CAPTURED_SUCCESS"
+    },
+    {
+      "key": "GET /public-api/gizmos/{id}",
+      "method": "GET",
+      "route": "/public-api/gizmos/{id}",
+      "name": "getPublicGizmoActualPath",
+      "family": "public-request",
+      "client": "PublicRequest",
+      "evidence": [
+        "CAPTURE_OSSGPT"
+      ],
+      "captureCount": 3,
+      "statuses": {
+        "403": 3
+      },
+      "scope": "CHATGPT_WEB_PUBLIC",
+      "verification": "CAPTURED_FORBIDDEN_ONLY"
+    },
+    {
+      "key": "PATCH /backend-api/my/image/{id}/{id}",
+      "method": "PATCH",
+      "route": "/backend-api/my/image/{id}/{id}",
+      "name": "patchMyImageByIdByIdCandidate",
+      "family": "my",
+      "client": "Request",
+      "evidence": [
+        "STATIC_OSSGPT"
+      ],
+      "captureCount": 0,
+      "statuses": {},
+      "scope": "CHATGPT_WEB_DYNAMIC_PATH_UNVALIDATED",
+      "verification": "STATIC_DYNAMIC_ROUTE_CANDIDATE"
+    },
+    {
+      "key": "POST /backend-api/hosting/sites/{id}/access",
+      "method": "POST",
+      "route": "/backend-api/hosting/sites/{id}/access",
+      "name": "postHostingSiteAccess",
+      "family": "hosting",
+      "client": "Request",
+      "evidence": [
+        "STATIC_OSSGPT"
+      ],
+      "captureCount": 0,
+      "statuses": {},
+      "scope": "WORK_HOSTING",
+      "verification": "STATIC_CALLSITE"
+    },
+    {
+      "key": "POST /backend-api/hosting/sites/{id}/source_repository/read_credential",
+      "method": "POST",
+      "route": "/backend-api/hosting/sites/{id}/source_repository/read_credential",
+      "name": "postHostingSiteSourceCredentialRead",
+      "family": "hosting",
+      "client": "Request",
+      "evidence": [
+        "STATIC_OSSGPT"
+      ],
+      "captureCount": 0,
+      "statuses": {},
+      "scope": "WORK_HOSTING_SECURITY_SENSITIVE",
+      "verification": "STATIC_CALLSITE"
+    }
+  ]
+}

package/src/api/index.js

@@ -5,9 +5,25 @@ const auth = require('../auth');
 const paths = require('../config/paths');
 const direct = require('../transport/direct/http-client');
 const catalogData = require('./catalog.json');
+const discoveredData = require('./discovered.json');
+const browserObservedData = require('./browser-observed.json');
+const contracts = require('./contracts.json');
 
-const catalog = Object.freeze(catalogData.entries.map((entry) => Object.freeze({ ...entry })));
-const summary = Object.freeze({ ...catalogData.summary, source: catalogData.source });
+const catalog = Object.freeze([...catalogData.entries, ...discoveredData.entries, ...browserObservedData.entries].map((entry) =>
+  Object.freeze({ ...entry, ...(contracts[entry.key] || {}) })));
+if (new Set(catalog.map((entry) => entry.key)).size !== catalog.length ||
+    new Set(catalog.map((entry) => entry.name)).size !== catalog.length) {
+  throw new Error('ChatGPT Web API catalog contains duplicate keys or function names');
+}
+const summary = Object.freeze({
+  ...catalogData.summary,
+  total: catalog.length,
+  publicRequest: catalog.filter((entry) => entry.client === 'PublicRequest').length,
+  supplemental: discoveredData.entries.length,
+  browserObserved: browserObservedData.entries.length,
+  source: catalogData.source,
+  supplementSource: discoveredData.source
+});
 
 const readSessionHeaders = (env) => {
   const file = paths.sessionFile(env);
@@ -103,7 +119,41 @@ 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);
+  for (const parameter of entry.requiredQuery || []) {
+    const value = options.query?.[parameter];
+    if (typeof value !== 'string' || !value.trim()) {
+      const err = new Error(`ChatGPT API requires query parameter ${parameter}: ${entry.key}`);
+      err.code = 'API_QUERY_PARAMETER_REQUIRED';
+      err.parameter = parameter;
+      err.route = entry.route;
+      throw err;
+    }
+  }
+  for (const field of entry.requiredBodyFields || []) {
+    if (!options.body || typeof options.body !== 'object' || !Object.hasOwn(options.body,field) ||
+        options.body[field] === undefined || options.body[field] === null) {
+      const err = new Error(`ChatGPT API requires body field ${field}: ${entry.key}`);
+      err.code='API_BODY_PARAMETER_REQUIRED';
+      err.parameter=field;
+      err.route=entry.route;
+      throw err;
+    }
+  }
+  if (entry.bodyAnyOf?.length && !entry.bodyAnyOf.some(field =>
+    typeof options.body?.[field] === 'string' && options.body[field].trim())) {
+    const err = new Error(`ChatGPT API requires one of ${entry.bodyAnyOf.join(', ')}: ${entry.key}`);
+    err.code='API_BODY_PARAMETER_REQUIRED';
+    err.parameter=entry.bodyAnyOf.join('|');
+    err.route=entry.route;
+    throw err;
+  }
+  const rendered = renderRoute(entry.route, options);
+  // PublicRequest uses /public-api as its base. Captured wire paths already include it.
+  const endpoint = entry.client === 'PublicRequest' && !rendered.startsWith('/public-api/')
+    ? '/public-api' + rendered : rendered;
+  // Captured 307 redirect: /models/ canonicalizes to /models. Keep the catalog alias callable.
+  const canonicalEndpoint = endpoint === '/backend-api/models/' ? '/backend-api/models' : endpoint;
+  const target = appendQuery(canonicalEndpoint, options.query);
   const context = await bindContext(entry, options);
   const responseType = options.responseType === 'text' ? 'text' : 'json';
   const request = responseType === 'text'
@@ -111,7 +161,7 @@ exports.invoke = async (reference, options = {}) => {
     : (options.requestJson || direct.requestJson);
   const requestOptions = {
     method: entry.method,
-    route: entry.route,
+    route: canonicalEndpoint === endpoint ? entry.route : canonicalEndpoint,
     retry: false,
     ...(options.body === undefined ? {} : { body: options.body }),
     ...(options.headers ? { headers: options.headers } : {}),
@@ -133,7 +183,15 @@ exports.invoke = async (reference, options = {}) => {
   }
   if (options.rawResponse === true) return response;
   if (responseType === 'text') return response.text ?? '';
-  return response.json ?? { success: true };
+  if (response.status === 204 || response.status === 205) return { success: true };
+  if (response.json === null || response.json === undefined) {
+    const error = new Error(`ChatGPT API expected JSON but received no valid JSON: ${entry.method} ${entry.route}`);
+    error.code = 'API_UNEXPECTED_RESPONSE';
+    error.status = response.status;
+    error.route = entry.route;
+    throw error;
+  }
+  return response.json;
 };
 
 const byKey = Object.create(null);

package/src/cli/sdk-dispatch.js

@@ -0,0 +1,341 @@
+'use strict';
+
+// Generic CLI adapter for the public SDK. No duplicate endpoint registry or operation implementation.
+const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
+const secretKey = /(?:access[_-]?token|refresh[_-]?token|id[_-]?token|auth(?:orization)?|cookie|password|passphrase|secret|credential|csrf|api[_-]?key|session[_-]?token|private[_-]?key)/i;
+const safeReaderName = /^(?:(?:get|list|read|find|search|has|is|can|check|describe|inspect|status|conversations)$|(?:get|list|read|find|search|has|is|can|check|describe|inspect|status)[A-Z_])/;
+const error = (message) => Object.assign(new Error(message), { code: 'CLI_USAGE', exitCode: 2 });
+const own = (obj, key) => {
+  if (!obj || typeof obj !== 'object' && typeof obj !== 'function' || forbiddenKeys.has(key)) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+  return descriptor && Object.hasOwn(descriptor, 'value') ? descriptor.value : undefined;
+};
+const json = (value) => JSON.stringify(value, null, 2);
+const publicOauthMetadata = new Set([
+  'authorization_url','authorization_server_base','authorization_response_iss_parameter_supported'
+]);
+const safeOauthMetadata = (key, entry) => {
+  if (!publicOauthMetadata.has(key)) return false;
+  if (key === 'authorization_response_iss_parameter_supported') return typeof entry === 'boolean' || entry === null;
+  if (typeof entry !== 'string') return false;
+  try {
+    const url = new URL(entry);
+    return url.protocol === 'https:' && !url.username && !url.password && !url.hash &&
+      [...url.searchParams.keys()].every(param =>
+        !/(token|code|state|nonce|secret|password|credential|key)/i.test(param));
+  } catch { return false; }
+};
+const redact = (value, depth = 0, seen = new WeakSet(), oauthMetadata = false) => {
+  if (depth > 30) return '[DEPTH_LIMIT]';
+  if (!value || typeof value !== 'object') return value;
+  if (seen.has(value)) return '[CIRCULAR]';
+  seen.add(value);
+  if (Array.isArray(value)) return value.map(entry => redact(entry, depth + 1, seen, oauthMetadata));
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => {
+    const isConfig = key === 'oauth_config' && entry && typeof entry === 'object' && !Array.isArray(entry);
+    const allowMetadata = oauthMetadata && safeOauthMetadata(key, entry);
+    return [key, secretKey.test(key) && !isConfig && !allowMetadata
+      ? '[REDACTED]' : redact(entry, depth + 1, seen, oauthMetadata || !!isConfig)];
+  }));
+};
+const show = (stdout, value) => stdout(json(redact(value)));
+const jsonArgument = (input, flag, kind) => {
+  let value;
+  try { value = JSON.parse(input); }
+  catch { throw error(flag + ' requires valid JSON'); }
+  if (kind === 'array' && !Array.isArray(value)) throw error(flag + ' must be a JSON array');
+  if (kind === 'object' && (value === null || typeof value !== 'object' || Array.isArray(value)))
+    throw error(flag + ' must be a JSON object');
+  return value;
+};
+const queryArgument = (input) => {
+  if (input.startsWith('{')) return jsonArgument(input, '--query', 'object');
+  if (!input.includes('=')) throw error('--query requires JSON or name=value parameters');
+  const query = {};
+  for (const [name,value] of new URLSearchParams(input)) {
+    if (!name || forbiddenKeys.has(name)) throw error('Invalid --query key');
+    if (Object.hasOwn(query,name)) {
+      const prior=query[name];
+      query[name]=Array.isArray(prior)?[...prior,value]:[prior,value];
+    } else query[name]=value;
+  }
+  return query;
+};
+const optionsFrom = (args, allowed) => {
+  const flags = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const key = args[index];
+    if (!allowed.includes(key)) throw error('Unknown option: ' + key);
+    if (Object.hasOwn(flags, key)) throw error('Duplicate option: ' + key);
+    if (key === '--allow-write' || key === '--json') { flags[key] = true; continue; }
+    if (index + 1 >= args.length || args[index + 1].startsWith('--'))
+      throw error('Missing value after ' + key);
+    flags[key] = args[++index];
+  }
+  return flags;
+};
+const getPublicFunction = (runtime, path) => {
+  if (typeof path !== 'string' || !/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/.test(path)) return null;
+  const parts = path.split('.');
+  if (parts[0] === 'api' || parts.some(part => forbiddenKeys.has(part))) return null;
+  let current = runtime;
+  for (const part of parts) current = own(current, part);
+  return typeof current === 'function' ? current : null;
+};
+const availableFunctions = (runtime, namespace) => {
+  const found = [];
+  const visit = (obj, prefix, depth) => {
+    if (!obj || typeof obj !== 'object' || depth > 5) return;
+    for (const key of Object.keys(obj)) {
+      if (forbiddenKeys.has(key)) continue;
+      const value = own(obj, key);
+      const name = prefix ? prefix + '.' + key : key;
+      if (typeof value === 'function') found.push(name);
+      else if (value && typeof value === 'object' && depth < 5) visit(value, name, depth + 1);
+    }
+  };
+  for (const owner of Object.keys(runtime)) {
+    if (owner === 'api' || forbiddenKeys.has(owner) || namespace && owner !== namespace) continue;
+    visit(own(runtime, owner), owner, 0);
+  }
+  return found.sort();
+};
+const writeRequired = (method) => !['GET','HEAD','OPTIONS'].includes(String(method || '').toUpperCase());
+
+const sdkNamespace = (runtime, key) => {
+  if (typeof key !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(key) ||
+      key === 'api' || forbiddenKeys.has(key)) return null;
+  const candidate = own(runtime, key);
+  return candidate && typeof candidate === 'object' ? candidate : null;
+};
+const namespaceHelp = (runtime, name) => {
+  if (!sdkNamespace(runtime, name)) throw error('Unknown SDK namespace: ' + name);
+  const methods = availableFunctions(runtime, name).map(path => path.slice(name.length + 1));
+  return [
+    'zgpt ' + name + ' — SDK namespace',
+    '',
+    'Usage: zgpt ' + name + ' <method> [arguments...] [--args JSON_ARRAY] [--allow-write]',
+    'Methods (' + methods.length + '):',
+    ...methods.map(method => '  zgpt ' + name + ' ' + method),
+    '',
+    'Details: zgpt help ' + name,
+    'Run state-changing methods explicitly with --allow-write.'
+  ].join('\n');
+};
+const apiFamilies = (api) => {
+  const counts = new Map();
+  for (const item of Array.isArray(own(api, 'catalog')) ? api.catalog : []) {
+    if (typeof item.family === 'string' && item.family) {
+      counts.set(item.family, (counts.get(item.family) || 0) + 1);
+    }
+  }
+  return [...counts].sort((a, b) => a[0].localeCompare(b[0]));
+};
+const apiRootHelp = (api, complete = false) => {
+  const families = apiFamilies(api);
+  const visible = complete ? families : families.slice(0, 18);
+  return [
+    'zgpt api — ChatGPT Web API catalog',
+    '',
+    'Usage:',
+    '  zgpt api <family> [methodName]',
+    '  zgpt api <family> list [--method GET] [--json]',
+    '  zgpt api list [--family NAME] [--method GET] [--json]',
+    '  zgpt api show "GET /backend-api/..."',
+    '  zgpt api invoke "GET /backend-api/..."',
+    '',
+    'API families (' + families.length + '):',
+    ...visible.map(([name, count]) => '  ' + name.padEnd(27) + count + ' routes'),
+    ...(visible.length < families.length ? ['  ... (' + (families.length - visible.length) + ' more: zgpt api families)'] : []),
+    '',
+    'View a family: zgpt api <family>',
+    'Routes are evidence-backed and not all are live-verified.'
+  ].join('\n');
+};
+const apiFamilyHelp = (api, family) => {
+  const matching = api.catalog.filter(item => item.family === family);
+  if (!matching.length) throw error('Unknown API family: ' + family);
+  return [
+    'zgpt api ' + family + ' — ' + matching.length + ' routes',
+    '',
+    'Usage: zgpt api ' + family + ' <methodName> [--path-values JSON_ARRAY] [--query JSON_OBJECT]',
+    '',
+    ...matching.map(item => '  zgpt api ' + family + ' ' + item.name + '  [' + item.method + ' ' + item.route + ']'),
+    '',
+    'Writes require --allow-write. API routes may be provisional.'
+  ].join('\n');
+};
+exports.help = (runtime = require('../index')) => {
+  const categories = Object.keys(runtime)
+    .filter(name => name !== 'api' && sdkNamespace(runtime, name))
+    .sort()
+    .map(name => [name, availableFunctions(runtime, name).length]);
+  const api = own(runtime, 'api');
+  const total = api && Array.isArray(api.catalog) ? api.catalog.length : 0;
+  return [
+    'Zero ChatGPT CLI',
+    '',
+    'Usage:',
+    '  zgpt <namespace> <method> [arguments...] [--args JSON_ARRAY]',
+    '  zgpt help <namespace>',
+    '  zgpt api <family> <methodName> [options]',
+    '',
+    'SDK namespaces:',
+    ...categories.map(([name, count]) => '  ' + name.padEnd(17) + count + ' functions'),
+    ...(api ? ['  api'.padEnd(19) + total + ' catalog routes'] : []),
+    '',
+    'Examples:',
+    '  zgpt profile getMe',
+    '  zgpt project listProjects',
+    '  zgpt help profile',
+    '  zgpt api models',
+    '',
+    'Legacy aliases (still supported):',
+    '  zgpt login | logout | auth-status',
+    '  zgpt conversations list [--json]',
+    '  zgpt get <conversation-id> [--limit N|A-B] [--debug|--json]',
+    '  zgpt export <conversation-id> [--out <path>]',
+    '  zgpt retry <conversation-id>',
+    '  zgpt functions [--namespace NAME] [--json]',
+    '  zgpt call <namespace.function> [--args JSON_ARRAY] [--allow-write]',
+    '',
+    'Change operations require --allow-write on the grouped command interface.'
+  ].join('\n');
+};
+
+async function apiCommand(argv, runtime, stdout) {
+  const api = own(runtime, 'api');
+  if (!api) throw error('The loaded SDK has no API catalog');
+  const action = argv[1];
+  if (!action || action === 'help' || action === '--help') {
+    if (argv.length > 2) throw error('Usage: zgpt api help');
+    stdout(apiRootHelp(api));
+    return 0;
+  }
+  if (action === 'families') {
+    if (argv.length > 3 || argv[2] && argv[2] !== '--json') throw error('Usage: zgpt api families [--json]');
+    const families = apiFamilies(api);
+    if (argv[2] === '--json') show(stdout, families.map(([name,count]) => ({name,count})));
+    else stdout(apiRootHelp(api, true));
+    return 0;
+  }
+  // Any family discovered in the SDK catalog is a navigable CLI command.
+  if (!['list','show','invoke'].includes(action)) {
+    if (!Array.isArray(own(api, 'catalog'))) throw error('The loaded SDK does not expose api.catalog');
+    if (!apiFamilies(api).some(([name]) => name === action)) throw error('Unknown API family: ' + action);
+    const selected = argv[2];
+    if (!selected || selected === 'help' || selected === '--help') {
+      if (argv.length > 3) throw error('Usage: zgpt api ' + action + ' help');
+      stdout(apiFamilyHelp(api, action));
+      return 0;
+    }
+    if (selected === 'list') {
+      const flags = optionsFrom(argv.slice(3), ['--method','--json']);
+      const rows = api.catalog.filter(item => item.family === action &&
+        (!flags['--method'] || item.method === flags['--method'].toUpperCase()));
+      if (flags['--json']) show(stdout, rows);
+      else stdout(rows.map(item => item.key).join('\\n'));
+      return 0;
+    }
+    const entry = api.catalog.find(item => item.family === action &&
+      (item.name === selected || item.key === selected));
+    if (!entry) throw error('Unknown API method in ' + action + ': ' + selected);
+    return apiCommand(['api','invoke',entry.key,...argv.slice(3)], runtime, stdout);
+  }
+  if (action === 'list') {
+    if (typeof own(api, 'list') !== 'function') throw error('The loaded SDK does not expose api.list');
+    const opts = optionsFrom(argv.slice(2), ['--family', '--method', '--json']);
+    const criteria = {};
+    if (opts['--family']) criteria.family = opts['--family'];
+    if (opts['--method']) criteria.method = opts['--method'].toUpperCase();
+    const rows = api.list(criteria);
+    if (opts['--json']) show(stdout, rows);
+    else stdout(rows.map(item => item.key).join('\n'));
+    return 0;
+  }
+  if (action === 'show') {
+    if (!Array.isArray(own(api, 'catalog'))) throw error('The loaded SDK does not expose api.catalog');
+    const key = argv[2];
+    if (!key || argv.length !== 3) throw error('Usage: zgpt api show "GET /backend-api/..."');
+    const entry = api.catalog.find(item => item.key === key || item.name === key);
+    if (!entry) throw error('Unknown API capability: ' + key);
+    show(stdout, entry);
+    return 0;
+  }
+  if (action === 'invoke') {
+    if (!Array.isArray(own(api, 'catalog')) || typeof own(api, 'invoke') !== 'function')
+      throw error('The loaded SDK does not expose api.invoke/catalog');
+    const key = argv[2];
+    if (!key) throw error('API method and route key required');
+    const entry = api.catalog.find(item => item.key === key || item.name === key);
+    if (!entry) throw error('Unknown API capability: ' + key);
+    const flags = optionsFrom(argv.slice(3),
+      ['--path-values', '--query', '--body', '--options', '--allow-write']);
+    const options = flags['--options'] === undefined ? {} : jsonArgument(flags['--options'], '--options', 'object');
+    for (const key of ['token','sessionHeaders','requestJson','requestText','env','sessionFile','headers','rawResponse','auth'])
+      if (Object.hasOwn(options, key)) throw error('CLI cannot override SDK authentication/transport: ' + key);
+    if (flags['--path-values']) options.pathValues = jsonArgument(flags['--path-values'], '--path-values', 'array');
+    if (flags['--query']) options.query = queryArgument(flags['--query']);
+    if (flags['--body']) options.body = jsonArgument(flags['--body'], '--body', 'object');
+    if (writeRequired(entry.method) && !flags['--allow-write']) throw error('Non-read API requires --allow-write');
+    if (!writeRequired(entry.method) && Object.hasOwn(options, 'body')) throw error('Read-only API cannot use --body');
+    show(stdout, await api.invoke(entry.key, options));
+    return 0;
+  }
+  throw error('Usage: zgpt api list|show|invoke');
+}
+
+async function callCommand(argv, runtime, stdout) {
+  const name = argv[1];
+  const fn = getPublicFunction(runtime, name);
+  if (!fn) throw error('Unknown SDK function: ' + (name || '(missing)'));
+  const tail = argv.slice(2);
+  const firstFlag = tail.findIndex(item => item.startsWith('--'));
+  const positionals = firstFlag === -1 ? tail : tail.slice(0, firstFlag);
+  const flags = optionsFrom(firstFlag === -1 ? [] : tail.slice(firstFlag), ['--args', '--allow-write']);
+  if (positionals.length && flags['--args'] !== undefined) throw error('Use positional arguments or --args, not both');
+  const args = flags['--args'] === undefined ? positionals : jsonArgument(flags['--args'], '--args', 'array');
+  const method = name.split('.').at(-1);
+  if (!safeReaderName.test(method) && !flags['--allow-write']) throw error('Mutating/unknown SDK function requires --allow-write');
+  show(stdout, await fn(...args));
+  return 0;
+}
+
+exports.run = async (argv, options = {}) => {
+  const runtime = options.runtime || require('../index');
+  const stdout = options.stdout || console.log;
+  const stderr = options.stderr || console.error;
+  try {
+    if (argv[0] === 'help' || argv[0] === '--help' || argv[0] === '-h') {
+      const name = argv[1];
+      if (argv.length > 3 || argv.length === 3 && name !== 'api') throw error('Usage: zgpt help [namespace]');
+      if (!name) stdout(exports.help(runtime));
+      else if (name === 'api') stdout(argv[2] ? apiFamilyHelp(own(runtime, 'api'), argv[2]) : apiRootHelp(own(runtime, 'api')));
+      else stdout(namespaceHelp(runtime, name));
+      return 0;
+    }
+    if (argv[0] === 'functions') {
+      const flags = optionsFrom(argv.slice(1), ['--namespace','--json']);
+      if (flags['--namespace'] && !Object.hasOwn(runtime, flags['--namespace']))
+        throw error('Unknown SDK namespace: ' + flags['--namespace']);
+      const names = availableFunctions(runtime, flags['--namespace']);
+      if (flags['--json']) show(stdout, names);
+      else stdout(names.join('\n'));
+      return 0;
+    }
+    if (argv[0] === 'api') return await apiCommand(argv, runtime, stdout);
+    if (argv[0] === 'call') return await callCommand(argv, runtime, stdout);
+    if (sdkNamespace(runtime, argv[0])) {
+      if (!argv[1] || argv[1] === 'help' || argv[1] === '--help') {
+        if (argv.length > 2) throw error('Usage: zgpt ' + argv[0] + ' [method]');
+        stdout(namespaceHelp(runtime, argv[0]));
+        return 0;
+      }
+      return await callCommand(['call', argv[0] + '.' + argv[1], ...argv.slice(2)], runtime, stdout);
+    }
+    throw error('Unknown SDK namespace or dispatch command: ' + (argv[0] || '(missing)'));
+  } catch (cause) {
+    stderr((cause.code === 'CLI_USAGE' ? '' : (cause.code ? cause.code + ': ' : '')) + (cause.message || 'SDK dispatch failed'));
+    return cause.exitCode || 1;
+  }
+};

package/src/cli.js

@@ -5,19 +5,7 @@ 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 usage = () => require('./cli/sdk-dispatch').help();
 
 const parseOptions = (argv) => {
   const result = { json: false, debug: false, limit: null, out: null };
@@ -49,9 +37,14 @@ exports.run = async (argv = [], options = {}) => {
   const stderr = options.stderr || console.error;
   const command = argv[0] || 'help';
   if (command === 'help' || command === '--help' || command === '-h') {
-    stdout(usage());
-    return 0;
+    return require('./cli/sdk-dispatch').run(argv, { ...options, stdout, stderr });
   }
+  // SDK namespaces are routed dynamically; legacy aliases below remain compatible.
+  const runtime = options.runtime || require('./index');
+  if (command === 'functions' || command === 'call' || command === 'api' ||
+      Object.hasOwn(runtime, command) && command !== 'api' && typeof runtime[command] === 'object') {
+    return require('./cli/sdk-dispatch').run(argv, { ...options, runtime, stdout, stderr });
+  }
   if (!['login', 'logout', 'auth-status', 'conversations', 'get', 'export', 'stream-status', 'retry', 'resume'].includes(command)) {
     stderr(`Unknown command: ${command}\n\n${usage()}`);
     return 2;

package/src/connector/index.js

@@ -2,5 +2,6 @@
 
 const read = require('./read');
 const write = require('./write');
+const mcp = require('./mcp');
 
-Object.assign(exports, read, write);
+Object.assign(exports, read, write, mcp);