@x-otto/plugin-github-copilot 0.1.0-alpha.0

package/plugin.ts

@@ -0,0 +1,35 @@
+/**
+ * plugin.ts —— GitHub Copilot 代码式 provider 工厂。
+ *
+ * GitHub Copilot 走不了声明式 `contributes.providers` 轴（`wireApi` schema 只覆盖
+ * openai-completions/openai-responses/anthropic-messages 三种通用协议）——Copilot 协议是
+ * 定制的：vision 场景动态请求头（`Copilot-Vision-Request`）、initiator 判断（`X-Initiator`
+ * 依据最后一条消息角色）、`copilot-integration-id`/`editor-version` 等专属请求头。
+ *
+ * RFC-140 架构下沉：具体的 Copilot 协议实现（`createCopilotProvider`）已物理迁移至本插件
+ * 目录的 `src/provider.ts`（不再驻留在 `@x-otto/provider` 通用契约包——它是 copilot 一家
+ * 厂商的专属实现，唯一消费方是本插件）。复用 `@x-otto/provider` 导出的 `streamChatCompletions`
+ * 协议基座（chat-completions SSE 解析循环单一实现，RFC-074 R-AICHAT），不复用整个 provider。
+ *
+ * OAuth 走声明式 `contributes.oauth`（`kind: 'device-flow'`，见 `otto-plugin.json`）——
+ * device-flow 流程本身与厂商协议无关，通用 `DeviceFlowOAuthTemplate` 已覆盖，不需要代码。
+ *
+ * 凭据解析：`ctx.resolveProviderCredential('github-copilot')` 由宿主装载器注入，内部转发
+ * `ProviderRegistry.resolveAccessKey` → `AuthStore.getCredentialKey`，每次请求时动态取
+ * 当前有效 token（而非构造时固定死一份，因为 OAuth token 会刷新轮换）。
+ *
+ * `codeProviderIds: ["github-copilot"]`（manifest 声明）让本工厂注册为裸 `github-copilot`
+ * api id（而非 `plugin-github-copilot:github-copilot`），与系统里既有的凭据槽/模型数据/
+ * `apiCredentialId()` 等硬编码裸 id 引用点保持兼容——现有用户凭据/模型缓存零迁移成本。
+ */
+import { definePlugin } from '@x-otto/plugin'
+import { createCopilotProvider } from './src/provider'
+
+export default definePlugin((ctx) => ({
+  providerFactories: {
+    'github-copilot': () =>
+      createCopilotProvider({
+        resolveOAuthAccessKey: () => ctx.resolveProviderCredential('github-copilot').then((k) => k ?? undefined),
+      }),
+  },
+}))

package/src/provider.test.ts

@@ -0,0 +1,273 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  createCopilotProvider,
+  inferCopilotInitiator,
+  hasCopilotVisionInput,
+  buildCopilotDynamicHeaders,
+} from './provider'
+
+import type {
+  AssistantMessage,
+  Message,
+  Model,
+  ToolResultMessage,
+  UserMessage,
+} from '@x-otto/provider'
+
+function makeModel(): Model {
+  return {
+    id: 'github-copilot/gpt-4.1',
+    name: 'gpt-4.1',
+    api: 'github-copilot',
+    provider: 'github-copilot',
+    baseUrl: 'https://api.githubcopilot.com',
+    reasoning: false,
+    input: ['text'],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxOutputTokens: 4096,
+  }
+}
+
+function makeUserMessage(content: UserMessage['content']): UserMessage {
+  return {
+    role: 'user',
+    content,
+    timestamp: Date.now(),
+  }
+}
+
+function makeAssistantMessage(content: AssistantMessage['content']): AssistantMessage {
+  return {
+    role: 'assistant',
+    content,
+    api: 'github-copilot',
+    provider: 'github-copilot',
+    model: 'github-copilot/gpt-4.1',
+    usage: {
+      inputTokens: 1,
+      outputTokens: 1,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+    },
+    stopReason: 'end_turn',
+  }
+}
+
+function makeToolResultMessage(content: ToolResultMessage['content']): ToolResultMessage {
+  return {
+    role: 'tool_result',
+    toolCallId: 'tc1',
+    toolName: 'read_file',
+    content,
+    details: null,
+    isError: false,
+    timestamp: Date.now(),
+  }
+}
+
+describe('GitHub Copilot Provider', () => {
+  // RFC-140 D5：resolveKey 统一为接口方法 resolveAuth(model): Promise<ResolvedAuth>。
+  it('resolveAuth uses resolveOAuthAccessKey when provided, returns oauth mode', async () => {
+    const provider = createCopilotProvider({
+      resolveOAuthAccessKey: async () => 'oauth-token',
+    })
+
+    const auth = await provider.resolveAuth?.(makeModel())
+    expect(auth).toEqual({ token: 'oauth-token', mode: 'oauth' })
+  })
+
+  it('exposes provider identity and converse function', () => {
+    const provider = createCopilotProvider()
+    expect(provider.id).toBe('github-copilot')
+    expect(provider.displayName).toBe('GitHub Copilot')
+    expect(typeof provider.converse).toBe('function')
+  })
+
+  it('resolveAuth is available', async () => {
+    const provider = createCopilotProvider()
+    expect(typeof provider.resolveAuth).toBe('function')
+  })
+
+  it('resolveAuth throws when resolver returns undefined', async () => {
+    const provider = createCopilotProvider({
+      resolveOAuthAccessKey: async () => undefined,
+    })
+
+    await expect(provider.resolveAuth?.(makeModel())).rejects.toThrow('Missing GitHub Copilot token')
+  })
+
+  it('resolveAuth throws when env and oauth are both unavailable', async () => {
+    const provider = createCopilotProvider()
+    await expect(provider.resolveAuth?.(makeModel())).rejects.toThrow('Missing GitHub Copilot token')
+  })
+})
+
+describe('inferCopilotInitiator', () => {
+  it('returns "user" when last message is from user', () => {
+    const messages: Message[] = [makeUserMessage('hello')]
+    expect(inferCopilotInitiator(messages)).toBe('user')
+  })
+
+  it('returns "agent" when last message is from assistant', () => {
+    const messages: Message[] = [
+      makeUserMessage('hello'),
+      makeAssistantMessage([{ type: 'text', text: 'hi' }]),
+    ]
+    expect(inferCopilotInitiator(messages)).toBe('agent')
+  })
+
+  it('returns "agent" when last message is tool_result', () => {
+    const messages: Message[] = [makeToolResultMessage([{ type: 'text', text: 'result' }])]
+    expect(inferCopilotInitiator(messages)).toBe('agent')
+  })
+
+  it('returns "user" for empty messages', () => {
+    expect(inferCopilotInitiator([])).toBe('user')
+  })
+})
+
+describe('hasCopilotVisionInput', () => {
+  it('returns false when no images', () => {
+    const messages: Message[] = [makeUserMessage('hello')]
+    expect(hasCopilotVisionInput(messages)).toBe(false)
+  })
+
+  it('returns true when user message has image content', () => {
+    const messages: Message[] = [
+      makeUserMessage([
+        { type: 'text', text: 'describe this' },
+        { type: 'image', source: 'base64data', mime: 'image/png' },
+      ]),
+    ]
+    expect(hasCopilotVisionInput(messages)).toBe(true)
+  })
+
+  it('returns true when tool_result has image content', () => {
+    const messages: Message[] = [
+      makeToolResultMessage([{ type: 'image', source: 'base64data', mime: 'image/png' }]),
+    ]
+    expect(hasCopilotVisionInput(messages)).toBe(true)
+  })
+})
+
+describe('buildCopilotDynamicHeaders', () => {
+  it('sets X-Initiator and Openai-Intent', () => {
+    const messages: Message[] = [makeUserMessage('hello')]
+    const headers = buildCopilotDynamicHeaders({ messages, hasImages: false })
+    expect(headers['X-Initiator']).toBe('user')
+    expect(headers['Openai-Intent']).toBe('conversation-edits')
+    expect(headers['Copilot-Vision-Request']).toBeUndefined()
+  })
+
+  it('includes Copilot-Vision-Request when hasImages is true', () => {
+    const messages: Message[] = [
+      makeUserMessage([{ type: 'image', source: 'base64data', mime: 'image/png' }]),
+    ]
+    const headers = buildCopilotDynamicHeaders({ messages, hasImages: true })
+    expect(headers['Copilot-Vision-Request']).toBe('true')
+    expect(headers['X-Initiator']).toBe('user')
+  })
+
+  it('does not include Copilot-Vision-Request when hasImages is false even with image content', () => {
+    const messages: Message[] = [
+      makeUserMessage([{ type: 'image', source: 'base64data', mime: 'image/png' }]),
+    ]
+    const headers = buildCopilotDynamicHeaders({ messages, hasImages: false })
+    expect(headers['Copilot-Vision-Request']).toBeUndefined()
+  })
+})
+
+describe('converse error contract (M12-09)', () => {
+  const encoder = new TextEncoder()
+
+  function sseResponse(body: ReadableStream<Uint8Array>): Response {
+    return new Response(body, {
+      status: 200,
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+
+  function makeProvider() {
+    return createCopilotProvider({ resolveOAuthAccessKey: async () => 'test-token' })
+  }
+
+  async function collect(response: Response) {
+    const original = globalThis.fetch
+    globalThis.fetch = (async () => response) as typeof fetch
+    try {
+      const provider = makeProvider()
+      const events: Array<{ type: string }> = []
+      for await (const event of provider.converse(
+        makeModel(),
+        { model: makeModel(), systemPrompt: '', messages: [makeUserMessage('hi')] },
+        {},
+        new AbortController().signal,
+      )) {
+        events.push(event)
+      }
+      return events
+    } finally {
+      globalThis.fetch = original
+    }
+  }
+
+  it('yields {type:"error"} instead of throwing when stream fails mid-flight', async () => {
+    let pulls = 0
+    const body = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        if (pulls++ === 0) {
+          controller.enqueue(encoder.encode('data: {"choices":[{"delta":{"content":"hel"}}]}\n\n'))
+        } else {
+          controller.error(new Error('socket reset'))
+        }
+      },
+    })
+
+    const events = await collect(sseResponse(body))
+    const types = events.map((e) => e.type)
+    expect(types).toContain('text_delta')
+    expect(types[types.length - 1]).toBe('error')
+  })
+
+  it('completes normally with done event when stream ends cleanly', async () => {
+    const body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(
+          encoder.encode('data: {"choices":[{"delta":{"content":"ok"},"finish_reason":"stop"}]}\n\n'),
+        )
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'))
+        controller.close()
+      },
+    })
+
+    const events = await collect(sseResponse(body))
+    const types = events.map((e) => e.type)
+    expect(types[types.length - 1]).toBe('done')
+    expect(types).not.toContain('error')
+  })
+
+  // RFC-074 B5：OpenAI 兼容后端把终止块发成无 delta 的 {finish_reason:'tool_calls'}。
+  // 修复前 `!delta continue` 在 finish_reason 之前 → stopReason 停 'end_turn'，有 tool_calls 也停轮不执行。
+  it('captures finish_reason from a delta-less terminal chunk (tool_calls → tool_use)', async () => {
+    const body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        // tool_call 分块先到（带 delta），终止块无 delta、只有 finish_reason。
+        controller.enqueue(
+          encoder.encode(
+            'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"c1","function":{"name":"read_file","arguments":"{}"}}]}}]}\n\n',
+          ),
+        )
+        controller.enqueue(encoder.encode('data: {"choices":[{"finish_reason":"tool_calls"}]}\n\n'))
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'))
+        controller.close()
+      },
+    })
+
+    const events = (await collect(sseResponse(body))) as Array<{ type: string; reason?: string }>
+    const done = events.find((e) => e.type === 'done')
+    expect(done?.reason).toBe('tool_use')
+  })
+})
+

package/src/provider.ts

@@ -0,0 +1,150 @@
+/**
+ * provider.ts —— GitHub Copilot 定制协议 provider 实现（RFC-140 架构下沉，从 @x-otto/provider
+ * 物理迁移至本插件目录）。
+ *
+ * Copilot 走不了声明式 `contributes.providers` 轴（`wireApi` schema 只覆盖
+ * openai-completions/openai-responses/anthropic-messages 三种通用协议）——协议本质是
+ * chat-completions 兼容形，但有厂商专属头（vision 动态请求头/initiator 判断/
+ * `copilot-integration-id` 等），复用 `@x-otto/provider` 导出的 `buildChatCompletionsBody`/
+ * `streamChatCompletions` 协议基座，只在 url/headers/body 上做定制。
+ *
+ * 此实现此前物理存在于 `@x-otto/provider`（通用契约包），但它是 copilot 一家厂商的专属
+ * 实现、唯一消费方是本插件——架构 review 判定不该驻留在"多厂商共享的通用插入点"里，
+ * 下沉到这里更贴合"各 provider 在插件实现，框架提供插入点"的终局方向。
+ */
+import { ProviderError } from '@x-otto/shared'
+import {
+  buildChatCompletionsBody,
+  streamChatCompletions,
+  registeredToolNames,
+  type Message,
+  type Model,
+  type ResolvedAuth,
+  type StreamContext,
+  type StreamEvent,
+  type StreamOptions,
+  type ProviderStream,
+  type WireProtocolLogger,
+} from '@x-otto/provider'
+
+/** RFC-185 D3：日志走宿主注入端口，缺省 no-op——插件源码禁 createLogger（防第二单例直写 stderr）。 */
+const noopLogger: WireProtocolLogger = { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} }
+
+const PROVIDER_VERSION = '1.0.0'
+const DEFAULT_COPILOT_INTEGRATION_ID = 'vscode-chat'
+
+function buildCopilotHeaders(token: string): Record<string, string> {
+  const integrationId = process.env['OTTO_COPILOT_INTEGRATION_ID'] || DEFAULT_COPILOT_INTEGRATION_ID
+
+  return {
+    authorization: `Bearer ${token}`,
+    'copilot-integration-id': integrationId,
+    'editor-version': `otto-coding/${PROVIDER_VERSION}`,
+    'editor-plugin-version': `otto-coding/${PROVIDER_VERSION}`,
+    'openai-intent': 'conversation-panel',
+  }
+}
+
+export function inferCopilotInitiator(messages: Message[]): 'user' | 'agent' {
+  const last = messages[messages.length - 1]
+  return last && last.role !== 'user' ? 'agent' : 'user'
+}
+
+export function hasCopilotVisionInput(messages: Message[]): boolean {
+  return messages.some((msg) => {
+    if (msg.role === 'user' && Array.isArray(msg.content)) {
+      return msg.content.some((c) => c.type === 'image')
+    }
+    if (msg.role === 'tool_result' && Array.isArray(msg.content)) {
+      return msg.content.some((c) => c.type === 'image')
+    }
+    return false
+  })
+}
+
+export function buildCopilotDynamicHeaders(params: {
+  messages: Message[]
+  hasImages: boolean
+}): Record<string, string> {
+  const headers: Record<string, string> = {
+    'X-Initiator': inferCopilotInitiator(params.messages),
+    'Openai-Intent': 'conversation-edits',
+  }
+  if (params.hasImages) {
+    headers['Copilot-Vision-Request'] = 'true'
+  }
+  return headers
+}
+
+function buildRequestBody(model: Model, context: StreamContext): Record<string, unknown> {
+  const modelId = model.id.includes('/') ? model.id.split('/')[1] : model.id
+  return buildChatCompletionsBody(model, context, { modelName: modelId })
+}
+
+export type CopilotCredentialResolver = () => Promise<string | undefined>
+
+class GitHubCopilotStream implements ProviderStream {
+  readonly id = 'github-copilot'
+  readonly displayName = 'GitHub Copilot'
+
+  constructor(
+    private readonly resolveOAuthAccessKey?: CopilotCredentialResolver,
+    private readonly logger: WireProtocolLogger = noopLogger,
+  ) {}
+
+  /** 统一鉴权解析（RFC-140 D5，`ProviderStream.resolveAuth`）——Copilot 用户令牌走 oauth 模式。 */
+  async resolveAuth(): Promise<ResolvedAuth> {
+    if (this.resolveOAuthAccessKey) {
+      const key = await this.resolveOAuthAccessKey()
+      if (key) {
+        return { token: key, mode: 'oauth' }
+      }
+    }
+
+    throw new ProviderError('Missing GitHub Copilot token.', {
+      code: 'PROVIDER_AUTH_MISSING',
+    })
+  }
+
+  async *converse(
+    model: Model,
+    context: StreamContext,
+    options: StreamOptions,
+    signal: AbortSignal,
+  ): AsyncIterable<StreamEvent> {
+    const { token: key } = await this.resolveAuth()
+
+    const baseUrl = model.baseUrl ?? 'https://api.githubcopilot.com'
+    const body = buildRequestBody(model, context)
+
+    this.logger.debug({ model: model.id }, 'Starting Copilot stream with body: %o', body)
+
+    // SSE 解析统一走 streamChatCompletions（RFC-074 R-AICHAT）；copilot 仅特殊在 url/headers/body。
+    yield* streamChatCompletions({
+      url: `${baseUrl}/chat/completions`,
+      headers: {
+        ...buildCopilotHeaders(key),
+        ...buildCopilotDynamicHeaders({
+          messages: context.messages,
+          hasImages: hasCopilotVisionInput(context.messages),
+        }),
+      },
+      body,
+      identity: { api: 'github-copilot', provider: 'github-copilot', model: model.id },
+      signal,
+      timeout: options.timeout,
+      // RFC-232（终局修正）：跨 wire 协议救回违约响应，见 @x-otto/provider stream-state.ts。
+      registeredToolNames: registeredToolNames(context.tools),
+    })
+  }
+}
+
+export interface CopilotProviderOptions {
+  resolveOAuthAccessKey?: CopilotCredentialResolver
+  /** RFC-185 D3：宿主注入的日志端口，缺省 no-op。 */
+  logger?: WireProtocolLogger
+}
+
+export function createCopilotProvider(options: CopilotProviderOptions = {}): ProviderStream {
+  return new GitHubCopilotStream(options.resolveOAuthAccessKey, options.logger)
+}