export function apply(ctx: Context) {  // Cordis Loader 加载本插件时调用，ctx 是运行时上下文  ctx.systemPrompt.section({ name: 'tool:cordis', order: 115, text: CORDIS_SYSTEM_PROMPT })  // 注入专属提示词段：order=115 决定它在 system prompt 中的位置；内容是完整工作流 + 高频错误清单  for (const provider of hostInspectProviders(ctx)) {  // 遍历第一方 Host inspect provider（Service / Event / Builtin / Tool 四个）    ctx.effect(() => ctx.cordisInspect.register(provider), `tool-cordis: inspect ${provider.manifest.id}`)  // effect() 注册：插件被 dispose 时自动反注册，不留孤儿条目  }  ctx.tools.register(defineTool({  // 开始逐个注册模型可见工具；register 返回 disposer（仓库约定：一切注册都是可撤销的 effect）    name: 'cordis_inspect_list',  // 第一个工具：列出 Host 已知的所有 inspect provider，是写代码前的"能力发现"入口

define(request) {  // 模型调 cordis_define：为新 Plugin 建首个 Package，或给已有 Plugin 追加一个版本  const name = request.name.trim()  // 元数据先 trim；空值在下面直接拒绝——fail loud，不静默接受垃圾数据  if (name.length === 0) throw new Error('cordis_define needs a non-empty `name`')  // 名字是审批卡片和 UI 上用户看到的标识，空名会让"这是什么"无从回答  if (request.code.host === undefined && request.code.client === undefined) {  // 至少提供一半代码，否则这个 Package 没有任何可执行内容    throw new Error('cordis_define needs `code.host`, `code.client`, or both')  // 两个半都缺 = 空包，直接拒绝而不是存一个永远跑不起来的版本  }  if (request.code.host !== undefined) precheckCode(request.code.host, 'code.host')  // 编译期语法预检：解析不过的代码根本不进注册表，把错误挡在 define 阶段  if (request.code.client !== undefined) precheckCode(request.code.client, 'code.client')  // Client 半同样预检——两半用同一套包装编译，行号语义一致  if (request.plugin.kind === 'new') {  // 分支 A：新建 Plugin    const prefix = request.plugin.idPrefix.trim()  // 取模型给的语义前缀并 trim——下面用正则严格校验形状    if (!/^[a-z]{3,6}$/.test(prefix)) {  // 前缀形状校验：语义可读（chart）+ 长度受限，防止模型塞进整句英文      throw new Error('cordis_define `plugin.idPrefix` must contain 3–6 lowercase English letters')  // 拒绝时把合法形状写进错误信息——模型改一次就能过    }    const pluginId = CordisDynamicPluginId(this.registry.mintPluginId(prefix))  // 铸造形如 chart-1 的进程内唯一 ID（前缀 + 自增序号）    this.registry.add(plugin)  // 写入进程内存注册表；不碰磁盘——定义不跨重启存活是刻意设计，避免"僵尸扩展"  } else {  // 分支 B：给已有 Plugin 追加版本    const found = this.registry.get(request.plugin.pluginId)    if (found === undefined || found.sessionId !== request.sessionId) {  // Session 归属校验：只能改自己 Session 拥有的 Plugin，跨 Session 引用直接拒绝      throw new Error(missingPluginMessage(request.plugin.pluginId))    }  }  const packageId = CordisDynamicPackageId(this.registry.mintPackageId())  // 每个版本铸造新的不可变 ID（pkg-N）——旧版本永远原样保留，这是回滚能力的来源  plugin.packages.set(packageId, definition)  // 追加进版本 Map。define 到此为止：不请求审批、不执行 apply、不动 currentPackageId

export function precheckCode(code: string, half: 'code.host' | 'code.client'): void {  // define 时的编译期检查；与运行时同一个 async 函数包装，保证行号一致  try {  // 只捕获"解析失败"这一类错误，其余异常原样上抛    new Script(`(async () => {\n${code}\n})()`, { filename: `cordis-dyn-${half}.js` })  // 构造 vm.Script 只解析不执行——模型代码被包成 async 函数体，filename 让错误栈可读  } catch (error) {  // 编译期唯一预期失败是 SyntaxError（在沙箱 realm 里构造）    if (!isSyntaxError(error)) throw error  // 非语法错误原样抛出——不伪装成"代码写错了"    throw new Error(parseErrorMessage(half, syntaxErrorContext(error)))  // 转成教学式错误：保留"出错行 + caret"前缀，再附修复提示  }}

const offendingLine = context.split('\n')[1] ?? ''  // 只检查"出错那一行"——代码别处的字符串里出现 ` as ` 不能误触发 TS 提示if (/\bas\b/.test(offendingLine)) {  // 启发式：模型写了 TypeScript 类型断言（最高频错误之一）  return ... 'The sandbox runs plain JavaScript, not TypeScript. Remove type annotations:\n'    + '  ✗ { type: \'text\' as const, text: x}\n'    + '  ✓ { type: \'text\', text: x }'  // 给出可直接复制的修法——错误信息本身就是修复补丁}return ... 'Note: it runs as the BODY of an async function (line numbers are offset by the 1-line wrapper). '  + 'Check bracket balance — ending the returned plugin object with `});` closes a call that was never opened'  // 第二高频错误：对象结尾多写一个右括号

const NODE_API_REDIRECTS: Record<string, string> = {  // 每个被禁的 Node API 都映射一条"重定向"文案——不只说 no，还告诉模型去哪  require: 'Node modules are unavailable. Use the cordis services on ctx instead — e.g. inject: [\'fs\'] for files...',  // 模块系统换成 Cordis Service：可观测、可策略检查、随 fiber 生命周期清理  setTimeout: TIMER_REDIRECT,  // 原生定时器被禁——必须用 fiber effect（ctx.timeout），这样 stop/update/undefine 时自动清理，不留幽灵任务  fetch: 'Network access goes through the cordis web service: declare inject: [\'web\'] and call ctx.web ...',  // 网络走真实 Service：有超时、可取消、进审计流}function nodeApiTraps(): Record<string, () => never> {  // 把每条重定向变成一个"调用即抛错"的函数  const traps: Record<string, () => never> = {}  // 陷阱表：键是全局名，值是教学错误工厂  for (const [name, redirect] of Object.entries(NODE_API_REDIRECTS)) {  // 逐条生成——新增被禁 API 只需在 NODE_API_REDIRECTS 加一行    traps[name] = () => { throw new Error(`${name} is not available in the dynamic package sandbox — ${redirect}`) }  // fail loud + teach：模型读到错误就能自我修正，而不是静默失败  }  return traps  // 返回给 createSandbox 展开进沙箱全局}

export function createSandbox(id: string, harnessExtras = {}): object {  // 为一个 Host 半构建 vm context；id 用作 console 标签和文件名主干  const sandbox = {    ...nodeApiTraps(),  // require/setTimeout/fetch 等变成教学陷阱：调用即抛"正确做法"错误    console: taggedConsole(id),  // [cordis:<id>] 前缀的 write-through console——输出直达宿主终端，不缓冲进工具结果（监听器触发时 run 早已返回）    harness: { defineTool: sandboxDefineTool, registerTool: sandboxRegisterTool, ...harnessExtras },  // 暴露给包代码的唯一"注册动词"；handle（私有 RPC）按包注入    btoa: (s: string) => Buffer.from(s, 'utf-8').toString('base64'),  // 裸 vm context 缺 Web 编码 API——用宿主闭包补上，而不是把 Buffer 本体塞进去    atob: (s: string) => Buffer.from(s, 'base64').toString('utf-8'),    TextEncoder,  // 同理：模型需要 base64/UTF-8 能力，但拿不到 Node 内建对象本身（闭包是受控的，Buffer 不是）    TextDecoder,  }  createContext(sandbox)  // contextify：这个对象从此成为沙箱的全局 globalThis  patchDualRealmInstanceof(sandbox)  // 修补跨 realm instanceof（见下节）——不补的话 vm 里的 Error 过不了宿主侧的 instanceof 检查  return sandbox}

function denyContext(value: unknown, service: string, reportFailure): unknown {  // 一条铁律：Service 绝不能把 Context 递给沙箱代码  if (value instanceof Context) {  // 返回的 Context = 一个未经守卫的运行时句柄——正是这个 façade 要堵住的逃逸路径    return rejectGuard(reportFailure, `service "${service}" returned a cordis Context ...`)  // fail loud，并把失败 steer 给所属 Agent，让模型知道为什么被拒  }  return value  // 普通数据原样通过}function guardedService(service: object, name: string, reportFailure): unknown {  // 每个注入的 Service 都包一层 Proxy  return new Proxy(service, {    get(target, prop) {      const value = Reflect.get(target, prop, target) as unknown      if (typeof value !== 'function') return denyContext(value, name, reportFailure)  // 数据成员立即检查（Service 可能直接返回 Context 对象）      return (...args: unknown[]): unknown => {  // 方法调用转发给真实实例……        const result = Reflect.apply(value, target, args) as unknown        if (result instanceof Promise) return result.then(v => denyContext(v, name, reportFailure))  // ……Promise 在 resolve 时再查——异步返回的逃逸同样堵死        return denyContext(result, name, reportFailure)      }    },  })}

async run(agent, pluginId, packageId, mode, signal?) {  // 模型调 cordis_run：激活一个精确的 Package 版本  const plan = this.resolvePlan(agent, pluginId, packageId, mode)  // 校验归属 + mode 语义（run vs update），非法组合返回可操作的错误信息而非裸异常  if (!plan.ok) return plan.response  // 计划解析失败直接透传结构化拒绝——模型拿到的是 reason + message，能据此改参数重试  if (this.registry.pendingRequestFor(pluginId) !== undefined) {  // 每个 Plugin 同时只允许一个在途转换——杜绝双激活竞态    return { ok: false, reason: 'transition-in-flight', message: `...already has a pending run request` }  // 拒绝第二个并发请求，而不是排队或覆盖  }  const attempt = this.createAttempt(plan)  // 铸造一次"尝试"记录（pluginRunId + host/client 状态）——后续所有状态更新都挂在它上面  plan.plugin.nextPackageId = packageId  // "next" 指向目标版本；current 保持不动，直到完全成功才切换  if (plan.definition.clientCode === undefined) {  // Host-only Package：没有浏览器参与，无需审批，直接激活    const started = await this.activate(plan, undefined, false, attempt)    if (started.ok) return this.runResponse(plan.plugin, started)    this.failAttempt(plan.plugin, attempt, 'host-load', started)  // 失败记录在 attempt 上（phase + message/stack），供 inspect_self 诊断    return { ...started, reason: 'host-half-failed' }  }  const requestId = ApprovalRequestId(this.registry.mintApprovalRequestId())  // 有 Client 半 → 铸造审批请求 ID，UI 凭它渲染审批卡片  const requiresApproval = !plan.plugin.clientVersionUpdatesApproved && !plan.plugin.approvedClientPackages.has(packageId)  // 两级授权：单版本（单勾）或该 Plugin 未来所有版本（双勾），已授权的直接放行  attempt.status = requiresApproval ? 'awaiting-approval' : 'starting-host'  // 状态机入口；工具立即返回，绝不在此等待浏览器  this.ctx.emit('cordis/request-run', { requestId, ..., name: plan.definition.name, purpose: plan.definition.purpose })  // 事件携带用户可见的元数据——审批卡片展示的是"这个包是干什么的"，不是 ID  return { ok: true, status: requiresApproval ? 'awaiting-approval' : 'starting', ... }  // 模型拿到回执；最终结局稍后通过 steering context 到达

private commitActivation(plugin, run) {  // 唯一提交点：只在 Host + Client 双半全部成功后调用  plugin.currentPackageId = run.packageId  // "current" 在这里原子前进——stop/失败从不触碰它，回滚永远有已知良好的版本可退  delete plugin.nextPackageId  // 清除待决目标；下次尝试会重新铸造  delete run.startedForRequest  // 解除与审批请求的绑定（授权本身留在 approvedClientPackages 里）  const attempt = plugin.latestRun  if (attempt?.pluginRunId === run.pluginRunId) {  // 只有当它仍是最新一次尝试时才更新状态——更新的 run 可能已经取代了它    attempt.status = ... 'waiting' : 'running'  // 某一半因 inject 未满足而 parked 时是 waiting 而非 failed——Cordis 会在服务出现后自动重新激活    delete attempt.approvalRequestId  // 审批已消费；attempt 上的临时字段全部清理，状态回到"干净"形态  }}

export async function evaluateClientHalf(pluginId, clientCode, env, styles) {  // 浏览器半求值：页面里没有 vm，用闭包参数当符号面  const traps = closureTraps()  // setTimeout/fetch/require/process/Buffer 变成"调用即抛教学错误"的参数——遮蔽掉环境全局而不碰页面本身  const parameters = ['React', 'console', 'styles', 'host', 'harness', ...Object.keys(traps), 'process', 'Buffer']  // 参数列表就是包代码看到的符号面：React 是注入的（JSX 被禁，必须 React.createElement）  let closure: (...args: unknown[]) => Promise<unknown>  // 待求值的闭包工厂；声明在 try 外，catch 分支也能引用  try {    const factory = new Function(...parameters, `return (async () => {\n${clientCode}\n})()`)  // 与 Host 预检完全相同的包装——两半行号一致，错误信息可互换理解    closure = factory  // 编译成功才赋值；SyntaxError 走下面的教学分支  } catch (error) {    if (!(error instanceof SyntaxError)) throw error  // 非语法错误（如内存问题）原样上抛，不伪装成"代码写错了"    throw new Error(`client half failed to parse in this browser: ${error.message}...`)  // 引擎分歧兜底：浏览器只给 message 没有 caret 前缀，补上"纯 JS、无 JSX"的提示  }  const host = {    call: (method: string, args: unknown = null): Promise<unknown> => env.invoke(method, args),  // Client→Host RPC；默认参数是 null 而非 undefined——undefined 不是 JSON，wire 传不过去  }  const returned = await closure(React, taggedConsole(pluginId, ...), styles, host, harnessTrap(), ...Object.values(traps), undefined, undefined)  // 注入符号面：harness 在浏览器侧是 Proxy 陷阱（碰了就教你"那是 Host 半的事"）；process/Buffer 保持 undefined，typeof 探测安全  if (!isDynamicCordisPlugin(returned)) {  // 必须返回函数或带 apply(ctx) 的对象——与 Host 半同一契约    throw new Error('client half returned `undefined` — did you forget `return`?...')  // 最高频错误：忘了 return，给模型一个明确的自查方向

@Remote('invoke')  // 通过 wire 协议暴露给浏览器async invoke(pluginId, pluginRunId, method, args) {  // Client 半调用"本包自己的" Host handler——跨包不可达  const plugin = this.registry.get(pluginId)  // 按 ID 取 Plugin 记录；查不到说明已被 undefine  if (plugin === undefined || plugin.run === undefined) {    return { ok: false, code: 'plugin-not-running', message: `...is not running` }  // 包已停止 → 类型化拒绝，而不是让异常跨 wire 飞过去  }  const run = plugin.run  // 当前激活的 Run——handlers、pluginRunId 都挂在它上面  if (run.pluginRunId !== pluginRunId) {  // stale-run 检查：旧激活的页面不能调用新 Run——防止跨版本 RPC 泄漏（update 后旧页面的闭包还活着）    return { ok: false, code: 'stale-run', message: `activation "${pluginRunId}" is no longer active` }  }  const handler = run.handlers.get(method)  // 只认本次 startHost 期间 harness.handle 注册过的方法——方法表随 Run 生灭  if (handler === undefined) return { ok: false, code: 'method-not-found', ... }  try {    return { ok: true, value: await handler(args) as JsonValue }  // 返回值在边界处 JSON 克隆（normalizeHandler），vm realm 对象绝不跨 wire  } catch (error) {    this.steerHostHandlerFailure(plugin, run, method, failure)  // handler 崩溃 → 诊断 steer 给模型，附"修好同一 Plugin 再 update"的指引    return { ok: false, code: 'handler-error', ...failure }  }}

ctx.on('agent/pre-step', async ({ agent, messages, signal }, next) => {  // 拦截模型每一步：用户消息里出现 @pluginId 时，注入该 Plugin 的上下文  const decision = await next()  // 先跑下游中间件——本钩子只增强不阻断（reject 决策原样放行）  if (decision.kind === 'reject') return decision  // 下游已决定拒绝本步 → 原样放行，注入上下文没有意义  const ids = referencedPluginIds(messages)  // 正则扫描用户消息中的 @<3-6小写字母>-<数字> token——恰好是铸造 ID 的形状，不会误伤普通文本  if (ids.length === 0) return decision  // 无引用 → 零开销，普通对话完全不受影响  const contexts = ids.map((id) => {  // 对每个被引用的 Plugin……    const reference = ctx.dynamicCordisRunner.reference(agent, CordisDynamicPluginId(id))  // ……取身份 + 版本指针（刻意不含源码——token 经济学：先给地图，模型要细节再 inspect_self）    return createUserMessage({ content: [{ type: 'text', text: renderReference(reference) }], ... })  // 渲染成指令块：以该 Package 为基线 → inspect_self 读源码 → define(existing) 追加版本 → run；引用不可用时换成"如实告知用户"的指令  })  return { kind: 'enter', messages: [...decision.messages, ...contexts] }  // 追加在既有上下文之后，模型把它当作用户侧消息看到

private async queryClient(providerId, methodName, input, agent, signal) {  // Client 侧 provider：Host 本地答不了，路由到浏览器页面  const requestId = `inspect-${this.nextRequest++}` as CordisInspectRequestId  // 铸造请求 ID；"第一个有效应答获胜"语义靠 pending Map 保证  const result = new Promise<CordisInspectQueryResolution>((resolve) => {  // 把工具调用挂起成 pending——这正是工具描述里"remains pending until a page answers"的实现    this.pending.set(requestId, { request, method, settle: resolve })  })  const onAbort = (): void => {  // 工具调用被取消 → 以 'cancelled' 结算挂起的 Promise，不留悬空 await    ...pending.settle({ ok: false, reason: 'cancelled', message: `...was cancelled` })  }  signal.addEventListener('abort', onAbort, { once: true })  this.ctx.emit('cordis/inspect-query', request)  // 事件跨 wire 到页面；页面的 provider 通过 resolveInspectQuery（@Remote）应答，第一个有效结果 settle 掉 Promise  const resolution = await result  // 工具在此阻塞直到页面应答或取消——查询是只读的，挂起没有副作用风险

define → run 全链路（含审批与双半激活）

▼

▼

▼

▼

▼