@miruzero/zgpt 0.1.4 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # Zero ChatGPT
 
-`M:\Zero_ChatGPT` is the standalone ChatGPT runtime and the only default owner of ChatGPT state.
+`@miruzero/zgpt` is the standalone ChatGPT SDK and CLI package. `M:\Zero_ChatGPT` is the developer checkout path, **not** a module import path for npm users.
 
 ## Scope
 
@@ -12,7 +12,7 @@ This package contains only ChatGPT-specific runtime code:
 - ChatGPT connector operations
 - ChatGPT Web protocol mechanics
 - direct HTTP/SSE transport
-- ChatGPT mutable state under `M:\Zero_ChatGPT\state`
+- ChatGPT mutable state in the runtime's configurable `state/` directory (`ZERO_CHATGPT_STATE_DIR`)
 
 It contains no Zero Core, MCP, Agent orchestration, or generic device/task runtime. The CLI is a thin adapter over the same public SDK exports.
 
@@ -25,13 +25,31 @@ npm install -g @miruzero/zgpt@latest
 zgpt
 ```
 
-For a project-local installation, use `npx`:
+For a project-local installation using the published package name:
 
 ```sh
 npm install @miruzero/zgpt@latest
 npx zgpt
 ```
 
+If you want the **short JavaScript import** `require('zgpt')`, install the published scoped package with an npm alias:
+
+```sh
+npm install zgpt@npm:@miruzero/zgpt@latest
+```
+
+```js
+const chatgpt = require('zgpt');
+```
+
+The two installation forms are alternatives. If you installed `@miruzero/zgpt` under its original name, import it using that same name:
+
+```js
+const chatgpt = require('@miruzero/zgpt');
+```
+
+The npm package name and the CLI binary name are independent; installing **only** `@miruzero/zgpt` does not create a local `node_modules/zgpt` alias.
+
 The package exposes the `zgpt` executable through npm's `bin` field. A local `npm install` does not add `node_modules/.bin` to the parent shell's PATH, so use `npx zgpt` for local installs or install globally for the bare `zgpt` command.
 
 ### Hierarchical SDK → CLI automatic command discovery
@@ -57,20 +75,28 @@ zgpt api invoke "GET /public-api/conversation_limit"
 
 ## Public API
 
+After `npm install zgpt@npm:@miruzero/zgpt@latest`:
+
 ```js
-const chatgpt = require('M:/Zero_ChatGPT');
+const chatgpt = require('zgpt');
 
+async function main() {
+// Configure ZERO_CHATGPT_STATE_DIR and authenticate before these calls.
+// Session acquisition can be requested via chatgpt.session.acquire() if needed.
 await chatgpt.auth.ensure();
-await chatgpt.session.acquire();
-await chatgpt.conversation.get(id);
-await chatgpt.conversation.send(id, message);
-await chatgpt.project.listProjects(options);
-await chatgpt.connector.listConnectors(options);
+const conversation = await chatgpt.conversation.get('YOUR_CONVERSATION_ID');
+const projects = await chatgpt.project.list();
+const connectors = await chatgpt.connector.listConnectors();
+
+// Mutations happen only when explicitly invoked:
+// await chatgpt.conversation.send('YOUR_CONVERSATION_ID', 'Hello');
+// await chatgpt.conversation.create('New conversation');
+// await chatgpt.project.create('My project');
 
 // Profile and Chat settings (only when entitled; writes require explicit bodies)
 await chatgpt.profile.getMe();
 await chatgpt.profile.getCreator();
-await chatgpt.profile.updateCreator({ body: { display_name: 'Sky' } });
+// await chatgpt.profile.updateCreator({ body: { display_name: 'Developer' } });
 await chatgpt.settings.getUser();
 await chatgpt.settings.getConsent();
 await chatgpt.settings.getNotifications();
@@ -78,7 +104,7 @@ await chatgpt.profile.getAuraIdentity();  // GET /backend-api/aura/identity
 
 // ChatGPT Web API catalog: saved Web evidence plus verified supplemental routes.
 // Generic routes require appropriate account permissions and exact request contracts.
-console.log(chatgpt.api.summary.total); // 1287 (includes provisional paths)
+console.log(chatgpt.api.summary.total); // 1291 (includes provisional paths)
 const route = chatgpt.api.find({ method: 'GET', route: '/api/auth/session' });
 const authSession = await chatgpt.api.invoke(route.key);
 const limits = await chatgpt.api.invoke('GET /public-api/conversation_limit');
@@ -87,10 +113,16 @@ const limits = await chatgpt.api.invoke('GET /public-api/conversation_limit');
 // Parameterized route and explicit one-shot writes (only with a verified payload):
 // await chatgpt.api.invoke('POST /backend-api/hosting/sites/{id}/access',
 //   { pathValues: [siteId], body: verifiedBody });
+}
+
+main().catch(error => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
 ```
 
-Discovered Web endpoints and their evidence are stored in `src/api/discovered.json`.
-Historical endpoints remain in `src/api/catalog.json`; the runtime combines both.
+Saved web evidence is stored in `src/api/discovered.json`, while the four authenticated Browser Network GET discoveries are in `src/api/browser-observed.json`.
+Historical endpoints remain in `src/api/catalog.json`; the runtime combines all three catalogs. Runtime query contracts are stored separately in `src/api/contracts.json`.
 `api.byKey`, `api.functions` and `api.groups` provide typed route-name dispatch.
 This is an **undocumented Web endpoint catalog**, not a guarantee of API stability,
 authorization, correct mutation payloads, or complete browser-feature parity.
@@ -101,4 +133,25 @@ authorization, correct mutation payloads, or complete browser-feature parity.
 - Session exchange transport must be supplied explicitly; no browser/CDP transport is implicit.
 - 429 opens shared cooldown and is not amplified by retries.
 - No hardcoded credentials or secret-bearing diagnostics.
-- Default writable state lives only under `M:\Zero_ChatGPT\state`.
+- By default, state is stored in `state/` relative to the installed package. For an npm-installed/global package, configure `ZERO_CHATGPT_STATE_DIR` to a **writable, user-owned directory outside `node_modules`** before authenticating. Never commit or publish this state.
+
+## API verification and request contracts (source checkout)
+
+A catalog entry is **not** a proof of a working API. The local verification report classifies all 1,287 routes, and the bounded auditor uses a known-safe GET allowlist, with no mutations, retries, response bodies, cookies, or credentials persisted.
+
+```powershell
+npm run api:audit
+npm run api:audit:live -- --start 0 --max 32
+npm run api:audit:live -- --start 32 --max 25
+
+zgpt api models getModelsTrailingSlash
+zgpt api images getImagesPromptItems --query surface=sketch_followups
+zgpt api apps getAppsDirectoryBrowse --query category=productivity
+zgpt api composer getComposerItems --query 'entrypoint=chat&limit=10'
+```
+
+The `--query` flag accepts shell-friendly `name=value` or `name=value&name2=value2`, as well as a JSON object. For GET routes requiring query parameters, see `zgpt api show "GET /backend-api/..."` and `src/api/contracts.json`. The auditor and capture scanners are developer scripts in this source checkout and are not bundled in the npm package. Version `0.1.5` includes the release-ready SDK/CLI changes described above once published.
+
+### Custom MCP server CRUD and action refresh
+
+The connector namespace supports MCP server creation, updates, deletion, OAuth metadata discovery, action refresh and `disconnectConnectorLink` (unlink a connected account without deleting the server definition). Discover exact SDK methods with `zgpt help connector`. **Live verified:** tunnel listing, OAuth discovery, and linked-action refresh (4 actions returned). **Mock verified only:** server create/edit/delete and connector unlink (no live destructive actions). Creating an OAuth-enabled connector auto-discovers metadata unless explicitly overridden. Refresh and unlink take a `linkId`, not a server definition ID. See the included `docs/custom-mcp-management-api.md` for request contracts and validation boundaries.

package/docs/architecture.md

@@ -74,4 +74,4 @@ conversation is the only owner of stream diagnosis and repair. Callers request a
 5. External ChatGPT responses are validated before state mutation.
 6. This package owns only ChatGPT runtime state.
 7. No Zero Core, MCP, Agent, device, task, or adapter implementation lives here.
-8. No background polling or hidden retry loop is allowed; recovery work occurs only on the active demand or an explicit retry demand.
+8. Loops, pagination, retry, and polling are allowed when required by the flow; they must have a measurable progress/termination condition, an explicit owner, and bounded failure recovery. Repeated writes must not be replayed without an idempotency guarantee. The current ChatGPT stream recovery remains demand-driven; no blanket prohibition on loops is implied.

package/docs/custom-mcp-management-api.md

@@ -0,0 +1,132 @@
+# Custom MCP Server API — Web Client source audit (2026-10-12)
+
+## Status and scope
+
+**Implemented in local source, no remote mutations performed.** The source of truth is existing ChatGPT Web callsites in the captured files `C:\Users\Administrator\Documents\OSSGPT\chatgpt.com\cdn\assets\conversation-small-cyhg2evird2sa17j.js` and `c2675c8c-j30y5ypuebsjl0k8.js`. The `OAI-Product-Sku` header was resolved from an imported constant in `4813494d-k4tqhmof689yx2je.js`; Web sends `OAI-Product-Sku: CONNECTOR_SETTING`.
+
+Browser form fields: name, optional description, HTTPS server URL or `tunnel_<32 lowercase letters/digits>`, optional PNG icon (data URL; max 10 KB), authentication selection. The Web flow builds `auth_request` from supported authentication types and OAuth discovery before creating a connector. OAuth connection/linking is a separate operation after creation.
+
+| Operation | Web route | Body from Web source | Verification |
+| --- | --- | --- | --- |
+| Create | POST `/backend-api/aip/connectors/mcp` | `{name,description,logo_url,mcp_url OR tunnel_id,custom_headers?,auth_request}` | Static callsite; SDK mocked |
+| Read detail | GET `/backend-api/aip/connectors/{id}` | Path `connector_id` | Static callsite; SDK mocked |
+| Rename | PATCH `/backend-api/aip/connectors/{id}/name` | `{name}` | Static callsite; SDK mocked |
+| Description | PATCH `/backend-api/aip/connectors/{id}/description` | `{description}` | Static callsite; SDK mocked |
+| Icon | PATCH `/backend-api/aip/connectors/{id}/logo` | `{logo_url}` | Static callsite; SDK mocked |
+| Delete | DELETE `/backend-api/aip/connectors/{id}` | Path `connector_id` | Static callsite; SDK mocked |
+| Refresh tools | POST `/backend-api/aip/connectors/mcp/refresh_actions` | `{link_id}` **not** connector ID | Static callsite; SDK mocked; previous SDK wrapper exists |
+| OAuth discovery | POST `/backend-api/aip/connectors/mcp/oauth_config` | `{mcp_url OR tunnel_id,custom_headers}` | **Live SDK and CLI verified using `https://mcps.devteam.sc/core`** |
+| List tunnels | GET `/backend-api/aip/connectors/mcp/tunnels` | None | **Live SDK HTTP 200**; CLI Exit 0 |
+
+No confirmed endpoint for editing an existing server's **MCP URL** directly. Do not infer that renaming/reloading edits the transport URL; recreation may be required but was not performed.
+
+## SDK API
+
+The public exports from `src/connector/mcp.js` are automatically exposed under `zgpt.connector` and as CLI commands via the existing dispatch logic:
+
+```js
+const zgpt = require('@miruzero/zgpt');
+
+// Real GET, with authorized local session:
+const {tunnels} = await zgpt.connector.listCustomMcpTunnels();
+
+// Read-only metadata discovery from the authenticated ChatGPT Web backend.
+const discovered = await zgpt.connector.getCustomMcpOAuthConfig(
+  'https://mcps.devteam.sc/core'
+);
+console.log(discovered.oauth_config.type); // OAUTH
+// Only call the next step if you intend to create an actual connector.
+// Default: auto-discover auth and preserve PKCE, scope and registration metadata.
+const created = await zgpt.connector.createCustomMcpServer({
+  name: 'DevTeam MCP',
+  mcpUrl: 'https://mcps.devteam.sc/core'
+});
+// To bypass discovery, supply a fully configured authRequest explicitly,
+// or set authentication:'NONE' only for intentionally unauthenticated servers.
+await zgpt.connector.renameCustomMcpServer({connectorId:created.connector.id,name:'Renamed MCP'});
+// NOTE: use a linkId returned by the connection/link flow, not created.connector.id:
+// await zgpt.connector.reloadCustomMcpServerActions({linkId:'link_...'});
+// Explicit destructive command only when intended:
+// await zgpt.connector.deleteCustomMcpServer({connectorId:created.connector.id});
+```
+
+**The above example includes mutations and was NOT executed on a live account.** Use only against servers you intend to create/change/delete.
+
+## CLI
+
+```powershell
+zgpt help connector
+zgpt connector listCustomMcpTunnels
+zgpt connector getCustomMcpOAuthConfig https://mcps.devteam.sc/core
+zgpt api show "POST /backend-api/aip/connectors/mcp"
+```
+
+All methods also appear under `zgpt connector <methodName>`. JSON object arguments are passed via `--args JSON_ARRAY` and all non-read methods require `--allow-write`. The general `api` dispatcher also uses the same catalog and enforces required body fields.
+
+## Verification and outstanding work
+
+- Unit/contract suite: **196/196 tests passed** (full project tests as of 2026-10-12).
+- Live read: `GET /backend-api/aip/connectors/mcp/tunnels` HTTP 200 and matching CLI operation exited 0.
+- Mutations (POST create, PATCH metadata, DELETE, POST refresh) **not live tested**; their success depends on actual owner permissions, OAuth configuration, valid image input and server capabilities.
+- The create function only creates a connector definition. Completing OAuth and linking a server is a separate browser/client flow. The wrapper deliberately does not invent OAuth registration/scopes or auto-install a connector link.
+- `logo_url` supports HTTPS or a PNG Data URL, matching the browser's FileReader path and 10 KB limit; generated artwork was not uploaded.
+- The source changes are local and **not yet included in published npm 0.1.4**.
+
+## Source paths
+
+- `src/connector/mcp.js`
+- `src/connector/write.js`
+- `src/connector/index.js`
+- `src/api/contracts.json`
+- `src/api/index.js`
+- `test/connector-mcp-management.test.js`
+
+## Live OAuth Discovery evidence (2026-10-12, MiruZero)
+
+- Actual MCP URL supplied by user: `https://mcps.devteam.sc/core`.
+- Used the existing authenticated SDK session to call `POST /backend-api/aip/connectors/mcp/oauth_config` with `{mcp_url:'https://mcps.devteam.sc/core', custom_headers:[]}` and product SKU `CONNECTOR_SETTING`.
+- **Live verified:** response carried `oauth_config.type=OAUTH`, resource matching the supplied URL, authorization/token/registration endpoints, `pkce_required=true`, `pkce_methods=['S256']`, `scopes_supported=['mcp:read']`, and `token_endpoint_auth_methods_supported=['none']`.
+- CLI `zgpt connector getCustomMcpOAuthConfig https://mcps.devteam.sc/core` returned Exit 0 and the same safe metadata. CLI now preserves public OAuth discovery fields without exposing client secrets, credentials, access tokens or state-bearing authorization URLs.
+- The local `createCustomMcpServer({name,mcpUrl})` defaults to automatic metadata discovery, maps the returned OAuth configuration into `auth_request.supported_auth`, and only then issues the create POST. This sequencing was tested using a stubbed transport, **not performed on the live user account**.
+- Discovery failures and malformed/unsupported OAuth metadata fail closed; the SDK does **not** switch to `NONE` automatically. To intentionally skip discovery, pass either `authentication:'NONE'` or a previously configured `authRequest`.
+- Connector creation does **not** mean OAuth authorization completed. Registration, PKCE redirect/callback, connector link creation, and action refresh are separate operations. They remain untested against this MCP server and are not automatically triggered.
+- Local source changes are **not** included in the npm release `@miruzero/zgpt@0.1.4` until a new version is published.
+
+## MCP action refresh: live SDK + CLI verification (2026-10-12)
+
+**VERIFIED for one authorized connection on MiruZero.** A user-supplied cURL trace was treated as evidence of the request shape rather than copied into source or the session store. Existing SDK auth/session logic supplied the access token and cookies; only the `linkId` came from the user's request. Neither bearer token, account ID, device ID nor browser fingerprint headers were hard-coded.
+
+Request contract: `POST /backend-api/aip/connectors/mcp/refresh_actions`, body `{link_id}`, `OAI-Product-Sku: CONNECTOR_SETTING`, authenticated via SDK, no automatic HTTP retry. The SDK's legacy `connector.refreshConnectorActions({linkId})` is the single request implementation; `connector.reloadCustomMcpServerActions({linkId})` delegates to it.
+
+Verified:
+- JavaScript SDK `connector.reloadCustomMcpServerActions({linkId: '<authorized-link-id>'})`: completed successfully and returned an `actions` array.
+- Windows CLI `zgpt connector reloadCustomMcpServerActions <authorized-link-id> --allow-write`: exit code **0**, response had an `actions` array containing **4 actions**.
+- Added string-argument convenience `connector.reloadCustomMcpServerActions('<authorized-link-id>')`, auto-exposed to CLI via grouped SDK dispatch.
+- Tests cover a single, non-retried POST with exact body, product-SKU header, automatic CLI write guard, both options-object and string argument support.
+
+Not verified: automatic OAuth linking, creating a connection link, or behavior for other connector accounts. No secrets were persisted from the sample cURL and no unrelated connectors were modified. The response contents and individual action names were intentionally not logged.
+
+## Connected account unlink — Settings “ยกเลิกการเชื่อมต่อ”
+
+**Implemented in SDK and automatically exposed in CLI. The real account link was NOT deleted.**
+
+The user-provided browser cURL shows a connected-account operation that is *different* from deleting the MCP server definition:
+
+- **Disconnect link:** `DELETE /backend-api/aip/connectors/links/{link_id}` (no JSON body)
+- **Delete MCP definition:** `DELETE /backend-api/aip/connectors/{connector_id}`
+- **Refresh linked actions:** `POST /backend-api/aip/connectors/mcp/refresh_actions` with `{link_id}`
+
+`zgpt.connector.disconnectConnectorLink({linkId})` delegates directly to the existing API catalog dispatcher, which binds Zero's current authorization/session and sends the CONNECTOR_SETTING product SKU. It accepts a positional string `linkId` for CLI convenience. It rejects malformed/non-link IDs before executing any HTTP request, and `retry:false` prevents replay of DELETE.
+
+```js
+const zgpt = require('@miruzero/zgpt');
+// Only run to intentionally disconnect an authorized account:
+await zgpt.connector.disconnectConnectorLink({linkId:'link_YOUR_LINK_ID'});
+```
+
+```powershell
+# Destructive: disconnect a link only when intended:
+zgpt connector disconnectConnectorLink link_YOUR_LINK_ID --allow-write
+```
+
+The CLI refuses the command without `--allow-write`. A 204 No Content response normalizes to `{success:true}`, while non-2xx statuses propagate as errors. Tests verify URL/method/no-body, existing injected auth, missing/wrong ID guards, HTTP 403, one-shot execution and CLI write approval. **Only the request shape and the mock transport behavior are verified; live deletion has deliberately not been attempted.** The supplied Bearer token, cookies, account identifiers and browser fingerprint headers were not inserted into the codebase.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miruzero/zgpt",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "commonjs",
   "main": "src/index.js",
   "bin": {
@@ -9,8 +9,11 @@
   "scripts": {
     "start": "src/cli.js",
     "test": "node --test",
+    "prepublishOnly": "npm test",
     "api:rescan": "node scripts/collect-web-api.js",
-    "api:reconcile": "node scripts/reconcile-web-api.js"
+    "api:reconcile": "node scripts/reconcile-web-api.js",
+    "api:audit": "node scripts/audit-web-api.js",
+    "api:audit:live": "node scripts/audit-web-api.js --live"
   },
   "engines": {
     "node": ">=20"
@@ -24,7 +27,8 @@
   "files": [
     "src",
     "README.md",
-    "docs/architecture.md"
+    "docs/architecture.md",
+    "docs/custom-mcp-management-api.md"
   ],
   "publishConfig": {
     "access": "public"

package/src/api/browser-observed.json

@@ -0,0 +1,82 @@
+{
+  "source": "Agent Browser v0.39.0 attached to logged-in chatgpt.com, captured read-only HTTP status metadata; no auth headers or payloads persisted",
+  "observedAt": "2026-10-12",
+  "entries": [
+    {
+      "key": "GET /backend-api/accounts/check/v4-2023-04-27",
+      "method": "GET",
+      "client": "Request",
+      "route": "/backend-api/accounts/check/v4-2023-04-27",
+      "name": "getAccountsCheckV420230427",
+      "family": "accounts",
+      "scope": "CHATGPT_WEB",
+      "evidence": [
+        "AGENT_BROWSER_SESSION_NETWORK"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "verification": "LIVE_BROWSER_HTTP_200",
+      "liveStatus": 200,
+      "observedAt": "2026-10-12"
+    },
+    {
+      "key": "GET /backend-api/ps/plugins/installed",
+      "method": "GET",
+      "client": "Request",
+      "route": "/backend-api/ps/plugins/installed",
+      "name": "getPsPluginsInstalled",
+      "family": "ps",
+      "scope": "CHATGPT_WEB_PLUGINS",
+      "evidence": [
+        "AGENT_BROWSER_SESSION_NETWORK"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "verification": "LIVE_BROWSER_HTTP_200",
+      "liveStatus": 200,
+      "observedAt": "2026-10-12"
+    },
+    {
+      "key": "GET /backend-api/wham/accounts/check",
+      "method": "GET",
+      "client": "Request",
+      "route": "/backend-api/wham/accounts/check",
+      "name": "getWhamAccountsCheck",
+      "family": "wham",
+      "scope": "WORK_ACCOUNTS",
+      "evidence": [
+        "AGENT_BROWSER_SESSION_NETWORK"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "verification": "LIVE_BROWSER_HTTP_200",
+      "liveStatus": 200,
+      "observedAt": "2026-10-12"
+    },
+    {
+      "key": "GET /backend-api/wham/sites/access",
+      "method": "GET",
+      "client": "Request",
+      "route": "/backend-api/wham/sites/access",
+      "name": "getWhamSitesAccess",
+      "family": "wham",
+      "scope": "WORK_SITES",
+      "evidence": [
+        "AGENT_BROWSER_SESSION_NETWORK"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "verification": "LIVE_BROWSER_HTTP_200",
+      "liveStatus": 200,
+      "observedAt": "2026-10-12"
+    }
+  ]
+}

package/src/api/contracts.json

@@ -0,0 +1,101 @@
+{
+  "GET /backend-api/models/config": {
+    "requiredQuery": [
+      "slug"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_SLUG",
+    "runtimeNotes": "Frontend supplies a model slug; live GET with current model slugs returned 404 in this session, so availability remains unverified."
+  },
+  "GET /backend-api/gizmos/user_action_settings": {
+    "requiredQuery": [
+      "gizmo_id"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_GIZMO_ID",
+    "runtimeNotes": "Requires a valid GPT identifier. No permitted GPT ID was available in the tested bootstrap response."
+  },
+  "GET /backend-api/apps/directory/browse": {
+    "requiredQuery": [
+      "category"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_CATEGORY; LIVE_200_CATEGORY_PRODUCTIVITY",
+    "runtimeNotes": "Use a category id from GET /backend-api/apps/directory/apps. Productivity returned HTTP 200 in this session."
+  },
+  "GET /backend-api/composer/items": {
+    "requiredQuery": [
+      "entrypoint"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_ENTRYPOINT; LIVE_200_ENTRYPOINT_CHAT",
+    "runtimeNotes": "The saved web callsite also sends limit and sometimes timezone; the server required entrypoint. entrypoint=chat&limit=10 returned HTTP 200."
+  },
+  "GET /backend-api/images/prompt-items": {
+    "requiredQuery": [
+      "surface"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_SURFACE; LIVE_200_SURFACE_SKETCH_FOLLOWUPS",
+    "runtimeNotes": "The web source passes surface=sketch_followups; live result was HTTP 200."
+  },
+  "POST /backend-api/aip/connectors/mcp": {
+    "requiredBodyFields": [
+      "name",
+      "auth_request"
+    ],
+    "bodyAnyOf": [
+      "mcp_url",
+      "tunnel_id"
+    ],
+    "contractEvidence": "OSSGPT_WEB_ONSUBMIT_CUSTOM_MCP; STATIC_WEB_SAFEPOST",
+    "runtimeNotes": "Create connector definition; no write-side effects tested. Browser UI sends name, description, logo_url, either mcp_url or tunnel_id, optional custom_headers, and auth_request with supported_auth/oauth_client_params/default_scopes/oidc_enabled/use_cimd. Linking/OAuth occurs in a subsequent flow."
+  },
+  "PATCH /backend-api/aip/connectors/{id}/name": {
+    "requiredBodyFields": [
+      "name"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPATCH",
+    "runtimeNotes": "Path connector_id, requestBody {name}. Not live-tested against user data."
+  },
+  "PATCH /backend-api/aip/connectors/{id}/description": {
+    "requiredBodyFields": [
+      "description"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPATCH",
+    "runtimeNotes": "Path connector_id, requestBody {description}; empty description is permitted for clearing. No live mutation test."
+  },
+  "PATCH /backend-api/aip/connectors/{id}/logo": {
+    "requiredBodyFields": [
+      "logo_url"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPATCH",
+    "runtimeNotes": "Path connector_id, requestBody {logo_url}; actual upload step is separate. No live mutation test."
+  },
+  "DELETE /backend-api/aip/connectors/{id}": {
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEDELETE",
+    "runtimeNotes": "Destructive removal of connector definition; never automatically executed by audit."
+  },
+  "DELETE /backend-api/aip/connectors/links/{id}": {
+    "contractEvidence": "USER_PROVIDED_BROWSER_CURL; SDK_MOCK_TEST",
+    "runtimeNotes": "Unlinks a connected account by link_id from ChatGPT Settings. No request body. Requires authenticated session and CONNECTOR_SETTING product SKU. Distinct from deleting the MCP connector definition. Never run against a live link without an explicit unlink instruction."
+  },
+  "POST /backend-api/aip/connectors/mcp/refresh_actions": {
+    "requiredBodyFields": [
+      "link_id"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPOST; EXISTING_CONNECTOR_TEST",
+    "runtimeNotes": "Refresh action list by link_id, NOT connector_id. Side-effecting command; not executed live."
+  },
+  "POST /backend-api/aip/connectors/mcp/oauth_config": {
+    "bodyAnyOf": [
+      "mcp_url",
+      "tunnel_id"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPOST",
+    "runtimeNotes": "RequestBody {mcp_url,custom_headers} or {tunnel_id,custom_headers}; response.oauth_config; potentially queries remote server. Not executed live."
+  },
+  "GET /backend-api/aip/connectors/mcp/tunnels": {
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEGET; LIVE_SDK_HTTP_200",
+    "runtimeNotes": "Read-only GET returned HTTP 200 with a tunnels array in this session."
+  },
+  "GET /backend-api/aip/connectors/{id}": {
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEGET",
+    "runtimeNotes": "Read connector by id; requires authorized connector_id and may include actions. Not probed with user ID."
+  }
+}

package/src/api/index.js

@@ -6,8 +6,11 @@ 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, ...discoveredData.entries].map((entry) => Object.freeze({ ...entry })));
+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');
@@ -17,6 +20,7 @@ const summary = Object.freeze({
   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
 });
@@ -115,11 +119,41 @@ exports.find = (criteria = {}) => exports.list(criteria)[0] || null;
 
 exports.invoke = async (reference, options = {}) => {
   const entry = resolveEntry(reference);
+  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;
-  const target = appendQuery(endpoint, options.query);
+  // 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'
@@ -127,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 } : {}),
@@ -149,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

@@ -3,7 +3,7 @@
 // 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)$|(?:get|list|read|find|search|has|is|can|check|describe|inspect|status)[A-Z_])/;
+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;
@@ -11,14 +11,32 @@ const own = (obj, key) => {
   return descriptor && Object.hasOwn(descriptor, 'value') ? descriptor.value : undefined;
 };
 const json = (value) => JSON.stringify(value, null, 2);
-const redact = (value, depth = 0, seen = new WeakSet()) => {
+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));
-  return Object.fromEntries(Object.entries(value).map(([key, entry]) =>
-    [key, secretKey.test(key) ? '[REDACTED]' : redact(entry, depth + 1, seen)]));
+  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) => {
@@ -30,6 +48,19 @@ const jsonArgument = (input, flag, kind) => {
     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) {
@@ -244,7 +275,7 @@ async function apiCommand(argv, runtime, stdout) {
     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 = jsonArgument(flags['--query'], '--query', 'object');
+    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');

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);

package/src/connector/mcp.js

@@ -0,0 +1,154 @@
+'use strict';
+
+// Browser-derived MCP connector operations. The single SDK API catalog owns routes,
+// authentication, transport, encoding and response handling. Never auto-create a link.
+const api = require('../api');
+
+const bad = (message) => Object.assign(new Error(message), { code: 'BAD_ARGS' });
+const nonempty = (value, field) => {
+  if (typeof value !== 'string' || !value.trim()) throw bad(field + ' is required');
+  return value.trim();
+};
+const safeHttpUrl = (value, field) => {
+  const text = nonempty(value, field);
+  let url;
+  try { url = new URL(text); } catch { throw bad(field + ' must be a valid HTTPS URL'); }
+  if (url.protocol !== 'https:' || url.username || url.password)
+    throw bad(field + ' must be a valid HTTPS URL without embedded credentials');
+  return text;
+};
+const logoValue = (value) => {
+  const input=nonempty(value,'logoUrl');
+  if (input.startsWith('data:')) {
+    const match=/^data:image\/png;base64,([A-Za-z0-9+/]+={0,2})$/.exec(input);
+    if (!match) throw bad('logoUrl must be a PNG data URL');
+    if (Buffer.from(match[1],'base64').length > 10 * 1024)
+      throw bad('logoUrl PNG exceeds the 10 KB maximum');
+    return input;
+  }
+  return safeHttpUrl(input,'logoUrl');
+};
+const makeTarget = ({mcpUrl, tunnelId}) => {
+  if (mcpUrl != null && tunnelId != null) throw bad('Choose either mcpUrl or tunnelId, not both');
+  if (mcpUrl != null) return {mcp_url:safeHttpUrl(mcpUrl,'mcpUrl')};
+  if (tunnelId != null) {
+    const id=nonempty(tunnelId,'tunnelId');
+    if (!/^tunnel_[a-z0-9]{32}$/.test(id)) throw bad('tunnelId must match tunnel_<32 lowercase letters or digits>');
+    return {tunnel_id:id};
+  }
+  throw bad('mcpUrl or tunnelId is required');
+};
+const request = (key, options, patch = {}) =>
+  api.invoke(key, {
+    ...options,...patch,
+    headers:{...options.headers,...patch.headers,'OAI-Product-Sku':'CONNECTOR_SETTING'}
+  });
+
+const authRequestFromDiscovery = (discovery) => {
+  const config=discovery?.oauth_config;
+  const invalid=() => Object.assign(new Error('MCP OAuth discovery returned incomplete or unsupported metadata'), {
+    code:'MCP_OAUTH_CONFIG_INVALID'
+  });
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw invalid();
+  if (config.type === 'NONE') return {supported_auth:[],oauth_client_params:null};
+  if (config.type !== 'OAUTH' ||
+      typeof config.authorization_url !== 'string' || !config.authorization_url ||
+      typeof config.token_url !== 'string' || !config.token_url) throw invalid();
+  // ChatGPT Web puts the discovered OAuth config inside supported_auth.
+  // Registration, PKCE, scopes and resource stay exactly as advertised by the server.
+  return {supported_auth:[config],oauth_client_params:null};
+};
+
+exports.createCustomMcpServer = async (options = {}) => {
+  const name = nonempty(options.name,'name');
+  const target=makeTarget(options);
+  let authRequest;
+  if (options.authRequest !== undefined) {
+    if (options.authentication) throw bad('Use authentication or authRequest, not both');
+    if (!options.authRequest || typeof options.authRequest !== 'object' ||
+        Array.isArray(options.authRequest) || !Array.isArray(options.authRequest.supported_auth))
+      throw bad('authRequest must be a web-compatible object with supported_auth array');
+    authRequest=options.authRequest;
+  } else if (options.authentication === 'NONE') {
+    authRequest={supported_auth:[],oauth_client_params:null};
+  } else if (options.authentication === undefined || options.authentication === 'AUTO') {
+    // Discovery is safe to repeat and does not create a connector or a link.
+    // Never silently downgrade OAuth to NONE on a discovery error.
+    const discovery=await exports.getCustomMcpOAuthConfig(options);
+    authRequest=authRequestFromDiscovery(discovery);
+  } else throw bad('Unknown authentication type; use AUTO, NONE or a configured authRequest');
+  if (options.description !== undefined && typeof options.description !== 'string') throw bad('description must be a string');
+  if (options.customHeaders !== undefined && !Array.isArray(options.customHeaders)) throw bad('customHeaders must be an array');
+  const body = {
+    name, ...target,
+    description:(options.description || '').trim(),
+    logo_url:options.logoUrl == null ? null : logoValue(options.logoUrl),
+    auth_request:authRequest
+  };
+  if (options.customHeaders?.length) body.custom_headers=options.customHeaders;
+  return request('POST /backend-api/aip/connectors/mcp',options,{body});
+};
+
+exports.renameCustomMcpServer = async (options = {}) =>
+  request('PATCH /backend-api/aip/connectors/{id}/name',options,{
+    pathValues:[nonempty(options.connectorId,'connectorId')],
+    body:{name:nonempty(options.name,'name')}
+  });
+
+exports.describeCustomMcpServer = async (options = {}) => {
+  if (typeof options.description !== 'string') throw bad('description must be a string');
+  return request('PATCH /backend-api/aip/connectors/{id}/description',options,{
+    pathValues:[nonempty(options.connectorId,'connectorId')],
+    body:{description:options.description}
+  });
+};
+
+exports.setCustomMcpServerLogo = async (options = {}) =>
+  request('PATCH /backend-api/aip/connectors/{id}/logo',options,{
+    pathValues:[nonempty(options.connectorId,'connectorId')],
+    body:{logo_url:logoValue(options.logoUrl)}
+  });
+
+exports.deleteCustomMcpServer = async (options = {}) =>
+  request('DELETE /backend-api/aip/connectors/{id}',options,{
+    pathValues:[nonempty(options.connectorId,'connectorId')]
+  });
+
+exports.getCustomMcpServer = async (options = {}) =>
+  request('GET /backend-api/aip/connectors/{id}',options,{
+    pathValues:[nonempty(options.connectorId,'connectorId')]
+  });
+
+exports.listCustomMcpTunnels = async (options = {}) =>
+  request('GET /backend-api/aip/connectors/mcp/tunnels',options);
+
+exports.getCustomMcpOAuthConfig = async (options = {}, injectedOptions = {}) => {
+  // A single URL argument makes `zgpt connector getCustomMcpOAuthConfig https://...` usable on PowerShell.
+  if (typeof options === 'string') options={...injectedOptions,mcpUrl:options};
+  if (options.customHeaders !== undefined && !Array.isArray(options.customHeaders))
+    throw bad('customHeaders must be an array');
+  return request('POST /backend-api/aip/connectors/mcp/oauth_config',options,{
+    body:{...makeTarget(options),custom_headers:options.customHeaders || []}
+  });
+};
+
+// Unlink an account connection without deleting the MCP connector definition.
+// The user must explicitly invoke this destructive operation; never auto-unlink
+// after an auth error, reconnect or action refresh.
+exports.disconnectConnectorLink = async (options = {}, injectedOptions = {}) => {
+  if (typeof options === 'string') options = { ...injectedOptions, linkId: options };
+  const linkId = nonempty(options.linkId, 'linkId');
+  if (!/^link_[A-Za-z0-9_-]+$/.test(linkId))
+    throw bad('linkId must be a connector link identifier (link_...)');
+  return request('DELETE /backend-api/aip/connectors/links/{id}', options, {
+    pathValues: [linkId]
+  });
+};
+
+// Refresh uses the linked connection ID, not the connector ID.
+exports.reloadCustomMcpServerActions = async (options = {}, injectedOptions = {}) => {
+  // Accept the linkId directly for `zgpt connector reloadCustomMcpServerActions <linkId>`.
+  // The legacy options-object form and the SDK's single refresh implementation stay intact.
+  if (typeof options === 'string') options = { ...injectedOptions, linkId: options };
+  return require('./write').refreshConnectorActions(options);
+};

package/src/connector/write.js

@@ -21,6 +21,7 @@ exports.refreshConnectorActions = async (options = {}) => {
   const target = '/backend-api/aip/connectors/mcp/refresh_actions';
   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
+    method: 'POST', body: { link_id: options.linkId }, route: target, retry: false,
+    headers:{...options.headers,'OAI-Product-Sku':'CONNECTOR_SETTING'}
   }), target);
 };

package/src/conversation/index.js

@@ -55,6 +55,35 @@ exports.send = async (id, message, options = {}) => write.sendConversation({
   message,
   ...(await bindCanonicalContext(options))
 });
+// CLI-friendly management façade matching the verified Zero_LLM command tree.
+// Mutations stay owned by ./write; no copied HTTP routes or parallel auth stack.
+const required = (value, name) => {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw Object.assign(new Error(name + ' is required'), { code: 'BAD_ARGS' });
+  }
+  return value.trim();
+};
+exports.create = async (message, options = {}) => write.createConversation({
+  ...(await bindCanonicalContext(options)),
+  message: required(message, 'message')
+});
+exports.rename = async (id, title, options = {}) => write.renameConversation({
+  ...(await bindCanonicalContext(options)),
+  conversationId: required(id, 'conversationId'),
+  title: required(title, 'title')
+});
+exports.delete = async (id, options = {}) => write.deleteConversation({
+  ...(await bindCanonicalContext(options)),
+  conversationId: required(id, 'conversationId')
+});
+exports.move = async (id, projectId = null, options = {}) => write.moveConversation({
+  ...(await bindCanonicalContext(options)),
+  conversationId: required(id, 'conversationId'),
+  projectId: projectId === 'exit' || projectId == null ? null : required(projectId, 'projectId')
+});
+// Compatibility with the Zero_LLM CLI: new/del map to the same owners.
+exports.new = exports.create;
+exports.del = exports.delete;
 exports.temp = {
   new: async (message, options = {}) => temporary.createConversation({
     message,

package/src/conversation/read.js

@@ -2,6 +2,14 @@
 
 const direct = require('../transport/direct/http-client');
 
+const pageBudget = (maxPages = 1000) => {
+  if (!Number.isSafeInteger(maxPages) || maxPages < 1) {
+    throw Object.assign(new Error('maxPages must be a positive safe integer'), { code: 'PAGINATION_BUDGET_INVALID' });
+  }
+  return maxPages;
+};
+const paginationError = (code, message) => Object.assign(new Error(message), { code });
+
 const requireOk = (response, target) => {
   if (!response || response.status !== 200 || !response.json) {
     const error = new Error(`ChatGPT request failed (${response?.status || 'no-status'}): ${target}`);
@@ -52,25 +60,45 @@ exports.listStandalone = async ({
   token,
   sessionHeaders,
   requestJson = direct.requestJson,
-  onProgress = () => {}
+  onProgress = () => {},
+  maxPages = 1000
 }) => {
+  const budget = pageBudget(maxPages);
   const items = [];
+  const seenItems = new Set();
   let offset = 0;
   const limit = 50;
 
-  for (let pageNumber = 0; pageNumber < 1000; pageNumber += 1) {
+  for (let pageNumber = 0; pageNumber < budget; 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 });
+    if (page.offset !== undefined && page.offset !== null && Number(page.offset) !== offset) {
+      throw paginationError('PAGINATION_STALLED', 'conversation pagination server offset did not advance');
+    }
+    let added = 0;
+    for (const item of pageItems) {
+      const id = item?.id || item?.conversation_id;
+      const key = id ? `id:${id}` : `row:${JSON.stringify(item)}`;
+      if (seenItems.has(key)) continue;
+      seenItems.add(key);
+      items.push(item);
+      added++;
+    }
+    if (pageItems.length > 0 && added === 0 && pageNumber > 0) {
+      throw paginationError('PAGINATION_STALLED', 'conversation pagination returned no new items');
+    }
+    onProgress({ type: 'conversation-page', count: items.length, pageCount: added, offset });
 
     const total = Number(page.total);
     const pageLimit = Number(page.limit) || limit;
+    if (!Number.isSafeInteger(pageLimit) || pageLimit <= 0) {
+      throw paginationError('PAGINATION_STALLED', 'conversation pagination returned an invalid page 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' });
+  throw paginationError('PAGINATION_LIMIT', `conversation pagination exceeded ${budget} pages`);
 };
 exports.searchGlobal = async ({
   query,
@@ -186,10 +214,12 @@ exports.getConversationMessagesPage = async ({
 exports.findConversationMessage = async ({
   conversationId, messageId, numTurns = 10, includeHasVersions = true,
   token, sessionHeaders, requestJson = direct.requestJson,
-  getConversation = exports.getConversation, getMessagesPage = exports.getConversationMessagesPage
+  getConversation = exports.getConversation, getMessagesPage = exports.getConversationMessagesPage,
+  maxPages = 1000
 }) => {
   if (!conversationId) throw new Error('conversationId is required');
   if (!messageId) throw new Error('messageId is required');
+  const budget = pageBudget(maxPages);
   const current = await getConversation({ conversationId, token, sessionHeaders, requestJson });
   let pagesScanned = 1;
   let nodesScanned = Array.isArray(current?.messages) ? current.messages.length : 0;
@@ -200,6 +230,7 @@ exports.findConversationMessage = async ({
   let hasPrevious = pageInfo.has_previous_page === true;
   const seen = new Set();
   while (hasPrevious && before) {
+    if (pagesScanned >= budget) throw paginationError('PAGINATION_LIMIT', `conversation message search exceeded ${budget} pages`);
     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 });
@@ -220,9 +251,11 @@ exports.findConversationMessage = async ({
 exports.getConversationHistory = async ({
   conversationId, numTurns = 10, includeHasVersions = true,
   token, sessionHeaders, requestJson = direct.requestJson,
-  getConversation = exports.getConversation, getMessagesPage = exports.getConversationMessagesPage
+  getConversation = exports.getConversation, getMessagesPage = exports.getConversationMessagesPage,
+  maxPages = 1000
 }) => {
   if (!conversationId) throw new Error('conversationId is required');
+  const budget = pageBudget(maxPages);
   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;
@@ -231,6 +264,7 @@ exports.getConversationHistory = async ({
   let hasPrevious = pageInfo.has_previous_page === true;
   const seen = new Set();
   while (hasPrevious && before) {
+    if (pages.length >= budget) throw paginationError('PAGINATION_LIMIT', `conversation history exceeded ${budget} pages`);
     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 });

package/src/project/index.js

@@ -3,4 +3,38 @@
 const read = require('./read');
 const write = require('./write');
 
-Object.assign(exports, read, write);
+Object.assign(exports, read, write);
+
+// Mirror the proven Zero_LLM Project CLI without copying HTTP implementations.
+// All actions use the same canonical Zero SDK session and project owner methods.
+const bindContext = require('../runtime-context').bind;
+const required = (value, name) => {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw Object.assign(new Error(name + ' is required'), { code: 'BAD_ARGS' });
+  }
+  return value.trim();
+};
+exports.list = async (options = {}) => read.listProjects(await bindContext(options));
+exports.get = async (id, options = {}) => read.getProject({
+  ...(await bindContext(options)), projectId: required(id, 'projectId')
+});
+exports.conversations = async (id, options = {}) => read.listProjectConversations({
+  ...(await bindContext(options)), projectId: required(id, 'projectId')
+});
+exports.create = async (name, options = {}) => write.createProject({
+  ...(await bindContext(options)), name: required(name, 'name')
+});
+exports.rename = async (id, name, options = {}) => write.renameProject({
+  ...(await bindContext(options)), projectId: required(id, 'projectId'), name: required(name, 'name')
+});
+exports.delete = async (id, options = {}) => write.deleteProject({
+  ...(await bindContext(options)), projectId: required(id, 'projectId')
+});
+exports.save = async (projectId, conversationId, messageId, options = {}) => write.saveProjectMessage({
+  ...(await bindContext(options)), projectId: required(projectId, 'projectId'),
+  conversationId: required(conversationId, 'conversationId'),
+  messageId: required(messageId, 'messageId')
+});
+// Keep the legacy LAB's natural command names without duplicating logic.
+exports.new = exports.create;
+exports.del = exports.delete;

package/src/transport/direct/http-client.js

@@ -1,4 +1,4 @@
-'use strict';
+'use strict';
 
 const https = require('node:https');
 const fs = require('node:fs');
@@ -6,6 +6,8 @@ const path = require('node:path');
 const paths = require('../../config/paths');
 
 const RETRY_AFTER_CAP_MS = 30000;
+const DEFAULT_HTTP_IDLE_TIMEOUT_MS = 30_000;
+const DEFAULT_HTTP_TOTAL_TIMEOUT_MS = 45_000;
 const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 30000;
 const MAX_RATE_LIMIT_COOLDOWN_MS = 15 * 60 * 1000;
 
@@ -141,6 +143,14 @@ exports.parseRetryAfterMs = (headers = {}) => {
 };
 const safeParse = (text) => { try { return JSON.parse(text); } catch { return null; } };
 const rawRequest = (target, token, sessionHeaders, options, parseBody) => new Promise((resolve, reject) => {
+  let settled = false;
+  let deadlineTimer = null;
+  const finish = (next, value) => {
+    if (settled) return;
+    settled = true;
+    if (deadlineTimer) clearTimeout(deadlineTimer);
+    next(value);
+  };
   const payload = options.body === undefined ? null : Buffer.from(JSON.stringify(options.body));
   let headers = exports.buildHeaders(token, sessionHeaders, target, options.route);
   if (options.headers) headers = cleanHeaders({ ...headers, ...options.headers });
@@ -151,28 +161,47 @@ const rawRequest = (target, token, sessionHeaders, options, parseBody) => new Pr
     const aborted = () => {
       const error = new Error(`ChatGPT upstream stream aborted: ${target}`);
       error.code = 'UPSTREAM_ABORTED';
-      reject(error);
+      finish(reject, error);
     };
     res.on('data', (chunk) => { options.onChunk?.(chunk); chunks.push(chunk); });
     res.on('end', () => {
       ended = true;
       const text = Buffer.concat(chunks).toString('utf8');
       const response = { status: res.statusCode, ...(parseBody ? { json: safeParse(text) } : { text }), contentType: res.headers['content-type'] || null, headers: { ...res.headers } };
-      exports.persistResponseHeaders(sessionHeaders, response.headers, options);
-      resolve(response);
+      try {
+        exports.persistResponseHeaders(sessionHeaders, response.headers, options);
+        finish(resolve, response);
+      } catch (error) { finish(reject, error); }
     });
     res.on('aborted', aborted);
-    res.on('error', reject);
+    res.on('error', error => finish(reject, error));
     res.on('close', () => { if (!ended) aborted(); });
   });
-  req.on('error', reject);
-  if (Number.isFinite(options.idleTimeoutMs) && options.idleTimeoutMs > 0 && typeof req.setTimeout === 'function') {
-    req.setTimeout(options.idleTimeoutMs, () => {
-      const error = new Error(`ChatGPT upstream stream idle timeout: ${target}`);
+  req.on('error', error => finish(reject, error));
+  const idleTimeoutMs = options.idleTimeoutMs === 0 ? 0
+    : Number.isFinite(options.idleTimeoutMs) && options.idleTimeoutMs > 0
+      ? options.idleTimeoutMs : DEFAULT_HTTP_IDLE_TIMEOUT_MS;
+  if (idleTimeoutMs && typeof req.setTimeout === 'function') {
+    req.setTimeout(idleTimeoutMs, () => {
+      const error = new Error(`ChatGPT upstream idle timeout: ${target}`);
       error.code = 'UPSTREAM_IDLE_TIMEOUT';
-      req.destroy(error);
+      if (typeof req.destroy === 'function') req.destroy(error);
+      finish(reject, error);
     });
   }
+  // Active SSE streams may run longer than a fixed total deadline; they still
+  // have an idle timeout. Ordinary HTTP gets both an idle and a total budget.
+  const streaming = typeof options.onChunk === 'function' ||
+    /text\/event-stream/i.test(String(options.headers?.accept || ''));
+  const totalTimeoutMs = options.totalTimeoutMs === 0 ? 0
+    : Number.isFinite(options.totalTimeoutMs) && options.totalTimeoutMs > 0
+      ? options.totalTimeoutMs : streaming ? 0 : DEFAULT_HTTP_TOTAL_TIMEOUT_MS;
+  if (totalTimeoutMs) deadlineTimer = setTimeout(() => {
+    const error = new Error(`ChatGPT upstream request deadline exceeded: ${target}`);
+    error.code = 'UPSTREAM_TIMEOUT';
+    if (typeof req.destroy === 'function') req.destroy(error);
+    finish(reject, error);
+  }, totalTimeoutMs);
   if (payload) req.write(payload);
   req.end();
 });
@@ -187,5 +216,4 @@ const guardedRequest = async (target, token, sessionHeaders, options, parseBody)
 exports.requestJson = (target, token, sessionHeaders = {}, options = {}) =>
   guardedRequest(target, token, sessionHeaders, options, true);
 exports.requestText = (target, token, sessionHeaders = {}, options = {}) =>
-  guardedRequest(target, token, sessionHeaders, options, false);
-
+  guardedRequest(target, token, sessionHeaders, options, false);