@hienlh/ppm 0.19.2 → 0.19.4

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

@@ -0,0 +1,161 @@
+/**
+ * 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.
+ */
+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;
+}
+
+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 } : {}),
+  });
+
+  return {
+    events: withTimeout(events),
+    cleanup: async () => {
+      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();
+  }
+}

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

@@ -0,0 +1,148 @@
+/**
+ * OpenAI Chat Completions wire format — the shared translation layer between
+ * PPM's proxy bridges and the shape an OpenAI client expects.
+ *
+ * Both proxy bridges speak this: the Claude SDK bridge (`proxy-openai-bridge.ts`)
+ * and the provider-agnostic agent bridge (`proxy-agent-bridge.ts`). Keeping the
+ * wire format in one place is what stops the two from drifting into subtly
+ * different `chat.completion` payloads.
+ */
+
+/** One entry of the OpenAI `messages` array (content is string or block array). */
+export interface OpenAiMessage {
+  role?: string;
+  content?: string | Array<{ type?: string; text?: string }> | null;
+}
+
+export interface OpenAiChatBody {
+  model?: string;
+  messages?: OpenAiMessage[];
+  stream?: boolean;
+}
+
+/**
+ * Flatten OpenAI `messages` into a single prompt plus a system prompt.
+ *
+ * Non-text blocks (notably `image_url`) are dropped: neither bridge can carry
+ * an inline image today. Callers that must not silently lose an attachment
+ * should check `hasUnsupportedBlocks` first.
+ */
+export function buildPromptFromOpenAiMessages(
+  body: OpenAiChatBody,
+): { prompt: string; systemPrompt?: string } {
+  const messages = body.messages ?? [];
+  let systemPrompt: string | undefined;
+  const conversationParts: string[] = [];
+
+  for (const m of messages) {
+    const text = typeof m.content === "string"
+      ? m.content
+      : Array.isArray(m.content)
+        ? m.content.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n")
+        : String(m.content ?? "");
+
+    if (m.role === "system") {
+      systemPrompt = systemPrompt ? `${systemPrompt}\n${text}` : text;
+    } else {
+      const role = m.role === "assistant" ? "Assistant" : "Human";
+      conversationParts.push(`${role}: ${text}`);
+    }
+  }
+
+  return { prompt: conversationParts.join("\n\n"), systemPrompt };
+}
+
+/** True when any message carries a content block this format cannot forward. */
+export function hasUnsupportedBlocks(body: OpenAiChatBody): 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 SSE_HEADERS = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache",
+  "Connection": "keep-alive",
+  "Access-Control-Allow-Origin": "*",
+} as const;
+
+export function openAiError(status: number, message: string): Response {
+  return new Response(
+    JSON.stringify({ error: { message, type: "server_error", code: String(status) } }),
+    { status, headers: JSON_HEADERS },
+  );
+}
+
+/** Token counts for the `usage` object; omitted fields report as 0. */
+export interface OpenAiUsage {
+  promptTokens?: number;
+  completionTokens?: number;
+}
+
+/** Build a non-streaming `chat.completion` response. */
+export function completionResponse(
+  content: string,
+  model: string,
+  usage?: OpenAiUsage,
+): Response {
+  const promptTokens = usage?.promptTokens ?? 0;
+  const completionTokens = usage?.completionTokens ?? 0;
+  return new Response(JSON.stringify({
+    id: `chatcmpl-${Date.now()}`,
+    object: "chat.completion",
+    created: Math.floor(Date.now() / 1000),
+    model,
+    choices: [{
+      index: 0,
+      message: { role: "assistant", content },
+      finish_reason: "stop",
+    }],
+    usage: {
+      prompt_tokens: promptTokens,
+      completion_tokens: completionTokens,
+      total_tokens: promptTokens + completionTokens,
+    },
+  }), { status: 200, headers: JSON_HEADERS });
+}
+
+/** Emits `chat.completion.chunk` frames for one streamed response. */
+export class ChunkWriter {
+  private readonly encoder = new TextEncoder();
+  private readonly id = `chatcmpl-${Date.now()}`;
+  private readonly created = Math.floor(Date.now() / 1000);
+
+  constructor(
+    private readonly controller: ReadableStreamDefaultController<Uint8Array>,
+    private readonly model: string,
+  ) {}
+
+  /** One SSE frame carrying a delta (and optionally the finish reason). */
+  send(delta: Record<string, unknown>, finishReason: string | null = null): void {
+    const payload = {
+      id: this.id, object: "chat.completion.chunk", created: this.created, model: this.model,
+      choices: [{ index: 0, delta, finish_reason: finishReason }],
+    };
+    this.controller.enqueue(this.encoder.encode(`data: ${JSON.stringify(payload)}\n\n`));
+  }
+
+  /** OpenAI clients treat the role-only first chunk as the start of the message. */
+  open(): void {
+    this.send({ role: "assistant", content: "" });
+  }
+
+  text(content: string): void {
+    if (content) this.send({ content });
+  }
+
+  /** Terminal frame plus the `[DONE]` sentinel every OpenAI client waits for. */
+  close(finishReason = "stop"): void {
+    this.send({}, finishReason);
+    this.controller.enqueue(this.encoder.encode("data: [DONE]\n\n"));
+    this.controller.close();
+  }
+}

package/src/services/slash-discovery/builtin-commands.ts

@@ -42,6 +42,19 @@ export function getBuiltinSlashItems(): SlashItem[] {
   }));
 }
 
+/**
+ * Built-ins that work no matter which provider the tab is on.
+ *
+ * `handler: "sdk"` commands (`/compact`, `/cost`, `/model`, …) are passed
+ * straight through to the Claude SDK, so they do nothing in a session driven by
+ * another runtime. The `ppm` and `client` ones are intercepted before any
+ * provider sees them — by the PPM server and the web UI respectively — so they
+ * belong in every picker.
+ */
+export function getHostBuiltinSlashItems(): SlashItem[] {
+  return getBuiltinSlashItems().filter((item) => item.handler !== "sdk");
+}
+
 /** Look up a builtin command by name (or alias) */
 export function getBuiltinByName(name: string): BuiltinSlashCommand | undefined {
   const lower = name.toLowerCase();

package/src/services/slash-discovery/codex-skill-items.ts

@@ -0,0 +1,57 @@
+import { readFileSync, statSync } from "node:fs";
+import { extname } from "node:path";
+import type { CodexSkill } from "../../providers/codex-app-server/codex-protocol.ts";
+import type { SlashItem } from "./types.ts";
+
+/** Icons above this are not worth inlining into every picker response. */
+const MAX_ICON_BYTES = 32 * 1024;
+
+const ICON_MIME: Record<string, string> = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+};
+
+/**
+ * Map the skills codex reported for a session into picker items.
+ *
+ * These are deliberately NOT merged with the disk-discovered Claude-side list.
+ * A codex session cannot run a Claude skill and vice versa, so mixing them
+ * offers the user entries that do nothing.
+ *
+ * Every item is marked `$`: codex activates a skill from a `$name` mention in
+ * the prompt, not from a leading slash.
+ */
+export function codexSkillsToSlashItems(skills: CodexSkill[]): SlashItem[] {
+  return skills.map((s) => ({
+    type: "skill" as const,
+    name: s.name,
+    description: s.interface?.shortDescription || s.description || "",
+    // "system" is codex's own bundled set; anything else the user put there.
+    scope: s.scope === "system" ? ("bundled" as const) : ("user" as const),
+    invokeSigil: "$" as const,
+    displayName: s.interface?.displayName,
+    iconDataUri: readIconDataUri(s.interface?.iconSmall),
+  }));
+}
+
+/**
+ * Read a skill icon into a data URI, or return undefined for anything that is
+ * missing, oversized, or of an unknown type.
+ *
+ * Never throws: a skill with a broken icon path still belongs in the picker,
+ * just without a picture.
+ */
+function readIconDataUri(path: string | undefined): string | undefined {
+  if (!path) return undefined;
+  const mime = ICON_MIME[extname(path).toLowerCase()];
+  if (!mime) return undefined;
+  try {
+    if (statSync(path).size > MAX_ICON_BYTES) return undefined;
+    return `data:${mime};base64,${readFileSync(path).toString("base64")}`;
+  } catch {
+    return undefined;
+  }
+}

package/src/services/slash-discovery/provider-skill-sigil.ts

@@ -0,0 +1,19 @@
+/**
+ * Swap the leading `/` of a typed command for the sigil the target runtime
+ * actually recognises.
+ *
+ * PPM's picker is slash-driven everywhere, but a provider may resolve its own
+ * skills differently — codex activates one from a `$name` mention in the prompt
+ * and treats `/name` as ordinary text, so a picked skill would appear to be
+ * ignored. Only the sigil changes; arguments after the name are untouched.
+ *
+ * The rewrite is deliberately conservative: the first word must match a skill
+ * the runtime reported, so a slash command the runtime does not own (a PPM
+ * built-in, a typo, a bare `/`) is returned exactly as typed.
+ */
+export function applySkillSigil(content: string, skillNames: Set<string>, sigil: string): string {
+  const match = content.match(/^\/(\S+)/);
+  const name = match?.[1];
+  if (!name || !skillNames.has(name)) return content;
+  return sigil + content.slice(1);
+}

package/src/services/slash-discovery/types.ts

@@ -35,6 +35,25 @@ export interface SlashItem {
   tools?: string[];
   /** Built-in only: which layer executes the command */
   handler?: SlashHandler;
+  /**
+   * Sigil the runtime expects when the item is invoked. Absent means `/`, which
+   * is every Claude-side skill and command. Codex resolves its skills from a
+   * `$name` mention inside the prompt instead, so an item carrying `"$"` must be
+   * sent with that prefix or codex treats it as ordinary prose.
+   */
+  invokeSigil?: "/" | "$";
+  /** Pretty label the runtime supplies for itself, when it does (codex system skills). */
+  displayName?: string;
+  /**
+   * Runtime-supplied icon, inlined as a data URI rather than a URL.
+   *
+   * The source files sit inside the codex account home, which the credential
+   * path guard refuses on every generic file route — correctly, since
+   * `auth.json` is a sibling. Inlining keeps that door shut: the icon never
+   * needs a servable path, and the client never sends one back. They are small
+   * enough for this to be cheap (under 3 KB each).
+   */
+  iconDataUri?: string;
 }
 
 export interface SkillRoot {