ag-ai 0.1.0

package/runtime/tests/protocol.test.mjs

@@ -0,0 +1,156 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+/* eslint-disable import/extensions -- Native Node ESM requires file extensions. */
+
+import {
+  GenerationProtocolError,
+  normalizeGenerationRequest,
+  normalizeModelCatalog,
+  toRunnerInput,
+} from '../protocol.mjs';
+
+const models = [
+  {
+    id: 'gpt-5.6-sol',
+    isDefault: true,
+    inputModalities: ['text', 'image'],
+    supportedReasoningEfforts: [{ reasoningEffort: 'low' }, { reasoningEffort: 'high' }],
+    defaultReasoningEffort: 'low',
+  },
+  {
+    id: 'gpt-5.6-luna',
+    inputModalities: ['text', 'image'],
+    supportedReasoningEfforts: [{ reasoningEffort: 'medium' }],
+    defaultReasoningEffort: 'medium',
+  },
+  {
+    id: 'gpt-5.5',
+    imageGeneration: true,
+    inputModalities: ['text', 'image'],
+    supportedReasoningEfforts: [{ reasoningEffort: 'high' }],
+    defaultReasoningEffort: 'high',
+  },
+  {
+    id: 'gpt-5.3-ag-ai-spark',
+    inputModalities: ['text'],
+    supportedReasoningEfforts: [{ reasoningEffort: 'low' }],
+    defaultReasoningEffort: 'low',
+  },
+];
+
+const request = (overrides = {}) => ({
+  version: 1,
+  input: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }],
+  output: ['text'],
+  ...overrides,
+});
+
+test('normalizes the actual model catalog without inventing availability', () => {
+  const catalog = normalizeModelCatalog(models);
+  assert.deepEqual(
+    catalog.map(({ id }) => id),
+    models.map(({ id }) => id),
+  );
+  assert.deepEqual(catalog[0].outputModalities, ['text']);
+  assert.deepEqual(catalog[1].outputModalities, ['text']);
+  assert.deepEqual(catalog[2].outputModalities, ['text', 'image']);
+  assert.deepEqual(catalog[3].outputModalities, ['text']);
+  assert.throws(
+    () => normalizeGenerationRequest(request({ model: 'missing-model' }), models),
+    (error) => {
+      assert(error instanceof GenerationProtocolError);
+      assert.equal(error.status, 422);
+      return true;
+    },
+  );
+});
+
+test('selects preferences from available models and keeps explicit model exact', () => {
+  assert.equal(
+    normalizeGenerationRequest(request({ prefer: 'fast' }), models).model,
+    'gpt-5.6-luna',
+  );
+  assert.equal(
+    normalizeGenerationRequest(request({ prefer: 'quality' }), models).model,
+    'gpt-5.6-sol',
+  );
+  const selected = normalizeGenerationRequest(
+    request({ model: 'gpt-5.6-luna', reasoningEffort: 'medium' }),
+    models,
+  );
+  assert.equal(selected.model, 'gpt-5.6-luna');
+  assert.equal(selected.reasoningEffort, 'medium');
+});
+
+test('rejects unsupported provider options and modalities explicitly', () => {
+  for (const value of [
+    request({ maxOutputTokens: 100 }),
+    request({ webSearch: true }),
+    request({
+      input: [{ role: 'user', content: [{ type: 'audio', mimeType: 'audio/wav', data: 'AAAA' }] }],
+    }),
+    request({ output: ['file'] }),
+  ]) {
+    assert.throws(
+      () => normalizeGenerationRequest(value, models),
+      (error) => {
+        assert(error instanceof GenerationProtocolError);
+        assert.equal(error.status, 422);
+        return true;
+      },
+    );
+  }
+
+  assert.throws(
+    () => normalizeGenerationRequest(request({ model: 'gpt-5.6-sol', output: ['image'] }), models),
+    (error) => {
+      assert(error instanceof GenerationProtocolError);
+      assert.equal(error.status, 422);
+      return true;
+    },
+  );
+
+  assert.deepEqual(
+    normalizeGenerationRequest(
+      request({ model: 'gpt-5.5', reasoningEffort: 'high', output: ['text', 'image'] }),
+      models,
+    ).output,
+    ['text', 'image'],
+  );
+});
+
+test('runner conversion keeps the generic media shape until executor translation', () => {
+  const normalized = normalizeGenerationRequest(
+    request({
+      model: 'gpt-5.5',
+      reasoningEffort: 'high',
+      input: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'describe this' },
+            { type: 'image', mimeType: 'image/png', data: 'iVBORw0KGgo=' },
+          ],
+        },
+      ],
+      output: ['text', 'image'],
+    }),
+    models,
+  );
+  const runnerInput = toRunnerInput(normalized, 'run-1', models);
+  assert.equal(runnerInput.messages[0].content[0].type, 'text');
+  assert.equal(runnerInput.messages[0].content[1].type, 'image');
+  assert.equal(runnerInput.messages[0].content[1].mimeType, 'image/png');
+  assert.equal(runnerInput.messages[0].content[1].data, 'iVBORw0KGgo=');
+});
+
+test('requires canonical request fields and rejects unknown fields', () => {
+  assert.throws(
+    () => normalizeGenerationRequest({ version: 1, output: ['text'] }, models),
+    GenerationProtocolError,
+  );
+  assert.throws(
+    () => normalizeGenerationRequest(request({ legacyText: 'x' }), models),
+    GenerationProtocolError,
+  );
+});

package/runtime/tests/server.test.mjs

@@ -0,0 +1,231 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+/* eslint-disable import/extensions -- Native Node ESM requires file extensions. */
+
+import { idempotencyDigest, requestDigest } from '../protocol.mjs';
+import {
+  GenerationServer,
+  createLocalRunner,
+  isAllowedPeer,
+  normalizeBindHost,
+} from '../server.mjs';
+import { GenerationStore } from '../store.mjs';
+
+const baseModels = [
+  {
+    id: 'gpt-5.6-sol',
+    model: 'gpt-5.6-sol',
+    isDefault: true,
+    inputModalities: ['text', 'image'],
+    supportedReasoningEfforts: [{ reasoningEffort: 'low' }, { reasoningEffort: 'high' }],
+    defaultReasoningEffort: 'low',
+  },
+  {
+    id: 'gpt-5.6-luna',
+    model: 'gpt-5.6-luna',
+    inputModalities: ['text', 'image'],
+    supportedReasoningEfforts: [{ reasoningEffort: 'medium' }],
+    defaultReasoningEffort: 'medium',
+  },
+];
+
+const request = {
+  version: 1,
+  input: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }],
+  output: ['text'],
+  prefer: 'quality',
+};
+
+const getFreePort = async () => {
+  const socket = createServer();
+  await new Promise((resolve) => socket.listen(0, '127.0.0.1', resolve));
+  const port = socket.address().port;
+  await new Promise((resolve) => socket.close(resolve));
+  return port;
+};
+
+const setup = async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ag-ai-generation-server-'));
+  const store = new GenerationStore(root);
+  await store.init();
+  let currentModels = structuredClone(baseModels);
+  const events = [];
+  const server = new GenerationServer({
+    host: '127.0.0.1',
+    port: await getFreePort(),
+    token: 'test-token',
+    store,
+    getModels: () => currentModels,
+    isReady: () => true,
+    analytics: {
+      emit: (...segments) => {
+        events.push(segments.join('/'));
+        return Promise.resolve(true);
+      },
+    },
+  });
+  await server.listen();
+  return {
+    root,
+    store,
+    server,
+    events,
+    setModels: (nextModels) => {
+      currentModels = nextModels;
+    },
+  };
+};
+
+const call = (address, pathName, options = {}) =>
+  fetch(`http://${address.address}:${address.port}${pathName}`, {
+    ...options,
+    headers: {
+      authorization: 'Bearer test-token',
+      ...(options.body === undefined ? {} : { 'content-type': 'application/json' }),
+      ...options.headers,
+    },
+  });
+
+test('bind and peer checks remain private-LAN-only', () => {
+  assert.equal(isAllowedPeer('127.0.0.1'), true);
+  assert.equal(isAllowedPeer('::ffff:127.0.0.1'), true);
+  assert.equal(isAllowedPeer('192.168.0.42'), true);
+  assert.equal(isAllowedPeer('192.168.1.42'), true);
+  assert.equal(isAllowedPeer('192.168.0.42', '192.168.0.'), true);
+  assert.equal(isAllowedPeer('192.168.1.42', '192.168.0.'), false);
+  assert.equal(isAllowedPeer('8.8.8.8'), false);
+  assert.throws(() => normalizeBindHost('0.0.0.0'));
+  assert.throws(() => normalizeBindHost('203.0.113.5'));
+});
+
+test('emits received and terminal events for every authenticated or rejected request', async () => {
+  const { root, store, server, events } = await setup();
+  try {
+    const address = server.address();
+    const unauthorized = await call(address, '/v1/models', {
+      headers: { authorization: '' },
+    });
+    assert.equal(unauthorized.status, 401);
+    const accepted = await call(address, '/v1/models');
+    assert.equal(accepted.status, 200);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    assert.equal(events.filter((event) => event.endsWith('/received')).length, 2);
+    assert.equal(events.filter((event) => event.includes('/responded/')).length, 2);
+    assert.ok(events.includes('http/models/authentication-rejected'));
+    assert.ok(events.includes('http/models/model-catalog-loaded'));
+    assert.ok(events.includes('http/models/responded/401'));
+    assert.ok(events.includes('http/models/responded/200'));
+  } finally {
+    await server.close();
+    await store.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('serves actual model capabilities and preserves raw idempotency across catalog changes', async () => {
+  const { root, store, server, setModels } = await setup();
+  try {
+    const address = server.address();
+    const modelsResponse = await call(address, '/v1/models');
+    assert.equal(modelsResponse.status, 200);
+    const catalog = await modelsResponse.json();
+    assert.equal(catalog.models[1].id, 'gpt-5.6-luna');
+    const key = 'request-1';
+    const firstResponse = await call(address, '/v1/jobs', {
+      method: 'POST',
+      headers: { 'idempotency-key': key },
+      body: JSON.stringify(request),
+    });
+    assert.equal(firstResponse.status, 202);
+    const first = await firstResponse.json();
+    const claimed = await store.claimNext();
+    assert.equal(claimed.model, 'gpt-5.6-sol');
+
+    setModels([
+      {
+        ...baseModels[1],
+        isDefault: true,
+      },
+    ]);
+    const replayResponse = await call(address, '/v1/jobs', {
+      method: 'POST',
+      headers: { 'idempotency-key': key },
+      body: JSON.stringify(request),
+    });
+    assert.equal(replayResponse.status, 200);
+    const replay = await replayResponse.json();
+    assert.equal(replay.id, first.id);
+    assert.equal(replay.status, 'running');
+
+    const conflictResponse = await call(address, '/v1/jobs', {
+      method: 'POST',
+      headers: { 'idempotency-key': key },
+      body: JSON.stringify({ ...request, instructions: 'different' }),
+    });
+    assert.equal(conflictResponse.status, 409);
+
+    await store.complete(claimed.id, {
+      output: [{ type: 'text', text: 'done' }],
+      model: claimed.model,
+      generatedAt: Date.now(),
+    });
+    const resultResponse = await call(address, `/v1/jobs/${first.id}`);
+    assert.equal(resultResponse.status, 200);
+    assert.equal((await resultResponse.json()).result.output[0].text, 'done');
+  } finally {
+    await server.close();
+    await store.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('local runner resolves uploaded image references into inline LAN results', async () => {
+  const { root, store, server } = await setup();
+  try {
+    const imageRequest = {
+      ...request,
+      model: 'gpt-5.6-luna',
+      reasoningEffort: 'medium',
+      output: ['text', 'image'],
+    };
+    const created = await store.create({
+      idempotencyKeyHash: idempotencyDigest('image-job'),
+      requestHash: requestDigest(imageRequest),
+      request: imageRequest,
+      model: imageRequest.model,
+      reasoningEffort: imageRequest.reasoningEffort,
+    });
+    const claimed = await store.claimNext();
+    const local = createLocalRunner({ store, record: claimed });
+    const png = Buffer.from('89504e470d0a1a0a', 'hex');
+    await local.upload(
+      claimed.id,
+      claimed.leaseToken,
+      Buffer.from(
+        JSON.stringify({
+          output: [
+            { type: 'text', text: 'done' },
+            { type: 'image', mimeType: 'image/png', name: 'image-0.png' },
+          ],
+          model: claimed.model,
+          generatedAt: Date.now(),
+        }),
+      ),
+      'response.json',
+    );
+    await local.upload(claimed.id, claimed.leaseToken, png, 'image-0.png');
+    await local.complete();
+    const result = await store.get(created.record.id);
+    assert.equal(result.result.output[1].data, png.toString('base64'));
+    assert.equal(typeof result.result.generatedAt, 'number');
+  } finally {
+    await server.close();
+    await store.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/runtime/tests/store.test.mjs

@@ -0,0 +1,114 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+/* eslint-disable import/extensions -- Native Node ESM requires file extensions. */
+
+import { idempotencyDigest, requestDigest } from '../protocol.mjs';
+import { GenerationStore } from '../store.mjs';
+
+const request = {
+  version: 1,
+  input: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }],
+  output: ['text'],
+  model: 'gpt-5.6-sol',
+  reasoningEffort: 'low',
+};
+
+const createStore = async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ag-ai-generation-store-'));
+  const store = new GenerationStore(root);
+  await store.init();
+  return { root, store };
+};
+
+const createJob = (store, key = 'key-1', body = request) =>
+  store.create({
+    idempotencyKeyHash: idempotencyDigest(key),
+    requestHash: requestDigest(body),
+    request: body,
+    model: body.model,
+    reasoningEffort: body.reasoningEffort,
+  });
+
+test('persists idempotency and keeps request bodies off the in-memory metadata map', async () => {
+  const { root, store } = await createStore();
+  try {
+    const first = await createJob(store);
+    const replay = await createJob(store);
+    assert.equal(first.created, true);
+    assert.equal(replay.created, false);
+    assert.equal(replay.record.id, first.record.id);
+    assert.equal(store.records.get(first.record.id).bodyPresent, true);
+    assert.equal('request' in store.records.get(first.record.id), false);
+    await assert.rejects(
+      createJob(store, 'key-1', { ...request, instructions: 'different' }),
+      (error) => error.code === 'idempotency_conflict',
+    );
+  } finally {
+    await store.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('marks in-flight jobs unknown after restart', async () => {
+  const { root, store } = await createStore();
+  try {
+    const created = await createJob(store);
+    const claimed = await store.claimNext();
+    assert.equal(claimed.id, created.record.id);
+    const restarted = new GenerationStore(root);
+    await restarted.init();
+    const record = await restarted.get(created.record.id);
+    assert.equal(record.status, 'unknown');
+    assert.equal(record.error.code, 'unknown_after_restart');
+    await restarted.close();
+  } finally {
+    await store.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('recovers a compaction crash with a tombstone and preserves replay identity', async () => {
+  const { root, store } = await createStore();
+  try {
+    const created = await createJob(store);
+    await store.claimNext();
+    await store.complete(created.record.id, {
+      output: [{ type: 'text', text: 'done' }],
+      model: request.model,
+      generatedAt: Date.now(),
+    });
+    const full = await store.get(created.record.id);
+    const metadata = {
+      version: 1,
+      id: full.id,
+      idempotencyKeyHash: full.idempotencyKeyHash,
+      requestHash: full.requestHash,
+      model: full.model,
+      reasoningEffort: full.reasoningEffort,
+      requestBytes: full.requestBytes,
+      status: full.status,
+      createdAt: full.createdAt,
+      updatedAt: full.updatedAt,
+      completedAt: full.completedAt,
+      cancelRequested: false,
+      bodyPresent: false,
+    };
+    await writeFile(path.join(root, `${full.id}.tombstone.json`), JSON.stringify(metadata));
+    const restarted = new GenerationStore(root);
+    await restarted.init();
+    const recovered = await restarted.get(full.id);
+    assert.equal(recovered.status, 'completed');
+    assert.equal(recovered.bodyPresent, false);
+    assert.equal(recovered.result, undefined);
+    assert.equal((await readdir(root)).includes(`${full.id}.json`), false);
+    const replay = await restarted.findByIdempotencyKeyHash(full.idempotencyKeyHash);
+    assert.equal(replay.id, full.id);
+    await restarted.close();
+  } finally {
+    await store.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/runtime/tests/telemetry.test.mjs

@@ -0,0 +1,138 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+/* eslint-disable import/extensions -- Native Node ESM requires file extensions. */
+
+import {
+  DEFAULT_ANALYTICA_EVENT_PREFIX,
+  DEFAULT_ANALYTICA_PAGE_LOCATION,
+  AnalyticaEvents,
+  analyticaEventName,
+} from '../telemetry.mjs';
+
+test('Analytica events contain bounded low-cardinality flow names and pod attribution', async () => {
+  const requests = [];
+  const analytics = new AnalyticaEvents({
+    token: 'test-token',
+    source: 'ag-ai-runner',
+    eventUrl: 'https://telemetry.example/api/site/event',
+    fetchImpl: async (url, init) => {
+      requests.push({ url, init });
+      return new Response(null, { status: 204 });
+    },
+  });
+
+  assert.equal(await analytics.emit('job', 'local', 'turn completed'), true);
+  await analytics.flush();
+
+  assert.equal(requests.length, 1);
+  assert.equal(requests[0].url, 'https://telemetry.example/api/site/event');
+  assert.equal(requests[0].init.headers.authorization, '');
+  const payload = JSON.parse(requests[0].init.body);
+  assert.deepEqual(payload, {
+    key: 'test-token',
+    data: {
+      eventName: `${DEFAULT_ANALYTICA_EVENT_PREFIX}/job/local/turn-completed`,
+      browserFingerprint: 'ag-ai-runner',
+      pageLocation: DEFAULT_ANALYTICA_PAGE_LOCATION,
+    },
+  });
+});
+
+test('Analytica event prefix and page location are configurable', async () => {
+  const requests = [];
+  const analytics = new AnalyticaEvents({
+    token: 'test-token',
+    source: 'runner',
+    eventPrefix: 'example/custom',
+    pageLocation: 'cluster://example',
+    fetchImpl: async (url, init) => {
+      requests.push({ url, init });
+      return new Response(null, { status: 204 });
+    },
+  });
+
+  await analytics.emit('flow', 'one');
+  await analytics.flush();
+  const payload = JSON.parse(requests[0].init.body);
+  assert.equal(payload.data.eventName, 'example/custom/flow/one');
+  assert.equal(payload.data.pageLocation, 'cluster://example');
+});
+
+test('Analytica delivery failures never fail a generation request', async () => {
+  const analytics = new AnalyticaEvents({
+    token: 'test-token',
+    source: 'runner',
+    fetchImpl: async () => {
+      throw new Error('collector unavailable');
+    },
+  });
+
+  assert.equal(await analytics.emit('http', 'jobs-create', 'received'), false);
+  await analytics.flush();
+});
+
+test('event name normalization never includes request-controlled path text', () => {
+  assert.equal(
+    analyticaEventName(
+      DEFAULT_ANALYTICA_EVENT_PREFIX,
+      'http',
+      '../v1/jobs/private-id?token=secret',
+      'responded',
+      200,
+    ),
+    `${DEFAULT_ANALYTICA_EVENT_PREFIX}/http/v1-jobs-private-id-token-secret/responded/200`,
+  );
+});
+
+test('Analytica delivery limits concurrent requests and drains queued events', async () => {
+  const releases = [];
+  let active = 0;
+  let maximumActive = 0;
+  const analytics = new AnalyticaEvents({
+    token: 'test-token',
+    source: 'runner',
+    maxConcurrent: 2,
+    fetchImpl: async () => {
+      active += 1;
+      maximumActive = Math.max(maximumActive, active);
+      await new Promise((resolve) => releases.push(resolve));
+      active -= 1;
+      return new Response(null, { status: 204 });
+    },
+  });
+
+  const deliveries = [
+    analytics.emit('flow', 'one'),
+    analytics.emit('flow', 'two'),
+    analytics.emit('flow', 'three'),
+  ];
+  assert.equal(releases.length, 2);
+  releases.shift()();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(releases.length, 2);
+  releases.shift()();
+  releases.shift()();
+  assert.deepEqual(await Promise.all(deliveries), [true, true, true]);
+  assert.equal(maximumActive, 2);
+});
+
+test('Analytica logs but safely drops collector delivery when its queue is full', async () => {
+  let release;
+  const analytics = new AnalyticaEvents({
+    token: 'test-token',
+    source: 'runner',
+    maxConcurrent: 1,
+    maxQueued: 0,
+    fetchImpl: async () => {
+      await new Promise((resolve) => {
+        release = resolve;
+      });
+      return new Response(null, { status: 204 });
+    },
+  });
+
+  const first = analytics.emit('flow', 'active');
+  assert.equal(await analytics.emit('flow', 'dropped'), false);
+  release();
+  assert.equal(await first, true);
+});