aki-pro-max 2.3.3

package/test/9router-executor.integration.test.mjs

@@ -0,0 +1,207 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import { createProviderServer } from '../src/server.mjs';
+
+// This suite exercises the real 9router DefaultExecutor and model parser checked out
+// at the pinned commit. Only the Postman-facing fetch inside the facade is injected.
+const routerRoot = new URL('../../../tmp/9router-pinned-17c4cc7/', import.meta.url);
+const { DefaultExecutor } = await import(new URL('open-sse/executors/default.js', routerRoot));
+const { parseModel } = await import(new URL('open-sse/services/model.js', routerRoot));
+
+const encoder = new TextEncoder();
+const sseResponse = frames => new Response(new ReadableStream({
+  start(controller) {
+    for (const frame of frames) controller.enqueue(encoder.encode(`event: message\ndata: ${JSON.stringify(frame)}\n\n`));
+    controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+    controller.close();
+  },
+}), { status: 200, headers: { 'content-type': 'text/event-stream' } });
+
+const textFrames = [
+  { eventType: 'conversation', data: { id: 'conv_fixture' } },
+  { eventType: 'textChunk', data: { textContent: 'hello' } },
+];
+const toolFrames = [
+  { eventType: 'conversation', data: { id: 'conv_tool' } },
+  { eventType: 'toolCallChunk', data: { id: 'call_fixture', index: 0, name: 'openai__lookup', toolCallGroupId: 'group_fixture' } },
+  { eventType: 'toolCallChunk', data: { id: 'call_fixture', index: 0, arguments: '{"q":' } },
+  { eventType: 'toolCallChunk', data: { id: 'call_fixture', index: 0, arguments: '"x"}' } },
+];
+
+const config = {
+  host: '127.0.0.1', port: 0, apiKey: 'router-to-facade-key', upstreamToken: 'fixture-upstream-token',
+  workspaceId: 'ws_fixture', upstreamOrigin: 'https://fixture.invalid', chatPath: '/chat', appVersion: 'integration/0.1',
+  models: ['fixture-model'], timeoutMs: 1000, maxBodyBytes: 1024 * 1024, maxEventBytes: 1024 * 1024,
+  maxOutputBytes: 1024 * 1024, maxToolArgumentBytes: 1024 * 1024, maxTools: 64, maxConcurrent: 8,
+  exposeHealthDetails: false, correlationEnabled: true, principalKey: 'router-test-principal', credentialSlotId: 'router-client',
+  maxToolResultBytes: 1024 * 1024, correlationPendingTtlMs: 1000, correlationTerminalTtlMs: 1000, correlationInflightTtlMs: 1000,
+  correlationMaxGroups: 100, correlationMaxCalls: 100, correlationMaxBytes: 1024 * 1024,
+};
+const log = { debug() {}, info() {}, error() {} };
+const provider = 'openai-compatible-chat-fixture';
+const credentialsFor = baseUrl => ({
+  apiKey: 'router-to-facade-key',
+  providerSpecificData: { baseUrl: `${baseUrl}/v1`, apiType: 'chat' },
+});
+
+async function withFacade(upstreamFixture, fn, configOverride = {}) {
+  const captures = [];
+  const server = createProviderServer({ ...config, ...configOverride }, {
+    logger: { error() {} },
+    fetchImpl: async (url, init) => {
+      captures.push({ url: String(url), init, body: JSON.parse(init.body) });
+      return upstreamFixture(captures.at(-1));
+    },
+  });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const { port } = server.address();
+  try { await fn(`http://127.0.0.1:${port}`, captures); }
+  finally { await new Promise(resolve => server.close(resolve)); }
+}
+
+function routedModel(value = `${provider}/fixture-model`) {
+  const parsed = parseModel(value);
+  assert.equal(parsed.provider, provider);
+  assert.equal(parsed.model, 'fixture-model');
+  return parsed;
+}
+
+const baseBody = { model: `${provider}/fixture-model`, messages: [{ role: 'user', content: 'hi' }], stream: false };
+
+async function execute(executor, baseUrl, body, signal = new AbortController().signal) {
+  const parsed = routedModel(body.model);
+  const forwarded = { ...body, model: parsed.model };
+  return executor.execute({ model: parsed.model, body: forwarded, stream: forwarded.stream === true, credentials: credentialsFor(baseUrl), signal, log });
+}
+
+test('pinned 9router executor builds exact URL/auth and strips route prefix for JSON', async () => {
+  await withFacade(() => sseResponse(textFrames), async (baseUrl, captures) => {
+    const executor = new DefaultExecutor(provider);
+    const { response, url, transformedBody, headers } = await execute(executor, baseUrl, baseBody);
+    assert.equal(url, `${baseUrl}/v1/chat/completions`);
+    assert.equal(headers.Authorization, 'Bearer router-to-facade-key');
+    assert.equal(transformedBody.model, 'fixture-model');
+    assert.equal(response.status, 200);
+    const result = await response.json();
+    assert.equal(result.model, 'fixture-model');
+    assert.equal(result.choices[0].message.content, 'hello');
+    assert.equal(captures.length, 1);
+    assert.equal(captures[0].url, 'https://fixture.invalid/chat');
+    assert.equal(captures[0].init.headers['x-access-token'], 'fixture-upstream-token');
+  });
+});
+
+test('pinned 9router executor preserves OpenAI SSE chunks and DONE from facade', async () => {
+  await withFacade(() => sseResponse(textFrames), async (baseUrl) => {
+    const executor = new DefaultExecutor(provider);
+    const { response } = await execute(executor, baseUrl, { ...baseBody, stream: true });
+    assert.match(response.headers.get('content-type'), /text\/event-stream/);
+    const wire = await response.text();
+    assert.match(wire, /"content":"hello"/);
+    assert.match(wire, /"finish_reason":"stop"/);
+    assert.match(wire, /data: \[DONE\]/);
+  });
+});
+
+test('pinned 9router executor consumes explicit web_session text JSON and SSE from the facade', async () => {
+  const webConfig = { transportStrategy: 'web_session', webSessionCookie: 'dummy-cookie-value', webSessionSubdomain: 'fixture-team', selectedUpstreamModel: 'GPT_56_SOL', webSessionObservedModels: ['gpt-5.6-sol'] };
+  const upstreamFixture = () => sseResponse([
+    { eventType: 'conversation', data: { id: 'web-conversation' } },
+    { eventType: 'textChunk', data: { textContent: 'web-session-ok', metadata: { model: 'gpt-5.6-sol' } } },
+  ]);
+  await withFacade(upstreamFixture, async baseUrl => {
+    const executor = new DefaultExecutor(provider);
+    let result = await execute(executor, baseUrl, baseBody);
+    assert.equal(result.response.status, 200); assert.equal((await result.response.json()).choices[0].message.content, 'web-session-ok');
+    result = await execute(executor, baseUrl, { ...baseBody, stream: true });
+    assert.equal(result.response.status, 200); const wire = await result.response.text(); assert.match(wire, /web-session-ok/); assert.match(wire, /\[DONE\]/);
+  }, webConfig);
+});
+
+test('pinned 9router executor completes native role=tool roundtrip and consumed replay is 409', async () => {
+  let sequence = 0;
+  await withFacade(() => sequence++ === 0 ? sseResponse(toolFrames) : sseResponse([{ eventType:'conversation',data:{id:'conv_tool'} },{ eventType:'textChunk',data:{textContent:'native final'} }]), async (baseUrl, captures) => {
+    const executor = new DefaultExecutor(provider);
+    const tool = { type: 'function', function: { name: 'lookup', description: 'lookup', parameters: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'], additionalProperties: false } } };
+    const first = await execute(executor, baseUrl, { ...baseBody, tools: [tool] });
+    const toolReply = await first.response.json(); const assistant=toolReply.choices[0].message; const call=assistant.tool_calls[0];
+    assert.match(call.id,/^call_pmn_/); assert.notEqual(call.id,'call_fixture');
+    const secondBody = { ...baseBody, tools: [tool], messages: [{ role:'user',content:'hi' },assistant,{ role:'tool',tool_call_id:call.id,content:'lookup-result' }] };
+    const second=await execute(executor,baseUrl,secondBody); assert.equal(second.response.status,200); assert.equal((await second.response.json()).choices[0].message.content,'native final');
+    const replay=await execute(executor,baseUrl,secondBody); assert.equal(replay.response.status,409); assert.equal((await replay.response.json()).error.code,'tool_call_already_consumed');
+    assert.equal(captures.length,2); assert.equal(captures[1].body.input.chatType,'TOOL_RESPONSE'); assert.equal(captures[1].body.input.toolCallGroupId,'group_fixture'); assert.equal(captures[1].body.input.toolResponses[0].toolCallId,'call_fixture');
+  });
+});
+test('pinned 9router executor completes web_session tool call -> result -> final against injected mock', async () => {
+  const webConfig = { transportStrategy: 'web_session', webSessionCookie: 'dummy-cookie-value', webSessionSubdomain: 'fixture-team', selectedUpstreamModel: 'GPT_56_SOL', webSessionObservedModels: ['gpt-5.6-sol'] };
+  let sequence=0;
+  const upstreamFixture=()=>sequence++===0?sseResponse([
+    {eventType:'conversation',data:{id:'web-tool-conv'}},
+    {eventType:'toolCallChunk',data:{id:'web-up-call',index:0,name:'openai__lookup',arguments:'{"q":"x"}',metadata:{model:'gpt-5.6-sol'}}},
+  ]):sseResponse([{eventType:'conversation',data:{id:'web-tool-conv'}},{eventType:'textChunk',data:{textContent:'web tool final',metadata:{model:'gpt-5.6-sol'}}}]);
+  await withFacade(upstreamFixture,async baseUrl=>{
+    const executor=new DefaultExecutor(provider);const tool={type:'function',function:{name:'lookup',parameters:{type:'object',properties:{q:{type:'string'}},required:['q'],additionalProperties:false}}};
+    const first=await execute(executor,baseUrl,{...baseBody,tools:[tool]});const assistant=(await first.response.json()).choices[0].message;const second=await execute(executor,baseUrl,{...baseBody,tools:[tool],messages:[{role:'user',content:'hi'},assistant,{role:'tool',tool_call_id:assistant.tool_calls[0].id,content:'ok'}]});assert.equal((await second.response.json()).choices[0].message.content,'web tool final');
+  },webConfig);
+});
+
+test('pinned 9router executor returns facade auth/model errors without live fallback', async () => {
+  await withFacade(() => sseResponse(textFrames), async (baseUrl) => {
+    const executor = new DefaultExecutor(provider);
+    const badCredentials = { apiKey: 'wrong', providerSpecificData: { baseUrl: `${baseUrl}/v1`, apiType: 'chat' } };
+    const auth = await executor.execute({ model: 'fixture-model', body: { ...baseBody, model: 'fixture-model' }, stream: false, credentials: badCredentials, signal: new AbortController().signal, log });
+    assert.equal(auth.response.status, 401);
+    assert.equal((await auth.response.json()).error.code, 'invalid_api_key');
+    const model = await executor.execute({ model: 'other', body: { ...baseBody, model: 'other' }, stream: false, credentials: credentialsFor(baseUrl), signal: new AbortController().signal, log });
+    assert.equal(model.response.status, 400);
+    assert.equal((await model.response.json()).error.code, 'model_not_allowed');
+  });
+});
+
+test('pinned 9router executor sees post-header error without successful DONE', async () => {
+  await withFacade(() => sseResponse([
+    { eventType: 'conversation', data: { id: 'conv_error' } },
+    { eventType: 'textChunk', data: { textContent: 'partial' } },
+    { eventType: 'error', data: { errorType: 'LLM_STREAM_ERROR', message: 'Bearer secret-value' } },
+  ]), async (baseUrl) => {
+    const executor = new DefaultExecutor(provider);
+    const { response } = await execute(executor, baseUrl, { ...baseBody, stream: true });
+    assert.equal(response.status, 200);
+    const wire = await response.text();
+    assert.match(wire, /"content":"partial"/);
+    assert.match(wire, /"code":"upstream_stream_error"/);
+    assert.equal(wire.includes('secret-value'), false);
+    assert.equal(wire.includes('finish_reason":"stop"'), false);
+    assert.equal(wire.includes('[DONE]'), false);
+  });
+});
+
+test('pinned 9router executor receives pre-header tool validation error as JSON', async () => {
+  await withFacade(() => sseResponse([{ eventType: 'error', errorType: 'TOOL_VALIDATION_ERROR', message: 'secret-value' }]), async (baseUrl) => {
+    const executor = new DefaultExecutor(provider);
+    const { response } = await execute(executor, baseUrl, baseBody);
+    assert.equal(response.status, 400);
+    const wire = await response.text();
+    const value = JSON.parse(wire);
+    assert.equal(value.error.code, 'upstream_tool_validation_error');
+    assert.equal(wire.includes('secret-value'), false);
+  });
+});
+
+test('pinned 9router executor propagates abort through facade to injected upstream', async () => {
+  let upstreamAborted = false;
+  await withFacade(capture => new Promise((resolve, reject) => {
+    capture.init.signal.addEventListener('abort', () => { upstreamAborted = true; reject(capture.init.signal.reason); }, { once: true });
+  }), async (baseUrl) => {
+    const executor = new DefaultExecutor(provider);
+    const controller = new AbortController();
+    const pending = execute(executor, baseUrl, baseBody, controller.signal);
+    setTimeout(() => controller.abort(new DOMException('integration abort', 'AbortError')), 30);
+    await assert.rejects(pending, error => error?.name === 'AbortError');
+    await new Promise(resolve => setTimeout(resolve, 30));
+    assert.equal(upstreamAborted, true);
+  });
+});
+

package/test/admin-auth.test.mjs

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { authStatus, discoverPostmanDesktop, saveAuthConfig, validateAuthInput } from '../src/admin-auth.mjs';
+
+const valid = { sessionCookie: 'session-secret-1234', subdomain: 'team-a', workspaceId: 'workspace-1', selectedModel: 'GPT_56_SOL' };
+
+test('auth input validates bounded fields without echo helpers', () => {
+  assert.deepEqual(validateAuthInput(valid), valid);
+  assert.throws(() => validateAuthInput({ ...valid, sessionCookie: 'bad;cookie' }), /unsupported/);
+  assert.throws(() => validateAuthInput({ ...valid, subdomain: 'Bad Host' }), /invalid/);
+  const status = authStatus({ transportStrategy: 'web_session', webSessionCookie: valid.sessionCookie, webSessionSubdomain: valid.subdomain, workspaceId: valid.workspaceId, selectedUpstreamModel: valid.selectedModel });
+  assert.equal(status.cookie.masked, '••••1234');
+  assert.equal(JSON.stringify(status).includes(valid.sessionCookie), false);
+});
+
+test('desktop discovery is bounded metadata-only and never imports session', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'postman-discovery-'));
+  const roaming = join(root, 'roaming'); const local = join(root, 'local');
+  const fs = await import('node:fs/promises');
+  await Promise.all([fs.mkdir(join(roaming, 'Postman'), { recursive: true }), fs.mkdir(join(local, 'Postman'), { recursive: true })]);
+  await fs.writeFile(join(local, 'Postman', 'Postman.exe'), '');
+  const found = await discoverPostmanDesktop({ APPDATA: roaming, LOCALAPPDATA: local });
+  assert.equal(found.installed, true); assert.equal(found.profileDetected, true);
+  assert.equal(found.sessionAutoImportAvailable, false); assert.equal(found.manualCredentialRequired, true);
+  assert.equal(JSON.stringify(found).includes('session-secret'), false);
+});
+
+test('auth config failed pre-rename apply restores original file', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'postman-auth-fault-')); const envFile = join(root, '.env');
+  const original = 'PROVIDER_PORT=8788\nPOSTMAN_SESSION_COOKIE=original\n'; await writeFile(envFile, original, 'utf8');
+  await assert.rejects(() => saveAuthConfig(valid, { envFile, beforeRename() { throw new Error('injected failure'); } }), /injected failure/);
+  assert.equal(await readFile(envFile, 'utf8'), original);
+});
+
+test('auth config save creates backup and atomically preserves unrelated fields', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'postman-auth-save-')); const envFile = join(root, '.env');
+  await writeFile(envFile, 'PROVIDER_PORT=8788\nUNRELATED=keep\nPOSTMAN_SESSION_COOKIE=old\n', 'utf8');
+  const result = await saveAuthConfig(valid, { envFile });
+  assert.equal(result.saved, true); assert.equal(result.restartRequired, true);
+  assert.equal(JSON.stringify(result).includes(valid.sessionCookie), false);
+  const updated = await readFile(envFile, 'utf8'); const backup = await readFile(result.backupFile, 'utf8');
+  assert.match(updated, /UNRELATED=keep/); assert.match(updated, /POSTMAN_SESSION_COOKIE=session-secret-1234/); assert.match(updated, /POSTMAN_WORKSPACE_SUBDOMAIN=team-a/);
+  assert.match(backup, /POSTMAN_SESSION_COOKIE=old/);
+});

package/test/admin.test.mjs

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import http from 'node:http';
+import { createProviderServer } from '../src/server.mjs';
+import { adminStaticAssets, isAllowedAdminHost, isLoopbackAddress } from '../src/admin.mjs';
+import { config, listen } from './helpers.mjs';
+
+const secret = 'sk-pmn-test-secret-never-static';
+
+async function withServer(fn) {
+  const server = createProviderServer({ ...config, apiKey: secret }, { fetchImpl: async () => { throw new Error('unexpected upstream'); }, logger: { error() {} } });
+  const base = await listen(server);
+  try { await fn(base, server); }
+  finally { server.close(); server.closeAllConnections?.(); await once(server, 'close'); }
+}
+
+test('admin loopback and Host validators fail closed', () => {
+  for (const value of ['127.0.0.1', '127.4.5.6', '::1', '::ffff:127.0.0.2']) assert.equal(isLoopbackAddress(value), true, value);
+  for (const value of ['10.0.0.1', '192.168.1.2', '::2', '::ffff:10.0.0.1', undefined]) assert.equal(isLoopbackAddress(value), false, String(value));
+  for (const host of ['localhost:8788', '127.0.0.1:8788', '[::1]:8788']) assert.equal(isAllowedAdminHost(host, 8788), true, host);
+  for (const host of ['attacker.test:8788', 'localhost:9999', '127.0.0.2:8788', undefined]) assert.equal(isAllowedAdminHost(host, 8788), false, String(host));
+});
+
+test('admin static assets never embed configured API key', () => {
+  for (const [name, value] of Object.entries(adminStaticAssets)) {
+    assert.equal(value.includes(secret), false, name);
+    assert.equal(value.includes('PROVIDER_API_KEY'), false, name);
+  }
+});
+
+test('admin GUI/config are localhost-only and credentials require explicit POST', async () => {
+  await withServer(async base => {
+    const gui = await fetch(`${base}/admin`);
+    assert.equal(gui.status, 200);
+    const html = await gui.text();
+    assert.match(html, /Aki Pro Max <em>Control/);
+    assert.doesNotMatch(html, /Postman2API/);
+    assert.equal(html.includes(secret), false);
+    assert.match(gui.headers.get('content-security-policy'), /default-src 'self'/);
+    assert.equal(gui.headers.get('access-control-allow-origin'), null);
+
+    const configResponse = await fetch(`${base}/admin/config`);
+    assert.equal(configResponse.status, 200);
+    assert.equal(configResponse.headers.get('cache-control'), 'no-store');
+    const metadata = await configResponse.json();
+    assert.equal(metadata.apiKey, undefined);
+    assert.deepEqual(metadata.models, config.models);
+
+    const noGetSecret = await fetch(`${base}/admin/credentials`);
+    assert.equal(noGetSecret.status, 404);
+    const credentials = await fetch(`${base}/admin/credentials`, { method: 'POST', headers: { 'content-type': 'application/json', origin: base }, body: '{}' });
+    assert.equal(credentials.status, 200);
+    assert.equal((await credentials.json()).apiKey, secret);
+    const crossOrigin = await fetch(`${base}/admin/credentials`, { method: 'POST', headers: { 'content-type': 'application/json', origin: 'http://attacker.test' }, body: '{}' });
+    assert.equal(crossOrigin.status, 403);
+
+    const target = new URL(base);
+    const rawStatus = await new Promise((resolve, reject) => {
+      const request = http.request({ hostname: target.hostname, port: target.port, path: '/admin/config', method: 'GET', headers: { Host: `attacker.test:${target.port}` } }, response => {
+        response.resume(); response.on('end', () => resolve(response.statusCode));
+      });
+      request.on('error', reject); request.end();
+    });
+    assert.equal(rawStatus, 403);
+  });
+});
+

package/test/config.test.mjs

@@ -0,0 +1,14 @@
+import test from 'node:test';import assert from 'node:assert/strict';
+import { loadConfig, authenticate, assertModel, upstreamUrl, ConcurrencyGate } from '../src/config.mjs';import { ProviderError } from '../src/errors.mjs';import { validateSchemaDefinition, validateValue } from '../src/schema.mjs';
+const env={PROVIDER_API_KEY:'a',POSTMAN_ACCESS_TOKEN:'b',POSTMAN_WORKSPACE_ID:'w',POSTMAN_ORIGIN:'https://gateway.example.test',PROVIDER_MODELS:'m1,m2'};
+test('loads exact HTTPS origin and explicit models',()=>{const c=loadConfig(env);assert.deepEqual(c.models,['m1','m2']);assert.equal(upstreamUrl(c).origin,'https://gateway.example.test');});
+test('rejects origin paths HTTP and unknown models',()=>{assert.throws(()=>loadConfig({...env,POSTMAN_ORIGIN:'http://x.test'}));assert.throws(()=>loadConfig({...env,POSTMAN_ORIGIN:'https://x.test/path'}));assert.throws(()=>assertModel('other',{models:['m']}),/Unknown/);});
+test('bearer is exact and concurrency releases',()=>{authenticate('Bearer abc','abc');assert.throws(()=>authenticate('Bearer ab','abc'),ProviderError);const g=new ConcurrencyGate(1),leave=g.enter();assert.throws(()=>g.enter(),/concurrency/);leave();assert.equal(g.active,0);});
+test('schema subset validates ordinary object tools and rejects unsupported keywords/value',()=>{const s={type:'object',properties:{q:{type:'string'},limit:{type:'integer',minimum:1,maximum:10},mode:{type:'string',enum:['fast','safe']}},required:['q'],additionalProperties:false};validateSchemaDefinition(s);validateValue({q:'x',limit:2,mode:'safe'},s);assert.throws(()=>validateValue({},s));assert.throws(()=>validateSchemaDefinition({type:'string',pattern:'x'}),/Unsupported/);});
+test('schema subset recursively validates patternProperties used by OpenClaw exec.env',()=>{const s={type:'object',patternProperties:{'^(.*)$':{type:'string'}}};validateSchemaDefinition(s);assert.throws(()=>validateSchemaDefinition({type:'object',patternProperties:[]}),/must be an object/);assert.throws(()=>validateSchemaDefinition({type:'object',patternProperties:{'.*':{type:'string',pattern:'x'}}}),/Unsupported JSON Schema keyword pattern/);});
+test('schema definitions reject malformed supported keywords instead of silently under-validating',()=>{assert.throws(()=>validateSchemaDefinition({type:'object',required:'q'}),/array of strings/);assert.throws(()=>validateSchemaDefinition({type:'object',additionalProperties:{type:'string'}}),/booleans only/);assert.throws(()=>validateSchemaDefinition({type:'string',minLength:-1}),/non-negative integer/);assert.throws(()=>validateSchemaDefinition({type:'number',minimum:'0'}),/finite number/);assert.throws(()=>validateSchemaDefinition({type:'string',enum:[]}),/non-empty array/);});
+test('const supports JSON object and array values',()=>{const objectConst={type:'object',const:{mode:'safe'}};validateSchemaDefinition(objectConst);validateValue({mode:'safe'},objectConst);assert.throws(()=>validateValue({mode:'fast'},objectConst));const arrayConst={type:'array',const:[1,2]};validateSchemaDefinition(arrayConst);validateValue([1,2],arrayConst);assert.throws(()=>validateValue([2,1],arrayConst));});
+
+test('catalog metadata defaults remain backward compatible and explicit values load',()=>{const defaults=loadConfig(env);assert.equal(defaults.platform,'OPENAI_COMPATIBLE_ADAPTER');assert.equal(defaults.nativeToolsHash,undefined);assert.deepEqual(defaults.excludedTools,[]);const configured=loadConfig({...env,POSTMAN_PLATFORM:'DESKTOP_CUSTOM',POSTMAN_NATIVE_TOOLS_HASH:'catalog-v12:opaque-123',POSTMAN_EXCLUDED_TOOLS:'readFile,webSearch'});assert.equal(configured.platform,'DESKTOP_CUSTOM');assert.equal(configured.nativeToolsHash,'catalog-v12:opaque-123');assert.deepEqual(configured.excludedTools,['readFile','webSearch']);assert.ok(Object.isFrozen(configured.excludedTools));});
+test('catalog metadata accepts exact documented bounds',()=>{const c=loadConfig({...env,POSTMAN_PLATFORM:'P'.repeat(64),POSTMAN_NATIVE_TOOLS_HASH:'H'.repeat(256),POSTMAN_EXCLUDED_TOOLS:Array.from({length:64},(_,i)=>{const prefix=`tool${i}`;return `${prefix}${'x'.repeat(128-prefix.length)}`;}).join(',')});assert.equal(c.platform.length,64);assert.equal(c.nativeToolsHash.length,256);assert.equal(c.excludedTools.length,64);assert.ok(c.excludedTools.every(value=>value.length===128));});
+test('catalog metadata rejects malformed ambiguous and unbounded config',()=>{for(const patch of [{POSTMAN_PLATFORM:'bad value'},{POSTMAN_PLATFORM:'x'.repeat(65)},{POSTMAN_NATIVE_TOOLS_HASH:'hash\nforged'},{POSTMAN_NATIVE_TOOLS_HASH:'x'.repeat(257)},{POSTMAN_EXCLUDED_TOOLS:'readFile,readFile'},{POSTMAN_EXCLUDED_TOOLS:'readFile,,webSearch'},{POSTMAN_EXCLUDED_TOOLS:'bad tool'},{POSTMAN_EXCLUDED_TOOLS:'x'.repeat(129)},{POSTMAN_EXCLUDED_TOOLS:Array.from({length:65},(_,i)=>`tool${i}`).join(',')},{POSTMAN_PLATFORM:null},{POSTMAN_PLATFORM:42},{POSTMAN_NATIVE_TOOLS_HASH:{}},{POSTMAN_NATIVE_TOOLS_HASH:[]},{POSTMAN_EXCLUDED_TOOLS:null},{POSTMAN_EXCLUDED_TOOLS:['readFile']}])assert.throws(()=>loadConfig({...env,...patch}),/POSTMAN_(?:PLATFORM|NATIVE_TOOLS_HASH|EXCLUDED_TOOLS)/);});

package/test/contract.test.mjs

@@ -0,0 +1,14 @@
+import test from 'node:test';import assert from 'node:assert/strict';import { once } from 'node:events';
+import { createProviderServer } from '../src/server.mjs';import { config,sseResponse,listen,request,json } from './helpers.mjs';
+const textEvents=[{data:{eventType:'conversation',data:{id:'conv'}}},{data:{eventType:'textChunk',data:{textContent:'hello'}}},{data:{eventType:'usage',data:{inputTokens:2,outputTokens:1}}}];
+const body={model:'fixture-model',messages:[{role:'user',content:'hi'}]};
+async function withServer(fetchImpl,fn,cfg=config){const server=createProviderServer(cfg,{fetchImpl,logger:{error(){}}});const base=await listen(server);try{await fn(base,server);}finally{server.close();server.closeAllConnections?.();await once(server,'close');}}
+test('health public models authenticated and chat JSON works',async()=>{let captured;await withServer(async(url,init)=>{captured={url:String(url),init};return sseResponse(textEvents);},async base=>{assert.equal((await json(await fetch(base+'/health'))).upstream_verified,false);assert.equal((await request(base,'/v1/models',{token:'bad'})).status,401);const models=await json(await request(base,'/v1/models'));assert.equal(models.data[0].id,'fixture-model');const result=await json(await request(base,'/v1/chat/completions',{method:'POST',body}));assert.equal(result.choices[0].message.content,'hello');assert.equal(captured.init.headers['x-access-token'],'upstream-secret');assert.equal(JSON.parse(captured.init.body).mandatoryContext.workspaceId,'ws_fixture');});});
+test('stream emits chunks finish usage and DONE',async()=>{await withServer(async()=>sseResponse(textEvents),async base=>{const res=await request(base,'/v1/chat/completions',{method:'POST',body:{...body,stream:true}});assert.match(res.headers.get('content-type'),/text\/event-stream/);const value=await res.text();assert.match(value,/chat\.completion\.chunk/);assert.match(value,/"content":"hello"/);assert.match(value,/\[DONE\]/);});});
+test('auth model invalid JSON and body limit errors',async()=>{await withServer(async()=>sseResponse(textEvents),async base=>{assert.equal((await request(base,'/v1/chat/completions',{method:'POST',token:'bad',body})).status,401);assert.equal((await request(base,'/v1/chat/completions',{method:'POST',body:{...body,model:'nope'}})).status,400);const bad=await fetch(base+'/v1/chat/completions',{method:'POST',headers:{authorization:'Bearer ingress-secret','content-type':'application/json'},body:'{'});assert.equal(bad.status,400);const large=await request(base,'/v1/chat/completions',{method:'POST',body:{...body,messages:[{role:'user',content:'x'.repeat(5000)}]}});assert.equal(large.status,413);});});
+test('upstream HTTP statuses non-SSE malformed and incomplete map cleanly',async()=>{for(const [factory,status,code] of [[()=>new Response('x',{status:401}),401,'upstream_http_error'],[()=>new Response('x',{status:403}),403,'upstream_http_error'],[()=>new Response('x',{status:429,headers:{'retry-after':'2'}}),429,'upstream_http_error'],[()=>new Response('x',{status:500}),500,'upstream_http_error'],[()=>new Response('<html>',{status:200,headers:{'content-type':'text/html'}}),502,'upstream_content_type_error'],[()=>new Response(new ReadableStream({start(c){c.enqueue(new TextEncoder().encode('data: not-json\\n\\ndata: [DONE]\\n\\n'));c.close();}}),{status:200,headers:{'content-type':'text/event-stream'}}),502,'upstream_invalid_json'],[()=>sseResponse(textEvents,{done:false}),502,'upstream_incomplete_stream']])await withServer(async()=>factory(),async base=>{const res=await request(base,'/v1/chat/completions',{method:'POST',body});assert.equal(res.status,status);const value=await res.json();assert.equal(value.error.code,code);});});
+test('concurrent requests remain isolated and enforce bound',async()=>{let releases=[];const slow=async(_u,init)=>new Promise((resolve,reject)=>{const abort=()=>reject(init.signal.reason);init.signal.addEventListener('abort',abort,{once:true});releases.push(()=>{init.signal.removeEventListener('abort',abort);resolve(sseResponse(textEvents));});});await withServer(slow,async base=>{const p1=request(base,'/v1/chat/completions',{method:'POST',body});while(!releases.length)await new Promise(r=>setTimeout(r,1));const p2=request(base,'/v1/chat/completions',{method:'POST',body});while(releases.length<2)await new Promise(r=>setTimeout(r,1));const p3=await request(base,'/v1/chat/completions',{method:'POST',body});assert.equal(p3.status,429);releases.splice(0).forEach(f=>f());const [a,b]=await Promise.all([p1,p2]);assert.equal((await a.json()).choices[0].message.content,'hello');assert.equal((await b.json()).choices[0].message.content,'hello');});});
+test('client abort propagates to injected fetch',async()=>{let aborted=false;await withServer(async(_u,init)=>new Promise((resolve,reject)=>init.signal.addEventListener('abort',()=>{aborted=true;reject(init.signal.reason);},{once:true})),async base=>{const c=new AbortController();const p=request(base,'/v1/chat/completions',{method:'POST',body,signal:c.signal}).catch(()=>null);setTimeout(()=>c.abort(),20);await p;await new Promise(r=>setTimeout(r,30));assert.equal(aborted,true);});});
+test('pre-header source-backed failures return sanitized JSON and no success body',async()=>{for(const [failure,status,code] of [[{data:{result:'failure',message:'Bearer top-secret raw body'}},502,'upstream_gateway_failure'],[{data:{eventType:'error',errorType:'TOOL_VALIDATION_ERROR',message:'top-secret'}},400,'upstream_tool_validation_error'],[{data:{eventType:'usage',data:{usageState:'BLOCKED',blockedUntil:'2026-09-06T19:17:37.905Z'}}},400,'upstream_credit_blocked']])await withServer(async()=>sseResponse([failure]),async base=>{const res=await request(base,'/v1/chat/completions',{method:'POST',body});assert.equal(res.status,status);const wire=await res.text();const value=JSON.parse(wire);assert.equal(value.error.code,code);assert.equal(wire.includes('top-secret'),false);assert.equal(wire.includes('blockedUntil'),false);assert.equal(wire.includes('chat.completion'),false);});});
+test('post-header stream failure emits error frame then closes without finish or DONE',async()=>{await withServer(async()=>sseResponse([{data:{eventType:'conversation',data:{id:'conv'}}},{data:{eventType:'textChunk',data:{textContent:'partial'}}},{data:{eventType:'error',data:{errorType:'LLM_STREAM_ERROR',message:'Bearer top-secret'}}}]),async base=>{const res=await request(base,'/v1/chat/completions',{method:'POST',body:{...body,stream:true}});assert.equal(res.status,200);const wire=await res.text();assert.match(wire,/"content":"partial"/);assert.match(wire,/"code":"upstream_stream_error"/);assert.equal(wire.includes('top-secret'),false);assert.equal(wire.includes('finish_reason":"stop"'),false);assert.equal(wire.includes('[DONE]'),false);});});
+

package/test/correlation-store.test.mjs

@@ -0,0 +1,19 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { CorrelationStore } from '../src/correlation-store.mjs';
+
+const binding={tools:[{type:'function',function:{name:'lookup',description:'lookup',parameters:{type:'object'}}}],toolChoice:'auto'};
+const transcript=[{role:'user',content:'hi'},{role:'assistant',content:null,tool_calls:[]}];
+const calls=(n=2)=>Array.from({length:n},(_,i)=>({upstreamToolCallId:`up-${i}`,upstreamGroupId:n>1?'grp':null,originalName:'lookup',argumentsJson:'{}',schemaHash:'schema'}));
+function admit(store,overrides={}){return store.admit({principalId:'P-A',workspaceId:'ws-A',model:'fixture-model',conversationId:'conv',upstreamGroupId:'grp',transcript,toolsBinding:binding,catalogMetadata:{platform:'OPENAI_COMPATIBLE_ADAPTER',excludedTools:[]},calls:calls(),...overrides});}
+const results=g=>g.calls.map((c,i)=>({toolCallId:c.publicToolCallId,content:`R${i}`}));
+const claim=(store,g,overrides={})=>store.claim({principalId:'P-A',results:results(g),workspaceId:'ws-A',model:'fixture-model',transcript,toolsBinding:binding,catalogMetadata:{platform:'OPENAI_COMPATIBLE_ADAPTER',excludedTools:[]},...overrides});
+
+test('opaque IDs are random-sized and hide upstream identifiers',()=>{const store=new CorrelationStore();const group=admit(store);for(const call of group.calls){assert.match(call.publicToolCallId,/^call_pmn_[A-Za-z0-9_-]{32}$/);assert.equal(call.publicToolCallId.includes(call.upstreamToolCallId),false);}assert.notEqual(group.calls[0].publicToolCallId,group.calls[1].publicToolCallId);});
+test('complete set claims once; partial duplicate mixed and cross-principal do not mutate',()=>{const store=new CorrelationStore();const a=admit(store),b=admit(store,{conversationId:'conv2',upstreamGroupId:'grp2'});assert.throws(()=>claim(store,a,{results:results(a).slice(0,1)}),e=>e.code==='tool_result_incomplete');assert.throws(()=>claim(store,a,{results:[results(a)[0],results(a)[0],results(a)[1]]}),e=>e.code==='tool_result_group_mismatch');assert.throws(()=>claim(store,a,{results:[results(a)[0],results(b)[1]]}),e=>e.code==='tool_result_group_mismatch');assert.throws(()=>store.claim({principalId:'P-B',results:results(a),workspaceId:'ws-A',model:'fixture-model',transcript,toolsBinding:binding}),e=>e.code==='unknown_tool_call');assert.equal(a.state,'PENDING');claim(store,a);assert.equal(a.state,'INFLIGHT');assert.throws(()=>claim(store,a),e=>e.code==='continuation_inflight');});
+test('model workspace tools history and conflicting replay are bound',()=>{for(const [field,value,code] of [['model','other','continuation_model_mismatch'],['workspaceId','ws-B','continuation_workspace_mismatch'],['transcript',[{role:'user',content:'bye'}],'continuation_history_mismatch'],['toolsBinding',{...binding,toolChoice:'none'},'continuation_tools_mismatch']]){const store=new CorrelationStore();const group=admit(store);assert.throws(()=>claim(store,group,{[field]:value}),e=>e.code===code);assert.equal(group.state,'PENDING');}const store=new CorrelationStore();const group=admit(store);claim(store,group);store.complete(group);assert.throws(()=>claim(store,group),e=>e.code==='tool_call_already_consumed');const changed=results(group);changed[0]={...changed[0],content:'different'};assert.throws(()=>claim(store,group,{results:changed}),e=>e.code==='continuation_conflict');});
+test('expiry tombstones, inflight uncertainty, terminal cleanup and no active eviction',()=>{let now=0;const store=new CorrelationStore({pendingTtlMs:10,inflightTtlMs:10,terminalTtlMs:10,maxGroups:1,now:()=>now});const first=admit(store);assert.throws(()=>admit(store,{conversationId:'other'}),e=>e.code==='correlation_capacity_exceeded');assert.ok(store.inspect('P-A',first.calls[0].publicToolCallId));now=11;store.sweep();assert.equal(first.state,'EXPIRED');assert.throws(()=>claim(store,first),e=>e.code==='tool_call_expired');now=22;store.sweep();assert.equal(store.inspect('P-A',first.calls[0].publicToolCallId),null);const second=admit(store);claim(store,second);now=33;store.sweep();assert.equal(second.state,'UNCERTAIN');assert.throws(()=>claim(store,second),e=>e.code==='continuation_outcome_uncertain');});
+test('singular ungrouped groups are admitted; multiple ungrouped calls reject',()=>{const store=new CorrelationStore();const one=admit(store,{upstreamGroupId:null,calls:calls(1)});assert.equal(one.calls.length,1);assert.throws(()=>admit(store,{upstreamGroupId:null,calls:calls(2).map(c=>({...c,upstreamGroupId:null}))}),e=>e.code==='upstream_ungrouped_tool_batch');});
+test('50 concurrent claims produce exactly one winner under single-process CAS',async()=>{const store=new CorrelationStore();const group=admit(store);const attempts=await Promise.all(Array.from({length:50},async()=>{try{return claim(store,group).dispatchAttemptId;}catch(e){return e.code;}}));assert.equal(attempts.filter(v=>typeof v==='string'&&!v.startsWith('continuation_')).length,1);assert.equal(attempts.filter(v=>v==='continuation_inflight').length,49);});
+
+test('catalog metadata is bound across continuation and mismatch does not mutate',()=>{const store=new CorrelationStore();const metadata={platform:'CUSTOM',nativeToolsHash:'catalog:1',excludedTools:['readFile']};const group=admit(store,{catalogMetadata:metadata});metadata.excludedTools.push('mutated-after-admit');assert.deepEqual(group.catalogMetadata.excludedTools,['readFile']);assert.throws(()=>claim(store,group,{catalogMetadata:{platform:'CUSTOM',nativeToolsHash:'catalog:2',excludedTools:['readFile']}}),error=>error.code==='continuation_catalog_mismatch');assert.equal(group.state,'PENDING');const accepted=claim(store,group,{catalogMetadata:{platform:'CUSTOM',nativeToolsHash:'catalog:1',excludedTools:['readFile']}});assert.equal(accepted.group.state,'INFLIGHT');});

package/test/correlation.integration.test.mjs

@@ -0,0 +1,48 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createProviderServer } from '../src/server.mjs';
+import { config as baseConfig, listen, request, sseResponse } from './helpers.mjs';
+
+const tool={type:'function',function:{name:'lookup',description:'lookup',parameters:{type:'object',properties:{q:{type:'string'}},required:['q'],additionalProperties:false}}};
+const config={...baseConfig,correlationEnabled:true,principalKey:'test-principal-key',credentialSlotId:'client-a',maxToolResultBytes:1024,correlationPendingTtlMs:1000,correlationTerminalTtlMs:1000,correlationInflightTtlMs:1000,correlationMaxGroups:10,correlationMaxCalls:20,correlationMaxBytes:1024*1024};
+const frames=(conv='conv-1',group='grp-1')=>[
+ {event:'message',data:{eventType:'conversation',data:{id:conv}}},
+ {event:'message',data:{eventType:'toolCallChunk',data:{id:`${conv}-up-a`,index:0,name:'openai__lookup',toolCallGroupId:group}}},
+ {event:'message',data:{eventType:'toolCallChunk',data:{id:`${conv}-up-a`,index:0,arguments:'{"q":"x"}'}}},
+ {event:'message',data:{eventType:'toolCallChunk',data:{id:`${conv}-up-b`,index:1,name:'openai__lookup',toolCallGroupId:group}}},
+ {event:'message',data:{eventType:'toolCallChunk',data:{id:`${conv}-up-b`,index:1,arguments:'{"q":"y"}'}}},
+];
+async function withServer(fetchImpl,fn,overrides={}){const server=createProviderServer({...config,...overrides},{fetchImpl,logger:{error(){}}});const base=await listen(server);try{await fn(base);}finally{await new Promise(r=>server.close(r));}}
+const initial={model:'fixture-model',messages:[{role:'user',content:'hi'}],tools:[tool],stream:false};
+const continuation=(message,contents=['X','Y'],extra={})=>({model:'fixture-model',messages:[{role:'user',content:'hi'},message,...message.tool_calls.map((call,i)=>({role:'tool',tool_call_id:call.id,content:contents[i]}))],tools:[tool],stream:false,...extra});
+
+test('grouped native continuation remaps IDs and sends exact source-backed TOOL_RESPONSE',async()=>{const captures=[];let n=0;await withServer(async(_url,init)=>{captures.push(JSON.parse(init.body));if(n++===0)return sseResponse(frames());return sseResponse([{data:{eventType:'conversation',data:{id:'conv-1'}}},{data:{eventType:'textChunk',data:{textContent:'final'}}}]);},async base=>{const first=await request(base,'/v1/chat/completions',{method:'POST',body:initial});const one=await first.json();const message=one.choices[0].message;assert.equal(message.tool_calls.length,2);assert.match(message.tool_calls[0].id,/^call_pmn_/);assert.equal(JSON.stringify(message).includes('conv-1-up'),false);const second=await request(base,'/v1/chat/completions',{method:'POST',body:continuation(message)});assert.equal(second.status,200);assert.equal((await second.json()).choices[0].message.content,'final');const input=captures[1].input;assert.equal(input.chatType,'TOOL_RESPONSE');assert.equal(input.query,'');assert.equal(input.conversationId,'conv-1');assert.equal(input.toolCallGroupId,'grp-1');assert.deepEqual(input.toolResponses.map(x=>[x.toolCallId,x.content,x.toolResponseStatus]),[['conv-1-up-a','X','SUCCESS'],['conv-1-up-b','Y','SUCCESS']]);});});
+test('partial duplicate history model tools and consumed replay never redispatch',async()=>{let calls=0;await withServer(async()=>{calls++;return calls===1?sseResponse(frames()):sseResponse([{data:{eventType:'conversation',data:{id:'conv-1'}}},{data:{eventType:'textChunk',data:{textContent:'done'}}}]);},async base=>{const message=(await (await request(base,'/v1/chat/completions',{method:'POST',body:initial})).json()).choices[0].message;const partial={...continuation(message),messages:[{role:'user',content:'hi'},message,{role:'tool',tool_call_id:message.tool_calls[0].id,content:'X'}]};assert.equal((await request(base,'/v1/chat/completions',{method:'POST',body:partial})).status,400);assert.equal((await request(base,'/v1/chat/completions',{method:'POST',body:continuation(message,['X','Y'],{model:'other-model'})})).status,400);const history=continuation(message);history.messages[0]={role:'user',content:'changed'};assert.equal((await request(base,'/v1/chat/completions',{method:'POST',body:history})).status,409);const ok=await request(base,'/v1/chat/completions',{method:'POST',body:continuation(message)});assert.equal(ok.status,200);const replay=await request(base,'/v1/chat/completions',{method:'POST',body:continuation(message)});assert.equal(replay.status,409);assert.equal((await replay.json()).error.code,'tool_call_already_consumed');assert.equal(calls,2);});});
+test('streaming tool calls are buffered until admission and expose only opaque IDs',async()=>{await withServer(async()=>sseResponse(frames()),async base=>{const response=await request(base,'/v1/chat/completions',{method:'POST',body:{...initial,stream:true}});assert.equal(response.status,200);const wire=await response.text();assert.match(wire,/call_pmn_/);assert.equal(wire.includes('conv-1-up-a'),false);assert.match(wire,/finish_reason":"tool_calls/);});});
+test('sequential rounds preserve resolved transcript and create a fresh group',async()=>{const captures=[];let n=0;await withServer(async(_url,init)=>{captures.push(JSON.parse(init.body));n++;if(n===1)return sseResponse(frames('conv-1','grp-1'));if(n===2)return sseResponse(frames('conv-2','grp-2'));return sseResponse([{data:{eventType:'conversation',data:{id:'conv-2'}}},{data:{eventType:'textChunk',data:{textContent:'complete'}}}]);},async base=>{const m1=(await (await request(base,'/v1/chat/completions',{method:'POST',body:initial})).json()).choices[0].message;const c1=continuation(m1);const m2=(await (await request(base,'/v1/chat/completions',{method:'POST',body:c1})).json()).choices[0].message;const c2={model:'fixture-model',tools:[tool],messages:[...c1.messages,m2,...m2.tool_calls.map((call,i)=>({role:'tool',tool_call_id:call.id,content:`Z${i}`}))]};const final=await request(base,'/v1/chat/completions',{method:'POST',body:c2});assert.equal(final.status,200);assert.equal((await final.json()).choices[0].message.content,'complete');assert.equal(captures[1].input.chatType,'TOOL_RESPONSE');assert.equal(captures[2].input.chatType,'TOOL_RESPONSE');});});
+test('failed tool stream emits no actionable IDs and admits no correlation record',async()=>{let calls=0;await withServer(async()=>{calls++;return sseResponse([...frames().slice(0,2),{data:{eventType:'error',data:{errorType:'LLM_STREAM_ERROR',message:'call_pmn_fake secret'}}}],{done:false});},async base=>{const res=await request(base,'/v1/chat/completions',{method:'POST',body:{...initial,stream:true}});assert.equal(res.status,200);const wire=await res.text();assert.match(wire,/"code":"upstream_stream_error"/);assert.equal(wire.includes('call_pmn_'),false);assert.equal(wire.includes('[DONE]'),false);assert.equal(calls,1);});});
+test('structured continuation failure after dispatch becomes UNCERTAIN and never redispatches',async()=>{let calls=0;await withServer(async()=>{calls++;if(calls===1)return sseResponse(frames());return sseResponse([{data:{eventType:'error',data:{errorType:'LLM_STREAM_ERROR'}}}]);},async base=>{const message=(await (await request(base,'/v1/chat/completions',{method:'POST',body:initial})).json()).choices[0].message;const first=await request(base,'/v1/chat/completions',{method:'POST',body:continuation(message)});assert.equal(first.status,502);assert.equal((await first.json()).error.code,'upstream_stream_error');const retry=await request(base,'/v1/chat/completions',{method:'POST',body:continuation(message)});assert.equal(retry.status,502);assert.equal((await retry.json()).error.code,'continuation_outcome_uncertain');assert.equal(calls,2);});});
+
+test('configured catalog metadata is stable through initial and continuation dispatch',async()=>{const captures=[];let n=0;await withServer(async(_url,init)=>{captures.push(JSON.parse(init.body));return n++===0?sseResponse(frames()):sseResponse([{data:{eventType:'conversation',data:{id:'conv-1'}}},{data:{eventType:'textChunk',data:{textContent:'done'}}}]);},async base=>{const message=(await (await request(base,'/v1/chat/completions',{method:'POST',body:{...initial,platform:'caller-value',nativeToolsHash:'caller-value',excludedTools:['caller-value']}})).json()).choices[0].message;const result=await request(base,'/v1/chat/completions',{method:'POST',body:continuation(message)});assert.equal(result.status,200);assert.equal(captures[0].platform,'CUSTOM_PLATFORM');assert.equal(captures[1].platform,'CUSTOM_PLATFORM');assert.deepEqual(captures[0].clientTools,captures[1].clientTools);assert.equal(captures[0].clientTools.nativeToolsHash,'catalog:authoritative-1');assert.deepEqual(captures[0].clientTools.excludedTools,['readFile']);},{platform:'CUSTOM_PLATFORM',nativeToolsHash:'catalog:authoritative-1',excludedTools:['readFile']});});
+
+test('tool_choice required to auto continuation succeeds and changed tool definition still rejects', async () => {
+  let calls = 0;
+  await withServer(async () => {
+    calls++;
+    return calls === 1 ? sseResponse(frames()) : sseResponse([{ data: { eventType: 'conversation', data: { id: 'conv-1' } } }, { data: { eventType: 'textChunk', data: { textContent: 'done' } } }]);
+  }, async base => {
+    const forcedInitial = { ...initial, tool_choice: 'required' };
+    const initialRes = await request(base, '/v1/chat/completions', { method: 'POST', body: forcedInitial });
+    assert.equal(initialRes.status, 200);
+    const message = (await initialRes.json()).choices[0].message;
+    const mutatedTool = { type: 'function', function: { name: 'lookup', description: 'lookup', parameters: { type: 'object', properties: { other: { type: 'string' } } } } };
+    const badContinuation = { ...continuation(message), tools: [mutatedTool], tool_choice: 'auto' };
+    const badRes = await request(base, '/v1/chat/completions', { method: 'POST', body: badContinuation });
+    assert.equal(badRes.status, 409);
+    assert.equal((await badRes.json()).error.code, 'continuation_tools_mismatch');
+    const relaxedContinuation = { ...continuation(message), tool_choice: 'auto' };
+    const okRes = await request(base, '/v1/chat/completions', { method: 'POST', body: relaxedContinuation });
+    assert.equal(okRes.status, 200);
+    assert.equal((await okRes.json()).choices[0].message.content, 'done');
+  });
+});

package/test/eventual-tool-loop.test.mjs

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runEventualToolLoop } from '../scripts/eventual-tool-loop.mjs';
+
+const call=(id,name,args)=>({id,type:'function',function:{name,arguments:JSON.stringify(args)}});
+const turn=(toolCalls,content=null)=>({status:200,data:{choices:[{finish_reason:toolCalls.length?'tool_calls':'stop',message:{role:'assistant',content, ...(toolCalls.length?{tool_calls:toolCalls}:{})}}]}});
+const base={model:'m',messages:[{role:'user',content:'use both'}],tools:[],tool_choice:'required'};
+const execute=async(name,args)=>`${name.toUpperCase()}_${args.slot}`;
+const validate=(content,executed)=>[...executed.values()].every(item=>content.includes(item.content));
+
+async function scripted(responses, options={}) {
+ let index=0; const requests=[];
+ const result=await runEventualToolLoop({initialBody:base,requiredTools:['alpha','beta'],executeTool:execute,validateFinal:validate,maxTurns:3,maxDispatches:4,request:async body=>{requests.push(structuredClone(body));return responses[index++]},...options});
+ return {result,requests};
+}
+
+test('eventual loop accepts two parallel calls and one final turn',async()=>{
+ const {result,requests}=await scripted([turn([call('a','alpha',{slot:'a'}),call('b','beta',{slot:'b'})]),turn([], 'ALPHA_a BETA_b')]);
+ assert.equal(result.turns,2);assert.equal(result.dispatches,2);assert.deepEqual(result.executed.map(x=>x.name),['alpha','beta']);assert.equal(requests[1].messages.filter(x=>x.role==='tool').length,2);
+});
+
+test('eventual loop accepts sequential calls across bounded turns',async()=>{
+ const {result,requests}=await scripted([turn([call('a','alpha',{slot:'a'})]),turn([call('b','beta',{slot:'b'})]),turn([], 'ALPHA_a BETA_b')]);
+ assert.equal(result.turns,3);assert.equal(result.dispatches,3);assert.deepEqual(result.executed.map(x=>x.name),['alpha','beta']);assert.equal(requests[1].messages.at(-1).role,'tool');assert.equal(requests[2].messages.filter(x=>x.role==='tool').length,2);
+});
+
+test('eventual loop rejects replayed signature and duplicate tool name',async()=>{
+ await assert.rejects(()=>scripted([turn([call('a','alpha',{slot:'a'})]),turn([call('a2','alpha',{slot:'a'})])]),error=>error.code==='tool_call_replay');
+ await assert.rejects(()=>scripted([turn([call('a','alpha',{slot:'a'})]),turn([call('a2','alpha',{slot:'other'})])]),error=>error.code==='tool_called_more_than_once');
+});
+
+test('eventual loop rejects stop-before-completion, invalid args, unexpected tool and false final',async()=>{
+ await assert.rejects(()=>scripted([turn([call('a','alpha',{slot:'a'})]),turn([], 'early')]),error=>error.code==='assistant_stopped_before_required_tools');
+ await assert.rejects(()=>scripted([turn([{id:'a',type:'function',function:{name:'alpha',arguments:'{'}}])]),error=>error.code==='invalid_tool_arguments');
+ await assert.rejects(()=>scripted([turn([call('x','gamma',{slot:'x'})])]),error=>error.code==='unexpected_tool_call');
+ await assert.rejects(()=>scripted([turn([call('a','alpha',{slot:'a'}),call('b','beta',{slot:'b'})]),turn([], 'wrong')]),error=>error.code==='final_validation_failed');
+});
+
+test('eventual loop enforces dispatch and turn budgets',async()=>{
+ await assert.rejects(()=>runEventualToolLoop({initialBody:base,requiredTools:['alpha','beta'],executeTool:execute,request:async()=>turn([call('a','alpha',{slot:'a'})]),maxTurns:3,maxDispatches:1}),error=>error.code==='dispatch_budget_exhausted');
+ await assert.rejects(()=>runEventualToolLoop({initialBody:base,requiredTools:['alpha','beta'],executeTool:execute,request:async({messages})=>messages.some(x=>x.role==='tool')?turn([call('b','beta',{slot:'b'})]):turn([call('a','alpha',{slot:'a'})]),validateFinal:validate,maxTurns:2,maxDispatches:4}),error=>error.code==='turn_budget_exhausted');
+});

package/test/fixtures/text.json

@@ -0,0 +1,8 @@
+{
+  "fixture_status": "source-derived-not-live-captured",
+  "frames": [
+    {"event":"message","data":{"eventType":"conversation","data":{"id":"conv_fixture"}}},
+    {"event":"message","data":{"eventType":"textChunk","data":{"textContent":"hello"}}},
+    {"event":"message","data":{"eventType":"usage","data":{"inputTokens":3,"outputTokens":1}}}
+  ]
+}

package/test/fixtures/tool.json

@@ -0,0 +1,7 @@
+{
+  "fixture_status": "source-derived-not-live-captured",
+  "frames": [
+    {"event":"message","data":{"eventType":"toolCallChunk","data":{"id":"call_fixture","index":0,"name":"openai__lookup","arguments":"{\"q\":"}}},
+    {"event":"message","data":{"eventType":"toolCallChunk","data":{"id":"call_fixture","index":0,"arguments":"\"x\"}"}}}
+  ]
+}

package/test/fixtures/web-session-observed-done.json

@@ -0,0 +1,12 @@
+{
+  "provenance": "source-derived synthetic fixture informed by sanitized OWNER-SESSION-TEXT-PROBE metadata; not retained raw captured SSE",
+  "routeEvidence": "one owner session returned HTTP 200 text/event-stream, seven textChunk events, exact PROXY_OBSERVATION_OK, explicit DONE, clean EOF, and observed model label gpt-5.6-sol",
+  "events": [
+    { "eventType": "conversation", "data": { "id": "conversation_fixture" } },
+    { "eventType": "planningChunk", "data": {} },
+    { "eventType": "textChunk", "data": { "textContent": "PROXY_", "metadata": { "model": "gpt-5.6-sol" } } },
+    { "eventType": "textChunk", "data": { "textContent": "OBSERVATION_" } },
+    { "eventType": "textChunk", "data": { "textContent": "OK" } }
+  ],
+  "done": true
+}

package/test/fixtures/web-session-tool-fragments.json

@@ -0,0 +1,14 @@
+{
+  "provenance": "offline source-derived fixture; synthetic identifiers/content; not captured from a live account",
+  "events": [
+    { "eventType": "conversation", "data": { "id": "conv_source_fixture" } },
+    { "eventType": "toolCallChunk", "data": { "toolCalls": [
+      { "index": 0, "id": "up_call_a", "toolCallGroupId": "up_group_1", "function": { "name": "openai__lookup", "arguments": "{\"q\":" } },
+      { "index": 1, "id": "up_call_b", "toolCallGroupId": "up_group_1", "function": { "name": "openai__count", "arguments": "{\"n\":" } }
+    ] } },
+    { "eventType": "toolCallChunk", "data": { "toolCalls": [
+      { "index": 0, "id": "up_call_a", "toolCallGroupId": "up_group_1", "function": { "name": "openai__lookup", "arguments": "\"x\"}" } },
+      { "index": 1, "id": "up_call_b", "toolCallGroupId": "up_group_1", "function": { "name": "openai__count", "arguments": "2}" } }
+    ] } }
+  ]
+}

package/test/full-ingress/alias-loader.mjs

@@ -0,0 +1,22 @@
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const root = process.env.NINEROUTER_ROOT;
+if (!root) throw new Error('NINEROUTER_ROOT is required');
+
+function candidate(specifier) {
+  if (specifier.startsWith('@/')) return path.join(root, 'src', specifier.slice(2));
+  if (specifier === 'open-sse') return path.join(root, 'open-sse', 'index.js');
+  if (specifier.startsWith('open-sse/')) return path.join(root, specifier);
+  return null;
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  const mapped = candidate(specifier);
+  if (!mapped) return nextResolve(specifier, context);
+  for (const file of [mapped, `${mapped}.js`, path.join(mapped, 'index.js')]) {
+    if (fs.existsSync(file) && fs.statSync(file).isFile()) return { url: pathToFileURL(file).href, shortCircuit: true };
+  }
+  throw new Error(`Cannot resolve isolated 9router alias: ${specifier}`);
+}