ag-ai 0.1.0

package/runtime/protocol.mjs

@@ -0,0 +1,384 @@
+// ag-ai generation protocol v1. The JSON request/result shape is unchanged from
+// the previous runtime; only provider-neutral naming and capability handling
+// differ.
+
+import { createHash } from 'node:crypto';
+
+const GENERATION_VERSION = 1;
+const MAX_TEXT_BYTES = 2 * 1024 * 1024;
+const MAX_INPUT_MESSAGES = 256;
+const MAX_CONTENT_PARTS = 128;
+const MAX_INPUT_ATTACHMENTS = 32;
+const MAX_INPUT_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+const MAX_INPUT_TOTAL_BYTES = 40 * 1024 * 1024;
+const MAX_SCHEMA_BYTES = 256 * 1024;
+const MAX_NAME_LENGTH = 200;
+const MAX_IDEMPOTENCY_KEY_LENGTH = 512;
+const INPUT_ROLES = new Set(['user', 'assistant', 'system', 'developer']);
+const INPUT_TYPES = new Set(['text', 'image', 'audio', 'video', 'file']);
+const OUTPUT_TYPES = new Set(['text', 'image', 'audio', 'video', 'file']);
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,199}$/;
+const MIME_TYPE =
+  /^[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~-]*\/[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~-]*(?:;[A-Za-z0-9][A-Za-z0-9!#$%&'*+.^_`|~=-]*)*$/;
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+
+class GenerationProtocolError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.name = 'GenerationProtocolError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+const asObject = (value) => (value && typeof value === 'object' ? value : null);
+
+const boundedString = (value, maximum, name, { allowEmpty = false } = {}) => {
+  if (typeof value !== 'string' || value.length > maximum || (!allowEmpty && value.length === 0)) {
+    throw new GenerationProtocolError(400, 'invalid_request', `${name} is invalid`);
+  }
+  return value;
+};
+
+const normalizeMimeType = (value, name) => {
+  const mimeType = boundedString(value, 160, name).toLowerCase();
+  if (!MIME_TYPE.test(mimeType) || mimeType.includes('\r') || mimeType.includes('\n')) {
+    throw new GenerationProtocolError(400, 'invalid_request', `${name} is invalid`);
+  }
+  return mimeType;
+};
+
+const decodeBase64 = (value, name) => {
+  const data = boundedString(value, Math.ceil((MAX_INPUT_ATTACHMENT_BYTES * 4) / 3) + 8, name);
+  if (!BASE64.test(data) || data.length % 4 !== 0) {
+    throw new GenerationProtocolError(400, 'invalid_request', `${name} is invalid`);
+  }
+  const bytes = Buffer.from(data, 'base64');
+  if (bytes.length === 0 || bytes.length > MAX_INPUT_ATTACHMENT_BYTES) {
+    throw new GenerationProtocolError(413, 'input_too_large', `${name} exceeds its size limit`);
+  }
+  if (bytes.toString('base64') !== data) {
+    throw new GenerationProtocolError(400, 'invalid_request', `${name} is invalid`);
+  }
+  return { data, bytes };
+};
+
+const normalizeCapabilities = (value) => {
+  const model = asObject(value);
+  const id = typeof model?.id === 'string' ? model.id : model?.model;
+  const inputModalities = Array.isArray(model?.inputModalities)
+    ? model.inputModalities.filter((item) => INPUT_TYPES.has(item))
+    : undefined;
+  const outputModalities = Array.isArray(model?.outputModalities)
+    ? model.outputModalities.filter((item) => OUTPUT_TYPES.has(item))
+    : undefined;
+  const supportedReasoningEfforts = Array.isArray(model?.supportedReasoningEfforts)
+    ? model.supportedReasoningEfforts
+        .map((item) => (typeof item === 'string' ? item : asObject(item)?.reasoningEffort))
+        .filter((item) => typeof item === 'string')
+    : [];
+  const defaultReasoningEffort =
+    typeof model?.defaultReasoningEffort === 'string'
+      ? model.defaultReasoningEffort
+      : supportedReasoningEfforts[0];
+  // Image output is delegated to the configured image adapter, so the catalog
+  // advertises it only when a provider explicitly marks the model capable.
+  const imageGeneration = model?.imageGeneration === true;
+  const declaredOutputModalities =
+    outputModalities === undefined ? undefined : [...new Set(outputModalities)];
+  const normalizedOutputModalities =
+    declaredOutputModalities === undefined
+      ? ['text']
+      : declaredOutputModalities.filter((item) => item !== 'image' || imageGeneration);
+  if (imageGeneration && declaredOutputModalities === undefined) {
+    normalizedOutputModalities.push('image');
+  }
+  return {
+    id: id ?? '',
+    inputModalities:
+      inputModalities === undefined ? ['text', 'image'] : [...new Set(inputModalities)],
+    outputModalities: normalizedOutputModalities,
+    imageGeneration,
+    supportedReasoningEfforts: [...new Set(supportedReasoningEfforts)],
+    ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
+    webSearch: model?.webSearch === true,
+    prefer: Array.isArray(model?.prefer)
+      ? model.prefer.filter((item) => item === 'fast' || item === 'quality')
+      : ['quality'],
+    isDefault: model?.isDefault === true,
+  };
+};
+
+const normalizeModelCatalog = (models) => {
+  const source = Array.isArray(models) ? models : [];
+  return source.map(normalizeCapabilities).filter((model) => model.id.length > 0);
+};
+
+const unsupported = (what) =>
+  new GenerationProtocolError(422, 'unsupported', `${what} is not supported by the selected model`);
+
+const normalizePart = (part, capabilities, total) => {
+  const object = asObject(part);
+  const type = object?.type;
+  if (!INPUT_TYPES.has(type)) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'input content part type is invalid');
+  }
+  if (type === 'text') {
+    return {
+      type,
+      text: boundedString(object.text, MAX_TEXT_BYTES, 'input text', { allowEmpty: true }),
+    };
+  }
+
+  if (type !== 'image') {
+    throw unsupported(`input ${type}`);
+  }
+
+  if (!capabilities.inputModalities.includes(type)) {
+    throw unsupported(`input ${type}`);
+  }
+  const mimeType = normalizeMimeType(object.mimeType, 'input mimeType');
+  if (type === 'image' && !['image/png', 'image/jpeg', 'image/webp'].includes(mimeType)) {
+    throw unsupported(`input ${mimeType}`);
+  }
+  const decoded = decodeBase64(object.data, 'input data');
+  total.bytes += decoded.bytes.length;
+  total.attachments += 1;
+  if (total.bytes > MAX_INPUT_TOTAL_BYTES) {
+    throw new GenerationProtocolError(
+      413,
+      'input_too_large',
+      'input attachments exceed their size limit',
+    );
+  }
+  if (total.attachments > MAX_INPUT_ATTACHMENTS) {
+    throw new GenerationProtocolError(413, 'input_too_large', 'too many input attachments');
+  }
+  const result = { type, mimeType, data: decoded.data };
+  if (object.name !== undefined) {
+    const name = boundedString(object.name, MAX_NAME_LENGTH, 'input name');
+    if (!SAFE_NAME.test(name)) {
+      throw new GenerationProtocolError(400, 'invalid_request', 'input name is invalid');
+    }
+    result.name = name;
+  }
+  return result;
+};
+
+const normalizeMessage = (message, capabilities, total) => {
+  const object = asObject(message);
+  if (!INPUT_ROLES.has(object?.role)) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'input message role is invalid');
+  }
+  if (!Array.isArray(object.content) || object.content.length > MAX_CONTENT_PARTS) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'input message content is invalid');
+  }
+  return {
+    role: object.role,
+    content: object.content.map((part) => normalizePart(part, capabilities, total)),
+  };
+};
+
+const normalizeOutput = (output, capabilities) => {
+  if (!Array.isArray(output) || output.length === 0 || output.length > 5) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'output is invalid');
+  }
+  const result = [];
+  for (const type of output) {
+    if (!OUTPUT_TYPES.has(type) || result.includes(type)) {
+      throw new GenerationProtocolError(400, 'invalid_request', 'output is invalid');
+    }
+    if (type !== 'text' && type !== 'image') {
+      throw unsupported(`output ${type}`);
+    }
+    if (!capabilities.outputModalities.includes(type)) {
+      throw unsupported(`output ${type}`);
+    }
+    result.push(type);
+  }
+  return result;
+};
+
+const normalizeOutputSchema = (value) => {
+  if (value === undefined) return undefined;
+  const object = asObject(value);
+  if (!object || Array.isArray(object.schema) || asObject(object.schema) === null) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'outputSchema is invalid');
+  }
+  const name = boundedString(object.name, 128, 'outputSchema name');
+  const serialized = JSON.stringify(object.schema);
+  if (Buffer.byteLength(serialized) > MAX_SCHEMA_BYTES) {
+    throw new GenerationProtocolError(
+      413,
+      'input_too_large',
+      'outputSchema exceeds its size limit',
+    );
+  }
+  return { name, schema: object.schema };
+};
+
+const toRunnerInput = (request, runId, models) => {
+  const normalized =
+    request?.model && request?.reasoningEffort && request?.version === GENERATION_VERSION
+      ? request
+      : normalizeGenerationRequest(request, models);
+  const input = normalized.input.map((message) => ({
+    role: message.role,
+    content: message.content.map((part) => {
+      if (part.type === 'text') return { type: 'text', text: part.text };
+      if (part.type === 'image') return { type: 'image', mimeType: part.mimeType, data: part.data };
+      throw unsupported(`input ${part.type}`);
+    }),
+  }));
+  return {
+    runId,
+    instructions: normalized.instructions,
+    messages: input,
+    output: normalized.output,
+    imageGeneration: normalized.output.includes('image'),
+    model: normalized.model,
+    reasoningEffort: normalized.reasoningEffort,
+    ...(normalized.outputSchema === undefined ? {} : { outputSchema: normalized.outputSchema }),
+  };
+};
+
+const normalizeGenerationRequest = (value, models) => {
+  const request = asObject(value);
+  if (request?.version !== GENERATION_VERSION) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'version must be 1');
+  }
+  const allowedKeys = new Set([
+    'version',
+    'instructions',
+    'input',
+    'output',
+    'model',
+    'prefer',
+    'reasoningEffort',
+    'maxOutputTokens',
+    'outputSchema',
+    'webSearch',
+  ]);
+  for (const key of Object.keys(request)) {
+    if (!allowedKeys.has(key)) {
+      throw new GenerationProtocolError(400, 'invalid_request', `unknown request field ${key}`);
+    }
+  }
+  const catalog = normalizeModelCatalog(models);
+  if (catalog.length === 0) {
+    throw new GenerationProtocolError(503, 'model_unavailable', 'no AI model is ready');
+  }
+  const prefer = request.prefer === undefined ? undefined : request.prefer;
+  if (prefer !== undefined && prefer !== 'fast' && prefer !== 'quality') {
+    throw new GenerationProtocolError(400, 'invalid_request', 'prefer is invalid');
+  }
+  let requestedModel;
+  if (request.model !== undefined) {
+    requestedModel = boundedString(request.model, 160, 'model');
+  } else if (prefer === 'fast') {
+    requestedModel = catalog.find((candidate) => candidate.prefer.includes('fast'))?.id;
+    requestedModel ??= catalog.find((candidate) => /(?:mini|luna)$/i.test(candidate.id))?.id;
+    if (!requestedModel) throw unsupported('fast model preference');
+  } else {
+    requestedModel =
+      catalog.find((candidate) => candidate.isDefault && candidate.prefer.includes('quality'))
+        ?.id ??
+      catalog.find((candidate) => candidate.isDefault)?.id ??
+      catalog.find((candidate) => candidate.prefer.includes('quality'))?.id ??
+      catalog[0].id;
+  }
+  const model = catalog.find((candidate) => candidate.id === requestedModel);
+  if (!model) throw unsupported(`model ${requestedModel}`);
+  const capabilities = normalizeCapabilities(model);
+  const instructions =
+    request.instructions === undefined
+      ? ''
+      : boundedString(request.instructions, MAX_TEXT_BYTES, 'instructions', { allowEmpty: true });
+  const messages = request.input;
+  if (!Array.isArray(messages) || messages.length > MAX_INPUT_MESSAGES) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'input is invalid');
+  }
+  const total = { bytes: 0, attachments: 0 };
+  const input = messages.map((message) => normalizeMessage(message, capabilities, total));
+  const output = normalizeOutput(request.output, capabilities);
+  const reasoningEffort =
+    request.reasoningEffort === undefined
+      ? (capabilities.defaultReasoningEffort ?? capabilities.supportedReasoningEfforts[0])
+      : boundedString(request.reasoningEffort, 32, 'reasoningEffort');
+  if (!reasoningEffort) {
+    throw new GenerationProtocolError(
+      503,
+      'model_unavailable',
+      'selected model has no reasoning effort',
+    );
+  }
+  if (!capabilities.supportedReasoningEfforts.includes(reasoningEffort)) {
+    throw unsupported(`reasoning effort ${reasoningEffort}`);
+  }
+  if (request.maxOutputTokens !== undefined && !Number.isInteger(request.maxOutputTokens)) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'maxOutputTokens is invalid');
+  }
+  if (request.maxOutputTokens !== undefined) {
+    throw unsupported('maxOutputTokens');
+  }
+  if (request.webSearch === true && !capabilities.webSearch) throw unsupported('web search');
+  if (request.webSearch !== undefined && typeof request.webSearch !== 'boolean') {
+    throw new GenerationProtocolError(400, 'invalid_request', 'webSearch is invalid');
+  }
+  const outputSchema = normalizeOutputSchema(request.outputSchema);
+  return {
+    version: GENERATION_VERSION,
+    instructions,
+    input,
+    output,
+    model: requestedModel,
+    ...(prefer === undefined ? {} : { prefer }),
+    reasoningEffort,
+    ...(outputSchema === undefined ? {} : { outputSchema }),
+    ...(request.webSearch === undefined ? {} : { webSearch: request.webSearch }),
+  };
+};
+
+const requestDigest = (request) =>
+  createHash('sha256').update(JSON.stringify(request)).digest('hex');
+const idempotencyDigest = (key) => createHash('sha256').update(key).digest('hex');
+
+const normalizeIdempotencyKey = (value) => {
+  const key = boundedString(value, MAX_IDEMPOTENCY_KEY_LENGTH, 'idempotency key');
+  // eslint-disable-next-line no-control-regex -- Protocol keys reject ASCII control bytes.
+  if (/^[\x00-\x1f\x7f]|[\x00-\x1f\x7f]$/.test(key)) {
+    throw new GenerationProtocolError(400, 'invalid_request', 'idempotency key is invalid');
+  }
+  return key;
+};
+
+const publicModelCatalog = (models, { ready = true } = {}) => ({
+  version: GENERATION_VERSION,
+  models: normalizeModelCatalog(models).map((model) => ({
+    id: model.id,
+    inputModalities: model.inputModalities,
+    outputModalities: model.outputModalities,
+    supportedReasoningEfforts: model.supportedReasoningEfforts,
+    ...(model.defaultReasoningEffort
+      ? { defaultReasoningEffort: model.defaultReasoningEffort }
+      : {}),
+    webSearch: model.webSearch,
+    prefer: model.prefer,
+    isDefault: model.isDefault,
+    ready,
+  })),
+});
+
+export {
+  GENERATION_VERSION,
+  MAX_INPUT_ATTACHMENT_BYTES,
+  MAX_INPUT_TOTAL_BYTES,
+  GenerationProtocolError,
+  idempotencyDigest,
+  normalizeGenerationRequest,
+  normalizeIdempotencyKey,
+  normalizeModelCatalog,
+  publicModelCatalog,
+  requestDigest,
+  toRunnerInput,
+};