@hienlh/ppm 0.19.3 → 0.19.5

package/src/services/proxy-agent-anthropic-bridge.ts

@@ -0,0 +1,104 @@
+/**
+ * Agent → Anthropic Messages, for `POST /proxy/<provider>/v1/messages`.
+ *
+ * The mirror of `proxy-agent-bridge.ts`: same agent turn (`proxy-agent-turn.ts`),
+ * same ephemeral-session and sandbox rules, rendered in Anthropic's dialect so a
+ * client already pointed at `ANTHROPIC_BASE_URL` can reach any PPM provider by
+ * setting that base to `…/proxy/<provider>`.
+ */
+import {
+  startAgentTurn, usageOf, resolveProvider, proxyableProviderIds,
+} from "./proxy-agent-turn.ts";
+import {
+  buildPromptFromAnthropicMessages, hasUnsupportedAnthropicBlocks, messageResponse, anthropicError,
+  MessageStreamWriter, ANTHROPIC_SSE_HEADERS, type AnthropicMessagesBody,
+} from "./proxy-anthropic-format.ts";
+
+/** Open the turn described by an Anthropic-format body. */
+function startTurn(providerId: string, body: AnthropicMessagesBody) {
+  const { prompt, systemPrompt } = buildPromptFromAnthropicMessages(body);
+  return startAgentTurn(providerId, { prompt, systemPrompt, model: body.model });
+}
+
+/** Non-streaming: drain the turn, return one `message`. */
+async function runNonStreaming(providerId: string, body: AnthropicMessagesBody): Promise<Response> {
+  const { events, cleanup } = await startTurn(providerId, body);
+  try {
+    let text = "";
+    let usage: ReturnType<typeof usageOf>;
+    for await (const ev of events) {
+      if (ev.type === "text") text += ev.content;
+      else if (ev.type === "error") throw new Error(ev.message);
+      // `done` ends the turn, but a provider's event stream stays open for the
+      // session's next turn and never returns. Without this break the request
+      // hangs on a completed answer until the idle timeout fires.
+      else if (ev.type === "done") { usage = usageOf(ev); break; }
+    }
+    return messageResponse(text, body.model || providerId, usage);
+  } finally {
+    await cleanup();
+  }
+}
+
+/** Streaming: map assistant text onto the Anthropic SSE event sequence. */
+async function runStreaming(providerId: string, body: AnthropicMessagesBody): Promise<Response> {
+  // Started before the stream so a setup failure is still a JSON error the
+  // client can read, rather than an SSE stream that opens and immediately dies.
+  const { events, cleanup } = await startTurn(providerId, body);
+  const model = body.model || providerId;
+
+  const readable = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const stream = new MessageStreamWriter(controller, model);
+      stream.open();
+      let usage: ReturnType<typeof usageOf>;
+      try {
+        for await (const ev of events) {
+          if (ev.type === "text") stream.text(ev.content);
+          else if (ev.type === "error") throw new Error(ev.message);
+          // See runNonStreaming: the stream outlives the turn, so `done` is the
+          // only signal that the answer is complete.
+          else if (ev.type === "done") { usage = usageOf(ev); break; }
+        }
+        stream.close(usage);
+      } catch (e) {
+        // The stream already carries a 200, so the error has to ride inside it.
+        stream.text(`\n\nError: ${(e as Error).message}`);
+        stream.close(usage);
+      } finally {
+        await cleanup();
+      }
+    },
+    async cancel() {
+      await cleanup();
+    },
+  });
+
+  return new Response(readable, { headers: ANTHROPIC_SSE_HEADERS });
+}
+
+/**
+ * Entry point for `POST /proxy/<provider>/v1/messages`.
+ * Never throws: every failure becomes an Anthropic-shaped error response.
+ */
+export async function forwardAgentMessages(
+  providerId: string,
+  body: AnthropicMessagesBody,
+): Promise<Response> {
+  if (!resolveProvider(providerId)) {
+    return anthropicError(404, `Unknown provider "${providerId}". Available: ${proxyableProviderIds().join(", ") || "none"}`);
+  }
+  // Silently dropping an image would answer the prompt as if the picture had
+  // been seen — worse than refusing, because the caller cannot tell. Images in
+  // this dialect are not staged yet; the OpenAI endpoint is the one to use.
+  if (hasUnsupportedAnthropicBlocks(body)) {
+    return anthropicError(400, "This endpoint accepts text content blocks only; send images to /v1/chat/completions or /v1/images/edits");
+  }
+  try {
+    return body.stream
+      ? await runStreaming(providerId, body)
+      : await runNonStreaming(providerId, body);
+  } catch (e) {
+    return anthropicError(502, (e as Error).message);
+  }
+}

package/src/services/proxy-agent-bridge.ts

@@ -0,0 +1,147 @@
+/**
+ * Agent → OpenAI Chat Completions, for `POST /proxy/<provider>/v1/chat/completions`.
+ *
+ * An OpenAI client points its `baseURL` at `…/proxy/codex/v1`; the provider comes
+ * from the URL and the model from the request body. Session lifetime, sandboxing
+ * and timeouts live in `proxy-agent-turn.ts`, shared with the Anthropic-format
+ * endpoint so the two cannot drift apart.
+ *
+ * Unlike the Claude-only bridge (`proxy-openai-bridge.ts`, a single SDK query),
+ * this drives a real agent session: a turn may run the provider's own tools
+ * before answering. Tool traffic has no place in the OpenAI wire format, so only
+ * assistant text reaches the caller.
+ */
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  startAgentTurn, usageOf, resolveProvider, proxyableProviderIds,
+} from "./proxy-agent-turn.ts";
+import { decodeImagePayload } from "./proxy-image-bridge.ts";
+import {
+  buildPromptFromOpenAiMessages, hasUnsupportedBlocks, extractImagePayloads,
+  completionResponse, openAiError,
+  ChunkWriter, SSE_HEADERS, type OpenAiChatBody,
+} from "./proxy-openai-format.ts";
+
+/**
+ * Inline images written to a scratch directory, since a provider may take an
+ * image only as a path. Returns the paths plus the cleanup that removes them.
+ */
+function stageImages(body: OpenAiChatBody): { paths: string[]; discard: () => void } {
+  const { dataUrls } = extractImagePayloads(body);
+  if (dataUrls.length === 0) return { paths: [], discard: () => {} };
+  const dir = mkdtempSync(join(tmpdir(), "ppm-chat-img-"));
+  const paths = dataUrls.map((url, i) => {
+    const { bytes, ext } = decodeImagePayload(url);
+    const path = join(dir, `image-${i}${ext}`);
+    writeFileSync(path, bytes);
+    return path;
+  });
+  return { paths, discard: () => { try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } } };
+}
+
+/** Open the turn described by an OpenAI-format body. */
+async function startTurn(providerId: string, body: OpenAiChatBody) {
+  const { prompt, systemPrompt } = buildPromptFromOpenAiMessages(body);
+  const staged = stageImages(body);
+  try {
+    const run = await startAgentTurn(providerId, {
+      prompt, systemPrompt, model: body.model, imagePaths: staged.paths,
+    });
+    // The agent reads the files during the turn, so they outlive startTurn and
+    // are dropped alongside the session.
+    return { ...run, cleanup: async () => { await run.cleanup(); staged.discard(); } };
+  } catch (e) {
+    staged.discard();
+    throw e;
+  }
+}
+
+/** Non-streaming: drain the turn, return one `chat.completion`. */
+async function runNonStreaming(providerId: string, body: OpenAiChatBody): Promise<Response> {
+  const { events, cleanup } = await startTurn(providerId, body);
+  try {
+    let content = "";
+    let usage: ReturnType<typeof usageOf>;
+    for await (const ev of events) {
+      if (ev.type === "text") content += ev.content;
+      else if (ev.type === "error") throw new Error(ev.message);
+      // `done` ends the turn, but a provider's event stream stays open for the
+      // session's next turn and never returns. Without this break the request
+      // hangs on a completed answer until the idle timeout fires.
+      else if (ev.type === "done") { usage = usageOf(ev); break; }
+    }
+    return completionResponse(content, body.model || providerId, usage && {
+      promptTokens: usage.inputTokens, completionTokens: usage.outputTokens,
+    });
+  } finally {
+    await cleanup();
+  }
+}
+
+/** Streaming: map assistant text onto `chat.completion.chunk` frames. */
+async function runStreaming(providerId: string, body: OpenAiChatBody): Promise<Response> {
+  // Started before the stream so a setup failure is still a JSON error the
+  // client can read, rather than an SSE stream that opens and immediately dies.
+  const { events, cleanup } = await startTurn(providerId, body);
+  const model = body.model || providerId;
+
+  const readable = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const chunks = new ChunkWriter(controller, model);
+      chunks.open();
+      try {
+        for await (const ev of events) {
+          if (ev.type === "text") chunks.text(ev.content);
+          else if (ev.type === "error") throw new Error(ev.message);
+          // See runNonStreaming: the stream outlives the turn, so `done` is the
+          // only signal that the answer is complete.
+          else if (ev.type === "done") break;
+        }
+        chunks.close();
+      } catch (e) {
+        // The stream already carries a 200, so the error has to ride inside it.
+        chunks.text(`\n\nError: ${(e as Error).message}`);
+        chunks.close();
+      } finally {
+        await cleanup();
+      }
+    },
+    async cancel() {
+      await cleanup();
+    },
+  });
+
+  return new Response(readable, { headers: SSE_HEADERS });
+}
+
+/**
+ * Entry point for `POST /proxy/<provider>/v1/chat/completions`.
+ * Never throws: every failure becomes an OpenAI-shaped error response.
+ */
+export async function forwardAgentChatCompletions(
+  providerId: string,
+  body: OpenAiChatBody,
+): Promise<Response> {
+  if (!resolveProvider(providerId)) {
+    return openAiError(404, `Unknown provider "${providerId}". Available: ${proxyableProviderIds().join(", ") || "none"}`);
+  }
+  // Silently dropping a block would answer the prompt as if it had been seen —
+  // worse than refusing, because the caller cannot tell.
+  if (hasUnsupportedBlocks(body)) {
+    return openAiError(400, "Only text and image_url content blocks are supported");
+  }
+  if (extractImagePayloads(body).remoteUrls > 0) {
+    return openAiError(400, "image_url must be a data: URL; remote URLs are not fetched");
+  }
+  try {
+    return body.stream
+      ? await runStreaming(providerId, body)
+      : await runNonStreaming(providerId, body);
+  } catch (e) {
+    return openAiError(502, (e as Error).message);
+  }
+}
+
+export { listProviderModels } from "./proxy-agent-turn.ts";

package/src/services/proxy-agent-turn.ts

@@ -0,0 +1,172 @@
+/**
+ * Running one agent turn for the provider-scoped proxy, independent of which
+ * API format the caller speaks.
+ *
+ * `/proxy/<provider>/v1/messages` (Anthropic) and
+ * `/proxy/<provider>/v1/chat/completions` (OpenAI) are two wire formats over
+ * this same machinery, so session lifetime, sandboxing and timeouts are decided
+ * here once rather than twice.
+ *
+ * Sessions are ephemeral: one per request, deleted afterwards. An API call must
+ * not leave a conversation behind in the sidebar, and an OpenAI or Anthropic
+ * client replays its whole conversation on every call, so a reused session would
+ * stack that history on itself.
+ */
+import { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { providerRegistry } from "../providers/registry.ts";
+import { getPpmDir } from "./ppm-dir.ts";
+import type { AIProvider, ChatEvent } from "../types/chat.ts";
+
+/**
+ * Read-only, no prompts. An agent reachable with the proxy key must not be able
+ * to write or run anything on the host, so the caller cannot raise this.
+ */
+const PROXY_PERMISSION_MODE = "plan";
+
+/**
+ * Two deadlines, because the two failures look nothing alike. A provider whose
+ * backend rejects the turn can report the failure on its subprocess stderr and
+ * emit no event at all, so the request would otherwise sit at full idle length
+ * waiting for a stream that will never start. Once text is flowing, a long gap
+ * is just the agent working and must not be cut short.
+ */
+const FIRST_EVENT_TIMEOUT_MS = 90_000;
+const IDLE_TIMEOUT_MS = 300_000;
+
+/** Providers that exist in the registry but must never be exposed over HTTP. */
+const NOT_PROXYABLE = new Set(["mock"]);
+
+/** Resolve a provider the proxy is allowed to expose, or null. */
+export function resolveProvider(providerId: string): AIProvider | null {
+  if (NOT_PROXYABLE.has(providerId)) return null;
+  return providerRegistry.get(providerId) ?? null;
+}
+
+/** Proxyable provider ids, for an error that tells the caller what does work. */
+export function proxyableProviderIds(): string[] {
+  return providerRegistry.listAll().map((p) => p.id).filter((id) => !NOT_PROXYABLE.has(id));
+}
+
+/**
+ * Empty scratch workspace. Agents need a cwd; giving every proxy turn the same
+ * empty directory keeps them away from real projects on this host.
+ */
+function proxyWorkspace(): string {
+  const dir = resolve(getPpmDir(), "proxy-agent-workspace");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Stop iterating if the agent goes quiet — a hung turn must not pin the request. */
+async function* withTimeout(events: AsyncIterable<ChatEvent>): AsyncIterable<ChatEvent> {
+  const iterator = events[Symbol.asyncIterator]();
+  let started = false;
+  for (;;) {
+    const ms = started ? IDLE_TIMEOUT_MS : FIRST_EVENT_TIMEOUT_MS;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<"timeout">((r) => { timer = setTimeout(() => r("timeout"), ms); });
+    try {
+      const next = await Promise.race([iterator.next(), timeout]);
+      if (next === "timeout") {
+        await iterator.return?.(undefined);
+        throw new Error(started
+          ? `Agent stalled for ${Math.round(ms / 1000)}s mid-answer`
+          : `Agent produced no output within ${Math.round(ms / 1000)}s — check the provider's account is still signed in`);
+      }
+      if (next.done) return;
+      started = true;
+      yield next.value;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** Token counts a provider reported on `done`, in the shape both formats need. */
+export interface TurnUsageCounts {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export function usageOf(ev: Extract<ChatEvent, { type: "done" }>): TurnUsageCounts | undefined {
+  const u = ev.usage;
+  if (!u) return undefined;
+  // The whole replayed prefix counts as input, cached portions included.
+  return {
+    inputTokens: u.inputTokens + u.cacheReadTokens + u.cacheWriteTokens,
+    outputTokens: u.outputTokens,
+  };
+}
+
+export interface TurnRequest {
+  /** Conversation flattened to a single prompt. */
+  prompt: string;
+  /** Leading instructions, if the caller sent any. */
+  systemPrompt?: string;
+  /** Model name passed straight to the provider. */
+  model?: string;
+  /**
+   * Local files holding the request's images. Codex takes an image as a path
+   * and has no base64 form, so an inline attachment reaches the agent only
+   * after the caller has written it to disk.
+   */
+  imagePaths?: string[];
+}
+
+export interface TurnRun {
+  events: AsyncIterable<ChatEvent>;
+  /** Deletes the ephemeral session. Callers must run it on every path. */
+  cleanup: () => Promise<void>;
+}
+
+/**
+ * Open an ephemeral session and start one turn. Throws if the provider is not
+ * proxyable or the request carries nothing to answer.
+ */
+export async function startAgentTurn(providerId: string, req: TurnRequest): Promise<TurnRun> {
+  const provider = resolveProvider(providerId);
+  if (!provider) throw new Error(`Unknown provider "${providerId}"`);
+  if (!req.prompt.trim()) throw new Error("messages must contain at least one non-system message");
+
+  // No provider-level system-prompt field survives the flattening, so the
+  // instructions lead the turn instead.
+  const message = req.systemPrompt ? `${req.systemPrompt}\n\n${req.prompt}` : req.prompt;
+
+  const session = await provider.createSession({
+    projectPath: proxyWorkspace(),
+    title: `[API] ${providerId}`,
+  });
+
+  const events = provider.sendMessage(session.id, message, {
+    permissionMode: PROXY_PERMISSION_MODE,
+    ...(req.model ? { model: req.model } : {}),
+    ...(req.imagePaths?.length ? { imagePaths: req.imagePaths } : {}),
+  });
+
+  return {
+    events: withTimeout(events),
+    cleanup: async () => {
+      // abortQuery is what kills the runtime; deleteSession alone may only drop
+      // the record, depending on the provider.
+      try { provider.abortQuery?.(session.id, "proxy"); } catch { /* best effort */ }
+      try { await provider.deleteSession(session.id); } catch { /* best effort */ }
+    },
+  };
+}
+
+/** `<provider>/v1/models` in OpenAI's list shape, so clients can discover models. */
+export async function listProviderModels(providerId: string): Promise<Response> {
+  const provider = resolveProvider(providerId);
+  if (!provider) {
+    return new Response(
+      JSON.stringify({ error: { message: `Unknown provider "${providerId}"`, type: "server_error", code: "404" } }),
+      { status: 404, headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" } },
+    );
+  }
+  const models = provider.listModels ? await provider.listModels() : [];
+  return new Response(JSON.stringify({
+    object: "list",
+    data: models.map((m) => ({ id: m.value, object: "model", owned_by: providerId })),
+  }), { status: 200, headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" } });
+}

package/src/services/proxy-anthropic-format.ts

@@ -0,0 +1,157 @@
+/**
+ * Anthropic Messages API wire format for the provider-scoped proxy.
+ *
+ * The mirror of `proxy-openai-format.ts`: same job, the other dialect, so
+ * `/proxy/<provider>/v1/messages` and `/proxy/<provider>/v1/chat/completions`
+ * expose the same agent through whichever SDK the caller already uses.
+ */
+
+/** One entry of the Anthropic `messages` array. */
+export interface AnthropicMessage {
+  role?: string;
+  content?: string | Array<{ type?: string; text?: string }> | null;
+}
+
+export interface AnthropicMessagesBody {
+  model?: string;
+  messages?: AnthropicMessage[];
+  /** Anthropic carries instructions top-level, not as a message role. */
+  system?: string | Array<{ type?: string; text?: string }>;
+  stream?: boolean;
+}
+
+/** Concatenate the text blocks of a content field, ignoring everything else. */
+function textOf(content: AnthropicMessage["content"] | AnthropicMessagesBody["system"]): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n");
+  }
+  return "";
+}
+
+/**
+ * Flatten an Anthropic request into a single prompt plus its system text.
+ *
+ * Non-text blocks (notably `image`) are dropped: the agent turn has no way to
+ * carry an inline image today.
+ */
+export function buildPromptFromAnthropicMessages(
+  body: AnthropicMessagesBody,
+): { prompt: string; systemPrompt?: string } {
+  const parts = (body.messages ?? []).map((m) => {
+    const role = m.role === "assistant" ? "Assistant" : "Human";
+    return `${role}: ${textOf(m.content)}`;
+  });
+  const systemPrompt = textOf(body.system) || undefined;
+  return { prompt: parts.join("\n\n"), systemPrompt };
+}
+
+/** True when any message carries a content block this format cannot forward. */
+export function hasUnsupportedAnthropicBlocks(body: AnthropicMessagesBody): boolean {
+  return (body.messages ?? []).some((m) =>
+    Array.isArray(m.content) && m.content.some((b) => b.type && b.type !== "text"),
+  );
+}
+
+const JSON_HEADERS = {
+  "Content-Type": "application/json",
+  "Access-Control-Allow-Origin": "*",
+} as const;
+
+export const ANTHROPIC_SSE_HEADERS = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache",
+  "Connection": "keep-alive",
+  "Access-Control-Allow-Origin": "*",
+} as const;
+
+/** Anthropic errors are `{type:"error", error:{type, message}}`, not OpenAI's shape. */
+export function anthropicError(status: number, message: string): Response {
+  const type = status === 404 ? "not_found_error" : status === 400 ? "invalid_request_error" : "api_error";
+  return new Response(
+    JSON.stringify({ type: "error", error: { type, message } }),
+    { status, headers: JSON_HEADERS },
+  );
+}
+
+export interface AnthropicUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+function messageId(): string {
+  return `msg_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** Build a non-streaming Messages response. */
+export function messageResponse(text: string, model: string, usage?: AnthropicUsage): Response {
+  return new Response(JSON.stringify({
+    id: messageId(),
+    type: "message",
+    role: "assistant",
+    model,
+    content: [{ type: "text", text }],
+    stop_reason: "end_turn",
+    stop_sequence: null,
+    usage: {
+      input_tokens: usage?.inputTokens ?? 0,
+      output_tokens: usage?.outputTokens ?? 0,
+    },
+  }), { status: 200, headers: JSON_HEADERS });
+}
+
+/**
+ * Emits the Anthropic streaming event sequence for one response.
+ *
+ * Anthropic SSE is named-event based (`event:` line plus `data:`), and clients
+ * reject a stream that skips the message_start / content_block_* / message_stop
+ * envelope — so the envelope is written even when no text arrives.
+ */
+export class MessageStreamWriter {
+  private readonly encoder = new TextEncoder();
+  private readonly id = messageId();
+  private outputTokens = 0;
+
+  constructor(
+    private readonly controller: ReadableStreamDefaultController<Uint8Array>,
+    private readonly model: string,
+  ) {}
+
+  private emit(event: string, data: Record<string, unknown>): void {
+    this.controller.enqueue(this.encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+  }
+
+  /** message_start + the single text block every response here uses. */
+  open(inputTokens = 0): void {
+    this.emit("message_start", {
+      type: "message_start",
+      message: {
+        id: this.id, type: "message", role: "assistant", model: this.model,
+        content: [], stop_reason: null, stop_sequence: null,
+        usage: { input_tokens: inputTokens, output_tokens: 0 },
+      },
+    });
+    this.emit("content_block_start", {
+      type: "content_block_start", index: 0, content_block: { type: "text", text: "" },
+    });
+  }
+
+  text(content: string): void {
+    if (!content) return;
+    this.emit("content_block_delta", {
+      type: "content_block_delta", index: 0, delta: { type: "text_delta", text: content },
+    });
+  }
+
+  /** Close the block and the message. `usage` reports what the turn actually cost. */
+  close(usage?: AnthropicUsage, stopReason = "end_turn"): void {
+    this.emit("content_block_stop", { type: "content_block_stop", index: 0 });
+    this.emit("message_delta", {
+      type: "message_delta",
+      delta: { stop_reason: stopReason, stop_sequence: null },
+      usage: { output_tokens: usage?.outputTokens ?? this.outputTokens },
+    });
+    this.emit("message_stop", { type: "message_stop" });
+    this.controller.close();
+  }
+}