@axiom-lattice/protocols 3.0.3 → 4.0.0

package/src/A2AProtocol.ts

@@ -1,190 +1,50 @@
 /**
- * A2AProtocol - Google Agent-to-Agent Protocol type definitions
- *
- * Based on the A2A open protocol spec for AI agent interoperability.
- * @see https://github.com/google/A2A
+ * A2AProtocol - re-exports standard A2A 0.3 types from @a2a-js/sdk
+ * plus Axiom-specific auth/exposure types.
  */
+export type {
+  AgentCard,
+  AgentSkill as A2ASkill,
+  Task as A2ATask,
+  Message as A2AMessage,
+  Part as A2APart,
+  TaskState as A2ATaskState,
+} from "@a2a-js/sdk";
 
-// ─── Agent Card ───────────────────────────────────────────────────────────
-
-export interface A2ASkill {
-  id: string;
-  name: string;
-  description: string;
-  tags: string[];
-  examples: string[];
-}
-
-export interface A2ACapabilities {
-  streaming: boolean;
-  pushNotifications: boolean;
-  stateTransitionHistory: boolean;
-}
-
-export interface A2AProvider {
-  organization: string;
-  url?: string;
-}
-
-export interface AgentCard {
-  name: string;
-  description: string;
-  url: string;
-  provider: A2AProvider;
-  version: string;
-  documentationUrl?: string;
-  capabilities: A2ACapabilities;
-  defaultInputModes: string[];
-  defaultOutputModes: string[];
-  skills: A2ASkill[];
-}
-
-// ─── Artifact / Part ──────────────────────────────────────────────────────
-
-export interface A2ATextPart {
-  type: "text";
-  text: string;
-}
-
-export interface A2AFilePart {
-  type: "file";
-  file: {
-    name: string;
-    mimeType: string;
-    bytes?: string;
-    uri?: string;
-  };
-}
-
-export interface A2ADataPart {
-  type: "data";
-  data: Record<string, unknown>;
-}
-
-export type A2APart = A2ATextPart | A2AFilePart | A2ADataPart;
-
-// ─── Message ──────────────────────────────────────────────────────────────
-
-export interface A2AMessage {
-  role: "user" | "agent";
-  parts: A2APart[];
-  messageId?: string;
-  contextId?: string;
-  referenceTaskIds?: string[];
-  metadata?: Record<string, unknown>;
-}
-
-// ─── Task ─────────────────────────────────────────────────────────────────
-
-export type A2ATaskState =
-  | "working"
-  | "input-required"
-  | "completed"
-  | "failed"
-  | "canceled"
-  | "rejected";
-
-export interface A2ATaskStatus {
-  state: A2ATaskState;
-  message?: A2AMessage;
-  timestamp: string;
-}
-
-export interface A2AArtifact {
-  name?: string;
-  description?: string;
-  parts: A2APart[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface A2ATask {
-  id: string;
-  sessionId?: string;
-  contextId?: string;
-  status: A2ATaskStatus;
-  artifacts: A2AArtifact[];
-  history?: A2AMessage[];
-  metadata?: Record<string, unknown>;
-}
-
-// ─── Request / Response ───────────────────────────────────────────────────
-
-export interface A2ATaskSendRequest {
-  id?: string;
-  sessionId?: string;
-  message: A2AMessage;
-  pushNotification?: A2APushNotification;
-  historyLength?: number;
-  metadata?: Record<string, unknown>;
-}
-
-export interface A2APushNotification {
-  url: string;
-  token?: string;
-}
-
-export interface A2ATaskUpdatePayload {
-  id: string;
-  sessionId?: string;
-  contextId?: string;
-  status: A2ATaskStatus;
-  final?: boolean;
-  metadata?: Record<string, unknown>;
-}
-
-export interface A2ATaskArtifactUpdatePayload {
-  id: string;
-  sessionId?: string;
-  contextId?: string;
-  artifact: A2AArtifact;
-  final?: boolean;
-  metadata?: Record<string, unknown>;
-}
-
-// ─── SSE Events ───────────────────────────────────────────────────────────
-
-export type A2ASSEEvent =
-  | { event: "task"; data: A2ATaskUpdatePayload }
-  | { event: "status-update"; data: A2ATaskUpdatePayload }
-  | { event: "artifact-update"; data: A2ATaskArtifactUpdatePayload }
-  | { event: "error"; data: { code: string; message: string } };
-
-// ─── Config ───────────────────────────────────────────────────────────────
-
-export interface A2AConfig {
-  agentName: string;
-  agentDescription: string;
-  agentUrl: string;
-  organization: string;
-  version?: string;
-  capabilities?: Partial<A2ACapabilities>;
-  defaultInputModes?: string[];
-  defaultOutputModes?: string[];
-  skills?: A2ASkill[];
-  apiKeyMap: Map<string, A2AApiKeyEntry>;
+/**
+ * Per-agent A2A exposure configuration — controls whether an agent is
+ * reachable over A2A and which skills are advertised on its AgentCard.
+ */
+export interface A2AExposure {
+  /** Whether this agent is exposed over the A2A protocol */
+  enabled: boolean;
+  /** Skills advertised on the AgentCard; defaults to a single generic skill when omitted */
+  skills?: Array<{ id: string; name: string; description: string; tags?: string[]; examples?: string[] }>;
+  /** Supported input modes (MIME types); defaults to text modes when omitted */
+  inputModes?: string[];
+  /** Supported output modes (MIME types); defaults to text modes when omitted */
+  outputModes?: string[];
 }
 
+/**
+ * In-memory API key entry used for request authentication.
+ * Empty/undefined assistantIds means all exposed agents in the tenant.
+ */
 export interface A2AApiKeyEntry {
   key: string;
-  tenantId?: string;
-  projectId?: string;
-  workspaceId?: string;
+  tenantId: string;
+  projectId: string;
+  assistantIds?: string[];
 }
 
-export const A2A_DEFAULT_CAPABILITIES: A2ACapabilities = {
-  streaming: true,
-  pushNotifications: false,
-  stateTransitionHistory: false,
-};
-
-export const A2A_DEFAULT_INPUT_MODES = ["text", "text/plain"];
-export const A2A_DEFAULT_OUTPUT_MODES = ["text", "text/plain", "text/markdown"];
-
+/**
+ * Authentication context attached to an incoming A2A request after key validation.
+ */
 export interface A2AAuthContext {
   authenticated: boolean;
   apiKey?: string;
   tenantId?: string;
   projectId?: string;
-  workspaceId?: string;
+  assistantIds?: string[];
   source?: "bearer" | "x-api-key";
 }

package/src/EvalStoreProtocol.ts

@@ -16,7 +16,8 @@ export interface CreateEvalProjectRequest {
   name: string;
   description?: string;
   version?: string;
-  judgeModelConfig: Record<string, unknown>;
+  /** Judge model config; omit to let the runner resolve its default model. */
+  judgeModelConfig?: Record<string, unknown>;
   targetServerConfig: Record<string, unknown>;
   concurrency?: number;
   reportConfig?: Record<string, unknown>;

package/src/SkillStoreProtocol.ts

@@ -250,4 +250,25 @@ export interface SkillStore {
    * @returns The resource content as string, or null if not found
    */
   loadSkillResource?(tenantId: string, id: string, resourcePath: string, context?: SkillStoreContext): Promise<string | null>;
+
+  /**
+   * Load a resource without text decoding.
+   * @returns The resource bytes, or null if the resource does not exist
+   */
+  loadSkillResourceRaw?(tenantId: string, id: string, resourcePath: string, context?: SkillStoreContext): Promise<Buffer | null>;
+
+  /**
+   * Write a resource file into a skill's resources directory
+   * @param tenantId Tenant identifier
+   * @param id Skill identifier
+   * @param resourcePath Path to the resource relative to resources/ directory
+   * @param content Resource content
+   * @param context Optional runtime context for sandbox resolution
+   */
+  writeSkillResource?(tenantId: string, id: string, resourcePath: string, content: string, context?: SkillStoreContext): Promise<void>;
+
+  /**
+   * Write a resource without text encoding.
+   */
+  writeSkillResourceRaw?(tenantId: string, id: string, resourcePath: string, data: Buffer, context?: SkillStoreContext): Promise<void>;
 }

package/src/TaskBeliefProtocol.ts

@@ -0,0 +1,324 @@
+/** A single canonical belief recorded in a task description. */
+export interface TaskBeliefEntry {
+  key: string;
+  probability: number;
+  target: number;
+  basis: string;
+}
+
+/** The canonical belief snapshot embedded in task Markdown. */
+export interface TaskBeliefState {
+  entries: TaskBeliefEntry[];
+}
+
+/** Stable diagnostic identifiers returned by the Belief State parser. */
+export type TaskBeliefDiagnosticCode =
+  | "MISSING_BELIEF_STATE"
+  | "DUPLICATE_BELIEF_STATE"
+  | "INVALID_BELIEF_HEADERS"
+  | "MALFORMED_BELIEF_ROW"
+  | "INVALID_BELIEF_KEY"
+  | "INVALID_BELIEF_PERCENT"
+  | "DUPLICATE_BELIEF_KEY";
+
+/** A structured failure produced while parsing a task Belief State. */
+export interface TaskBeliefParseFailure {
+  success: false;
+  code: TaskBeliefDiagnosticCode;
+  message: string;
+  line?: number;
+  key?: string;
+  column?: "probability" | "target";
+}
+
+/** A successfully parsed task Belief State. */
+export interface TaskBeliefParseSuccess {
+  success: true;
+  state: TaskBeliefState;
+}
+
+/** The discriminated result of parsing a task Belief State. */
+export type TaskBeliefParseResult = TaskBeliefParseSuccess | TaskBeliefParseFailure;
+
+interface MarkdownLine {
+  text: string;
+  start: number;
+  end: number;
+  fenced: boolean;
+  lineNumber: number;
+}
+
+interface SectionRange {
+  headingLine: number;
+  start: number;
+  end: number;
+}
+
+const BELIEF_HEADING = "## Belief State";
+const ACCEPTANCE_HEADING = "## Acceptance Criteria";
+const EXPECTED_HEADERS = ["Belief Key", "Probability", "Target", "Basis"];
+const KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PERCENT_PATTERN = /^(?:100|[0-9]{1,2})%$/;
+
+function markdownLines(markdown: string): MarkdownLine[] {
+  const lines: MarkdownLine[] = [];
+  let start = 0;
+  let fence: { marker: "`" | "~"; length: number } | undefined;
+
+  while (start <= markdown.length) {
+    const newline = markdown.indexOf("\n", start);
+    const end = newline === -1 ? markdown.length : newline + 1;
+    const textEnd = newline === -1 ? markdown.length : newline;
+    const rawText = markdown.slice(start, textEnd);
+    const text = rawText.endsWith("\r") ? rawText.slice(0, -1) : rawText;
+    const fenceMatch = text.match(/^ {0,3}(`{3,}|~{3,})/);
+    const fenced = fence !== undefined;
+
+    if (!fence && fenceMatch) {
+      const marker = fenceMatch[1][0] as "`" | "~";
+      fence = { marker, length: fenceMatch[1].length };
+    } else if (fence) {
+      const closePattern = new RegExp(`^ {0,3}\\${fence.marker}{${fence.length},}[ \\t]*$`);
+      if (closePattern.test(text)) fence = undefined;
+    }
+
+    lines.push({
+      text,
+      start,
+      end,
+      fenced: fenced || fenceMatch !== null,
+      lineNumber: lines.length + 1,
+    });
+    if (newline === -1) break;
+    start = end;
+  }
+
+  return lines;
+}
+
+function sectionRanges(markdown: string, heading: string): SectionRange[] {
+  const lines = markdownLines(markdown);
+  const ranges: SectionRange[] = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.fenced || line.text.trimEnd().replace(/^ {0,3}/, "") !== heading) continue;
+
+    let end = markdown.length;
+    for (let next = index + 1; next < lines.length; next += 1) {
+      if (!lines[next].fenced && /^ {0,3}#{1,2}(?:[ \t]+|$)/.test(lines[next].text)) {
+        end = lines[next].start;
+        break;
+      }
+    }
+    ranges.push({ headingLine: index, start: line.start, end });
+  }
+
+  return ranges;
+}
+
+function splitTableRow(line: string): string[] | undefined {
+  const trimmed = line.trim();
+  const finalPipe = trimmed.length - 1;
+  if (!trimmed.startsWith("|") || !trimmed.endsWith("|") || isEscapedPipe(trimmed, finalPipe)) {
+    return undefined;
+  }
+
+  const cells: string[] = [];
+  let cell = "";
+  for (let index = 1; index < trimmed.length - 1; index += 1) {
+    const character = trimmed[index];
+    if (character === "|" && isEscapedPipe(trimmed, index)) {
+      cell += character;
+    } else if (character === "|") {
+      cells.push(unescapeTableCell(cell.trim()));
+      cell = "";
+    } else {
+      cell += character;
+    }
+  }
+  cells.push(unescapeTableCell(cell.trim()));
+  return cells;
+}
+
+function unescapeTableCell(cell: string): string {
+  let unescaped = "";
+  for (let index = 0; index < cell.length; index += 1) {
+    if (cell[index] === "\\" && (cell[index + 1] === "\\" || cell[index + 1] === "|")) {
+      index += 1;
+    }
+    unescaped += cell[index];
+  }
+  return unescaped;
+}
+
+function isEscapedPipe(line: string, pipeIndex: number): boolean {
+  let backslashes = 0;
+  for (let index = pipeIndex - 1; index >= 0 && line[index] === "\\"; index -= 1) {
+    backslashes += 1;
+  }
+  return backslashes % 2 === 1;
+}
+
+function failure(
+  code: TaskBeliefDiagnosticCode,
+  message: string,
+  details: Pick<TaskBeliefParseFailure, "line" | "key" | "column"> = {},
+): TaskBeliefParseFailure {
+  return { success: false, code, message, ...details };
+}
+
+function normalizedText(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function validateTaskBeliefState(state: TaskBeliefState): void {
+  const keys = new Set<string>();
+  for (const entry of state.entries) {
+    if (!KEY_PATTERN.test(entry.key)) {
+      throw new Error("Belief keys must be kebab-case without backticks or newlines.");
+    }
+    if (keys.has(entry.key)) {
+      throw new Error(`Belief key '${entry.key}' appears more than once.`);
+    }
+    for (const field of ["probability", "target"] as const) {
+      const value = entry[field];
+      if (!Number.isInteger(value) || value < 0 || value > 100) {
+        throw new Error(`Belief ${field} must be an integer from 0 to 100.`);
+      }
+    }
+    if (entry.basis.trim().length === 0 || /[\r\n]/.test(entry.basis)) {
+      throw new Error("Belief basis must be a nonempty single line.");
+    }
+    keys.add(entry.key);
+  }
+}
+
+function formatTaskBeliefState(state: TaskBeliefState): string {
+  validateTaskBeliefState(state);
+  const rows = state.entries.map(({ key, probability, target, basis }) => {
+    const escapedBasis = normalizedText(basis).replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+    return `| \`${key}\` | ${probability}% | ${target}% | ${escapedBasis} |`;
+  });
+  return [
+    BELIEF_HEADING,
+    "",
+    "| Belief Key | Probability | Target | Basis |",
+    "|---|---:|---:|---|",
+    ...rows,
+  ].join("\n");
+}
+
+/** Parses the unique non-code-fenced canonical Belief State section in Markdown. */
+export function parseTaskBeliefState(markdown: string): TaskBeliefParseResult {
+  const sections = sectionRanges(markdown, BELIEF_HEADING);
+  if (sections.length === 0) {
+    return failure("MISSING_BELIEF_STATE", "Markdown does not contain a Belief State section.");
+  }
+  if (sections.length > 1) {
+    return failure("DUPLICATE_BELIEF_STATE", "Markdown contains more than one Belief State section.");
+  }
+
+  const lines = markdownLines(markdown);
+  const section = sections[0];
+  const content = lines
+    .slice(section.headingLine + 1)
+    .filter((line) => line.start < section.end && line.text.trim() !== "");
+  const header = content[0] && splitTableRow(content[0].text);
+  const separator = content[1] && splitTableRow(content[1].text);
+  if (
+    !header ||
+    header.length !== EXPECTED_HEADERS.length ||
+    header.some((cell, index) => cell !== EXPECTED_HEADERS[index]) ||
+    !separator ||
+    separator.length !== EXPECTED_HEADERS.length ||
+    separator.some((cell) => !/^:?-{3,}:?$/.test(cell))
+  ) {
+    return failure("INVALID_BELIEF_HEADERS", "Belief State must use the canonical four-column headers.");
+  }
+
+  const entries: TaskBeliefEntry[] = [];
+  const keys = new Set<string>();
+  for (const line of content.slice(2)) {
+    const cells = splitTableRow(line.text);
+    if (!cells || cells.length !== 4 || cells[3].length === 0) {
+      return failure("MALFORMED_BELIEF_ROW", "Belief State contains a malformed row.", {
+        line: line.lineNumber,
+      });
+    }
+
+    const keyMatch = cells[0].match(/^`([^`]+)`$/);
+    if (!keyMatch || !KEY_PATTERN.test(keyMatch[1])) {
+      return failure("INVALID_BELIEF_KEY", "Belief keys must be backtick-wrapped kebab-case.", {
+        line: line.lineNumber,
+      });
+    }
+    const key = keyMatch[1];
+    if (keys.has(key)) {
+      return failure("DUPLICATE_BELIEF_KEY", `Belief key '${key}' appears more than once.`, {
+        line: line.lineNumber,
+        key,
+      });
+    }
+
+    for (const [index, column] of [[1, "probability"], [2, "target"]] as const) {
+      if (!PERCENT_PATTERN.test(cells[index])) {
+        return failure("INVALID_BELIEF_PERCENT", `Belief ${column} must be an integer from 0% to 100%.`, {
+          line: line.lineNumber,
+          column,
+        });
+      }
+    }
+
+    keys.add(key);
+    entries.push({
+      key,
+      probability: Number.parseInt(cells[1], 10),
+      target: Number.parseInt(cells[2], 10),
+      basis: cells[3],
+    });
+  }
+
+  return { success: true, state: { entries } };
+}
+
+/** Compares two Belief States while ignoring entry order and insignificant whitespace. */
+export function taskBeliefStatesEqual(left: TaskBeliefState, right: TaskBeliefState): boolean {
+  if (left.entries.length !== right.entries.length) return false;
+
+  const byKey = new Map(right.entries.map((entry) => [entry.key, entry]));
+  return left.entries.every((entry) => {
+    const other = byKey.get(entry.key);
+    return other !== undefined &&
+      entry.probability === other.probability &&
+      entry.target === other.target &&
+      normalizedText(entry.basis) === normalizedText(other.basis);
+  });
+}
+
+/**
+ * Replaces a unique Belief State section, or inserts one after Acceptance Criteria content.
+ *
+ * @throws {Error} If the state is noncanonical or the Markdown contains duplicate sections.
+ */
+export function replaceTaskBeliefState(markdown: string, state: TaskBeliefState): string {
+  const replacement = formatTaskBeliefState(state);
+  const sections = sectionRanges(markdown, BELIEF_HEADING);
+  if (sections.length > 1) {
+    throw new Error("Cannot replace duplicate Belief State sections.");
+  }
+  if (sections.length === 1) {
+    const section = sections[0];
+    const originalSection = markdown.slice(section.start, section.end);
+    const trailingWhitespace = originalSection.match(/\s*$/)?.[0] ?? "";
+    return markdown.slice(0, section.start) + replacement + trailingWhitespace + markdown.slice(section.end);
+  }
+
+  const acceptance = sectionRanges(markdown, ACCEPTANCE_HEADING)[0];
+  const insertion = acceptance?.end ?? markdown.length;
+  const before = markdown.slice(0, insertion);
+  const after = markdown.slice(insertion);
+  const leadingBreaks = before.length === 0 ? "" : before.endsWith("\n\n") ? "" : before.endsWith("\n") ? "\n" : "\n\n";
+  const trailingBreaks = after.length === 0 ? "" : after.startsWith("\n") ? "\n" : "\n\n";
+  return before + leadingBreaks + replacement + trailingBreaks + after;
+}