aki-pro-max 2.3.3

package/docs/WEB-SESSION-TRANSPORT-DESIGN.md

@@ -0,0 +1,423 @@
+# Web-session transport design (offline, implementation-ready)
+
+Date: 2026-09-12 (Asia/Bangkok)  
+Status: design only; no Postman request, browser access, credential discovery, configuration change, or implementation was performed.
+
+## 1. Decision
+
+Add a **separate upstream transport strategy**, `web_session`, beside the current `access_token` strategy. Do not replace, auto-select, or fail over between them.
+
+```text
+POSTMAN_TRANSPORT_STRATEGY = access_token | web_session
+```
+
+The first implementation slice is deliberately narrow:
+
+- keep `/v1/chat/completions`, `/v1/models`, OpenAI normalization, response shaping, limits, concurrency, and downstream bearer authentication unchanged;
+- add only an owner-configured `postman.sid` transport to `POST https://{subdomain}.postman.co/_gw/chat`;
+- support a fresh, non-tool, text request only;
+- do not create or accept an invented caller session ID;
+- do not enable conversation reuse, tool advertising, tool-result continuation, metadata discovery, account failover, user-setting mutation, or challenge handling in this slice;
+- add no runtime dependency.
+
+This is an original local design informed by static source observations. The two inspected repositories have no demonstrated reuse license, so their code is not to be copied.
+
+## 2. Evidence boundary and exact references
+
+### Pinned public sources
+
+- `TTGREEN/postman2api-full@0c3fd893767655aa10afd25135f20ed344b447d8`
+  - `src/provider/postman.ts:82`: `CHAT_ENDPOINT = "/_gw/chat"`.
+  - `src/provider/postman.ts:336-350`: `buildHeaders` sends `Cookie: postman.sid=...`, JSON content type, SSE accept, `x-pstmn-req-service`, a browser User-Agent, and same-subdomain `Origin`/`Referer`.
+  - `src/provider/postman.ts:813-971`: request body builder uses `platform: "WEB"`, `mandatoryContext.workspaceId`, and a selected model in `devModeOptions`; it also contains much broader tool/settings behavior that is not adopted here.
+  - `src/provider/postman.ts:1584+`: streaming path reads response-body chunks rather than waiting for an upstream `[DONE]` token.
+  - `src/provider/sse-stream.ts:89-143`: parses JSON only from `data:` lines and recognizes `usage`, `conversation`, `textChunk`, `thinkingChunk`, `failure/error`, `toolCallChunk`, `loopApprovalChunk`, plus ignored informational events.
+  - `src/provider/sse-stream.ts:145-149`: `finish()` synthesizes `stop` or `tool_calls` when the reader is finished; this is implementation behavior, not proof of a native upstream terminal event.
+- `gfushilu07-arch/postman2api@62aee6d2d87841ebcd42618c4ac5d9cf22f4dc36`
+  - `src/provider/postman.ts:44`: `CHAT_ENDPOINT = "/_gw/chat"`.
+  - `src/provider/postman.ts:209-222`: the same cookie, SSE, service, User-Agent, Origin, and Referer header pattern.
+  - `src/provider/postman.ts:318-407`: body builder uses `platform: "WEB"`, `mandatoryContext.workspaceId`, static catalog metadata, and selected-model options.
+  - `src/provider/postman.ts:692+`, especially body-read `done` branches around `:763` and `:915`: EOF drives reader finalization and downstream `[DONE]` emission.
+  - `src/provider/sse-stream.ts:86-133`: parses the same main event families.
+  - `src/provider/sse-stream.ts:135-139`: also synthesizes finish on reader completion.
+  - `src/provider/sse-stream.ts:286+`: observes an upstream model label and can reject a mismatch against the requested/selected model.
+
+These sources demonstrate a plausible cookie-authenticated direct HTTP route. They do **not** prove that arbitrary EOF is a successful terminal signal, that PMAK exchanges into this session, that every account receives the same event shapes, or that the static model/catalog values are authoritative now.
+
+### Existing local provider
+
+- `src/config.mjs`
+  - currently requires `POSTMAN_ACCESS_TOKEN`, exact HTTPS `POSTMAN_ORIGIN`, workspace ID, explicit models, bounded integer settings, and visible-ASCII catalog tokens;
+  - `upstreamUrl()` verifies the constructed URL retains the configured origin.
+- `src/postman-request.mjs`
+  - currently sends `x-access-token`, `redirect: 'error'`, and an operator-owned request envelope;
+  - request-body fields cannot override configured catalog metadata.
+- `src/transport.mjs`
+  - currently requires exact upstream `data: [DONE]`; EOF first is `upstream_incomplete_stream`.
+- `src/postman-events.mjs`
+  - validates bounded event shapes and maps failures to redacted stable errors.
+- `src/correlation-store.mjs` and `src/server.mjs`
+  - correlation is admitted only after trusted upstream conversation/tool IDs and binds principal, workspace, model, transcript, tools, and catalog metadata;
+  - uncertain dispatched continuations are not retried automatically.
+- `test/9router-executor.integration.test.mjs`
+  - seven actual pinned-9router tests exercise exact facade URL/auth behavior, JSON, SSE, native tool roundtrip/replay, errors, and abort propagation.
+
+## 3. Configuration contract
+
+### 3.1 Strategy and mutually exclusive secrets
+
+The strategy is explicit and closed:
+
+```text
+POSTMAN_TRANSPORT_STRATEGY=access_token
+  requires: POSTMAN_ACCESS_TOKEN, POSTMAN_ORIGIN, POSTMAN_WORKSPACE_ID
+  forbids:  POSTMAN_SESSION_COOKIE, POSTMAN_WORKSPACE_SUBDOMAIN
+
+POSTMAN_TRANSPORT_STRATEGY=web_session
+  requires: POSTMAN_SESSION_COOKIE, POSTMAN_WORKSPACE_SUBDOMAIN, POSTMAN_WORKSPACE_ID
+  forbids:  POSTMAN_ACCESS_TOKEN, POSTMAN_ORIGIN, POSTMAN_CHAT_PATH
+```
+
+Concrete choices:
+
+1. No default strategy after this feature is enabled. An explicit value prevents an old deployment with a newly injected secret from silently changing behavior.
+2. Both secrets configured is a startup error, even if one appears unused.
+3. A secret belonging to the other strategy is a startup error, not ignored configuration.
+4. The cookie value is the **value of `postman.sid` only**, not an entire `Cookie` header. Suggested field name: `POSTMAN_SESSION_COOKIE`; do not name it a generic token.
+5. The cookie is explicitly owner-provided. The service does not read browser storage, handshake responses, files outside its configuration mechanism, or repository examples.
+6. Secret bounds: string, 1-4096 bytes UTF-8, visible ASCII `0x21-0x7e`, and reject semicolon, comma, backslash, whitespace, CR, LF, NUL, and all control bytes. The builder adds the single literal prefix `postman.sid=`.
+7. Subdomain bounds: lowercase ASCII DNS label, 1-63 characters, regex `^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$`; reject dots, percent encoding, Unicode, underscores, leading/trailing hyphen, URL syntax, CR/LF, and whitespace.
+8. Workspace ID remains an opaque configured identifier under the existing visible-ASCII/no-whitespace discipline, with an explicit upper bound (recommended 256 bytes). It is never learned from request content.
+9. Continue existing configuration-source precedence; do not add a request-body or header override for strategy, cookie, subdomain, origin, path, workspace, or catalog metadata.
+
+The downstream `PROVIDER_API_KEY` remains a distinct facade credential and is never forwarded upstream.
+
+### 3.2 Exact web-session URL
+
+For `web_session`, the URL is constructed internally and cannot be operator-replaced:
+
+```text
+https://${POSTMAN_WORKSPACE_SUBDOMAIN}.postman.co/_gw/chat
+```
+
+Validation after construction must assert all of:
+
+- protocol exactly `https:`;
+- username/password empty;
+- hostname exactly `${validatedSubdomain}.postman.co`;
+- hostname has the `.postman.co` suffix and contains exactly the expected validated left label;
+- explicit/default port resolves to 443; reject a configured port because none is accepted as input;
+- pathname exactly `/_gw/chat`;
+- query and fragment empty;
+- serialized origin exactly `https://${validatedSubdomain}.postman.co`.
+
+Use `redirect: 'error'`. Do not manually follow redirects. Any 3xx is a bounded upstream error, so the cookie cannot be replayed to a redirected host or path.
+
+The existing `access_token` exact-origin/path construction remains unchanged.
+
+## 4. Header policy
+
+### 4.1 `web_session` request headers
+
+Build a fresh allowlisted header object:
+
+```text
+content-type: application/json
+accept: text/event-stream
+cookie: postman.sid=<owner-provided value>
+x-pstmn-req-service: agent-mode-service
+origin: https://<subdomain>.postman.co
+referer: https://<subdomain>.postman.co/
+user-agent: <operator-configured bounded value or one documented fixed compatibility value>
+[x-app-version: <operator-configured bounded value only if explicitly set>]
+```
+
+Decisions:
+
+- Never send `x-access-token`, downstream `Authorization`, `PROVIDER_API_KEY`, host headers, proxy headers, or arbitrary operator headers on this strategy.
+- Never import caller headers wholesale.
+- `Origin` and `Referer` are derived from the validated subdomain and cannot be independently configured.
+- Every configured header value uses bounded visible ASCII and rejects CR/LF/NUL. Header names are constants.
+- Do not claim a browser identity dynamically. If compatibility requires User-Agent, use one bounded, documented constant or a separately validated operator string; it grants no browser automation behavior.
+- `x-app-version` is optional and operator-pinned. Do not fetch or infer it in the transport path.
+
+### 4.2 Redaction
+
+Maintain a strategy-level secret set containing the active upstream secret and downstream facade key. Error/log serialization must redact:
+
+- exact secret values and any `postman.sid=...` sequence;
+- `Cookie`, `Authorization`, and `x-access-token` header values case-insensitively;
+- URL userinfo (although validation forbids it);
+- upstream response bodies and event messages by default.
+
+Log only request ID, strategy name, HTTP status, stable error code, retry-after after bounded parsing, event type, byte counts, and boolean terminal/model observations. Do not log request bodies, response text, cookie length, workspace ID, conversation IDs, tool IDs, or model content in generic error records.
+
+## 5. Request body: smallest text-first profile
+
+Create a strategy-specific request builder rather than conditionally mutating the current envelope.
+
+For the first slice, accept only normalized requests satisfying:
+
+- no tools;
+- no trailing tool result;
+- no parallel-tool option;
+- no request field purporting to supply session/conversation/group IDs;
+- text-capable messages already accepted by current ingress;
+- model is in the existing operator allowlist.
+
+Suggested web-session body:
+
+```json
+{
+  "input": {
+    "chatType": "USER_QUERY",
+    "query": "<bounded current local transcript representation>",
+    "conversationId": null,
+    "product": "workspace_v12",
+    "useCase": null,
+    "agent": null,
+    "startedFrom": "CHAT_INPUT"
+  },
+  "platform": "WEB",
+  "clientTools": { "native": [] },
+  "clientKBTerms": { "native": [] },
+  "mandatoryContext": { "workspaceId": "<configured>" },
+  "selectedContext": [],
+  "backgroundContext": [],
+  "devModeOptions": {
+    "selectedModel": "<mapped operator-pinned upstream value>",
+    "isParallelToolCallingSupported": false,
+    "autoRun": false,
+    "supportsAskUser": false,
+    "supportsActionRecommendations": false,
+    "useThinkingModeIfAvailable": false
+  }
+}
+```
+
+Required decisions before implementation:
+
+- `query` uses the current deterministic transcript serializer or a new bounded text serializer; it must not fabricate the source repositories' private `_sessionId`, seeding acknowledgements, priming turns, or tool groups.
+- Keep existing `MAX_BODY_BYTES`; serialize once, measure UTF-8 bytes, and reject before fetch.
+- Request fields are constants/config-derived/normalized-request-derived only. Unknown client body fields cannot override any upstream field.
+- `selectedModel` needs an explicit operator-owned mapping if public facade IDs differ from the upstream enum. Do not copy a static model catalog from either repository and do not auto-discover entitlement.
+- Do not send `userSettings.ai_user_agent_mode`, enable-web flags, loop-approval automation, available skills, third-party tool groups, native hashes, or native terms hashes in this text-only profile.
+
+If the minimal no-tools body proves insufficient later, any catalog/settings addition is a separately reviewed profile revision with fixtures; it is not an automatic fallback.
+
+## 6. Stream and completion state machine
+
+### 6.1 Preserve legacy behavior
+
+`access_token` keeps its current rule exactly:
+
+```text
+exact SSE data payload [DONE] -> complete
+EOF before [DONE]             -> upstream_incomplete_stream
+```
+
+This preserves the 54-test path and its protection against false success.
+
+### 6.2 Separate web-session decoder
+
+The pinned web-session sources parse JSON `data:` lines and finalize on body EOF, then synthesize downstream finish. They do not demonstrate upstream `[DONE]`. Therefore `web_session` must not reuse a universal `require [DONE]` rule, but it also must not equate every EOF with success.
+
+Track these independent facts:
+
+```text
+saw_valid_event
+saw_meaningful_output       // text or a later-supported complete tool call
+saw_conversation_id
+saw_usage
+saw_failure
+saw_native_terminal         // only an explicitly enumerated source/live-fixture-backed event
+transport_eof
+parser_buffer_complete      // no partial SSE frame / UTF-8 / JSON payload
+```
+
+Event mapping for the text-first slice:
+
+- `conversation` with a bounded non-empty ID: record internally as an observation only; do not expose it or persist it yet.
+- `textChunk.data.textContent`: bounded text delta.
+- `usage`: bounded known numeric fields; unknown credit states remain fail-closed under current error policy.
+- `thinkingChunk`, `thinkingComplete`, `usageUpdate`, `ping`, `info`, `planningChunk`, `progressUpdate`, `todoChunk`, `streamingFormat`: ignore only after a valid bounded JSON object and known event name.
+- `failure`, `error`, failure result, or known error type: terminal failure; never emit successful finish.
+- In the first text-only slice, `toolCallChunk` and `loopApprovalChunk` were explicit unsupported-profile errors. The later bounded offline tool slice supports source-backed `toolCallChunk` forms as documented by `WEB-SESSION-TOOLS-INTEGRATION.md`; loop approval remains unsupported.
+- unknown event type: current fail-closed `upstream_unverified_event_shape` behavior.
+
+### 6.3 Terminal outcome rules
+
+The decoder exposes a transport outcome, not an OpenAI finish reason:
+
+1. `failure` observed at any point -> `FAILED`; partial downstream text may already exist, but do not emit `finish_reason` or `[DONE]`.
+2. Exact `[DONE]` observed, if the web route happens to emit it -> `COMPLETE_EXPLICIT` after validating no pending partial frame.
+3. A separately enumerated native terminal event supported by a pinned/live sanitized fixture -> `COMPLETE_EXPLICIT`. **No such event is proven by the two current sources**, so the initial enum is empty.
+4. EOF with partial UTF-8, SSE frame, or JSON -> `INCOMPLETE_TRUNCATED`.
+5. EOF after valid meaningful output but without explicit terminal evidence -> `AMBIGUOUS_EOF`.
+6. EOF after only metadata/heartbeats or no valid event -> `INCOMPLETE_EMPTY`.
+7. timeout, abort, reader error, or socket error -> existing abort/timeout/upstream error classification, never completion.
+
+Initial production behavior for `AMBIGUOUS_EOF` is fail-closed: stable `upstream_completion_ambiguous`, no successful OpenAI finish, and no downstream `[DONE]`. This avoids both bad universals: forcing upstream `[DONE]` and accepting a truncated EOF as success.
+
+A later owner-approved, content-discarding protocol observation may justify one of two bounded changes:
+
+- identify a real native terminal event and add it to `saw_native_terminal`; or
+- establish a precise EOF completion contract (for example, a required ordered set of final event categories and a complete frame) and version that rule with fixtures.
+
+Do not loosen EOF semantics based only on the repositories' `finish()` helper.
+
+### 6.4 Downstream finish emission
+
+`server.mjs` emits OpenAI `finish_reason` and downstream `[DONE]` only after `canonicalEvents` yields a successful canonical `finish`. A web-session ambiguous/truncated/error outcome yields no canonical finish, matching the existing post-header failure behavior tested through actual 9router.
+
+## 7. Requested model versus observed model
+
+Represent identity as two fields internally:
+
+```text
+requestedModel = validated public model ID from the caller
+selectedUpstreamModel = operator-pinned mapping used in the request
+observedUpstreamModel = bounded label parsed from supported event metadata, or null
+```
+
+Rules:
+
+- OpenAI response `model` remains the requested public ID for compatibility, but that field is not evidence of the actual upstream model.
+- Record `observedUpstreamModel` only when a recognized event contains a bounded supported model field. Do not manufacture it from the request.
+- If no model is observed, mark internal verification state `unobserved`; do not state that the upstream model was verified.
+- Add an operator mapping/alias table only if needed. Comparison must be exact against the configured allowed observed labels for that public ID; do not infer fuzzy aliases.
+- Default mismatch behavior: fail before successful finish with `upstream_model_mismatch`; never silently accept replacement.
+- If output arrived before a mismatch was observed, terminate as post-header failure without `[DONE]`.
+- Logs contain only `model_observed: true|false` and `model_match: true|false|unknown` unless an explicitly approved diagnostic mode permits bounded labels.
+
+## 8. Correlation and sessions
+
+Do not reuse current correlation merely because a `conversation` event appears.
+
+Current correlation is valid for one purpose: native tool-result continuation after the service has admitted trusted upstream tool IDs, conversation ID, group information, transcript, tools binding, catalog metadata, principal, workspace, and model. The text-first `web_session` slice has no tools, so it does not admit correlation records.
+
+Ordinary conversation continuation is deferred because it needs a different store/key contract. It must not:
+
+- accept a fabricated `_sessionId` or upstream `conversationId` from the OpenAI body;
+- expose upstream IDs downstream;
+- conflate a 9router request ID with an upstream conversation;
+- reuse the tool-call store without a separately defined principal-scoped session anchor and replay semantics.
+
+A future session design may reuse the existing principal derivation, workspace/model binding, TTL/capacity patterns, and uncertain-dispatch state machine, but it requires its own record type and tests.
+
+## 9. Errors, expiry, and prohibited automatic behavior
+
+Stable web-session errors should distinguish:
+
+- invalid startup configuration;
+- `upstream_web_session_auth_failed` for 401/403 (cookie absent, expired, account/workspace mismatch, or entitlement unknown);
+- `upstream_redirect_rejected` for 3xx;
+- current rate-limit/quota/status classes without reflecting response bodies;
+- `upstream_content_type_error`;
+- malformed/oversized SSE and output;
+- `upstream_completion_ambiguous`, `upstream_incomplete_stream`, and `upstream_empty_stream`;
+- `upstream_model_mismatch`;
+- unsupported text-profile events (`toolCallChunk`, `loopApprovalChunk`).
+
+There is no silent refresh, retry storm, credential exchange, account rotation, strategy failover, browser login, CAPTCHA/Turnstile action, challenge workaround, or automatic change to `ai_user_agent_mode`. A 401/403 fails the request and tells the owner, through a redacted stable message, that the configured web session may need manual replacement.
+
+Retries, if ever added, must retain the current dispatch-uncertainty discipline; no automatic retry after a request may have reached upstream.
+
+## 10. Optional future metadata discovery (separate permission)
+
+TTGREEN contains read-only HTML/asset inspection intended to discover app/native catalog metadata. This is not part of transport setup or fallback.
+
+If requested later, design it as a separate read-only command or offline fixture importer with all of:
+
+- explicit owner permission for that operation;
+- same validated host and owner-provided cookie;
+- GET only, redirect denied, strict byte/content-type/asset-count/time bounds;
+- no update of user settings and no inference request;
+- output is a reviewable candidate metadata artifact, never an automatic config mutation;
+- operator must pin accepted values before the chat transport uses them;
+- failure leaves existing pins unchanged.
+
+## 11. Offline test matrix
+
+All tests inject `fetchImpl`; no test uses a real credential, DNS, Postman endpoint, browser, model, recorder, or quota.
+
+| Area | Required cases | Expected proof |
+|---|---|---|
+| Strategy enum | missing, unknown, `access_token`, `web_session` | only two explicit values accepted; no implicit branch |
+| Secret exclusivity | neither, both, wrong-strategy secret, valid one-secret sets | startup fails except exact valid set |
+| Cookie validation | min/max, >4096 bytes, CR/LF, NUL, whitespace, semicolon/comma/backslash, non-string | no header injection or whole-cookie input |
+| Subdomain validation | valid hyphen label; dot, Unicode, `%`, URL, `@`, slash, port, leading/trailing hyphen, >63 | final host is exactly one label under `.postman.co` |
+| URL | constructed exact HTTPS URL; path/query/fragment absent; 3xx fixture | exact `https://label.postman.co/_gw/chat`; redirect rejected |
+| Header isolation | capture both strategy requests | cookie path has no x-access/downstream auth; token path has no cookie; Origin/Referer derived |
+| Body override | caller supplies strategy/origin/cookie/workspace/platform/session-like fields | captured upstream body uses only config/constants/normalized input |
+| Text profile | simple text, tools, tool result, unsupported options | text accepted; non-text profile rejected before fetch |
+| Size bounds | body/event/output boundary and +1 | existing byte limits apply before unbounded allocation/send |
+| Event shapes | conversation, text, usage, ignored known events, malformed JSON, unknown event | conservative canonical mapping and fail-closed unknowns |
+| Failure redaction | upstream event/body includes fake Cookie/Bearer/session values | stable error contains none of them |
+| Completion: legacy | exact `[DONE]`, EOF first, data after done | current tests unchanged |
+| Completion: web | explicit `[DONE]`; EOF after text; EOF mid-frame; empty EOF; failure after partial text; timeout/abort | only explicit terminal succeeds initially; ambiguous/truncated/error emits no finish/DONE |
+| Unsupported native event | toolCallChunk, loopApprovalChunk | stable unsupported-profile failure; no fabricated call/group/session |
+| Model observation | absent, exact allowed observed label, mismatch before output, mismatch after partial output, overlong label | unobserved is honest; mismatch never finishes successfully |
+| Correlation regression | existing admission/claim/replay/uncertain suites | unchanged access-token tool continuation behavior |
+| Existing 54-test path | add `POSTMAN_TRANSPORT_STRATEGY=access_token` to shared legacy config fixtures, then run every existing behavioral case | only fixture configuration changes; zero changed legacy request/response expectations |
+| Actual 9router JSON | add a second fixture config and capture URL/headers/body | DefaultExecutor still calls facade; facade selects exact web-session upstream request |
+| Actual 9router SSE explicit finish | web fixture includes terminal evidence | router receives content, stop, and one downstream `[DONE]` |
+| Actual 9router ambiguous EOF | web fixture ends after partial text without terminal evidence | post-header stable error, no stop, no `[DONE]` |
+| Actual 9router auth/model/abort | 401/403, mismatch event, client abort | redacted stable errors and abort propagation; no fallback |
+
+The legacy suite should remain a required separate command/path, not be rewritten to parameterize every old assertion through the new strategy. Add focused web-session files so regressions identify the responsible strategy.
+
+## 12. Estimated implementation impact
+
+Smallest credible implementation: **5 existing files modified, 3 new test/design files**, approximately **250-450 production lines and 300-500 test lines** depending on whether model mapping is placed in config or a small module.
+
+Expected files:
+
+1. `src/config.mjs` — strategy enum, mutually exclusive fields, cookie/subdomain validation, derived web endpoint settings.
+2. `src/postman-request.mjs` — dispatch to separate request builders; preserve legacy builder byte-for-byte where practical.
+3. `src/transport.mjs` — choose legacy versus web completion policy.
+4. `src/postman-events.mjs` — bounded observed-model extraction and explicit unsupported text-profile events (or a new `src/web-session-events.mjs` to reduce legacy risk).
+5. `src/server.mjs` — pass strategy/model-observation context without changing ingress routes/correlation admission.
+6. `test/web-session-config.test.mjs` — new.
+7. `test/web-session-transport.test.mjs` — new.
+8. `test/9router-executor.integration.test.mjs` — add focused web-session cases; retain all current cases.
+
+Optional separation that improves reviewability: add `src/web-session-request.mjs` and `src/web-session-events.mjs`, increasing new files while reducing conditional changes in legacy modules. No package change is required.
+
+README/example environment updates should wait until the implementation exists and tests pass; they must state that `postman.sid` is manually owner-supplied and session expiry is expected.
+
+## 13. Smallest safe next offline implementation
+
+Implement only configuration and pure request construction first:
+
+1. add `POSTMAN_TRANSPORT_STRATEGY` and strict mutual-exclusion/validation;
+2. add a pure `buildWebSessionTextRequest()` returning exact URL/init/body for a normalized no-tools request;
+3. add offline capture tests proving URL, redirect denial, header isolation, CRLF/bounds, body non-override, and unchanged legacy request snapshots;
+4. do **not** wire `web_session` into `server.mjs` or make any live-capable request yet.
+
+That slice is reviewable without a credential and cannot accidentally turn the service into a live web-session client. The next offline slice would add the separate event/completion state machine and actual-9router injected fixtures. Only after both slices pass and the owner separately approves a minimal live check should the route be considered for runtime use.
+
+## 14. Required owner inputs and unresolved protocol facts
+
+Inputs required before any future live validation:
+
+- explicit approval for one bounded inference request;
+- owner-supplied current `postman.sid` value (not harvested);
+- exact workspace subdomain label;
+- workspace/team ID used by `mandatoryContext.workspaceId`;
+- one entitled public model ID plus its operator-pinned upstream selected-model value and allowed observed label(s);
+- decision whether an operator-pinned User-Agent and `x-app-version` are required for the first check.
+
+Unknowns that this design does not pretend to solve:
+
+- whether the session is currently authorized for AI and the chosen workspace/model;
+- exact upstream normal terminal evidence, if any, beyond connection EOF;
+- whether `x-app-version` is required for text-only requests now;
+- the current minimal body accepted across accounts;
+- actual model-label locations/aliases for the chosen model;
+- session expiry duration and revocation behavior;
+- whether native catalog metadata is required only for tools or also for some text requests;
+- grouped tool continuation shape (the pinned sources differ);
+- ordinary multi-turn conversation persistence semantics for this facade.
+
+The implementation must keep these as explicit unknowns until bounded evidence resolves them.

package/gitleaks-report-all.json

@@ -0,0 +1 @@
+[]

package/gitleaks-report-latest.json

@@ -0,0 +1 @@
+[]

package/gitleaks-report.json

@@ -0,0 +1 @@
+[]

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "aki-pro-max",
+  "version": "2.3.3",
+  "description": "Local-first OpenAI-compatible gateway and control plane for an authorized Postman web session.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "aki-pro-max": "bin/aki-pro-max.js",
+    "akimcp": "bin/aki-pro-max.js"
+  },
+  "engines": {
+    "node": ">=22.15"
+  },
+  "scripts": {
+    "start": "node --env-file-if-exists=.env src/index.mjs",
+    "test": "node --test test/*.test.mjs",
+    "test:contract": "node --test test/contract.test.mjs",
+    "verify:release": "node scripts/verify-release.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/khangtudo/aki-pro-max.git"
+  },
+  "keywords": [
+    "openai-compatible",
+    "gateway",
+    "postman",
+    "local-first",
+    "tool-calling",
+    "mcp",
+    "cli"
+  ]
+}

package/scripts/eventual-tool-loop.mjs

@@ -0,0 +1,55 @@
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (object(value)) return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+function toolCall(call) {
+  if (!object(call) || call.type !== 'function' || typeof call.id !== 'string' || !call.id || !object(call.function) || typeof call.function.name !== 'string' || typeof call.function.arguments !== 'string') throw Object.assign(new Error('invalid_tool_call'), { code: 'invalid_tool_call' });
+  let args;
+  try { args = JSON.parse(call.function.arguments || '{}'); }
+  catch { throw Object.assign(new Error('invalid_tool_arguments'), { code: 'invalid_tool_arguments' }); }
+  if (!object(args)) throw Object.assign(new Error('invalid_tool_arguments'), { code: 'invalid_tool_arguments' });
+  return { id: call.id, name: call.function.name, args, signature: `${call.function.name}:${stable(args)}` };
+}
+
+export async function runEventualToolLoop({ request, initialBody, executeTool, requiredTools, maxTurns = 3, maxDispatches = 4, validateFinal = () => true }) {
+  if (typeof request !== 'function' || typeof executeTool !== 'function' || !object(initialBody) || !Array.isArray(initialBody.messages) || !Array.isArray(requiredTools) || !requiredTools.length) throw new TypeError('invalid_eventual_tool_loop_options');
+  const required = new Set(requiredTools);
+  const executed = new Map();
+  const messages = structuredClone(initialBody.messages);
+  const trace = [];
+  let dispatches = 0;
+
+  for (let turn = 1; turn <= maxTurns; turn++) {
+    if (dispatches >= maxDispatches) throw Object.assign(new Error('dispatch_budget_exhausted'), { code: 'dispatch_budget_exhausted', trace });
+    const response = await request({ ...initialBody, messages, tool_choice: executed.size >= required.size ? 'auto' : (initialBody.tool_choice ?? 'required') }, { turn, dispatch: ++dispatches });
+    const message = response?.data?.choices?.[0]?.message;
+    const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
+    trace.push({ turn, status: response?.status ?? null, finishReason: response?.data?.choices?.[0]?.finish_reason ?? null, callCount: calls.length, callNames: calls.map(call => call?.function?.name ?? null) });
+    if (response?.status !== 200 || !object(message)) throw Object.assign(new Error('assistant_turn_failed'), { code: 'assistant_turn_failed', trace });
+
+    if (!calls.length) {
+      const missing = [...required].filter(name => ![...executed.values()].some(item => item.name === name));
+      const content = typeof message.content === 'string' ? message.content : '';
+      if (missing.length) throw Object.assign(new Error('assistant_stopped_before_required_tools'), { code: 'assistant_stopped_before_required_tools', missing, trace });
+      if (!validateFinal(content, executed)) throw Object.assign(new Error('final_validation_failed'), { code: 'final_validation_failed', trace });
+      return { content, messages: [...messages, message], turns: turn, dispatches, executed: [...executed.values()].map(({ id, name, signature }) => ({ id, name, signature })), trace };
+    }
+
+    messages.push(message);
+    for (const raw of calls) {
+      const call = toolCall(raw);
+      if (!required.has(call.name)) throw Object.assign(new Error('unexpected_tool_call'), { code: 'unexpected_tool_call', name: call.name, trace });
+      if (executed.has(call.signature)) throw Object.assign(new Error('tool_call_replay'), { code: 'tool_call_replay', name: call.name, trace });
+      if ([...executed.values()].some(item => item.name === call.name)) throw Object.assign(new Error('tool_called_more_than_once'), { code: 'tool_called_more_than_once', name: call.name, trace });
+      const content = await executeTool(call.name, call.args, { turn, id: call.id });
+      if (typeof content !== 'string') throw Object.assign(new Error('invalid_tool_result'), { code: 'invalid_tool_result', name: call.name, trace });
+      executed.set(call.signature, { ...call, content });
+      messages.push({ role: 'tool', tool_call_id: call.id, content });
+    }
+  }
+  throw Object.assign(new Error('turn_budget_exhausted'), { code: 'turn_budget_exhausted', trace });
+}

package/scripts/install-local.ps1

@@ -0,0 +1,35 @@
+# Aki Pro Max local installer / runner (Windows PowerShell)
+# Usage:
+#   irm https://raw.githubusercontent.com/khangtudo/aki-pro-max/main/scripts/install-local.ps1 | iex
+# or clone the repo then: .\scripts\install-local.ps1
+
+$ErrorActionPreference = 'Stop'
+$Package = 'aki-pro-max'
+
+Write-Host "Aki Pro Max Local Installer" -ForegroundColor Cyan
+Write-Host "Installing the Aki Pro Max server, local tray helper shortcut, and Control Plane launcher..." -ForegroundColor DarkGray
+
+npm install -g $Package
+
+$Bin = (Get-Command aki-pro-max -ErrorAction Stop).Source
+$ShortcutDir = Join-Path $env:APPDATA 'Microsoft\Windows\Start Menu\Programs\Aki Pro Max'
+New-Item -ItemType Directory -Force -Path $ShortcutDir | Out-Null
+
+$VbsPath = Join-Path $ShortcutDir 'Start Aki Pro Max Control.vbs'
+$VbsContent = @"
+Set shell = CreateObject("WScript.Shell")
+shell.Run "cmd /c aki-pro-max start", 0, False
+"@
+Set-Content -Path $VbsPath -Value $VbsContent -Encoding ASCII
+
+$UrlPath = Join-Path $ShortcutDir 'Open Aki Pro Max Control.url'
+$UrlContent = @"
+[InternetShortcut]
+URL=http://127.0.0.1:8788/admin
+"@
+Set-Content -Path $UrlPath -Value $UrlContent -Encoding ASCII
+
+Write-Host "Installed command: $Bin" -ForegroundColor Green
+Write-Host "Start server: aki-pro-max start" -ForegroundColor Yellow
+Write-Host "Open Control Plane: http://127.0.0.1:8788/admin" -ForegroundColor Yellow
+Write-Host "Start-menu shortcuts added under: $ShortcutDir" -ForegroundColor Green

package/scripts/live-eventual-multitool.mjs

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises';
+import { once } from 'node:events';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { createProviderServer } from '../src/server.mjs';
+import { loadConfig } from '../src/config.mjs';
+import { runEventualToolLoop } from './eventual-tool-loop.mjs';
+
+const ROOT=new URL('../',import.meta.url);const REPORT=new URL('../reports/LIVE-EVENTUAL-MULTITOOL-V2.3.1.json',import.meta.url);
+const COOKIE_PATH=process.env.AKI_POSTMAN_COOKIE_FILE||'D:/postman.sid.txt';const ORIGIN='https://akimax6.postman.co';const WORKSPACE_ID='358aa6cf-3b60-449f-8981-c60263000413';const MODEL='gpt-5.6-sol';const SELECTED='GPT_56_SOL';const TIMEOUT_MS=90000;
+const apiKey=randomBytes(24).toString('base64url');const cookie=(await fs.readFile(COOKIE_PATH,'utf8')).replace(/^\uFEFF/,'').split(/\r?\n/).map(x=>x.trim()).find(Boolean);if(!cookie||!/^[\x21-\x7E]{1,4096}$/.test(cookie)||/[;,\\]/.test(cookie))throw new Error('cookie_format_invalid');
+const markers={alpha:`ALPHA_${randomBytes(12).toString('hex')}`,beta:`BETA_${randomBytes(12).toString('hex')}`};
+const tools=[{type:'function',function:{name:'alpha_probe',description:'Read the private alpha probe value. Call once with slot alpha.',parameters:{type:'object',properties:{slot:{type:'string',enum:['alpha']}},required:['slot'],additionalProperties:false}}},{type:'function',function:{name:'beta_probe',description:'Read the private beta probe value. Call once with slot beta.',parameters:{type:'object',properties:{slot:{type:'string',enum:['beta']}},required:['slot'],additionalProperties:false}}}];
+const config=loadConfig({PROVIDER_HOST:'127.0.0.1',PROVIDER_PORT:'0',PROVIDER_API_KEY:apiKey,PROVIDER_MODELS:MODEL,POSTMAN_TRANSPORT_STRATEGY:'web_session',POSTMAN_SESSION_COOKIE:cookie,POSTMAN_WORKSPACE_SUBDOMAIN:'akimax6',POSTMAN_WORKSPACE_ID:WORKSPACE_ID,POSTMAN_WEB_SESSION_SELECTED_MODEL:SELECTED,POSTMAN_WEB_SESSION_OBSERVED_MODELS:'gpt-5.6-sol,GPT_56_SOL',REQUEST_TIMEOUT_MS:String(TIMEOUT_MS),MAX_BODY_BYTES:'104857600',MAX_EVENT_BYTES:'1048576',MAX_OUTPUT_BYTES:'1048576',MAX_TOOL_ARGUMENT_BYTES:'4096',MAX_TOOL_RESULT_BYTES:'4096',MAX_TOOLS:'8',MAX_CONCURRENT_REQUESTS:'1',CORRELATION_PRINCIPAL_KEY:randomBytes(32).toString('base64url')});
+let upstreamDispatches=0;const upstreamShapes=[];const fetchImpl=async(url,init)=>{if(String(url)!==`${ORIGIN}/_gw/chat`)throw Object.assign(new Error('unexpected_upstream_url'),{code:'unexpected_upstream_url',preSend:true});upstreamDispatches++;if(upstreamDispatches>4)throw Object.assign(new Error('upstream_budget_exhausted'),{code:'upstream_budget_exhausted',preSend:true});const b=JSON.parse(init.body);upstreamShapes.push({dispatch:upstreamDispatches,chatType:b?.input?.chatType??null,toolCallIdPresent:Boolean(b?.input?.toolCallId),toolCallGroupIdPresent:Boolean(b?.input?.toolCallGroupId),toolResponsePresent:typeof b?.input?.toolResponse==='string',toolResponseCount:(()=>{try{const x=JSON.parse(b?.input?.toolResponse);return Array.isArray(x)?x.length:null}catch{return null}})(),catalogCount:Object.values(b?.clientTools?.thirdParty??{}).reduce((n,x)=>n+(Array.isArray(x?.tools)?x.tools.length:0),0),parallelSupported:b?.devModeOptions?.isParallelToolCallingSupported===true});return fetch(url,{...init,signal:init.signal})};
+const logs=[];const logger={error(line){try{const x=JSON.parse(line);logs.push({event:x.event??null,status:x.status??null,code:x.code??null,upstreamCode:x.upstream?.code??null,requestIdPresent:Boolean(x.upstream?.requestId)})}catch{logs.push({event:'unparsed'})}}};const server=createProviderServer(config,{fetchImpl,logger});
+const sessionId=`v231-${randomUUID()}`;const evidence={schema:'aki-live-eventual-multitool/v1',releaseVersion:'2.3.1-candidate',model:MODEL,policy:{maxTurns:3,maxFacadeDispatches:3,maxUpstreamDispatches:4,retry:false,failover:false},pass:false,facade:null,loop:null,upstreamShapes,logs,serverClosed:false,generatedAt:null};
+const post=async(base,body)=>{const controller=new AbortController();const timer=setTimeout(()=>controller.abort(),TIMEOUT_MS+5000);try{const response=await fetch(`${base}/v1/chat/completions`,{method:'POST',signal:controller.signal,headers:{authorization:`Bearer ${apiKey}`,'content-type':'application/json','x-session-id':sessionId},body:JSON.stringify(body)});let data=null;try{data=await response.json()}catch{}return{status:response.status,data}}finally{clearTimeout(timer)}};
+try{server.listen(0,'127.0.0.1');await once(server,'listening');const base=`http://127.0.0.1:${server.address().port}`;let facadeDispatches=0;const result=await runEventualToolLoop({initialBody:{model:MODEL,messages:[{role:'user',content:'Use both alpha_probe and beta_probe exactly once. They may be called in parallel or sequentially. Do not stop until both results are available, then reply with exactly ALPHA=<alpha result>;BETA=<beta result>.'}],tools,tool_choice:'required',parallel_tool_calls:true,stream:false},requiredTools:['alpha_probe','beta_probe'],maxTurns:3,maxDispatches:3,request:async body=>{facadeDispatches++;return post(base,body)},executeTool:async(name,args)=>{if(name==='alpha_probe'&&args.slot==='alpha')return markers.alpha;if(name==='beta_probe'&&args.slot==='beta')return markers.beta;throw Object.assign(new Error('tool_schema_mismatch'),{code:'tool_schema_mismatch'})},validateFinal:(content,executed)=>content.trim()===`ALPHA=${markers.alpha};BETA=${markers.beta}`&&[...executed.values()].every(item=>content.includes(item.content))});evidence.facade={dispatches:facadeDispatches};evidence.loop={turns:result.turns,dispatches:result.dispatches,executed:result.executed.map(x=>({name:x.name,signature:x.signature})),trace:result.trace,exactFinal:true};evidence.pass=result.executed.length===2&&new Set(result.executed.map(x=>x.name)).size===2&&result.dispatches<=3&&upstreamDispatches<=4;}catch(error){evidence.failure={code:error?.code??'unclassified',message:String(error?.message??'').slice(0,120),trace:error?.trace??null};process.exitCode=1}finally{server.closeAllConnections?.();if(server.listening){server.close();await once(server,'close')}evidence.serverClosed=!server.listening;evidence.generatedAt=new Date().toISOString();evidence.upstreamDispatches=upstreamDispatches;await fs.mkdir(new URL('../reports/',import.meta.url),{recursive:true});await fs.writeFile(REPORT,JSON.stringify(evidence,null,2)+'\n','utf8');console.log(JSON.stringify({report:REPORT.pathname,pass:evidence.pass,loop:evidence.loop,facade:evidence.facade,upstreamDispatches,upstreamShapes,serverClosed:evidence.serverClosed,failure:evidence.failure??null}));}

package/scripts/upgrade-admin-v232.mjs

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+
+const file = new URL('../src/admin.mjs', import.meta.url);
+let text = fs.readFileSync(file, 'utf8');
+
+text = text.replace(
+  '<body><main class="shell"><header>',
+  '<body><main class="shell"><section id="updateBanner" class="update hidden" aria-live="polite"><div><span class="pill">UPDATE AVAILABLE</span><h2 id="updateTitle">Aki Pro Max update available</h2><p id="updateCopy">Checking release status…</p></div><div class="update-actions"><button id="copyUpdate">Copy update command</button><button id="dismissUpdate">Later</button></div><ol id="updateSteps"><li>Stop the active proxy PID completely.</li><li>Open PowerShell and run the update command.</li><li>Click Reload after the command completes to start a new proxy PID.</li></ol><code id="updateCommand"></code><button id="reloadProxy">Reload Control Plane</button></section><header>'
+);
+text = text.replace(
+  '.status.up{color:#6ee7b7}',
+  '.status.up{color:#6ee7b7}.update{border-color:#f97316;background:linear-gradient(135deg,#351c0b,#111827);position:relative}.update.hidden{display:none}.update h2{margin:8px 0}.update p{margin:6px 0}.update-actions{position:absolute;right:20px;top:20px;display:flex;gap:8px}.update ol{margin:15px 0 12px;padding-left:20px;color:#cbd5e1;line-height:1.7}.update code{display:block;padding:10px;border-radius:9px;background:#020617;color:#fde68a;word-break:break-all}.update #reloadProxy{margin-top:10px;border-color:#fb923c;background:#c2410c}@media(max-width:760px){.update-actions{position:static;margin-top:10px}}'
+);
+text = text.replace(
+  "const $=id=>document.getElementById(id); let secret='';",
+  "const $=id=>document.getElementById(id); let secret=''; const semver=v=>String(v||'0.0.0').replace(/^v/,'').split('.').map(n=>Number(n)||0); const newer=(a,b)=>{const x=semver(a),y=semver(b);return x.some((n,i)=>n>(y[i]||0)&&x.slice(0,i).every((m,j)=>m===(y[j]||0)))};"
+);
+text = text.replace(
+  "$('snippet').textContent=JSON.stringify({baseURL:config.baseUrl,apiKey:'<reveal-and-copy-from-this-page>',model:config.models[0]},null,2); $('healthBoundary').textContent=health.upstream_verified?'upstream verified':'facade healthy · upstream not verified by /health';",
+  "$('snippet').textContent=JSON.stringify({baseURL:config.baseUrl,apiKey:'<reveal-and-copy-from-this-page>',model:config.models[0]},null,2); $('healthBoundary').textContent=health.upstream_verified?'upstream verified':'facade healthy · upstream not verified by /health'; await checkUpdates(config);"
+);
+text = text.replace(
+  "$('copyKey').addEventListener('click',()=>copy(secret));",
+  "async function checkUpdates(config){const url=config.updateManifestUrl;if(!url)return;try{const c=new AbortController();const t=setTimeout(()=>c.abort(),3000);const m=await fetch(url,{cache:'no-store',signal:c.signal}).then(r=>r.ok?r.json():null);clearTimeout(t);if(!m||!newer(m.latest,config.currentVersion)||localStorage.getItem('aki-update-dismissed')===m.latest)return;$('updateBanner').classList.remove('hidden');$('updateTitle').textContent='Aki Pro Max '+m.latest+' is available';$('updateCopy').textContent='Current version: '+config.currentVersion+'. Update manually to avoid interrupting an active request.';$('updateCommand').textContent=m.updateCommand||'npm update -g '+(m.installPackage||'aki-pro-max');$('copyUpdate').onclick=()=>copy($('updateCommand').textContent);$('dismissUpdate').onclick=()=>{localStorage.setItem('aki-update-dismissed',m.latest);$('updateBanner').classList.add('hidden')};$('reloadProxy').onclick=()=>location.reload()}catch(e){console.info('Update check skipped:',e.message)}}$('copyKey').addEventListener('click',()=>copy(secret));"
+);
+text = text.replace(
+  "workspaceId: config.workspaceId,\n    models: config.models,",
+  "workspaceId: config.workspaceId,\n    models: config.models,\n    currentVersion: '2.3.3',\n    updateManifestUrl: process.env.AKI_UPDATE_MANIFEST_URL || 'https://raw.githubusercontent.com/khangtudo/aki-pro-max/main/version.json',"
+);
+
+if (!text.includes('updateBanner') || !text.includes('checkUpdates')) throw new Error('Update patch markers missing');
+fs.writeFileSync(file, text, 'utf8');
+console.log('Updated admin control plane with safe update banner.');