罐头 SDK

Cantelop 运行代理 用于您的应用 在孤立的 Sandboxs 中 具有持久工作空间 . @cantelop/sdk 您的后端如何和它们交谈, 您如何定义每个会话内部的运行 。 它包括了被包装的克洛德代码(Claude Code)吊带,所以一个工作代理App是一个简短的定义文件.

• 应用 : a 已部署的代理,带有名称、会话运行时间及其配置.
• 工作空间 : 耐用文件和数据库,一般每个客户或用户一个. 每个工作区的会议都分享.
• 会话 : 一个谈话或任务。 它的 Sandbox 被闲置并被下个消息所重新启动时会被放出;会话身份仍然可以重新使用.

您定义会话运行时间 。 SDK生成App的边缘API,Cantelop同时部署. 应用软件的使用 项目计划 3。 。 。 .

对于一个本地编辑 远程特工执行, workspace.sync() 将本地目录与工作空间对齐 project/ 文件夹。 SDK包括它的本土文件系统适配器;消费者应用程序不需要Cantelop CLI或Go. Hosted write 仍然被封口等待存储资格.

开始吧

你需要的就是: 爱丽丝

• 22号节点或更新
• Cantelop CLI 0.15.2或更新型: brew install stepandel/tap/cantelop (与 cantelop version(中文(简体) )
• 嵌入器为 linux/amd64 建立支持
• Claude 订阅( Pro 或 Max) 在
• 部署时的 Cantelop 账户

1. 界定应用程序

在空目录中 :

npm init -y
npm pkg set type=module
npm install @cantelop/sdk

添加 cantelop.json,将 CLI 指向您的 App 定义:

{ "schema_version": 3, "definition": "src/cantelop.ts" }

添加 src/cantelop.ts数字 :

import { CantelopClient } from "@cantelop/sdk";
import {
  createClaudeRuntime, claudeAuth, claudeDockerfile,
  type ClaudeSessionCommand, type ClaudeSessionEvent,
  type ClaudeSessionReply, type ClaudeSessionView,
} from "@cantelop/sdk/harnesses/claude";

const cantelop = new CantelopClient();

export const agent = cantelop.app<ClaudeSessionCommand, ClaudeSessionEvent, ClaudeSessionReply, ClaudeSessionView>({
  name: "hello",
  runtime: createClaudeRuntime(),
  auth: claudeAuth,
  dockerfile: claudeDockerfile,
});

这是整个App. createClaudeRuntime 运行股票 Claude Code CLI,为正在进行的工作提供新的投入,并保持持久的对话观点。 当闲置时,如果检查点可用,新输入会恢复已保存的本地对话. claudeAuth 让每个工作空间用用户自己的克洛德订阅签名. claudeDockerfile 是安装了 CLI 的 SDK 维护的 Sandbox 图像 . name 是App的部署弹.

2. 在当地运行

cantelop dev --container

此构建 Sandbox 图像, 为 App 服务 http://127.0.0.1:8787并记录了SDK的证书 local 简介。 Claude的CLI和它的登录助手 都生活在这个形象中 所以请使用 --container编辑后重新启动 src/cantelop.ts。 。 。 .

在第二个终端中,编译后端客户端. 它保留了App的出口和类型,但是没有它的Sandbox代码,因此后端可以导入它:

node --input-type=module -e 'import { buildBackendClient } from "@cantelop/sdk/build"; await buildBackendClient({ definition: "src/cantelop.ts", outdir: ".cantelop/client" })'

cantelop build 财务报告和审定财务报表 cantelop deploy 也写这个客户端. 修改 App 定义时重建它 .

3. 签署和发出迅速通知

保存此后端脚本为 try.mjs数字 :

import { createInterface } from "node:readline/promises";
import { agent } from "./.cantelop/client/client.mjs";
import { applyClaudeSessionChange } from "@cantelop/sdk/harnesses/claude/protocol";

const workspace = agent.workspace({ slug: "ada" });

// Sign the Workspace in to Claude once. The credentials stay in the Workspace.
const auth = workspace.auth();
const login = await auth.login();
if (!login.authenticated) {
  console.log(`Sign in to Claude: ${login.url}`);
  const terminal = createInterface({ input: process.stdin, output: process.stdout });
  const code = await terminal.question("Paste the code: ");
  terminal.close();
  if (!await auth.submitCode({ attemptId: login.attemptId, code })) throw new Error("Sign-in failed");
}

const session = workspace.session();
const id = crypto.randomUUID();
const reply = await session.request({ type: "input", id, text: "Summarize the files in this directory" });
if (reply.type === "error") throw new Error(reply.code);

const snapshot = await session.view();
let state = snapshot.state;
console.log(state);
const finished = () => state.inputs.some(input => input.id === id &&
  ["completed", "failed", "cancelled", "interrupted"].includes(input.status));
if (!finished()) for await (const event of session.stream({ after: snapshot.cursor })) {
  if (event.data.type !== "session.changed") continue;
  state = applyClaudeSessionChange(state, event.data);
  console.log(state);
  if (finished()) break;
}

CANTELOP_PROFILE=local node try.mjs

第一个运行打印 克劳德签入链接。 打开,签入,并粘贴页面显示的代码. 之后运行重用工作空间的证书. 在第一个提示前签入一个工作空间:没有证书,控制带不能运行克洛德,而早前发送的提示失败而不输出.

dispatch() 返回信件被永久承认时,而不是代理完成时. stream() 中继代理的事件.

4. 部署

cantelop login
cantelop deploy --create-app
cantelop app credentials --app hello   # backend configuration, in dotenv form

deploy 构建和上传 App 并刷新 .cantelop/client/。将打印的证书存储在您的后端的秘密仓库中;参见 应用程序配置。然后,每个用户的工作空间一次通过同一程序签名 login() 财务报告和审定财务报表 submitCode() 电话,从你的后端.

运行时逻辑或类型的任何更改都会给 App 新的运行时身份, 所以每次部署 App 时都会重建并重新部署您的后端; 查看 在 App 中部署后端。 。 。 .

从后端使用 App

import { agent } from "./.cantelop/client/client.mjs";

const workspace = agent.workspace({ slug: "customer-123" });
// Or: agent.workspace({ id: canonicalWorkspaceId });
const session = workspace.session({ id: "conversation-456" });

const message = await session.dispatch({ type: "input", id: "issue-123", text: "Investigate this issue" });
const status = await message.status();

后端导入已编译客户端,或将 App 定义与 Cantelop 编译器插件捆绑,该插件会去除 Sandbox 唯一的依赖性 。 导入 src/cantelop.ts 未变形的加载了吊带及其依赖性. 见 运行时间汇编。 。 。 .

CantelopClient 供应共享连接上下文,可选择选择配置文件。 每个 cantelop.app({ name, runtime }) 宣告一个名为 App 的自打运行时间和工作空间命名空间 。 一个客户端可以定义多个App. App名称为部署 satters,独立于JavaScript导出名称. 连接和范围化的证书自动解决每个 App;构建这些对象不会提供资源. 见 应用程序配置。 。 。 .

交通情况如下 backend → SDK → protocol-managed App Edge Worker → outbound Worker/broker → Session runtime。所有 App 操作都使用该版本 { protocolVersion, id, workspace, session, command } 信封,每个在自己的 POST /commands/{type} 路径( r)/commands/dispatch, (中文(简体) ), /commands/view),所以请求日志和Cantelop控制台显示SDK调用每个请求是哪个. Edge QQ Sandbox是独立版本的演员协议. 见 命令和持久视图合同。 。 。 .

工作空间和会话参考文献都很懒. 选择会话 ID 立即生成会话 . dispatch() 懒散地解决/ 提供工作空间弹片, 并在需要时激活 Sandbox 。 警犬工作室的ID从不提供替代。 清晰的分辨率和数据库访问权限共享工作空间参考的缓存元数据。 会话ID是App-scope,即使引用被嵌入到工作空间下.

接受意味着持久的信息接纳,而不是代理完成. 声明回复类型的运行时间,例如 createClaudeRuntime 或自定义控制器,也支持 session.request(message, { timeoutMs })等待一个JSON的答复。 超时或断开结束等待, 不证明执行已停止 。 失败的请求会通过 : RemoteAppError; 重用该ID进行模棱两可的重试。 SDK 不自动重放写入 .

引导、 取消和停止

await session.steer({ type: "steer", id: "focus-auth", text: "Focus on the authentication module" });
await session.cancel(); // { state: "requested" | "idle" }
await session.stop();   // release the Sandbox; the Session identity stays reusable

发送并引导接受相同的消息类型并返回一个ID/状态引用 。 都接受可选 { id, keepAliveSeconds, signal }从方法选项返回到会话引用到配置的 App 默认值。 耐用克洛德运行时间在闲暇时开始输入,在繁忙时指导进行中的工作. 工厂的运行时间 代表发送到绳子 queue 方法与方向 steer 方法;这些工具确定了自己的投入政策.

session.cancel({ id?, signal? }) 没有目标消息ID。 它表示积极管理的活动 或代表工厂的吊带 cancel() 方法. requested 承认中断, 清理未完成; 在清理结算前, 执行仍然为所有 。 闲置时取消不影响后期输入. 重试同一平台命令ID重用其结果,不能中断后续运行.

提交ID服务于收据、重试和输出相关性。 信件状态描述接收, 这样活动的工作可以超过其信件的 handled 状态.

stop() 释放当前 Sandbox 并关闭流, 可能打断工作 。 下一个消息在新的 Sandbox 上激活相同的会话 。 工作空间保存耐用的文件和数据库;会话内存,调用内存和临时文件属于一个Sandbox化身. 多会话可能共享一个工作空间,因此应用程序拥有共享状态的协调.

流出

for await (const event of session.stream({ signal })) {
  console.log(event.data, event.cursor, event.messageId);
}

stream() 是一个对会话 SSE 输出的同步执行器。 元数据包括光标 { streamId, sequence },会话ID,信件ID,和创建时间. 明确恢复 session.stream({ after: savedCursor })。重放被绑定;光标过期后流重置时保留其远程错误代码。 SDK不自动重接.

中断迭代或中止订阅只会关闭其流. 它不会取消代理工作或者让沙盒保持温暖. 浏览器-快取路由仍然是应用程序自身授权后端的一部分.

克洛德的电源 克洛德代码的原生 stream-json 对象。 超过48个基 B 的框架以 native.fragment 事件; 合并它们 json 内 index 命令并分析结果.

在工作空间中签名

声明 auth 让每个工作空间在用户自己订阅的股票CLI上签名. 土著证书留在工作区,所以每个会议都分享这些证书。 仅在属于单一已验证用户的工作空间上使用认证,并从该用户的身份中获取选择器.

app.workspace(selector).auth() 暴露了登录方法. 供货商 codeLogin 适配器,例如 claudeAuth, (中文(简体) ), login() 返回时 {authenticated:true} 或者说 {authenticated:false,attemptId,url,expiresAt}。 。 。 . submitCode({attemptId,code}) 返回本地认证状态或稳定状态 code_rejected 错误,以及 cancelLogin({attemptId}) 停止尝试. login({force:true}) 在开始新登录前确认本地登录 。 SDK拥有尝试,即时解析,限定私人输出,到期和流程清理. 应用程序授权和账户偏好保留在您的后端 .

低级 terminal()编号 :close() 服务于有意暴露CLI自身终端的集成. 主机Cantelop尚未将终端转发给浏览器. 见 本地认证。 。 。 .

配置 Claude 带

为每个会话通过选择模型、工具、快取和限制的选项:

export const agent = cantelop.app<ClaudeMessage, ClaudeEvent>({
  name: "hello",
  runtime: {
    create: (context) => createClaudeHarness(context, {
      model: "sonnet",
      permissionMode: "dontAsk",
      allowedTools: ["Read", "Grep", "Glob"],
      systemPrompt: "Investigate issues and report your findings.",
      maxTurns: 24,
    }),
  },
  auth: claudeAuth,
  dockerfile: claudeDockerfile,
});

选项也涵盖 tools, (中文(简体) ), settingSources, (中文(简体) ), mcps (单位:千美元) conversation 种子 。 当工厂运行时,它们会被快照;SDK上下文提供犬科会话的特性. 没有选项, 吊带保持 CLI 的本土配置, 带有 CLAUDE_MODEL 财务报告和审定财务报表 CLAUDE_PATH 从App宣布的环境读取.

createClaudeRuntime(options) 提供本土流入和持久观测. {type:"input",id,text} 在闲暇时启动跑步,在繁忙时引导同样的跑道; {type:"steer",...} 有着同样的本土行为。 在出版之前,一直坚持接受投入、尝试提供、本土观察和结果. session.view() 返回已承诺的投影; applyClaudeSessionChange 后续应用 session.changed 事件是一流的。 没有后续队列 。 设置可以在运行之间更改;运行返回时不兼容的更改 active_settings_conflict。其协议类型为 @cantelop/sdk/harnesses/claude/protocol编辑 Claude 代码示例 包括两个,加上自定义图像和 NativeClaude 用于定制建筑.

其他运行时间

库存CLI 用于 代码 财务报告和审定财务报表 打开代码 采用与克洛德机具相同的模式,作为例子而不是包装出口. Pi 财务报告和审定财务报表 OpenAI 代理服务器 显示框架集成.

要写你自己的,还一把从 runtime.create数字 :

// src/agent.ts — the harness factory compiled into the Sandbox.
import type { SessionHarness, SessionHarnessContext } from "@cantelop/sdk/session";
import type { Message, Event, Reply } from "./contracts.js";
import { createHarness } from "./harness.js";

export function create(context: SessionHarnessContext): SessionHarness<Message, Event, Reply> {
  return createHarness(context); // Implements queue(message, work), steer(message, work), cancel().
}

工厂运行一次每会场运行时间化身,在第一个牵引指令或恢复上. 它返回一个执行工具 queue(message, work), (中文(简体) ), steer(message, work),以及 cancel()。每个执行系统拥有命令、引导行为、中断和清理。 SDK直接调用这些方法,并让摄入量在承诺仍未兑现时作出反应. queue 在所提交的作业及其清理之后解决;其返回价值用品 session.request() 答复. steer 解决执行的完成边界:可以立即接受本地输入,而中断和重续执行则可以等转向.

工作收到信号,打出输出/视图,提交身份和会话资源. SDK在不选择提供者调度行为的情况下跟踪操作寿命,归属和最后期限. cancel() 返回当前操作是否被标记,并保存等待输入。 编译器将工厂及其附属物捆绑入"沙盒",同时将它们排除在后端和"边缘"的文物外.

自定义运行时间可以使用 runtime: { receive, onActivate?, onRecover?, redelivery? }。其摄入量按序列排列;将长期工作移入 context.activity 与 activity.start, (中文(简体) ), queue, (中文(简体) ), steer,以及 cancel,并通过活动选项登记提供者方法 onSteer 财务报告和审定财务报表 onCancel。 。 。 .

申请拥有持久工作、检查站和公正无私。 可选 onActivate 钩子每个化身恢复一次状态;可选 onRecover 钩选入替换-桑德克回收. 重新交付是用于调试摄入处理器的选择。 成功 receive (a) 承认申请的录取; 长期状态 /workspace 或工作空间数据库。 输出/复制机保持其JSON和尺寸限制.

不需要自定义图像的运行时间可以本地运行 --container平话 cantelop dev 用 Bun 1.3.10 以本地方式运行会话,并在编辑时重建.

持久会议意见

SDK通过平台的持久取景服务承担预测. 读取最后一个承诺的视图不会激活 Sandbox .

运行时间明确承诺应用程序的读取模式:

async function receive(context: SessionContext<Message, Event, Reply, State>) {
  const state = await updateApplicationState(context.message.payload);
  await context.view.commit(state);
  context.reply(state);
}

view.commit 在平台存储投影及其原子事件边界后解决。 客户端代码拥有应用程序状态和恢复;执行视图不会取代应用程序的数据库或重放其运行时间关闭.

const snapshot = await session.view();
render(snapshot.state);
for await (const event of session.stream({ after: snapshot.cursor })) {
  apply(event.data);
}

监督活动也可以称为自己的 view.commit(state) 活动时的能力。 这种能力遵循活动信号,并在活动结束时关闭.

读取的视图从不打开工作空间或激活 Sandbox 。 缺少预测返回 session_view_not_found。视图幸存的停止和主机重新启动;流恢复取决于该平台的限定回放保留。 投影承诺推进流光标而不作为应用事件出现 .

实例

• 克劳德代码: 包装的带子、链接/编码签入和耐用 createClaudeRuntime 生命周期.
• 网络聊天: 浏览器 – 应用程序后端 – CantelopClient 一体化.
• GitHub 发行代理: a App webhook,通过同一个App接口验证签名的送出和发送.
• 多笔:两个App在一个客户端下.
• 所有实例,包括Codex,OpenCode,Pi和OpenAI代理.

工作空间数据库 包括续约、交易和计划迁移.

开发 SDK

pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm test:native
pnpm check:examples
pnpm check:package
pnpm test:bun

包资资格检查实际npm的柏油球及其被包装的文件,生成了Edge和原生跑道建造的文物,以及清洁的消费者的融合类型. 出版是一个单独的操作;参见 发布指导。 。 。 .

定义共享应用程序 cantelop.fleet({...}) 并通过 fleet.instance(...)。见 车队和实例 使用寿命周期、打入App接入和CLI整合合同.