@semanticist14/clco 0.1.0

package/src/translate.ts

@@ -0,0 +1,384 @@
+// Translation between the Anthropic Messages API (what Claude Code speaks)
+// and GitHub Copilot's OpenAI-style chat/completions API.
+//
+// Content classification lives in blocks.ts; wire types in wire.ts;
+// streaming response state lives in stream.ts.
+
+import type {
+  CacheControl,
+  AnthropicMessage,
+  AnthropicRequest,
+  OpenAITextPart,
+  OpenAIImagePart,
+  OpenAIMessage,
+  OpenAIRequest,
+  OpenAIUsage,
+  OpenAIChoice,
+  OpenAIResponse,
+  AnthropicContentBlock,
+  AnthropicResponse,
+} from "./wire"
+import {
+  type ImageBlock,
+  type ToolResultBlock,
+  type ToolUseBlock,
+  classifyContent,
+} from "./blocks"
+
+function marked(blocks: unknown): boolean {
+  return (
+    Array.isArray(blocks) &&
+    blocks.some(
+      (b) => b && typeof b === "object" && (b as CacheControl).cache_control,
+    )
+  )
+}
+
+// Copilot's OpenAI-compatible surface spells the prompt-cache marker
+// `copilot_cache_control` rather than the standard `cache_control`.
+const COPILOT_CACHE = { type: "ephemeral" } as const
+
+// Copilot declares the reasoning_effort values each model accepts in its
+// /models capabilities. Send the effort only when the model claims it —
+// anything else is dropped rather than risking a 400.
+export function effortFor(
+  payload: AnthropicRequest,
+  allowed: string[] | null | undefined,
+): string | undefined {
+  const effort = payload.output_config?.effort
+  if (!effort || !allowed || !allowed.includes(effort)) return undefined
+  return effort
+}
+
+// ---------------------------------------------------------------------------
+// Request direction: Anthropic -> OpenAI
+// ---------------------------------------------------------------------------
+
+// Ids clco advertised to Claude Code, mapped back to the upstream slug they
+// stand for. Populated from the live /models response after discovery, so the
+// table always matches what the picker actually offered. Kept here rather
+// than read from token.ts to avoid a cycle.
+let modelAliases = new Map<string, string>()
+
+export function setModelAliases(aliases: Map<string, string>): void {
+  modelAliases = aliases
+}
+
+// Copilot slugs are dot-form ("claude-sonnet-4.5"). Claude Code may echo back
+// an advertised alias, dash-form, a date suffix, or a bracket suffix like
+// [1m]; normalize all. The alias table wins over the pattern rules because it
+// is derived from the upstream's own list — the patterns are only a fallback
+// for ids discovery never saw (and they miss families like fable entirely).
+export function normalizeModel(model: string): string {
+  let m = model.replace(/\[[^\]]*\]$/, "")
+  m = m.replace(/-\d{8}$/, "")
+  const alias = modelAliases.get(m)
+  if (alias) return alias
+  m = m.replace(
+    /^claude-(opus|sonnet|haiku)-(\d+)-(\d+)$/,
+    "claude-$1-$2.$3",
+  )
+  m = m.replace(/^claude-(\d+)-(\d+)-(sonnet|haiku|opus)$/, "claude-$1.$2-$3")
+  return m
+}
+
+function debugWarn(message: string): void {
+  if (process.env.CLCO_DEBUG) console.error("[clco:debug]", message)
+}
+
+function toImagePart(block: ImageBlock): OpenAIImagePart {
+  return {
+    type: "image_url",
+    image_url: {
+      url: `data:${block.source.media_type};base64,${block.source.data}`,
+    },
+  }
+}
+
+// Tool messages must carry string content (OpenAI schema); images are moved
+// into the adjacent user message instead, otherwise one image tool_result
+// would poison every subsequent request in the session.
+function toolResultText(result: ToolResultBlock): {
+  text: string
+  images: OpenAIImagePart[]
+} {
+  const images: OpenAIImagePart[] = []
+  let text: string
+  if (typeof result.content === "string") {
+    text = result.content
+  } else if (Array.isArray(result.content)) {
+    const texts: string[] = []
+    for (const view of classifyContent(result.content)) {
+      if (view.kind === "text") texts.push(view.text)
+      else if (view.kind === "image") images.push(toImagePart(view.block))
+      // A tool_result nesting a tool_use or a document is not something the
+      // protocol produces, but saying so beats dropping it.
+      else if (view.kind === "unsupported") {
+        texts.push(view.text)
+        debugWarn(`tool_result carried a ${view.blockType} block`)
+      }
+    }
+    text = texts.filter(Boolean).join("\n\n")
+  } else {
+    text = ""
+  }
+  if (result.is_error) text = `[error] ${text}`
+  if (images.length > 0) {
+    text =
+      (text ? `${text}\n\n` : "") +
+      `[${images.length} image(s) - attached to the next user message]`
+  }
+  return { text, images }
+}
+
+function translateUserMessage(message: AnthropicMessage): OpenAIMessage[] {
+  if (typeof message.content === "string") {
+    return [{ role: "user", content: message.content }]
+  }
+  const out: OpenAIMessage[] = []
+  const toolResults = message.content.filter(
+    (b): b is ToolResultBlock => b.type === "tool_result",
+  )
+  const rest = message.content.filter((b) => b.type !== "tool_result")
+
+  // Protocol order: tool_use -> tool_result -> user.
+  const images: OpenAIImagePart[] = []
+  for (const result of toolResults) {
+    const { text, images: resultImages } = toolResultText(result)
+    images.push(...resultImages)
+    out.push({ role: "tool", tool_call_id: result.tool_use_id, content: text })
+  }
+
+  const restTexts: string[] = []
+  const restImages: OpenAIImagePart[] = []
+  for (const view of classifyContent(rest)) {
+    if (view.kind === "text") restTexts.push(view.text)
+    else if (view.kind === "image") restImages.push(toImagePart(view.block))
+    // Never silence. A PDF attachment used to translate to nothing at all, so
+    // the model answered about a document it had never seen.
+    else if (view.kind === "unsupported") {
+      restTexts.push(view.text)
+      debugWarn(`dropped a ${view.blockType} block from a user message`)
+    }
+  }
+
+  if (images.length > 0 || restImages.length > 0) {
+    const parts: Array<OpenAITextPart | OpenAIImagePart> = [
+      ...images,
+      ...restImages,
+    ]
+    const text = restTexts.join("\n\n")
+    if (text) parts.push({ type: "text", text })
+    out.push({ role: "user", content: parts })
+  } else if (rest.length > 0) {
+    out.push({ role: "user", content: restTexts.filter(Boolean).join("\n\n") })
+  }
+  return out
+}
+
+function translateAssistantMessage(message: AnthropicMessage): OpenAIMessage[] {
+  if (typeof message.content === "string") {
+    return [{ role: "assistant", content: message.content }]
+  }
+  const toolUses = message.content.filter(
+    (b): b is ToolUseBlock => b.type === "tool_use",
+  )
+  // OpenAI has no thinking blocks; the classifier folds them into text (they
+  // are usually empty here anyway because CLAUDE_CODE_DISABLE_THINKING is set).
+  const text = classifyContent(message.content)
+    .map((view) => {
+      if (view.kind === "text") return view.text
+      if (view.kind === "unsupported") {
+        debugWarn(`dropped a ${view.blockType} block from an assistant message`)
+        return view.text
+      }
+      return ""
+    })
+    .filter(Boolean)
+    .join("\n\n")
+
+  if (toolUses.length > 0) {
+    return [
+      {
+        role: "assistant",
+        content: text || null,
+        tool_calls: toolUses.map((use) => ({
+          id: use.id,
+          type: "function" as const,
+          function: {
+            name: use.name,
+            arguments: JSON.stringify(use.input),
+          },
+        })),
+      },
+    ]
+  }
+  return [{ role: "assistant", content: text }]
+}
+
+function translateSystem(
+  system: AnthropicRequest["system"],
+): OpenAIMessage[] {
+  if (!system) return []
+  const text =
+    typeof system === "string"
+      ? system
+      : system.map((b) => b.text).join("\n\n")
+  return [
+    {
+      role: "system",
+      content: text,
+      ...(marked(system) && { copilot_cache_control: COPILOT_CACHE }),
+    },
+  ]
+}
+
+function translateTools(
+  tools: AnthropicRequest["tools"],
+): OpenAIRequest["tools"] {
+  if (!tools || tools.length === 0) return undefined
+  return tools.map((tool) => ({
+    type: "function" as const,
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.input_schema,
+    },
+  }))
+}
+
+function translateToolChoice(
+  choice: AnthropicRequest["tool_choice"],
+): OpenAIRequest["tool_choice"] {
+  if (!choice) return undefined
+  switch (choice.type) {
+    case "auto":
+      return "auto"
+    case "any":
+      return "required"
+    case "none":
+      return "none"
+    case "tool":
+      return choice.name
+        ? { type: "function", function: { name: choice.name } }
+        : undefined
+    default:
+      return undefined
+  }
+}
+
+export function translateRequest(
+  payload: AnthropicRequest,
+  allowedEfforts?: string[] | null,
+): OpenAIRequest {
+  const effort = effortFor(payload, allowedEfforts)
+  return {
+    model: normalizeModel(payload.model),
+    ...(effort && { reasoning_effort: effort }),
+    messages: [
+      ...translateSystem(payload.system),
+      ...payload.messages.flatMap((message) => {
+        const out =
+          message.role === "user"
+            ? translateUserMessage(message)
+            : translateAssistantMessage(message)
+        // Carry a cache breakpoint onto the last message this turn produced.
+        const last = out[out.length - 1]
+        if (last && marked(message.content)) {
+          last.copilot_cache_control = COPILOT_CACHE
+        }
+        return out
+      }),
+    ],
+    max_tokens: payload.max_tokens,
+    stop: payload.stop_sequences?.length ? payload.stop_sequences : null,
+    stream: payload.stream,
+    stream_options: payload.stream ? { include_usage: true } : undefined,
+    temperature: payload.temperature,
+    top_p: payload.top_p,
+    user: payload.metadata?.user_id ?? null,
+    tools: translateTools(payload.tools),
+    tool_choice: translateToolChoice(payload.tool_choice),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Response direction: OpenAI -> Anthropic (non-streaming)
+// ---------------------------------------------------------------------------
+
+export function mapStopReason(
+  finish: OpenAIChoice["finish_reason"],
+): AnthropicResponse["stop_reason"] {
+  if (finish === null) return null
+  switch (finish) {
+    case "stop":
+      return "end_turn"
+    case "length":
+      return "max_tokens"
+    case "tool_calls":
+      return "tool_use"
+    case "content_filter":
+      return "end_turn"
+  }
+}
+
+export function usageFromOpenAI(usage: OpenAIUsage | undefined) {
+  const cached = usage?.prompt_tokens_details?.cached_tokens
+  return {
+    input_tokens: Math.max(
+      0,
+      (usage?.prompt_tokens ?? 0) - (cached ?? 0),
+    ),
+    output_tokens: usage?.completion_tokens ?? 0,
+    ...(cached !== undefined && { cache_read_input_tokens: cached }),
+  }
+}
+
+export function translateResponse(upstream: OpenAIResponse): AnthropicResponse {
+  const choice = upstream.choices?.[0]
+  const content: AnthropicContentBlock[] = []
+
+  const messageContent = choice?.message?.content
+  if (typeof messageContent === "string" && messageContent.length > 0) {
+    content.push({ type: "text", text: messageContent })
+  } else if (Array.isArray(messageContent)) {
+    for (const part of messageContent) {
+      if (part.type === "text") content.push({ type: "text", text: part.text })
+    }
+  }
+  for (const call of choice?.message?.tool_calls ?? []) {
+    let input: Record<string, unknown> = {}
+    try {
+      input = JSON.parse(call.function.arguments || "{}") as Record<
+        string,
+        unknown
+      >
+    } catch {
+      // Malformed arguments: fall back to empty input rather than failing.
+    }
+    content.push({
+      type: "tool_use",
+      id: call.id,
+      name: call.function.name,
+      input,
+    })
+  }
+  if (content.length === 0) content.push({ type: "text", text: "" })
+
+  let stopReason = mapStopReason(choice?.finish_reason ?? null)
+  // "tool_use" with no tool_use block is not a valid Anthropic response.
+  if (stopReason === "tool_use" && !content.some((b) => b.type === "tool_use")) {
+    stopReason = "end_turn"
+  }
+
+  return {
+    id: upstream.id,
+    type: "message",
+    role: "assistant",
+    model: upstream.model,
+    content,
+    stop_reason: stopReason,
+    stop_sequence: null,
+    usage: usageFromOpenAI(upstream.usage),
+  }
+}

package/src/wire.ts

@@ -0,0 +1,149 @@
+// Wire shapes shared by the request and response dialects.
+import type { ContentBlock, ToolUseBlock } from "./blocks"
+
+export interface CacheControl {
+  cache_control?: { type?: string } | null
+}
+
+export interface AnthropicTextBlock extends CacheControl {
+  type: "text"
+  text: string
+}
+
+export interface AnthropicMessage {
+  role: "user" | "assistant"
+  content: string | ContentBlock[]
+}
+
+export interface AnthropicTool {
+  name: string
+  description?: string
+  input_schema: Record<string, unknown>
+}
+
+export interface AnthropicRequest {
+  model: string
+  max_tokens: number
+  messages: AnthropicMessage[]
+  system?: string | Array<AnthropicTextBlock>
+  tools?: AnthropicTool[]
+  tool_choice?: { type: "auto" | "any" | "tool" | "none"; name?: string }
+  stream?: boolean
+  temperature?: number
+  top_p?: number
+  stop_sequences?: string[]
+  metadata?: { user_id?: string }
+  thinking?: unknown
+  /** Claude Code's /effort setting rides here (gateway protocol). */
+  output_config?: { effort?: string }
+}
+
+export interface OpenAITextPart {
+  type: "text"
+  text: string
+}
+
+export interface OpenAIImagePart {
+  type: "image_url"
+  image_url: { url: string }
+}
+
+export type OpenAIContent = string | Array<OpenAITextPart | OpenAIImagePart> | null
+
+export interface OpenAIToolCall {
+  id: string
+  type: "function"
+  function: { name: string; arguments: string }
+}
+
+export interface OpenAIMessage {
+  role: "system" | "user" | "assistant" | "tool"
+  content: OpenAIContent
+  tool_calls?: OpenAIToolCall[]
+  tool_call_id?: string
+  copilot_cache_control?: { type: "ephemeral" }
+}
+
+export interface OpenAIRequest {
+  model: string
+  messages: OpenAIMessage[]
+  max_tokens?: number
+  stop?: string[] | null
+  stream?: boolean
+  stream_options?: { include_usage: boolean }
+  reasoning_effort?: string
+  temperature?: number
+  top_p?: number
+  user?: string | null
+  tools?: Array<{
+    type: "function"
+    function: {
+      name: string
+      description?: string
+      parameters: Record<string, unknown>
+    }
+  }> | null
+  tool_choice?:
+    | "none"
+    | "auto"
+    | "required"
+    | { type: "function"; function: { name: string } }
+    | null
+}
+
+export interface OpenAIUsage {
+  prompt_tokens?: number
+  completion_tokens?: number
+  prompt_tokens_details?: { cached_tokens?: number }
+}
+
+export interface OpenAIChoice {
+  index: number
+  finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null
+  message?: { role: "assistant"; content: OpenAIContent; tool_calls?: OpenAIToolCall[] }
+  delta?: {
+    role?: string
+    content?: string | null
+    tool_calls?: Array<{
+      index: number
+      id?: string
+      function?: { name?: string; arguments?: string }
+    }>
+  }
+}
+
+export interface OpenAIResponse {
+  id: string
+  model: string
+  choices?: OpenAIChoice[]
+  usage?: OpenAIUsage
+  error?: { message?: string; code?: string | number }
+}
+
+// ---------------------------------------------------------------------------
+// Anthropic response types
+// ---------------------------------------------------------------------------
+
+export type AnthropicContentBlock =
+  | AnthropicTextBlock
+  | ToolUseBlock
+
+export interface AnthropicResponse {
+  id: string
+  type: "message"
+  role: "assistant"
+  model: string
+  content: AnthropicContentBlock[]
+  stop_reason: "end_turn" | "max_tokens" | "tool_use" | null
+  stop_sequence: null
+  usage: {
+    input_tokens: number
+    output_tokens: number
+    cache_read_input_tokens?: number
+  }
+}
+
+export interface StreamEventData {
+  event: string
+  data: Record<string, unknown>
+}

package/uninstall.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# clco uninstaller.
+#   curl -fsSL https://raw.githubusercontent.com/semanticist21/clco/main/uninstall.sh | bash
+#   ... --full   : also remove config and the GitHub token (~/.config/clco)
+set -euo pipefail
+
+CLCO_DIR="${CLCO_DIR:-$HOME/.local/share/clco}"
+BIN_DIR="${BIN_DIR:-$HOME/.local/bin}"
+
+log() { printf '\033[1;36m==>\033[0m %s\n' "$*"; }
+fail() { printf '\033[1;31mError:\033[0m %s\n' "$*" >&2; exit 1; }
+
+removed=0
+if [ -f "$BIN_DIR/clco" ]; then rm -f "$BIN_DIR/clco"; log "Removed: $BIN_DIR/clco"; removed=1; fi
+if [ -d "$CLCO_DIR" ]; then
+  if [ ! -d "$CLCO_DIR/.git" ]; then
+    fail "$CLCO_DIR is not a clco install (git repo) - check it yourself before deleting"
+  fi
+  rm -rf "$CLCO_DIR"; log "Removed: $CLCO_DIR"; removed=1
+fi
+if [ -d "$CLCO_DIR.previous" ]; then
+  [ -d "$CLCO_DIR.previous/.git" ] \
+    || fail "$CLCO_DIR.previous is not a clco rollback install - check it yourself before deleting"
+  rm -rf "$CLCO_DIR.previous"; log "Removed: $CLCO_DIR.previous"; removed=1
+fi
+if [ -d "$CLCO_DIR.update.lock" ]; then
+  rmdir "$CLCO_DIR.update.lock" \
+    || fail "$CLCO_DIR.update.lock is not empty - verify no update is running before removing it"
+  log "Removed stale update lock: $CLCO_DIR.update.lock"; removed=1
+fi
+
+if [ "${1:-}" = "--full" ]; then
+  if [ -d "$HOME/.config/clco" ]; then
+    rm -rf "$HOME/.config/clco"
+    log "Removed: ~/.config/clco (including the GitHub token)"
+  fi
+else
+  [ -d "$HOME/.config/clco" ] && log "Kept config: ~/.config/clco (including the GitHub token) - remove it with: $0 --full"
+fi
+
+[ "$removed" = "1" ] || [ "${1:-}" = "--full" ] || log "Nothing to remove"
+log "Done"