SDK 云端会话

云端会话在 GitHub 托管计算中执行，并出现在 GitHub agents panel。前提包括用户拥有 cloud-agent 权益、可用的 GitHub 用户身份，以及组织策略允许相关远程控制和云端查看流程。

创建与关联仓库

在创建会话配置中传入 cloud：

const session = await client.createSession({
  streaming: true,
  cloud: {
    repository: {
      owner: "github",
      name: "copilot-sdk",
      branch: "main",
    },
  },
});

仓库为官方示例，实际使用时换成任务目标。repository 在 SDK 类型中可选，但应用知道仓库时应传入；其中 owner、name 必填，branch 可选。省略 branch 由 runtime 选择默认分支或当前仓库上下文，不承诺始终使用 main。

权限请求仍应由应用按权限处理配置，上例只展示云端创建和仓库字段。

首条消息必须等 worker 就绪

云端初始化分两阶段：createSession 返回表示任务已预留，远端 copilot-agent worker 还需连接。官方记录了一种竞态：过早调用 send 时，底层报“Remote session is still starting”，但包装层吞掉错误并返回 messageId，导致 prompt 实际丢失。

可靠流程是先订阅事件，等待 session.start 且 event.data.producer === "copilot-agent"，再发首条消息。为等待设置应用超时，例如官方建议的 60 秒；这是示例超时，不是启动时间保证。超时应显示未就绪并处理失败，而非把取得 messageId 当成已送达。

同一会话后续发送不受这次初始化竞态影响。需要实时文字增量时，创建配置设置 streaming: true；否则仍可接收最终 assistant.message，但 UI 不会得到预期的 message_delta。

获取 GitHub 会话地址

worker 连接后，runtime 通过 session.info 发布地址；筛选 infoType 为 remote：

session.on("session.info", (event) => {
  if (event.data.infoType === "remote" && event.data.url) {
    console.log("Session URL:", event.data.url);
  }
});

云端本来就是远程任务，无需再调用 remote.enable。官方给出的地址形态为 https://github.com/copilot/tasks/{sessionId}，但应用应保存实际返回 URL。该事件不会因组件重新挂载而自动重发，需把地址与应用会话状态一起保存。

恢复与政策错误

恢复时使用通常的 client.resumeSession(...)，不再传 cloud；已有元数据决定会话由云端支撑。重新提供新建配置不能把同一个恢复操作变成创建另一种执行环境。

创建失败的 reason 为 policy_blocked 时，检查权益和组织策略。这是授权或政策结果，不是预期通过原样重试解决的临时基础设施问题。

路由和部署范围

GITHUB_COPILOT_INTEGRATION_ID 影响 Copilot-Integration-Id 路由与归属；SDK 云端内部使用 copilot-developer-sandbox agent slug，名称不表示本地 Windows 沙箱。不能用本地 SANDBOX=true 当云端执行开关。

默认任务 endpoint 从 Copilot API URL 推导。官方列出高级覆盖变量 COPILOT_MC_BASE_URL，并要求特殊企业部署先与 GitHub 确认值及支持状态；这不是对所有 GitHub Enterprise Server 部署的通用支持承诺。

若希望任务仍在本机或自有服务器执行，只从 Web/Mobile 查看和访问，应选择本地会话远程访问。