@chamvi/http (中文(简体) )

REST,SSE,为chamvi代理服务的webhooks和MCP,在routup上.
每个chamvi应用一个routup App:人类启动和跟踪运行在REST和SSE,
频道收货 /channels/<name>,代理调用为 MCP 工具.

目录

• 安装
• 使用量
• 终点
• 权限
• 认证器
• 频道
• MCP工具
• 业务
• 关闭
• 选项
• API 密码
• 许可证

安装

npm install @chamvi/http @chamvi/core --save

仅限无害环境管理,节点.js >=26.0.0。 。 。 . @chamvi/core 是同龄人依赖; 错误 v6,该 MCP 类型脚本 SDK v2, (英语), 当然 而认证服务器适配器则安装在软件包中.

使用量

createHttpApp() 返回 rout 键 App· ; app.fetch(request) 回答任何工作组 Request和鲁特的 serve() 监听端口:

import type { LanguageModel } from 'ai';
import { Engine, createMemoryStore, defineModelAgent } from '@chamvi/core';
import {
    createHttpApp,
    createShutdown,
    http,
    httpChannel,
    mcpChannel,
    staticTokens,
} from '@chamvi/http';

export async function createAgentServer(model: LanguageModel) {
    const echo = defineModelAgent({
        name: 'echo',
        model,
        instructions: 'Answer with a short summary of the payload.',
        // http.on() lets REST (POST /agents/echo/runs) and MCP (run_echo) start runs
        channels: [http.on()],
    });

    const engine = new Engine({
        store: createMemoryStore(),
        agents: [echo],
        // REST runs carry channel http, MCP runs channel mcp
        channels: [httpChannel(), mcpChannel()],
    });

    const token = process.env.CHAMVI_TOKEN;

    if (!token) {
        throw new Error('Set CHAMVI_TOKEN (at least 16 characters).');
    }

    const shutdown = createShutdown({ engine });
    const app = createHttpApp({
        // routes read the store, the agents and the clock from the engine
        engine,
        auth: staticTokens({
            tokens: [{
                value: token,
                id: 'ci',
                permissions: ['*'],
            }],
        }),
        shutdown,
    });

    await engine.start();

    // serve it with routup (srvx); let createShutdown own SIGTERM:
    // const server = serve(app, { port: 3000, gracefulShutdown: false });
    // process.once('SIGTERM', () => shutdown.shutdown());
    return {
        app,
        engine,
        shutdown,
    };
}

每条路线都会回答JSON. 错误总是 { status, code, message, issues? } (对于无与伦比的路线也是如此)一个5xx的身体说 Internal Server Error 和事业走向 onError。一个问题保持其 received 值只当这个字符最多为 256 个字符为 JSON 时,所以一个 400 个字符从未与一个大体相呼应( 超大小) attachments 列表,长 address 或媒体类型)后. 每401个 WWW-Authenticate: Bearer。 。 。 .

终点

路径相对 basePath (默认无).

GET /runs 拿着 拉皮克语 URL 语法 : filter[agent]=triage, (中文(简体) ), filter[status]=queued,running, (中文(简体) ), page[limit]=20 (违约50起,最多100起), page[offset]=40 财务报告和审定财务报表 sort=createdAt (最古老的,默认)或 sort=-createdAt (最新第一). 表达式方言也起作用( :filter=eq(agent,'triage'); 仅加入过滤器 and 被支持。 未知的密钥, 运算符和类型 回答 400 .

机构是JSON(application/json 或者说 *+json),最多时 bodyLimit 字节( 上面413个, 另一种介质类型为 415个) 。 被拒绝的尸体被排出(至多 bodyLimit 更多字节),所以保持-活性连接服务于下个请求;一个较长的连接会关闭连接. 一个受保护的路由在读取正文之前检查了无记名符号,所以一个未经认证的客户端不能让服务器缓冲. 未知的正文密钥被丢弃而不出错 。 NUL 字符 (U+000, Postgres 文本列拒绝此字符) 在 URL 中, 在一个 idempotencyKey, (中文(简体) ), address 或其他字符串字段,或者在密钥中,网钩来自其有效载荷答案400.

attachments 最多取取16个文件 { mediaType, filename?, data }数字 : mediaType 实值 type/subtype 没有参数, filename 1到255个字符, data 严格的基数64(加法、标准字母、无白空格);其他的都是400 validation_error 与球场的路径, 和什么也没有发出。 这些文件作为运行的文物被存储(参见: @chamvi/core),并交给模型作为文件部件. 基地64骑 在JSON的身体,所以 bodyLimit 也绑定文件 .

GET /runs/:id 403前的答案 404,所以任何认证的正本都可以分辨是否存在运行的ID;运行的ID是随机的UUID. 在铁丝网上跑来跑去的 claim (所有权和租赁).

POST /agents/:name/runs 和 MCP 软件 run_<agent> 将认证的本金记录为运行的援引者(run.trigger.invoker数字 : id, (中文(简体) ), kind, (中文(简体) ), permissions,则a name 从 name 或者说 preferred_username 索赔,从未 email,因为每个读取器看到它;静态符号没有),所以工具代码和一个核心 toolPolicy 能分辨是谁发动了这次逃亡. POST /runs/:id/approve 和 MCP 软件 approve_run 将批准人记录在 wait 步数( e)output.approver) (中文(简体) ). 两者都只来自认证者,从不来自一具尸体. Webhook 运行没有引用器 。 请求人和批准人离开包件(REST、SSE、MCP),而无需他们 permissions,所以一个 run:read 持有者从不学习另一本金.

SSE 流跟随运行 engine.on 和民意测验 商店每 stream.pollMs (default 2 s)),因此它也会在另一个复制品上看到运行执行. delta 活动(data: { step, kind: 'text' | 'reasoning', text }) 前进引擎的 run.delta 当模型写(step 是该 llm 步骤生成(每个模式调用一个),而不是 step.appended id,这也算 tool 财务报告和审定财务报表 wait 他们没有 id (单位:千美元)Last-Event-ID 继续保留一个步骤索引),从不重放,只来自执行运行的复制品. Last-Event-ID 步骤索引后恢复;查询 ?after=<step index> 对于不能设置头号的客户端(一个非负整数,给定一次,否则为400个)也这样做。 当两者都存在时 Last-Event-ID 胜出, 因为它包含客户端在重新连接上的进展, 而 URL 则保持第一个连接; 错误的 Last-Event-ID 读作缺席 ?after 适用.

溪流只取无记名符. 浏览器 EventSource 无法发送 Authorization 标题,所以浏览器会读取以获取为基础的SSE读取器(fetch 附加一个 SSE 解析器以覆盖响应体 ) Authorization 当它重新连接的时候, Last-Event-ID 最后一个 id (或 ?after=) (中文(简体) ).

每个应用程序都覆盖开放的SSE流和MCP run_<agent> 呼唤等待waitSeconds (单位:千美元) stream.maxOpen (默认1000,两个都有一个计数器). 盖子上的一股流回音 503 { code: 'service_unavailable' } 与 Retry-After: 5 (未报告) onError; MCP 调用上限不会等待并立即以 { runId, status, deduplicated },如同 waitSeconds: 0,因为它已经发出运行。 当流结束( 确定运行、 客户端消失、 失败、 关闭) 或等待答案时, 空出一个空格 ; 一个客户端在没有请求信号中止的情况下取消机体在下次写入时释放它 stream.pollMs。 。 。 .

权限

A 类 * 段完全匹配一个段 : agent:*:run 赠款 agent:triage:run 但没有 agent:triage:approve,以及 agent:* 也没有赠款。 匹配是区分大小写. agentPermission(agent, action) 导出; 自己检查本金, 使用 hasPermission(principal.permissions, permission) 从 @chamvi/core路线使用的匹配器.

POST /runs/:id/approve { approvalId, approved, reason? } 单凭批准权限回答当前等待点; 另一条 approvalId 而不是跑的当前,一个已过期的等待点,一个没有等待的跑和第二个答案是409.

认证器

auth 使用一个认证器或链;第一个主胜。 认证器决定 undefined 对于它不承认的请求(链条在继续),它会拒绝401个证书。 解决的本金需要非空的 id 财务报告和审定财务报表 kind (单位:千美元) permissions 数组字符串; 其它任何东西都是服务器配置错误( 500, 报告给) onError)并结束链.

const ciToken = process.env.CI_TOKEN;
auth: [
    // static tokens first: authup() in remote mode introspects every non-JWT bearer
    ...(ciToken ?
        [staticTokens({
            tokens: [{
                value: ciToken,
                id: 'ci',
                permissions: ['agent:deploy:run'],
            }],
        })] :
        []),
    // an authup TokenVerifier in remote mode (with a creator), so tokens carry their grants
    authup({ verifier }),
    oidc({ issuers: [githubActions], principal: mapGithubClaims }),
],

• staticTokens({ tokens: [{ value, id, permissions }] }):无记名标志(value)至少16个字符,相较于SHA-256文摘. A 类 value 可能出现一次;若干个符号可能共享 id,因此一个旋转的令牌可以与旧令牌相重叠. 符合CI和服务账户。 放进去 在此之前 authup() 财务报告和审定财务报表 oidc()数字 : authup() 在远程模式下,将每个不是JWT的持卡人发送到认证服务器的内向端点,因此在每次请求时都会向服务器泄露后放入一个静态符号.
• authup({ verifier }):通过核查 @authup/server-adapter-web。只在其 scope 包含 global其他信使保留他们的身份,却一无所获(因此他们回答403)。 本地核查总是不能产生许可:赠款需要远程模式(creator,内论. 权限 policies, (中文(简体) ), realm_id 财务报告和审定财务报表 client_id 不予评价。 缓存( Caching): 缓存结果会送达到符号 exp,所以在本地模式下,它比已禁用的签名密钥有效,而在远程模式下,则比已取消的令牌有效(maxRemoteCacheTTL 边框远程缓存; 无 cache没有缓存.
• oidc({ issuers, principal }): 任何 OIDC 发行者通过担保,例如 GitHub 动作符. 每个发行商都需要一个 audience (碰巧跳过 aud 不检查一个,所以一个公共发行人 的标志任何观众通过; oidc() 以其他方式投掷). principal 实值 所需经费 并将经核实的索偿要求映射给本金(或 undefined 拒绝:公众发行商让任何人为观众铸造一个纪念物 sub 或者说 repository 获得哪些补助。 未配置到下个验证器的发证人发证;无法到达的发证人回答503.

频道

代理订阅频道defineModelAgent({ channels: [...] }),参见 @chamvi/core); 引擎持有通道实例(new Engine({ channels })) (中文(简体) ). 这个包裹三号船:

• httpChannel() (名称) http和 mcpChannel() (名称) mcp: 没有 in,没有 out。 。 。 . http.on({ schema? }) 是控制平面订阅( id http中,每个代理最多一个: POST /agents/:name/runs 开始作为频道运行 http,和 MCP 软件 run_<name> 作为频道 mcp,所以两者保持单独的同能范围. 一个没有它的代理在REST上回答404,没有获得MCP工具. schema (任何标准Schema)验证有效载荷;故障回答400与 issues。引擎拒绝 http.on() 订阅,除非持有 httpChannel()。 。 。 .
• webhookChannel({ auth, name?, bodyLimit? }) (名称) webhook 默认 : webhook.on(path, { schema?, idempotencyKey?, concurrencyKey? }) (单位:千美元) webhook:<path>(每个代理商中有许多人)在代理商的手下按自己的路径提供服务: webhook.on('/issues') 关于代理人 intake 实值 POST /channels/webhook/intake/issues,路径 / 实值 /channels/webhook/intake (单位:千美元)GET /agents 每个列表 hook URL) (中文(简体) ). 比赛是准确的, 包括了后遗症。 交货需要主要 auth (一个认证器或一个链条,作为应用程序的) auth; 需要, 因为应用程序从未认证频道路线) 持有 agent:<agent>:run,在读取尸体前检查。 尸体是JSON价值最多 bodyLimit 字节(默认为 1 MiB;上方为413,为另一种介质类型为415),是有效载荷. 独能键来自 Idempotency-Key 信头,其他来自 idempotencyKey(payload);用一键再试出货,产生一跑. 它立即回答202, 并且从不同步运行代理; 运行不携带引用器 。 二审(webhookChannel({ name: 'hooks', auth })(b) 自行订阅 on()。签名验证的网络呼号(GitHub)是 @chamvi/github频道.

createHttpApp({ channels }) 挂载 POST /channels/<name> 财务报告和审定财务报表 POST /channels/<name>/... (每个频道都需要一个) in 并且必须是引擎在其名称下持有的对象;否则 InvalidAgentDefinitionError) (中文(简体) ). 这些路线是限速的,但从未被应用认证:每个频道检查自己的资质. in({ request, subpath }, ctx) 获取原始请求( 未读; 用此软件包读取) readRequestBody(request, { limit }),它回答超过极限的413,并关闭连接)和生子路径('' 对于赤裸的路径, 否则从 /,仍然以百分比编码) ctx.dispatch 作为频道发送。 内容 Response 已按原样发送; 抛出的错误会像任何路径的错误。 任何其他 /channels/... 路径为 404.

MCP工具

/mcp 是一个可流式的HTTP MCP端点(MCP TypeSDK v2;2025-时代的客户端在无国籍状态下得到服务),具有与REST相同的无记名认证. 客户所看到的工具取决于其主因:

• run_<agent> 列出每个代理人,并附有 http.on() 订阅主机可运行( 运行带频道) mcp页:1 payload 带有订阅图的 JSON Schema( 本地 $ref重新扎根于 payload) (中文(简体) ). 工具定义在 createHttpApp,该投出 InvalidAgentDefinitionError 对于有效载荷计划, MCP 验证器无法编译或工具名称高于 MCP 允许的 64个字符( 代理名称高于 60; 设置) mcp: false 保留它. waitSeconds (默认 0) 等待 completed, (中文(简体) ), failed, (中文(简体) ), cancelled 或者说 waiting最多 mcp.maxWaitSeconds (默认 60; 较大值被夹住). 等待一个应用程序的 stream.maxOpen 插槽; 全部同时带回调用 { runId, status, deduplicated }一样 waitSeconds: 0,运行开始。 等待者每隔一秒钟就对商店进行民意测验,所以在另一个复制品上看到跑步被处决,当客户离开时就停止. A 类 waiting 回答工具的名称和批准 title 财务报告和审定财务报表 body。 。 。 .
• 同上,propotency keys是每个代理商、信道和主机的范围: MCP 启动取消 <agent>:mcp:<kind>:<id>,在 <agent>:http:<kind>:<id> (校长的 kind 财务报告和审定财务报表 id, URI- encoded)),所以在两种运输方式上使用的一键,或者由两个主键,创建了两跑. Webhook 开始在下面不带引用器和调试器 <agent>:webhook。 。 。 .
• get_run 财务报告和审定财务报表 list_runs 遵循 REST 读取规则; 被拒绝的权限和未知的运行作为工具错误返回( )isError) (中文(简体) ).

业务

• /metrics 不认证(scrapers 很少发送无记名符号): 防止公众侵犯(网络政策,或单独的内部倾听者),或使其无法使用 metrics: false。每个应用程序都有自己的 prom-client Registry; 数据 path 标签是路由模板(/runs/:id, (中文(简体) ), /channels/:name/*; 未知路径为 /_unmatched),所以ids和探测器不是薄荷系列. SSE流和限速请求没有定时. metrics.normalizePath 覆盖标签.
• 费率限制默认每个客户地址每分钟300个请求, /healthz, (中文(简体) ), /readyz, (中文(简体) ), /metrics 和CORS的飞行前。 关键是套接字地址, 除非 trustProxy 设置:在反向代理后,设置(例如:. 'loopback' 或一个hop计数)或每个客户共享代理的桶; X-Forwarded-For 从来没有信任过。 没有套接字地址( 正在进行中) app.fetch, unix sockets) 所有客户共享一桶.
• (简体中文) 关闭,除非 cors 已提供(@routup/cors 选项).
• 准备情况 关闭时失败, 引擎会排出, 或商店内部不回答 readyTimeoutMs。 。 。 .

关闭

createShutdown() 运行关闭顺序 : 无法准备, 等待 readinessDelayMs运行 onShutdown 按添加顺序调回( http app的自有端打开 SSE 流和 MCP) run_<agent> 等待(以存储的运行方式等待答案),关闭 MCP;新流和 MCP 请求然后回答 503 , 停止接受连接, engine.drain() (它先是停止每个频道,其中的曲折排程) 然后最多等待 closeTimeoutMs 在关闭前打开连接。 过 gracefulShutdown: false 改为 serve() 因此 srvx 不安装自己的信号处理器 :

import { serve } from 'routup';

let server: ReturnType<typeof serve> | undefined;
const shutdown = createShutdown({
    engine,
    // the server is created after the app; the helper only calls close() at shutdown
    server: { close: async (force) => { await server?.close(force); } },
});
const app = createHttpApp({ engine, auth, shutdown });
server = serve(app, { port: 3000, gracefulShutdown: false });

process.once('SIGTERM', () => {
    void shutdown.shutdown();
});

shutdown.onShutdown(fn) 添加您自己的清理; 在准备失败后和服务器关闭前运行 .

选项

createHttpApp(options)数字 :

createShutdown(options)数字 :

API 密码

类型 : HttpAppOptions, (中文(简体) ), McpOptions, (中文(简体) ), CorsOptions, (中文(简体) ), RateLimitOptions, (中文(简体) ), PrometheusOptions, (中文(简体) ), TrustProxyInput, (中文(简体) ), Principal, (中文(简体) ), Authenticator, (中文(简体) ), PermissionName, (中文(简体) ), AgentAction, (中文(简体) ), StaticToken, (中文(简体) ), StaticTokensOptions, (中文(简体) ), AuthupOptions, (中文(简体) ), OidcOptions, (中文(简体) ), IShutdown, (中文(简体) ), ShutdownOptions, (中文(简体) ), RunView, (中文(简体) ), InvokerView, (中文(简体) ), RunListQuery, (中文(简体) ), RunSummary, (中文(简体) ), RunToolResult, (中文(简体) ), AgentSummary, (中文(简体) ), ScheduleSummary, (中文(简体) ), ScheduleOverlap, (中文(简体) ), WebhookChannel, (中文(简体) ), WebhookChannelOptions, (中文(简体) ), HttpSubscriber, (中文(简体) ), HttpSubscriptionOptions, (中文(简体) ), WebhookSubscriber, (中文(简体) ), WebhookSubscriptionOptions。 。 。 .

许可证

原载 Apache 许可证 2.0。 。 。 .