aki-pro-max 2.3.3

package/scripts/verify-issue-closure.mjs

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const EXPECTED = Object.freeze({
+  claudePublicModel: 'claude-opus-4-8',
+  claudeSelectedModel: 'CLAUDE_OPUS_48_BEDROCK',
+  pmnConnectionId: '6706879a-9897-4b2a-9142-728ca64276d4',
+  pmnConnectionName: 'Aki Pro Max Local',
+  pmnModel: 'gpt-5.6-sol',
+  markerCompletionTokens: 4,
+});
+
+function invariant(condition, code) {
+  if (!condition) throw new Error(code);
+}
+
+export function verifyIssueClosure({ claude, trace }) {
+  invariant(claude?.schema === 'live-two-model-tools-evidence/v1', 'claude_schema_invalid');
+  invariant(claude?.policy?.retry === false, 'claude_retry_must_be_false');
+  invariant(claude?.policy?.failover === false, 'claude_failover_must_be_false');
+  invariant(claude?.startedWithPriorCurrentProbeAttempts === 0, 'claude_probe_not_fresh');
+  invariant(claude?.allServersCleaned === true, 'claude_cleanup_unproven');
+
+  const branch = claude.branches?.find((item) => item.publicModel === EXPECTED.claudePublicModel);
+  invariant(branch, 'claude_branch_missing');
+  invariant(branch.selectedModel === EXPECTED.claudeSelectedModel, 'claude_selected_model_mismatch');
+  invariant(branch.initial?.facadeStatus === 200, 'claude_initial_not_200');
+  invariant(branch.initial?.toolCallCount === 1, 'claude_tool_call_count_invalid');
+  invariant(branch.initial?.exactlyOneValidToolCall === true, 'claude_tool_call_invalid');
+  invariant(branch.initial?.argumentsValid === true, 'claude_arguments_invalid');
+  invariant(branch.initial?.argumentsDiagnostic?.parsedType === 'object', 'claude_arguments_not_object');
+  invariant(branch.initial?.argumentsDiagnostic?.keyCount === 0, 'claude_arguments_not_empty');
+  invariant(branch.initial?.argumentsDiagnostic?.parseError === null, 'claude_arguments_parse_error');
+  invariant(branch.continuation?.facadeStatus === 200, 'claude_continuation_not_200');
+  invariant(branch.finalMatchesMarker === true, 'claude_final_marker_mismatch');
+  invariant(branch.terminal === 'completed_match', 'claude_terminal_invalid');
+  invariant(branch.error === null, 'claude_branch_error');
+
+  invariant(Array.isArray(trace?.rows), 'trace_rows_missing');
+  invariant(trace?.connections && typeof trace.connections === 'object', 'trace_connections_missing');
+  const pmnConnection = trace.connections[EXPECTED.pmnConnectionId];
+  invariant(pmnConnection?.name === EXPECTED.pmnConnectionName, 'pmn_connection_mapping_invalid');
+  invariant(pmnConnection?.isActive === 1, 'pmn_connection_inactive');
+  const cpx = Object.values(trace.connections).find((item) => item?.name === 'CPX');
+  invariant(cpx?.isActive === 1, 'cpx_not_active_during_trace');
+
+  const pmnRows = trace.rows.filter((row) => row.connectionId === EXPECTED.pmnConnectionId);
+  invariant(pmnRows.length === 1, 'pmn_row_count_invalid');
+  const row = pmnRows[0];
+  invariant(row.model === EXPECTED.pmnModel, 'pmn_row_model_invalid');
+  invariant(row.status === 'ok', 'pmn_row_not_ok');
+  invariant(row.completionTokens === EXPECTED.markerCompletionTokens, 'pmn_marker_token_count_invalid');
+  invariant(trace.rows.some((item) => item.connectionId === cpx.id), 'cpx_control_row_missing');
+
+  return Object.freeze({
+    verdict: 'PASS',
+    claude: { terminal: branch.terminal, selectedModel: branch.selectedModel },
+    pmn: { usageId: row.id, connectionId: row.connectionId, completionTokens: row.completionTokens },
+    controls: { retry: false, failover: false, cpxActive: true },
+  });
+}
+
+function readJson(name) {
+  return JSON.parse(fs.readFileSync(path.join(ROOT, name), 'utf8'));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = verifyIssueClosure({
+      claude: readJson('CLAUDE-LIVE-TOOLS-EVIDENCE.json'),
+      trace: readJson('FULL-TRACE-EVIDENCE.json'),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`ISSUE_CLOSURE_REJECTED:${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/verify-release.mjs

@@ -0,0 +1,31 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { extname, join, relative, resolve } from 'node:path';
+
+const root = resolve(new URL('..', import.meta.url).pathname.replace(/^\/(.:)/, '$1'));
+const textExtensions = new Set(['.md','.json','.txt','.mjs','.js','.html','.css','.yaml','.yml','.toml','.env','.example']);
+const forbiddenNames = new Set(['.env']);
+const secretPatterns = [
+  ['GitHub token', /\bgh[opusr]_[A-Za-z0-9_]{20,}\b/],
+  ['OpenAI-shaped key', /\bsk-[A-Za-z0-9_-]{16,}\b/],
+  ['Postman session assignment', new RegExp(['POSTMAN_SESSION','COOKIE=(?!TEST_ONLY_|your_|$)[^\\s]+'].join('_'))],
+];
+const files = [];
+async function walk(dir) { for (const entry of await readdir(dir, { withFileTypes: true })) { if (entry.name === '.git' || entry.name === 'node_modules') continue; const path = join(dir, entry.name); if (entry.isDirectory()) await walk(path); else files.push(path); } }
+await walk(root);
+for (const file of files) {
+  const name = relative(root, file).replaceAll('\\','/');
+  if (forbiddenNames.has(name) || /^\.env\.(?!example$)/.test(name)) throw new Error(`Forbidden credential file: ${name}`);
+  const ext = extname(file).toLowerCase();
+  if (!textExtensions.has(ext) && !name.endsWith('.env.example')) continue;
+  const text = await readFile(file, 'utf8');
+  let scannedText = text;
+  if (name.startsWith('test/')) {
+    scannedText = scannedText.replaceAll(new RegExp(['POSTMAN_SESSION','COOKIE=(?:TEST_ONLY_[A-Z_]+|original|old|session-secret-1234)'].join('_'), 'g'), 'ALLOWLISTED_TEST_FIXTURE');
+    scannedText = scannedText.replaceAll(/sk-(?:pmn-test-secret-never-static|client-full-ingress-offline|facade-full-ingress-offline)/g, 'ALLOWLISTED_TEST_KEY');
+  }
+  if (name === 'scripts/verify-release.mjs') scannedText = scannedText.replaceAll(/POSTMAN_SESSION|COOKIE=/g, 'DETECTOR_SOURCE');
+  for (const [label, pattern] of secretPatterns) if (pattern.test(scannedText)) throw new Error(`${label} pattern in ${name}`);
+}
+const canary = ['sk', 'CANARY_REAL_LOOKING_TOKEN_123456789'].join('-');
+if (!secretPatterns.some(([, pattern]) => pattern.test(canary))) throw new Error('Secret detector positive control failed');
+console.log(JSON.stringify({ release: 'aki-pro-max', files: files.length, secretScan: 'pass', positiveControl: 'pass' }));

package/src/admin-auth.mjs

@@ -0,0 +1,94 @@
+import { access, copyFile, readFile, rename, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+const SUBDOMAIN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const VISIBLE_ASCII = /^[\x21-\x7e]+$/;
+
+function required(value, field, max = 256) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${field} is required`);
+  const text = value.trim();
+  if (text.length > max) throw new Error(`${field} exceeds ${max} characters`);
+  return text;
+}
+
+export function validateAuthInput(input) {
+  if (!input || typeof input !== 'object') throw new Error('auth payload is required');
+  const sessionCookie = required(input.sessionCookie, 'postman.sid', 4096);
+  if (!VISIBLE_ASCII.test(sessionCookie) || /[;,\\]/.test(sessionCookie)) throw new Error('postman.sid contains unsupported characters');
+  const subdomain = required(input.subdomain, 'team subdomain', 63).toLowerCase();
+  if (!SUBDOMAIN.test(subdomain) || subdomain.startsWith('xn--')) throw new Error('team subdomain is invalid');
+  const workspaceId = required(input.workspaceId, 'workspace ID', 256);
+  if (!VISIBLE_ASCII.test(workspaceId)) throw new Error('workspace ID must be visible ASCII');
+  const selectedModel = required(input.selectedModel, 'selected upstream model', 128);
+  if (!VISIBLE_ASCII.test(selectedModel)) throw new Error('selected upstream model must be visible ASCII');
+  return Object.freeze({ sessionCookie, subdomain, workspaceId, selectedModel });
+}
+
+export function authStatus(config) {
+  return {
+    configured: Boolean(config.webSessionCookie),
+    transportStrategy: config.transportStrategy,
+    subdomain: config.webSessionSubdomain || null,
+    workspaceId: config.workspaceId || null,
+    selectedModel: config.selectedUpstreamModel || null,
+    cookie: config.webSessionCookie ? { present: true, masked: `••••${config.webSessionCookie.slice(-4)}` } : { present: false, masked: null },
+  };
+}
+
+async function exists(path) {
+  try { await access(path, constants.F_OK); return true; } catch { return false; }
+}
+
+export async function discoverPostmanDesktop(env = process.env) {
+  const roaming = env.APPDATA ? resolve(env.APPDATA, 'Postman') : null;
+  const local = env.LOCALAPPDATA ? resolve(env.LOCALAPPDATA, 'Postman') : null;
+  const executable = local ? resolve(local, 'Postman.exe') : null;
+  const profileDetected = Boolean(roaming && await exists(roaming));
+  const installed = Boolean(executable && await exists(executable));
+  return {
+    installed,
+    profileDetected,
+    sources: [
+      ...(installed ? [{ type: 'desktop-install', path: executable }] : []),
+      ...(profileDetected ? [{ type: 'chromium-profile', path: roaming }] : []),
+    ],
+    sessionAutoImportAvailable: false,
+    manualCredentialRequired: true,
+    reason: profileDetected ? 'Postman Chromium session storage is protected; this control plane will not decrypt or extract postman.sid automatically.' : 'No readable Postman Desktop profile was detected.',
+  };
+}
+
+function replaceEnvLine(text, key, value) {
+  const line = `${key}=${value}`;
+  const expression = new RegExp(`^${key}=.*$`, 'm');
+  if (expression.test(text)) return text.replace(expression, line);
+  return `${text.replace(/\s*$/, '')}\n${line}\n`;
+}
+
+export async function saveAuthConfig(input, options = {}) {
+  const validated = validateAuthInput(input);
+  const envFile = resolve(options.envFile || resolve(process.cwd(), '.env'));
+  let original = await readFile(envFile, 'utf8');
+  let updated = original;
+  updated = replaceEnvLine(updated, 'POSTMAN_TRANSPORT_STRATEGY', 'web_session');
+  updated = replaceEnvLine(updated, 'POSTMAN_SESSION_COOKIE', validated.sessionCookie);
+  updated = replaceEnvLine(updated, 'POSTMAN_WORKSPACE_SUBDOMAIN', validated.subdomain);
+  updated = replaceEnvLine(updated, 'POSTMAN_WORKSPACE_ID', validated.workspaceId);
+  updated = replaceEnvLine(updated, 'POSTMAN_WEB_SESSION_SELECTED_MODEL', validated.selectedModel);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupFile = `${envFile}.bak-${stamp}`;
+  const temporary = resolve(dirname(envFile), `.env.auth-${process.pid}-${randomBytes(5).toString('hex')}.tmp`);
+  await copyFile(envFile, backupFile);
+  await import('node:fs/promises').then(fs => fs.chmod(backupFile, 0o600));
+  try {
+    await writeFile(temporary, updated, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    if (options.beforeRename) await options.beforeRename({ envFile, backupFile, temporary });
+    await rename(temporary, envFile);
+  } catch (error) {
+    try { await rename(backupFile, envFile); } catch {}
+    throw error;
+  }
+  return { saved: true, restartRequired: true, backupFile, fields: { subdomain: validated.subdomain, workspaceId: validated.workspaceId, selectedModel: validated.selectedModel } };
+}

package/src/admin.mjs

@@ -0,0 +1,133 @@
+import { authStatus, discoverPostmanDesktop, saveAuthConfig, validateAuthInput } from './admin-auth.mjs';
+
+const LOOPBACK_V4 = /^127(?:\.\d{1,3}){3}$/;
+
+export function isLoopbackAddress(value) {
+  if (typeof value !== 'string') return false;
+  const address = value.toLowerCase().startsWith('::ffff:') ? value.slice(7) : value;
+  if (address === '::1') return true;
+  if (!LOOPBACK_V4.test(address)) return false;
+  return address.split('.').every(part => Number(part) >= 0 && Number(part) <= 255);
+}
+
+export function isAllowedAdminHost(value, localPort) {
+  if (typeof value !== 'string' || !value) return false;
+  const allowed = new Set([
+    `localhost:${localPort}`,
+    `127.0.0.1:${localPort}`,
+    `[::1]:${localPort}`,
+  ]);
+  return allowed.has(value.toLowerCase());
+}
+
+export function assertLocalAdminRequest(req) {
+  // Deliberately ignore X-Forwarded-For: the socket peer is the security boundary.
+  return isLoopbackAddress(req.socket?.remoteAddress) && isAllowedAdminHost(req.headers?.host, req.socket?.localPort);
+}
+
+const ADMIN_HTML = `<!doctype html>
+<html lang="vi"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Aki Pro Max Control Plane</title><link rel="stylesheet" href="/admin/app.css"></head>
+<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><div><span class="pill">LOCAL CONTROL PLANE</span><h1>Aki Pro Max <em>Control</em></h1><p>Credentials, runtime health và OpenAI-compatible connection.</p></div><div id="health" class="status">Đang kiểm tra…</div></header>
+<section class="grid metrics"><article><label>Facade</label><strong id="baseUrl">—</strong><button data-copy="baseUrl">Copy URL</button></article><article><label>Transport</label><strong id="transport">—</strong><small id="workspace">—</small></article><article><label>Models</label><strong id="modelCount">—</strong><small>Public aliases</small></article></section>
+<section class="grid main"><article class="credentials"><div class="title"><div><label>Provider API key</label><h2>Credentials</h2></div><span class="safe">Loopback only</span></div><div class="secret"><code id="apiKey">••••••••••••••••••••••••</code><button id="reveal">Reveal</button><button id="copyKey" disabled>Copy key</button></div><p class="hint">Key chỉ được tải sau khi bấm Reveal. Không nằm trong HTML, JS, health response hoặc browser storage.</p></article>
+<article><label>Client setup</label><h2>OpenAI-compatible</h2><pre id="snippet">—</pre><button data-copy="snippet">Copy config</button></article></section>
+<section><div class="title"><div><label>Upstream authentication</label><h2>Postman Session</h2></div><span id="authState" class="safe">Loading…</span></div><div class="auth-grid"><label>postman.sid<input id="sessionCookie" type="password" autocomplete="off" placeholder="Paste session cookie"></label><label>Team subdomain<input id="subdomain" autocomplete="off" placeholder="team-name"></label><label>Workspace ID<input id="workspaceId" autocomplete="off" placeholder="UUID"></label><label>Selected upstream model<input id="selectedModel" autocomplete="off" placeholder="GPT_56_SOL"></label></div><div class="actions"><button id="discoverAuth">Auto Discover</button><button id="validateAuth">Test fields</button><button id="applyAuth">Save auth</button></div><p id="authMessage" class="hint">Stored cookie is never returned. Auto discovery detects Postman Desktop but does not decrypt protected Chromium session storage.</p></section>
+<section><div class="title"><div><label>Available models</label><h2>Catalog</h2></div></div><div id="models" class="models"></div></section>
+<footer><span>Bound to local machine</span><span id="healthBoundary">upstream not probed yet</span></footer></main><script src="/admin/app.js"></script></body></html>`;
+
+const ADMIN_CSS = `:root{color-scheme:dark;--bg:#070b14;--panel:#101827;--line:#273449;--text:#f8fafc;--muted:#94a3b8;--orange:#fb923c;--green:#34d399}*{box-sizing:border-box}body{margin:0;background:radial-gradient(circle at 20% 0,#4a210f 0,transparent 32%),radial-gradient(circle at 90% 90%,#18205a 0,transparent 32%),var(--bg);font:14px Inter,system-ui,sans-serif;color:var(--text);min-height:100vh}.shell{max-width:1100px;margin:auto;padding:42px 20px}header{display:flex;justify-content:space-between;gap:24px;align-items:center;margin-bottom:22px}h1{font-size:48px;letter-spacing:-.05em;margin:10px 0 5px}h1 em{font-style:normal;color:var(--orange);font-weight:500}h2{margin:5px 0 16px;font-size:22px}p,.hint,small{color:var(--muted)}.pill,.safe{display:inline-block;border:1px solid #f9731655;background:#f9731620;color:#fdba74;border-radius:999px;padding:6px 10px;font-size:10px;font-weight:800;letter-spacing:.1em}.safe{color:#6ee7b7;border-color:#10b98155;background:#10b98120}.status{border:1px solid var(--line);padding:11px 15px;border-radius:14px;background:#0b1220}.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}}.grid{display:grid;gap:14px}.metrics{grid-template-columns:2fr 1fr 1fr}.main{grid-template-columns:1.15fr .85fr;margin-top:14px}article,section{background:#0f172acc;border:1px solid var(--line);border-radius:18px;padding:20px}section{margin-top:14px}section article{padding:0;border:0;background:none}label{display:block;text-transform:uppercase;letter-spacing:.13em;font-size:10px;color:var(--muted)}strong{display:block;font-size:18px;margin:10px 0;word-break:break-all}.title{display:flex;justify-content:space-between;align-items:start}.secret{display:flex;gap:8px;align-items:center;background:#020617;padding:12px;border-radius:12px;border:1px solid #1e293b}.secret code{flex:1;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;color:#fde68a}button{border:1px solid #334155;color:#e2e8f0;background:#172033;padding:8px 11px;border-radius:9px;cursor:pointer}button:hover{border-color:var(--orange)}button:disabled{opacity:.45;cursor:not-allowed}pre{white-space:pre-wrap;background:#020617;padding:12px;border-radius:12px;border:1px solid #1e293b;color:#a7f3d0;font:12px ui-monospace,monospace;min-height:96px}.models{display:grid;grid-template-columns:repeat(4,1fr);gap:9px}.model{padding:10px;border-radius:11px;border:1px solid #26344a;background:#0a1120;font:11px ui-monospace,monospace;color:#cbd5e1}.auth-grid{display:grid;grid-template-columns:repeat(2,1fr);gap:12px}.auth-grid label{font-size:10px}.auth-grid input{display:block;width:100%;margin-top:7px;padding:11px;border-radius:10px;border:1px solid #334155;background:#020617;color:#f8fafc;font:13px ui-monospace,monospace}.actions{display:flex;gap:9px;margin-top:14px}footer{display:flex;justify-content:space-between;color:#64748b;font-size:11px;padding:18px 4px}@media(max-width:760px){header{align-items:flex-start;flex-direction:column}.metrics,.main,.models,.auth-grid{grid-template-columns:1fr}h1{font-size:38px}.secret{align-items:stretch;flex-direction:column}}`;
+
+const ADMIN_JS = `'use strict';
+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)))};
+const copy=async text=>{await navigator.clipboard.writeText(text)};
+async function init(){
+ const [health,config]=await Promise.all([fetch('/health').then(r=>r.json()),fetch('/admin/config',{cache:'no-store'}).then(r=>{if(!r.ok)throw new Error('Admin config '+r.status);return r.json()})]);
+ $('health').textContent=health.status==='ok'?'UP · '+config.port:'DEGRADED'; $('health').classList.add(health.status==='ok'?'up':'');
+ $('baseUrl').textContent=config.baseUrl; $('transport').textContent=config.transportStrategy; $('workspace').textContent='Workspace '+config.workspaceId; $('modelCount').textContent=String(config.models.length); $('models').replaceChildren(...config.models.map(id=>{const d=document.createElement('div');d.className='model';d.textContent=id;return d}));
+ $('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);
+}
+$('reveal').addEventListener('click',async()=>{const r=await fetch('/admin/credentials',{method:'POST',headers:{'content-type':'application/json'},body:'{}',cache:'no-store'});if(!r.ok)throw new Error('Credentials '+r.status);secret=(await r.json()).apiKey;$('apiKey').textContent=secret;$('copyKey').disabled=false;$('reveal').textContent='Hide';$('reveal').onclick=()=>{const shown=$('apiKey').textContent===secret;$('apiKey').textContent=shown?'••••••••••••••••••••••••':secret;$('reveal').textContent=shown?'Show':'Hide'}});
+const authPayload=()=>({sessionCookie:$('sessionCookie').value,subdomain:$('subdomain').value,workspaceId:$('workspaceId').value,selectedModel:$('selectedModel').value});
+async function loadAuth(){const s=await fetch('/admin/auth/status',{cache:'no-store'}).then(r=>r.json());$('authState').textContent=s.configured?'Configured '+s.cookie.masked:'Not configured';$('subdomain').value=s.subdomain||'';$('workspaceId').value=s.workspaceId||'';$('selectedModel').value=s.selectedModel||'';}
+$('discoverAuth').addEventListener('click',async()=>{const d=await fetch('/admin/auth/discover',{method:'POST',headers:{'content-type':'application/json'},body:'{}'}).then(r=>r.json());$('authMessage').textContent=d.installed?(d.reason+' Manual cookie entry remains required.'):'Postman Desktop was not detected.'});
+$('validateAuth').addEventListener('click',async()=>{const r=await fetch('/admin/auth/validate',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(authPayload())});const d=await r.json();$('authMessage').textContent=r.ok?'Valid fields · cookie '+d.cookie.masked:d.error.message});
+$('applyAuth').addEventListener('click',async()=>{const r=await fetch('/admin/auth/apply',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(authPayload())});const d=await r.json();$('authMessage').textContent=r.ok?'Saved safely. Restart provider to activate. Backup: '+d.backupFile:d.error.message;if(r.ok){$('sessionCookie').value='';await loadAuth()}});
+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)); document.querySelectorAll('[data-copy]').forEach(b=>b.addEventListener('click',()=>copy($(b.dataset.copy).textContent))); Promise.all([init(),loadAuth()]).catch(e=>{$('health').textContent='ERROR';console.error(e)});`;
+
+const securityHeaders = Object.freeze({
+  'cache-control': 'no-store',
+  'x-content-type-options': 'nosniff',
+  'referrer-policy': 'no-referrer',
+  'cross-origin-resource-policy': 'same-origin',
+  'content-security-policy': "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",
+});
+
+function send(res, status, contentType, body, extra = {}) {
+  res.writeHead(status, { ...securityHeaders, 'content-type': contentType, ...extra });
+  res.end(body);
+}
+
+function sameOrigin(req) {
+  const origin = req.headers.origin;
+  const expectedOrigin = `http://${req.headers.host}`;
+  const fetchSite = req.headers['sec-fetch-site'];
+  return (!origin || origin === expectedOrigin) && (!fetchSite || fetchSite === 'same-origin');
+}
+
+async function readJson(req, maxBytes = 8192) {
+  const chunks = []; let bytes = 0;
+  for await (const chunk of req) {
+    bytes += chunk.length;
+    if (bytes > maxBytes) throw new Error('request body too large');
+    chunks.push(chunk);
+  }
+  const text = Buffer.concat(chunks).toString('utf8');
+  return text ? JSON.parse(text) : {};
+}
+
+export async function handleAdminRequest(req, res, config, pathname) {
+  if (!pathname.startsWith('/admin')) return false;
+  if (!assertLocalAdminRequest(req)) {
+    send(res, 403, 'application/json; charset=utf-8', JSON.stringify({ error: { message: 'Local admin access denied.', code: 'admin_local_only' } }));
+    return true;
+  }
+  if (pathname === '/admin' && req.method === 'GET') send(res, 200, 'text/html; charset=utf-8', ADMIN_HTML);
+  else if (pathname === '/admin/app.css' && req.method === 'GET') send(res, 200, 'text/css; charset=utf-8', ADMIN_CSS);
+  else if (pathname === '/admin/app.js' && req.method === 'GET') send(res, 200, 'text/javascript; charset=utf-8', ADMIN_JS);
+  else if (pathname === '/admin/config' && req.method === 'GET') send(res, 200, 'application/json; charset=utf-8', JSON.stringify({
+    baseUrl: `http://127.0.0.1:${req.socket.localPort}/v1`,
+    port: req.socket.localPort,
+    transportStrategy: config.transportStrategy,
+    workspaceId: config.workspaceId,
+    models: config.models,
+    currentVersion: '2.3.3',
+    updateManifestUrl: process.env.AKI_UPDATE_MANIFEST_URL || 'https://raw.githubusercontent.com/khangtudo/aki-pro-max/main/version.json',
+  }));
+  else if (pathname === '/admin/credentials' && req.method === 'POST') {
+    if (!sameOrigin(req)) send(res, 403, 'application/json; charset=utf-8', JSON.stringify({ error: { message: 'Credential reveal origin denied.', code: 'admin_origin_denied' } }));
+    else send(res, 200, 'application/json; charset=utf-8', JSON.stringify({ apiKey: config.apiKey }));
+  }
+  else if (pathname === '/admin/auth/status' && req.method === 'GET') send(res, 200, 'application/json; charset=utf-8', JSON.stringify(authStatus(config)));
+  else if (pathname === '/admin/auth/discover' && req.method === 'POST') {
+    if (!sameOrigin(req)) send(res, 403, 'application/json; charset=utf-8', JSON.stringify({ error: { message: 'Auth discovery origin denied.', code: 'admin_origin_denied' } }));
+    else send(res, 200, 'application/json; charset=utf-8', JSON.stringify(await discoverPostmanDesktop()));
+  }
+  else if (pathname === '/admin/auth/validate' && req.method === 'POST') {
+    if (!sameOrigin(req)) send(res, 403, 'application/json; charset=utf-8', JSON.stringify({ error: { message: 'Auth validation origin denied.', code: 'admin_origin_denied' } }));
+    else {
+      try { const fields = validateAuthInput(await readJson(req)); send(res, 200, 'application/json; charset=utf-8', JSON.stringify({ valid: true, fields: { subdomain: fields.subdomain, workspaceId: fields.workspaceId, selectedModel: fields.selectedModel }, cookie: { present: true, masked: `••••${fields.sessionCookie.slice(-4)}` } })); }
+      catch (error) { send(res, 400, 'application/json; charset=utf-8', JSON.stringify({ error: { message: error.message, code: 'invalid_auth_config' } })); }
+    }
+  }
+  else if (pathname === '/admin/auth/apply' && req.method === 'POST') {
+    if (!sameOrigin(req)) send(res, 403, 'application/json; charset=utf-8', JSON.stringify({ error: { message: 'Auth apply origin denied.', code: 'admin_origin_denied' } }));
+    else {
+      try { const result = await saveAuthConfig(await readJson(req)); send(res, 200, 'application/json; charset=utf-8', JSON.stringify(result)); }
+      catch (error) { send(res, 400, 'application/json; charset=utf-8', JSON.stringify({ error: { message: error.message, code: 'auth_apply_failed' } })); }
+    }
+  }
+  else send(res, 404, 'application/json; charset=utf-8', JSON.stringify({ error: { message: 'Admin route not found.', code: 'not_found' } }));
+  return true;
+}
+
+export const adminStaticAssets = Object.freeze({ html: ADMIN_HTML, css: ADMIN_CSS, js: ADMIN_JS });

package/src/canonical.mjs

@@ -0,0 +1,23 @@
+import { createHash, createHmac } from 'node:crypto';
+
+function ordered(value) {
+  if (Array.isArray(value)) return value.map(ordered);
+  if (value && typeof value === 'object') {
+    const output = {};
+    for (const key of Object.keys(value).sort()) output[key] = ordered(value[key]);
+    return output;
+  }
+  return value;
+}
+
+export function canonicalString(value) {
+  return JSON.stringify({ version: 1, value: ordered(value) });
+}
+
+export function canonicalHash(value) {
+  return createHash('sha256').update(canonicalString(value), 'utf8').digest('hex');
+}
+
+export function derivePrincipalId(serverKey, credentialSlotId) {
+  return createHmac('sha256', serverKey).update(credentialSlotId, 'utf8').digest('hex');
+}

package/src/config.mjs

@@ -0,0 +1,88 @@
+import { timingSafeEqual, randomBytes } from 'node:crypto';
+import { ProviderError, invalid } from './errors.mjs';
+import { derivePrincipalId } from './canonical.mjs';
+const int = (value, fallback, min, max) => { const n = Number(value ?? fallback); if (!Number.isSafeInteger(n) || n < min || n > max) throw new Error(`Invalid integer configuration: ${value}`); return n; };
+const exactOrigin = (value) => { const url = new URL(value); if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('POSTMAN_ORIGIN must be an exact HTTPS origin with no path, credentials, query, or fragment.'); return url.origin; };
+const list = (value) => String(value || '').split(',').map(v => v.trim()).filter(Boolean);
+const opaqueToken = (value, field, fallback, max) => { if (value !== undefined && typeof value !== 'string') throw new Error(`${field} must be a string when configured.`); const text = value === undefined || value === '' ? fallback : value; if (text === undefined) return undefined; if (!text.length || text.length > max || !/^[\x21-\x7E]+$/.test(text)) throw new Error(`${field} must be ${max} or fewer visible ASCII characters with no whitespace.`); return text; };
+const strategyValue = env => {
+  const configured = env.POSTMAN_TRANSPORT_STRATEGY;
+  if (configured === undefined || configured === '') {
+    if (env.POSTMAN_SESSION_COOKIE !== undefined || env.POSTMAN_WORKSPACE_SUBDOMAIN !== undefined) throw new Error('POSTMAN_TRANSPORT_STRATEGY is required when web-session configuration is present.');
+    return { strategy: 'access_token', explicit: false };
+  }
+  if (configured !== 'access_token' && configured !== 'web_session') throw new Error('POSTMAN_TRANSPORT_STRATEGY must be access_token or web_session.');
+  return { strategy: configured, explicit: true };
+};
+const present = value => value !== undefined && value !== '';
+const requiredString = (value, field) => { if (typeof value !== 'string' || value === '') throw new Error(`${field} is required.`); return value; };
+const sessionCookie = value => {
+  const text = requiredString(value, 'POSTMAN_SESSION_COOKIE');
+  if (Buffer.byteLength(text, 'utf8') > 4096 || !/^[\x21-\x7E]+$/.test(text) || /[;,\\]/.test(text)) throw new Error('POSTMAN_SESSION_COOKIE must be 1-4096 visible ASCII bytes and contain no whitespace, controls, semicolon, comma, or backslash.');
+  return text;
+};
+const workspaceSubdomain = value => {
+  const text = requiredString(value, 'POSTMAN_WORKSPACE_SUBDOMAIN');
+  if (text.length > 63 || text.startsWith('xn--') || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(text)) throw new Error('POSTMAN_WORKSPACE_SUBDOMAIN must be one non-punycode lowercase ASCII DNS label of 1-63 characters.');
+  return text;
+};
+const workspaceIdentifier = value => opaqueToken(value, 'POSTMAN_WORKSPACE_ID', undefined, 256);
+const optionalHeaderValue = (value, field, max) => present(value) ? opaqueToken(value, field, undefined, max) : undefined;
+const excludedTools = value => { if (value === undefined || value === '') return Object.freeze([]); if (typeof value !== 'string') throw new Error('POSTMAN_EXCLUDED_TOOLS must be a comma-separated string when configured.'); const raw = value.split(','); if (raw.length > 64) throw new Error('POSTMAN_EXCLUDED_TOOLS must contain at most 64 entries.'); const values = raw.map(value => value.trim()); if (values.some(value => !/^[A-Za-z0-9_.:-]{1,128}$/.test(value))) throw new Error('POSTMAN_EXCLUDED_TOOLS entries must be 1-128 tool-name characters.'); if (new Set(values).size !== values.length) throw new Error('POSTMAN_EXCLUDED_TOOLS must not contain duplicates.'); return Object.freeze(values); };
+const observedModels = value => { if (value === undefined || value === '') return Object.freeze([]); if (typeof value !== 'string') throw new Error('POSTMAN_WEB_SESSION_OBSERVED_MODELS must be a comma-separated string when configured.'); const values = value.split(',').map(value => value.trim()); if (values.length > 16 || values.some(value => !value || Buffer.byteLength(value, 'utf8') > 128 || !/^[\x21-\x7E]+$/.test(value))) throw new Error('POSTMAN_WEB_SESSION_OBSERVED_MODELS must contain at most 16 bounded visible-ASCII labels.'); if (new Set(values).size !== values.length) throw new Error('POSTMAN_WEB_SESSION_OBSERVED_MODELS must not contain duplicates.'); return Object.freeze(values); };
+export function loadConfig(env = process.env) {
+  const models = list(env.PROVIDER_MODELS); if (!models.length) throw new Error('PROVIDER_MODELS must contain at least one explicit model ID.');
+  const apiKey = String(env.PROVIDER_API_KEY || ''); if (!apiKey) throw new Error('PROVIDER_API_KEY is required.');
+  const { strategy, explicit } = strategyValue(env);
+  const workspaceId = workspaceIdentifier(env.POSTMAN_WORKSPACE_ID); if (!workspaceId) throw new Error('POSTMAN_WORKSPACE_ID is required.');
+  let upstreamToken, upstreamOrigin, chatPath, webSessionCookie, webSessionSubdomain, selectedUpstreamModel, webSessionAppVersion, webSessionObservedModels = Object.freeze([]);
+  if (strategy === 'access_token') {
+    if (present(env.POSTMAN_SESSION_COOKIE) || present(env.POSTMAN_WORKSPACE_SUBDOMAIN) || present(env.POSTMAN_WEB_SESSION_SELECTED_MODEL)) throw new Error('access_token forbids web-session configuration.');
+    upstreamToken = requiredString(env.POSTMAN_ACCESS_TOKEN, 'POSTMAN_ACCESS_TOKEN');
+    upstreamOrigin = exactOrigin(env.POSTMAN_ORIGIN);
+    chatPath = env.POSTMAN_CHAT_PATH || '/chat';
+  } else {
+    if (present(env.POSTMAN_ACCESS_TOKEN) || present(env.POSTMAN_ORIGIN) || present(env.POSTMAN_CHAT_PATH)) throw new Error('web_session forbids POSTMAN_ACCESS_TOKEN, POSTMAN_ORIGIN, and POSTMAN_CHAT_PATH.');
+    webSessionCookie = sessionCookie(env.POSTMAN_SESSION_COOKIE);
+    webSessionSubdomain = workspaceSubdomain(env.POSTMAN_WORKSPACE_SUBDOMAIN);
+    selectedUpstreamModel = opaqueToken(env.POSTMAN_WEB_SESSION_SELECTED_MODEL, 'POSTMAN_WEB_SESSION_SELECTED_MODEL', undefined, 128);
+    if (!selectedUpstreamModel) throw new Error('POSTMAN_WEB_SESSION_SELECTED_MODEL is required.');
+    webSessionAppVersion = optionalHeaderValue(env.POSTMAN_APP_VERSION, 'POSTMAN_APP_VERSION', 128);
+    webSessionObservedModels = observedModels(env.POSTMAN_WEB_SESSION_OBSERVED_MODELS);
+  }
+  return Object.freeze({
+    host: env.PROVIDER_HOST || '127.0.0.1', port: int(env.PROVIDER_PORT, 0, 0, 65535), apiKey, transportStrategy: strategy, transportStrategyExplicit: explicit, upstreamToken, workspaceId,
+    upstreamOrigin, chatPath, appVersion: strategy === 'access_token' ? (env.POSTMAN_APP_VERSION || 'offline-adapter/0.1.0') : undefined,
+    webSessionCookie, webSessionSubdomain, selectedUpstreamModel, webSessionAppVersion, webSessionObservedModels,
+    platform: opaqueToken(env.POSTMAN_PLATFORM, 'POSTMAN_PLATFORM', 'OPENAI_COMPATIBLE_ADAPTER', 64), nativeToolsHash: opaqueToken(env.POSTMAN_NATIVE_TOOLS_HASH, 'POSTMAN_NATIVE_TOOLS_HASH', undefined, 256), excludedTools: excludedTools(env.POSTMAN_EXCLUDED_TOOLS),
+    models: Object.freeze(models), timeoutMs: int(env.REQUEST_TIMEOUT_MS, 120000, 100, 600000), maxBodyBytes: int(env.MAX_BODY_BYTES, 104857600, 1024, 209715200),
+    maxEventBytes: int(env.MAX_EVENT_BYTES, 1048576, 1024, 8388608), maxOutputBytes: int(env.MAX_OUTPUT_BYTES, 4194304, 1024, 16777216),
+    maxToolArgumentBytes: int(env.MAX_TOOL_ARGUMENT_BYTES, 262144, 256, 4194304), maxTools: int(env.MAX_TOOLS, 64, 0, 256),
+    maxToolResultBytes: int(env.MAX_TOOL_RESULT_BYTES, 262144, 256, 4194304), maxConcurrent: int(env.MAX_CONCURRENT_REQUESTS, 16, 1, 1024),
+    correlationEnabled: env.CORRELATION_ENABLED !== 'false', principalKey: env.CORRELATION_PRINCIPAL_KEY || randomBytes(32).toString('base64url'), credentialSlotId: env.PROVIDER_CREDENTIAL_SLOT_ID || 'default',
+    correlationPendingTtlMs: int(env.CORRELATION_PENDING_TTL_MS, 900000, 100, 86400000), correlationTerminalTtlMs: int(env.CORRELATION_TERMINAL_TTL_MS, 900000, 100, 86400000), correlationInflightTtlMs: int(env.CORRELATION_INFLIGHT_TTL_MS, 150000, 100, 3600000),
+    correlationMaxGroups: int(env.CORRELATION_MAX_GROUPS, 1000, 1, 100000), correlationMaxCalls: int(env.CORRELATION_MAX_CALLS, 4096, 1, 100000), correlationMaxBytes: int(env.CORRELATION_MAX_BYTES, 16777216, 1024, 1073741824), exposeHealthDetails: env.EXPOSE_HEALTH_DETAILS === 'true'
+  });
+}
+export function authenticate(value, expected, config = null) {
+  const bearer = typeof value === 'string' && value.startsWith('Bearer ') ? value.slice(7) : '';
+  const a = Buffer.from(bearer), b = Buffer.from(expected);
+  if (!b.length || a.length !== b.length || !timingSafeEqual(a, b)) throw new ProviderError(401, 'Invalid bearer token.', 'authentication_error', 'invalid_api_key');
+  if (!config) return true;
+  const slot = config.credentialSlotId || 'default';
+  return { credentialSlotId: slot, principalId: derivePrincipalId(config.principalKey || `ephemeral:${expected}`, slot), workspaceId: config.workspaceId };
+}
+export function assertModel(model, config) { if (typeof model !== 'string' || !config.models.includes(model)) throw invalid('Unknown or disallowed model.', 'model_not_allowed'); return model; }
+export function webSessionUrl(config) {
+  if (config.transportStrategy !== 'web_session') throw new Error('webSessionUrl requires web_session configuration.');
+  const expectedOrigin = `https://${config.webSessionSubdomain}.postman.co`;
+  const url = new URL('/_gw/chat', `${expectedOrigin}/`);
+  if (url.protocol !== 'https:' || url.username || url.password || url.hostname !== `${config.webSessionSubdomain}.postman.co` || url.port || url.pathname !== '/_gw/chat' || url.search || url.hash || url.origin !== expectedOrigin) throw new Error('Web-session URL construction failed validation.');
+  return url;
+}
+export function upstreamUrl(config) { const path = config.chatPath.startsWith('/') ? config.chatPath : `/${config.chatPath}`; const url = new URL(path, `${config.upstreamOrigin}/`); if (url.origin !== config.upstreamOrigin) throw new Error('Upstream origin changed unexpectedly.'); return url; }
+export class ConcurrencyGate {
+  #active = 0; constructor(limit) { this.limit = limit; }
+  enter() { if (this.#active >= this.limit) throw new ProviderError(429, 'Provider concurrency limit reached.', 'rate_limit_error', 'concurrency_limit'); this.#active++; let left=false; return () => { if (!left) { left=true; this.#active--; } }; }
+  get active() { return this.#active; }
+}

package/src/correlation-store.mjs

@@ -0,0 +1,120 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { ProviderError } from './errors.mjs';
+import { canonicalHash } from './canonical.mjs';
+
+const fail = (status, code, message) => new ProviderError(status, message, status === 429 ? 'rate_limit_error' : 'invalid_request_error', code);
+const publicId = rng => `call_pmn_${rng(24).toString('base64url')}`;
+
+// Correlation binds the declared tool contract, not the per-turn execution directive.
+// A normal tool lifecycle may use `required` (or a named choice) to obtain a call,
+// then `auto` after supplying the result. The function definitions must remain exact.
+export function structuralToolsBinding(toolsBinding) {
+  const tools = structuredClone(toolsBinding?.tools ?? []);
+  tools.sort((a, b) => (a?.function?.name ?? '').localeCompare(b?.function?.name ?? ''));
+  return {
+    tools,
+    toolExecutionDisabled: toolsBinding?.toolChoice === String.fromCharCode(110, 111, 110, 101),
+  };
+}
+
+export class CorrelationStore {
+  #groups = new Map();
+  #calls = new Map();
+  #bytes = 0;
+  constructor({ pendingTtlMs = 900000, terminalTtlMs = 900000, inflightTtlMs = 150000, maxGroups = 1000, maxCalls = 4096, maxBytes = 16 * 1024 * 1024, maxTerminalResponseBytes = 1024 * 1024, now = Date.now, rng = randomBytes } = {}) {
+    Object.assign(this, { pendingTtlMs, terminalTtlMs, inflightTtlMs, maxGroups, maxCalls, maxBytes, maxTerminalResponseBytes, now, rng });
+  }
+  get size() { return this.#groups.size; }
+  get bytes() { return this.#bytes; }
+  #key(principalId, id) {
+    const cleanId = typeof id === 'string' ? id.replace(/[^a-zA-Z0-9]/g, '') : id;
+    return `${principalId}:${cleanId}`;
+  }
+  #transitionExpired(group, now = this.now()) {
+    if (group.state === 'PENDING' && now >= group.pendingExpiresAt) {
+      group.state = 'EXPIRED'; group.terminalExpiresAt = now + this.terminalTtlMs;
+    } else if (group.state === 'INFLIGHT' && now >= group.inflightExpiresAt) {
+      group.state = 'UNCERTAIN'; group.terminalExpiresAt = now + this.terminalTtlMs;
+    }
+  }
+  #estimate(record) { return Buffer.byteLength(JSON.stringify(record), 'utf8'); }
+  admit({ principalId, workspaceId, model, transportStrategy = 'access_token', transportOrigin = null, conversationId, upstreamGroupId = null, transcript, toolsBinding, catalogMetadata = {}, calls }) {
+    if (!principalId || !workspaceId || !model || !conversationId || !Array.isArray(calls) || !calls.length) throw new TypeError('Invalid correlation admission.');
+    if (calls.length > 1 && !upstreamGroupId) throw fail(502, 'upstream_ungrouped_tool_batch', 'Upstream returned multiple ungrouped tool calls.');
+    const ids = [];
+    for (let index = 0; index < calls.length; index++) {
+      let id; do id = publicId(this.rng); while (this.#calls.has(this.#key(principalId, id)) || ids.includes(id));
+      ids.push(id);
+    }
+    const publicTranscript = structuredClone(transcript);
+    for (const message of publicTranscript) if (Array.isArray(message.tool_calls)) for (const call of message.tool_calls) {
+      const index = calls.findIndex(value => value.upstreamToolCallId === call.id); if (index >= 0) call.id = ids[index];
+    }
+    const now = this.now();
+    const group = {
+      principalId, workspaceId, model, transportStrategy, transportOrigin, conversationId, upstreamGroupId, groupKey: randomUUID(), state: 'PENDING',
+      issuedAt: now, pendingExpiresAt: now + this.pendingTtlMs, terminalExpiresAt: null, inflightExpiresAt: null,
+      transcript: publicTranscript, transcriptHash: canonicalHash(publicTranscript), transcriptPrefixLength: publicTranscript.length,
+      toolsBinding: structuralToolsBinding(toolsBinding), toolsHash: canonicalHash(structuralToolsBinding(toolsBinding)), catalogMetadata: structuredClone(catalogMetadata), catalogMetadataHash: canonicalHash(catalogMetadata), acceptedResultsHash: null, dispatchAttemptId: null,
+      terminalResponse: null, terminalResponseDigest: null,
+      calls: calls.map((call, index) => ({ ...call, index, publicToolCallId: ids[index], argumentsHash: canonicalHash([call.originalName, call.argumentsJson, call.schemaHash]) })),
+    };
+    group.recordBytes = this.#estimate(group);
+    this.sweep(now);
+    const liveCalls = [...this.#groups.values()].reduce((n, value) => n + value.calls.length, 0);
+    if (this.#groups.size + 1 > this.maxGroups || liveCalls + group.calls.length > this.maxCalls || this.#bytes + group.recordBytes > this.maxBytes) throw fail(429, 'correlation_capacity_exceeded', 'Tool-call correlation capacity is full.');
+    this.#groups.set(group.groupKey, group); this.#bytes += group.recordBytes;
+    for (const call of group.calls) this.#calls.set(this.#key(principalId, call.publicToolCallId), group);
+    return group;
+  }
+  resolve(principalId, ids) {
+    const distinct = [...new Set(ids)];
+    const groups = distinct.map(id => this.#calls.get(this.#key(principalId, id)));
+    if (groups.some(group => !group)) throw fail(404, 'unknown_tool_call', 'Unknown tool call.');
+    const group = groups[0];
+    if (groups.some(value => value !== group)) throw fail(400, 'tool_result_group_mismatch', 'Tool results belong to different groups.');
+    this.#transitionExpired(group);
+    return group;
+  }
+  claim({ principalId, results, workspaceId, model, transportStrategy = 'access_token', transportOrigin = null, transcript, toolsBinding, catalogMetadata = {} }) {
+    if (!Array.isArray(results) || !results.length) throw fail(400, 'tool_result_incomplete', 'Tool results are incomplete.');
+    const ids = results.map(result => result.toolCallId);
+    if (new Set(ids).size !== ids.length) throw fail(400, 'tool_result_group_mismatch', 'Duplicate tool results are not allowed.');
+    const group = this.resolve(principalId, ids);
+    const orderedResults = group.calls.map(call => results.find(result => result.toolCallId === call.publicToolCallId));
+    if (results.length !== group.calls.length || orderedResults.some(value => !value)) throw fail(400, 'tool_result_incomplete', 'Tool results are incomplete.');
+    const resultsHash = canonicalHash(orderedResults.map((result, index) => [group.calls[index].publicToolCallId, result.content]));
+    if (group.state === 'EXPIRED') throw fail(410, 'tool_call_expired', 'Tool call expired.');
+    if (group.state === 'CANCELLED') throw fail(409, 'tool_call_cancelled', 'Tool call was cancelled.');
+    if (group.state === 'UNCERTAIN') throw fail(502, 'continuation_outcome_uncertain', 'Tool result outcome is uncertain and cannot be retried automatically.');
+    if (group.state === 'INFLIGHT') throw fail(409, group.acceptedResultsHash === resultsHash ? 'continuation_inflight' : 'continuation_conflict', group.acceptedResultsHash === resultsHash ? 'Tool result continuation is already in flight.' : 'Tool result conflicts with the in-flight continuation.');
+    if (group.state === 'CONSUMED') throw fail(409, group.acceptedResultsHash === resultsHash ? 'tool_call_already_consumed' : 'continuation_conflict', group.acceptedResultsHash === resultsHash ? 'Tool result continuation was already consumed.' : 'Tool result conflicts with the consumed continuation.');
+    if (workspaceId !== group.workspaceId) throw fail(409, 'continuation_workspace_mismatch', 'Continuation workspace does not match.');
+    if (transportStrategy !== group.transportStrategy) throw fail(409, 'continuation_strategy_mismatch', 'Continuation transport strategy does not match.');
+    if (transportOrigin !== group.transportOrigin) throw fail(409, 'continuation_origin_mismatch', 'Continuation transport origin does not match.');
+    if (model !== group.model) throw fail(409, 'continuation_model_mismatch', 'Continuation model does not match.');
+    if (canonicalHash(structuralToolsBinding(toolsBinding)) !== group.toolsHash) throw fail(409, 'continuation_tools_mismatch', 'Continuation tools do not match.');
+    if (canonicalHash(catalogMetadata) !== group.catalogMetadataHash) throw fail(409, 'continuation_catalog_mismatch', 'Continuation catalog metadata does not match.');
+    if (canonicalHash(transcript) !== group.transcriptHash) throw fail(409, 'continuation_history_mismatch', 'Continuation history does not match.');
+    const now = this.now(); group.state = 'INFLIGHT'; group.acceptedResultsHash = resultsHash; group.dispatchAttemptId = randomUUID(); group.inflightExpiresAt = now + this.inflightTtlMs;
+    return { group, orderedResults, dispatchAttemptId: group.dispatchAttemptId };
+  }
+  complete(group, response = null) {
+    if (group.state !== 'INFLIGHT') return;
+    group.state = 'CONSUMED'; group.terminalExpiresAt = this.now() + this.terminalTtlMs; group.inflightExpiresAt = null;
+    if (response !== null) { const text = typeof response === 'string' ? response : JSON.stringify(response); if (Buffer.byteLength(text) <= this.maxTerminalResponseBytes) { group.terminalResponse = response; group.terminalResponseDigest = canonicalHash(response); } }
+  }
+  releasePreSend(group) { if (group.state === 'INFLIGHT') { group.state = 'PENDING'; group.acceptedResultsHash = null; group.dispatchAttemptId = null; group.inflightExpiresAt = null; } }
+  uncertain(group) { if (group.state === 'INFLIGHT') { group.state = 'UNCERTAIN'; group.terminalExpiresAt = this.now() + this.terminalTtlMs; group.inflightExpiresAt = null; } }
+  cancel(group) { if (group.state === 'PENDING') { group.state = 'CANCELLED'; group.terminalExpiresAt = this.now() + this.terminalTtlMs; return true; } return false; }
+  sweep(now = this.now()) {
+    for (const group of [...this.#groups.values()]) {
+      this.#transitionExpired(group, now);
+      if (group.terminalExpiresAt !== null && now >= group.terminalExpiresAt && !['PENDING', 'INFLIGHT'].includes(group.state)) {
+        this.#groups.delete(group.groupKey); this.#bytes -= group.recordBytes;
+        for (const call of group.calls) this.#calls.delete(this.#key(group.principalId, call.publicToolCallId));
+      }
+    }
+  }
+  inspect(principalId, id) { const group = this.#calls.get(this.#key(principalId, id)); if (group) this.#transitionExpired(group); return group || null; }
+}

package/src/errors.mjs

@@ -0,0 +1,18 @@
+export class ProviderError extends Error {
+  constructor(status, message, type = 'api_error', code = 'provider_error', param = null, options = {}) {
+    super(message, options);
+    this.name = 'ProviderError'; this.status = status; this.type = type; this.code = code; this.param = param;
+    this.retryAfter = options.retryAfter;
+  }
+}
+export const invalid = (message, code = 'invalid_request') => new ProviderError(400, message, 'invalid_request_error', code);
+export const upstream = (message, code = 'upstream_error', status = 502, options = {}) => new ProviderError(status, message, status === 429 ? 'rate_limit_error' : status === 401 || status === 403 ? 'authentication_error' : 'api_error', code, null, options);
+export function errorBody(error, requestId) {
+  const value = error instanceof ProviderError ? error : new ProviderError(500, 'The provider could not complete the request.', 'api_error', 'internal_error');
+  const body = { error: { message: value.message, type: value.type, code: value.code, param: value.param }, request_id: requestId };
+  if (value.code === 'upstream_model_mismatch') {
+    if (typeof value.observedModel === 'string' && /^[\x20-\x7E]{1,128}$/.test(value.observedModel)) body.error.observed_model = value.observedModel;
+    if (typeof value.observedModelField === 'string' && /^(?:metadata|data)(?:\.metadata)?\.(?:model|modelId|selectedModel)$/.test(value.observedModelField)) body.error.observed_model_field = value.observedModelField;
+  }
+  return body;
+}