@finalai/agent-provider 0.1.0

package/dist/modules/conformance/agent.mjs

@@ -0,0 +1,623 @@
+import {
+  agent,
+  methods,
+  PROTOCOL_VERSION,
+  RequestError
+} from "@agentclientprotocol/sdk/experimental/v2";
+import {
+  RESOURCE_LINK_DESCRIPTION_BYTES,
+  utf8Prefix
+} from "@finalai/acp-session";
+import {
+  Client,
+  StreamableHTTPClientTransport
+} from "@modelcontextprotocol/client";
+import * as z from "zod";
+import { PromptWhileRunning } from "../harness.mjs";
+import { jsonValueSchema } from "../json.mjs";
+import { conformanceImageBase64 } from "./image.mjs";
+import {
+  AFTER_SEQ_REPLAY_TYPE,
+  ConformanceDirective,
+  FINAL_META_KEY,
+  OBSERVE_METHOD,
+  parseDirective
+} from "./protocol.mjs";
+const observeParamsSchema = z.object({
+  sessionId: z.string(),
+  content: z.array(z.object({ type: z.string(), text: z.string().optional() }).passthrough())
+});
+const textOf = (content) => content.map((block) => textBlockSchema.safeParse(block).data?.text ?? "").join("");
+const authorMetaSchema = z.object({
+  _meta: z.object({
+    [FINAL_META_KEY]: z.object({ author: z.object({ displayName: z.string().min(1) }) })
+  })
+});
+const directiveTextOf = (content, text) => {
+  const author = content.map((block) => authorMetaSchema.safeParse(block).data?._meta[FINAL_META_KEY].author).find((entry) => entry != null);
+  const trimmed = text.trimStart();
+  if (author != null && trimmed.startsWith(`${author.displayName}: `))
+    return trimmed.slice(author.displayName.length + 2);
+  const prefixed = /^[^\n]+?: (conformance:[\s\S]*)$/u.exec(trimmed);
+  return prefixed?.[1] ?? text;
+};
+const randomId = () => crypto.randomUUID();
+const delay = (ms, signal) => new Promise((resolve) => {
+  if (signal.aborted) {
+    resolve();
+    return;
+  }
+  const timer = setTimeout(resolve, ms);
+  signal.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(timer);
+      resolve();
+    },
+    { once: true }
+  );
+});
+const toolResultSchema = z.object({
+  content: z.array(z.object({ type: z.string(), text: z.string().optional() }))
+});
+const mcpResultText = (parsed) => parsed.success ? parsed.data.content.map((block) => block.text ?? "").join("") : "unreadable tool result";
+const textBlockSchema = z.object({ type: z.literal("text"), text: z.string() });
+const acpServerSchema = z.object({
+  type: z.literal("acp"),
+  name: z.string(),
+  serverId: z.string()
+});
+const httpServerSchema = z.object({
+  type: z.literal("http"),
+  name: z.string(),
+  url: z.string(),
+  headers: z.array(z.object({ name: z.string(), value: z.string() })).optional()
+});
+const namedServerSchema = z.object({ name: z.string() });
+const afterSeqSchema = z.object({ seq: z.number().int().nonnegative() });
+const permissionResultSchema = z.object({
+  outcome: z.union([
+    z.object({ outcome: z.literal("selected"), optionId: z.string() }),
+    z.object({ outcome: z.literal("cancelled") })
+  ])
+});
+const elicitationResultSchema = z.object({
+  action: z.string(),
+  content: z.record(z.string(), z.unknown()).optional()
+});
+const rawRequestSchema = z.object({ id: z.union([z.string(), z.number()]), method: z.string() });
+const rawResponseSchema = z.object({
+  id: z.union([z.string(), z.number()]),
+  result: jsonValueSchema
+});
+const rawErrorSchema = z.object({ id: z.union([z.string(), z.number()]), error: z.unknown() });
+const isBatch = (wire) => Array.isArray(wire);
+const isCall = (message) => "method" in message;
+const isResponse = (message) => !("method" in message);
+const messagesOf = (wire) => isBatch(wire) ? wire : [wire];
+const memoryAttachments = () => {
+  let counter = 0;
+  return {
+    put: async () => {
+      counter += 1;
+      return { uri: `memory://conformance-attachments/${counter}` };
+    }
+  };
+};
+const cancelledAnswer = (method) => method === methods.client.session.requestPermission ? { outcome: { outcome: "cancelled" } } : { action: "cancel" };
+const LINK_SEPARATOR = "|";
+const createConformanceAgent = (options = {}) => {
+  const extensions = options.extensions ?? true;
+  const slowTurnMs = options.slowTurnMs ?? 3e4;
+  const inject = options.promptWhileRunning === PromptWhileRunning.Inject;
+  const survives = options.survivesDisconnect ?? false;
+  const attachments = options.attachments ?? memoryAttachments();
+  const sessions = /* @__PURE__ */ new Map();
+  const links = /* @__PURE__ */ new Map();
+  const linkOf = (requestId) => {
+    const parsed = z.string().safeParse(requestId);
+    if (!parsed.success) return null;
+    const separator = parsed.data.indexOf(LINK_SEPARATOR);
+    return separator < 0 ? null : links.get(parsed.data.slice(0, separator)) ?? null;
+  };
+  const getSession = (sessionId) => {
+    const session = sessions.get(sessionId);
+    if (session == null) throw RequestError.resourceNotFound(sessionId);
+    return session;
+  };
+  const attach = (session, client, requestId) => {
+    session.client = client;
+    session.link = linkOf(requestId) ?? session.link;
+  };
+  const emit = async (session, update, record = true) => {
+    if (record) session.history.push(update);
+    const sending = session.client.notify(methods.client.session.update, {
+      sessionId: session.id,
+      update
+    });
+    if (survives) await sending.catch(() => void 0);
+    else await sending;
+  };
+  const say = async (session, messageId, text) => {
+    const middle = Math.ceil(text.length / 2);
+    const parts = text.length > 1 ? [text.slice(0, middle), text.slice(middle)] : [text];
+    for (const part of parts) {
+      await emit(session, {
+        sessionUpdate: "agent_message_chunk",
+        messageId,
+        content: { type: "text", text: part }
+      });
+    }
+  };
+  const ask = async (session, method, params, viaSdk) => {
+    const current = session.link;
+    if (!survives || current == null) {
+      return current == null ? viaSdk().then((result) => jsonValueSchema.parse(result)) : Promise.race([
+        viaSdk().then((result) => jsonValueSchema.parse(result)),
+        current.gone.then(() => cancelledAnswer(method))
+      ]);
+    }
+    const id = `conformance-request-${randomId()}`;
+    const message = { jsonrpc: "2.0", id, method, params };
+    const answered = new Promise((resolve) => {
+      session.open.set(id, { method, message, resolve });
+    });
+    if (!current.closed) await current.write(message).catch(() => void 0);
+    try {
+      return await answered;
+    } finally {
+      session.open.delete(id);
+    }
+  };
+  const callMcp = async (session, rest) => {
+    const [serverName = "", toolName = "", ...argParts] = rest.split(" ");
+    const toolArgs = argParts.length === 0 ? {} : z.record(z.string(), z.json()).parse(JSON.parse(argParts.join(" ")));
+    const server = session.mcpServers.find(
+      (entry) => namedServerSchema.safeParse(entry).data?.name === serverName
+    );
+    if (server == null) throw new Error(`no MCP server named ${serverName}`);
+    const acp = acpServerSchema.safeParse(server);
+    const http = httpServerSchema.safeParse(server);
+    if (acp.success) {
+      const response = await session.client.request(methods.client.mcp.message, {
+        serverId: acp.data.serverId,
+        requestId: randomId(),
+        method: "tools/call",
+        params: { name: toolName, arguments: toolArgs }
+      });
+      if ("error" in response) throw new Error(response.error.message);
+      return mcpResultText(toolResultSchema.safeParse(response.result));
+    }
+    if (http.success) {
+      const headers = {};
+      for (const header of http.data.headers ?? []) headers[header.name] = header.value;
+      const client = new Client({ name: "final-conformance-agent", version: "1" });
+      await client.connect(
+        new StreamableHTTPClientTransport(new URL(http.data.url), {
+          fetch: options.fetch,
+          requestInit: { headers }
+        })
+      );
+      try {
+        return mcpResultText(
+          toolResultSchema.safeParse(
+            await client.callTool({ name: toolName, arguments: toolArgs })
+          )
+        );
+      } finally {
+        await client.close();
+      }
+    }
+    throw new Error(`unsupported MCP server type ${server.type}`);
+  };
+  const linked = async (args) => {
+    const { uri } = await attachments.put(args);
+    const link = {
+      type: "resource_link",
+      uri,
+      name: args.name,
+      mimeType: args.mimeType,
+      size: args.bytes.length
+    };
+    if (args.text != null)
+      link.description = utf8Prefix(args.text, RESOURCE_LINK_DESCRIPTION_BYTES);
+    return link;
+  };
+  const runTurn = async (session, text, signal) => {
+    const messageId = randomId();
+    const parsed = parseDirective(text);
+    const endTurn = {
+      sessionUpdate: "state_update",
+      state: "idle",
+      stopReason: "end_turn"
+    };
+    const cancelled = {
+      sessionUpdate: "state_update",
+      state: "idle",
+      stopReason: "cancelled"
+    };
+    if (parsed == null) {
+      await say(session, messageId, `unknown directive: ${text}`);
+      return endTurn;
+    }
+    switch (parsed.name) {
+      case ConformanceDirective.Echo:
+        await say(session, messageId, parsed.rest);
+        return endTurn;
+      case ConformanceDirective.Permission: {
+        const params = {
+          sessionId: session.id,
+          title: "Conformance permission",
+          options: [
+            { optionId: "allow", name: "Allow once", kind: "allow_once" },
+            { optionId: "reject", name: "Reject", kind: "reject_once" }
+          ]
+        };
+        const response = permissionResultSchema.safeParse(
+          await ask(
+            session,
+            methods.client.session.requestPermission,
+            params,
+            () => session.client.request(methods.client.session.requestPermission, params)
+          )
+        );
+        const outcome = response.success ? response.data.outcome : { outcome: "cancelled" };
+        const kind = outcome.outcome === "selected" && "optionId" in outcome ? outcome.optionId === "allow" ? "allow_once" : "reject_once" : "cancelled";
+        await say(session, messageId, `permission:${kind}`);
+        return endTurn;
+      }
+      case ConformanceDirective.Elicit: {
+        const params = {
+          mode: "form",
+          sessionId: session.id,
+          message: "Conformance question",
+          requestedSchema: {
+            type: "object",
+            properties: { answer: { type: "string", title: "Answer" } },
+            required: ["answer"]
+          }
+        };
+        const response = elicitationResultSchema.safeParse(
+          await ask(
+            session,
+            methods.client.elicitation.create,
+            params,
+            () => session.client.request(methods.client.elicitation.create, params)
+          )
+        );
+        const action = response.success ? response.data.action : "cancel";
+        const answer = z.object({ answer: z.union([z.string(), z.number(), z.boolean()]) }).safeParse(response.data?.content);
+        await say(
+          session,
+          messageId,
+          `elicitation:${action}:${action === "accept" && answer.success ? String(answer.data.answer) : ""}`
+        );
+        return endTurn;
+      }
+      case ConformanceDirective.Slow:
+        await say(session, messageId, "slow:started");
+        await delay(slowTurnMs, signal);
+        return signal.aborted ? cancelled : endTurn;
+      case ConformanceDirective.Wait: {
+        await say(session, messageId, "wait:started");
+        await delay(Number.parseInt(parsed.rest, 10) || 500, signal);
+        if (signal.aborted) return cancelled;
+        await say(session, messageId, "wait:done");
+        return endTurn;
+      }
+      case ConformanceDirective.Clear:
+        session.nativeId = randomId();
+        session.transcript = [];
+        await say(session, messageId, "cleared");
+        return endTurn;
+      case ConformanceDirective.Big: {
+        const bytes = Number.parseInt(parsed.rest, 10) || 3 * 1024 * 1024;
+        const toolCallId = randomId();
+        const text2 = "x".repeat(bytes);
+        const image = conformanceImageBase64();
+        const encoder = new TextEncoder();
+        const blocks = extensions ? [
+          await linked({
+            bytes: encoder.encode(text2),
+            mimeType: "text/plain",
+            name: "output.txt",
+            text: text2
+          }),
+          await linked({
+            bytes: Uint8Array.from(atob(image), (char) => char.charCodeAt(0)),
+            mimeType: "image/png",
+            name: "image.png",
+            text: null
+          })
+        ] : [
+          { type: "text", text: text2 },
+          { type: "image", mimeType: "image/png", data: image }
+        ];
+        await emit(session, {
+          sessionUpdate: "tool_call_update",
+          toolCallId,
+          title: "Produce a large result",
+          kind: "read",
+          status: "in_progress"
+        });
+        await emit(session, {
+          sessionUpdate: "tool_call_update",
+          toolCallId,
+          status: "completed",
+          content: blocks.map((content) => ({ type: "content", content }))
+        });
+        await say(session, messageId, "big:done");
+        return endTurn;
+      }
+      case ConformanceDirective.Error: {
+        const error = { code: -32603, message: "conformance error" };
+        if (!extensions)
+          return { sessionUpdate: "state_update", state: "idle", stopReason: "error", error };
+        const providerError = {
+          code: "conformance_error",
+          message: "conformance error",
+          retryable: false
+        };
+        return {
+          sessionUpdate: "state_update",
+          state: "idle",
+          stopReason: "error",
+          error,
+          _meta: { [FINAL_META_KEY]: { providerError } }
+        };
+      }
+      case ConformanceDirective.Mcp: {
+        let reply;
+        try {
+          reply = `mcp:${await callMcp(session, parsed.rest)}`;
+        } catch (error) {
+          reply = `mcp-error:${error instanceof Error ? error.message : String(error)}`;
+        }
+        await say(session, messageId, reply);
+        return endTurn;
+      }
+      case ConformanceDirective.History:
+        await say(session, messageId, session.transcript.join("\n"));
+        return endTurn;
+    }
+  };
+  const echo = (session, prompt, userMessageId) => emit(session, {
+    sessionUpdate: "user_message",
+    messageId: userMessageId,
+    content: [...prompt]
+  });
+  const injectIntoTurn = (session, turn, prompt, userMessageId) => {
+    const text = textOf(prompt);
+    session.transcript.push(text);
+    const work = (async () => {
+      await echo(session, prompt, userMessageId);
+      await runTurn(session, directiveTextOf(prompt, text), turn.signal);
+    })().catch(() => void 0);
+    session.injected.push(work);
+  };
+  const startTurn = (session, prompt, userMessageId) => {
+    const text = textOf(prompt);
+    const cancels = session.cancels;
+    session.queue = session.queue.then(async () => {
+      if (session.cancels !== cancels) return;
+      session.transcript.push(text);
+      const controller = new AbortController();
+      session.turn = controller;
+      try {
+        await echo(session, prompt, userMessageId);
+        await emit(session, { sessionUpdate: "state_update", state: "running" });
+        const end = await runTurn(session, directiveTextOf(prompt, text), controller.signal).catch(
+          (cause) => ({
+            sessionUpdate: "state_update",
+            state: "idle",
+            stopReason: "error",
+            error: {
+              code: -32603,
+              message: cause instanceof Error ? cause.message : String(cause)
+            }
+          })
+        );
+        while (session.injected.length > 0) await Promise.all(session.injected.splice(0));
+        await emit(
+          session,
+          controller.signal.aborted && end.sessionUpdate === "state_update" ? { sessionUpdate: "state_update", state: "idle", stopReason: "cancelled" } : end
+        );
+      } catch {
+      } finally {
+        session.turn = null;
+      }
+    });
+  };
+  const cancelOpen = (session) => {
+    for (const request of session.open.values()) request.resolve(cancelledAnswer(request.method));
+  };
+  const app = agent({ name: "final-conformance-agent" }).onRequest(methods.agent.initialize, () => ({
+    protocolVersion: PROTOCOL_VERSION,
+    info: { name: "final-conformance-agent", version: "1" },
+    capabilities: extensions ? {
+      session: { mcp: { acp: {}, http: {} } },
+      _meta: {
+        [FINAL_META_KEY]: {
+          supports: { observe: true, authorMeta: false, afterSeqReplay: true },
+          privateMethods: options.privateMethods ?? []
+        }
+      }
+    } : { session: { mcp: { acp: {}, http: {} } } }
+  })).onRequest(methods.agent.session.new, ({ params, client, requestId }) => {
+    const id = randomId();
+    sessions.set(id, {
+      id,
+      nativeId: randomId(),
+      cwd: params.cwd,
+      mcpServers: params.mcpServers ?? [],
+      history: [],
+      transcript: [],
+      client,
+      link: linkOf(requestId),
+      turn: null,
+      queue: Promise.resolve(),
+      injected: [],
+      cancels: 0,
+      open: /* @__PURE__ */ new Map()
+    });
+    return { sessionId: id };
+  }).onRequest(methods.agent.session.resume, async ({ params, client, requestId }) => {
+    const session = getSession(params.sessionId);
+    attach(session, client, requestId);
+    session.cwd = params.cwd;
+    if (params.mcpServers != null) session.mcpServers = params.mcpServers;
+    const replayFrom = params.replayFrom;
+    let replay = [];
+    if (replayFrom?.type === "start") replay = [...session.history];
+    else if (extensions && replayFrom?.type === AFTER_SEQ_REPLAY_TYPE) {
+      const seq = afterSeqSchema.safeParse(replayFrom).data?.seq ?? 0;
+      replay = session.history.slice(Math.max(0, seq));
+    }
+    for (const update of replay) await emit(session, update, false);
+    const link = session.link;
+    if (link != null) {
+      for (const request of session.open.values()) {
+        await link.write(request.message).catch(() => void 0);
+      }
+    }
+    return {};
+  }).onRequest(methods.agent.session.prompt, ({ params, client, requestId }) => {
+    const session = getSession(params.sessionId);
+    attach(session, client, requestId);
+    const messageId = randomId();
+    setTimeout(() => {
+      const running = session.turn;
+      if (inject && running != null) injectIntoTurn(session, running, params.prompt, messageId);
+      else startTurn(session, params.prompt, messageId);
+    }, 0);
+    return { messageId };
+  }).onRequest(methods.agent.session.close, async ({ params }) => {
+    const session = sessions.get(params.sessionId);
+    if (session != null) {
+      session.cancels += 1;
+      session.turn?.abort();
+      cancelOpen(session);
+      await session.queue;
+    }
+    sessions.delete(params.sessionId);
+    return {};
+  }).onNotification(methods.agent.session.cancel, ({ params }) => {
+    const session = sessions.get(params.sessionId);
+    if (session == null) return;
+    session.cancels += 1;
+    session.turn?.abort();
+    cancelOpen(session);
+  });
+  for (const method of extensions ? options.privateMethods ?? [] : []) {
+    app.onNotification(method, z.unknown(), () => void 0);
+  }
+  if (extensions) {
+    app.onNotification(OBSERVE_METHOD, observeParamsSchema, ({ params }) => {
+      const session = sessions.get(params.sessionId);
+      if (session == null) return;
+      session.transcript.push(params.content.map((block) => block.text ?? "").join(""));
+    });
+  }
+  const openRequestOf = (id) => {
+    for (const session of sessions.values()) {
+      const request = session.open.get(String(id));
+      if (request != null) return request;
+    }
+    return null;
+  };
+  const connect = (stream) => {
+    const linkId = randomId();
+    const originals = /* @__PURE__ */ new Map();
+    const writer = stream.writable.getWriter();
+    let writing = Promise.resolve();
+    const write = (message) => {
+      writing = writing.then(() => writer.write(message));
+      return writing;
+    };
+    const gone = Promise.withResolvers();
+    const link = { id: linkId, write, closed: false, gone: gone.promise };
+    links.set(linkId, link);
+    const writable = new WritableStream({
+      write: async (wire) => {
+        const restored = messagesOf(wire).map((message) => {
+          if ("method" in message) return message;
+          const id = z.string().safeParse(message.id);
+          if (!id.success) return message;
+          const original = originals.get(id.data);
+          if (original === void 0) return message;
+          originals.delete(id.data);
+          return { ...message, id: original };
+        });
+        const [first, ...rest] = restored;
+        await write(
+          isBatch(wire) && first != null ? mergeBatch(first, rest, wire) : first ?? wire
+        );
+      },
+      close: () => writing.then(() => writer.close()),
+      abort: (reason) => writer.abort(reason)
+    });
+    const readable = stream.readable.pipeThrough(
+      new TransformStream({
+        transform: (wire, controller) => {
+          const passed = [];
+          for (const message of messagesOf(wire)) {
+            const answered = rawResponseSchema.safeParse(message);
+            const failed = rawErrorSchema.safeParse(message);
+            const id = answered.success ? answered.data.id : failed.success ? failed.data.id : null;
+            const open = id == null || "method" in message ? null : openRequestOf(id);
+            if (open != null) {
+              open.resolve(answered.success ? answered.data.result : null);
+              continue;
+            }
+            const request = rawRequestSchema.safeParse(message);
+            if (request.success && "method" in message && "id" in message) {
+              const scoped = `${linkId}${LINK_SEPARATOR}${JSON.stringify(request.data.id)}`;
+              originals.set(scoped, request.data.id);
+              passed.push({ ...message, id: scoped });
+              continue;
+            }
+            passed.push(message);
+          }
+          const [first, ...rest] = passed;
+          if (first == null) return;
+          controller.enqueue(isBatch(wire) ? mergeBatch(first, rest, wire) : first);
+        },
+        // The client hung up: the SDK connection may outlive it while its own
+        // requests are open.
+        flush: () => {
+          link.closed = true;
+          gone.resolve();
+        }
+      })
+    );
+    const connection = app.connect({ readable, writable });
+    void connection.closed.then(() => {
+      link.closed = true;
+      links.delete(linkId);
+      gone.resolve();
+    });
+    return connection;
+  };
+  return {
+    app,
+    connect,
+    sessions: () => [...sessions.keys()],
+    nativeId: (sessionId) => sessions.get(sessionId)?.nativeId ?? null
+  };
+};
+const mergeBatch = (first, rest, original) => {
+  const all = [first, ...rest];
+  const calls = all.filter(isCall);
+  const [firstCall, ...restCalls] = calls;
+  if (firstCall != null && calls.length === all.length) return [firstCall, ...restCalls];
+  const responses = all.filter(isResponse);
+  const [firstResponse, ...restResponses] = responses;
+  if (firstResponse != null && responses.length === all.length) {
+    return [firstResponse, ...restResponses];
+  }
+  return original;
+};
+export {
+  createConformanceAgent
+};
+//# sourceMappingURL=agent.mjs.map