Runtime 语义

Ageniti 把关键行为集中在 runtime 中，因此 CLI、HTTP、MCP、React、JSON automation、dev tool 和 LLM adapter 都共享同一套执行模型。

执行流程

调用一个 action 时，runtime 会按顺序执行这些步骤：

根据名称或对象引用解析 action。
检查该 action 是否支持当前 surface。
用输入 schema 做输入校验。
对受保护 action 执行确认检查。
执行权限检查。
执行中间件链。
结合超时和重试运行 action。
确保输出可以安全序列化为 JSON。
如果声明了输出 schema，则继续做输出校验。
返回结构化的成功或失败 envelope。

Surface 规则

每个 action 通过 supportedSurfaces 声明可用入口。

默认支持的 surface：

cli, json, http, mcp, react, dev, ai-sdk

如果某个 surface 不被支持，runtime 会返回 UNSUPPORTED_SURFACE。

确认规则

当 action 的 requiresConfirmation: true 时，runtime 需要显式确认标记。

默认情况下，destructive action 会自动继承该要求。

不过以下 surface 不会在 runtime 层强制阻塞确认：

react
dev

也就是说，UI 场景下确认流程应由 UI 自己负责，再去调用 action。

权限检查

permissionChecker({ action, input, context }) 可以返回：

true：允许执行
false：拒绝执行，并返回通用授权错误
字符串：拒绝执行，并把该字符串作为错误信息

权限检查失败时，runtime 返回 AUTHORIZATION_ERROR。

超时与重试

超时来源：

action 级别的 timeoutMs
单次调用级别的 timeoutMs

重试来源：

action 级别的 retry
单次调用级别的 retry

只有当错误是可重试的，runtime 才会重试。通常这意味着 action 抛出了 retryable: true 的 AgenitiError，或者超时逻辑把该错误标记为可重试。

retry: true 会被标准化为：

{
  "retries": 2,
  "delayMs": 100
}

重试采用按尝试次数递增的线性退避。

日志、进度与 Artifacts

每次调用都会累积结构化日志和 artifacts。

context.logger 提供：

debug(message, fields?)
info(message, fields?)
warn(message, fields?)
error(message, fields?)

context.progress.report()：

会追加一条日志，其中 fields.type = "progress"
可包含 percent
可附带额外结构化字段

context.artifacts.add()：

若缺少 id 会自动补全
type 默认是 "file"
metadata 会被标准化成对象

成功 Envelope

{
  "ok": true,
  "data": {},
  "artifacts": [],
  "logs": [],
  "meta": {
    "action": "create_task",
    "invocationId": "invocation-id",
    "surface": "cli",
    "durationMs": 12
  }
}

失败 Envelope

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid action input.",
    "issues": [],
    "retryable": false
  },
  "artifacts": [],
  "logs": [],
  "meta": {
    "action": "create_task",
    "invocationId": "invocation-id",
    "surface": "mcp",
    "durationMs": 3
  }
}

常见 Runtime 错误码

核心 runtime 错误码：

ACTION_NOT_FOUND
UNSUPPORTED_SURFACE
VALIDATION_ERROR
CONFIRMATION_REQUIRED
AUTHORIZATION_ERROR
OUTPUT_SERIALIZATION_ERROR
OUTPUT_VALIDATION_ERROR
TIMEOUT
CANCELLED
INTERNAL_ERROR

你还可能在包装层中看到：

INVALID_JSON_RUNNER_PAYLOAD
DEV_SERVER_ERROR
本地 dev server HTTP route 返回的 NOT_FOUND

错误是如何被标准化的

如果 action 抛出：

AgenitiError，则保留其 code、message、issues 和 retryable
AbortError，runtime 返回 CANCELLED
其他任意错误，runtime 返回 INTERNAL_ERROR

CLI Exit Code

内建 CLI 会把 runtime 错误码映射成进程退出码。

重要映射：

VALIDATION_ERROR -> 2
AUTHENTICATION_ERROR -> 3
AUTHORIZATION_ERROR -> 3
ACTION_NOT_FOUND -> 4
EXTERNAL_SERVICE_ERROR -> 5
TIMEOUT -> 124
CANCELLED -> 130
其他错误 -> 1

输出保证

Ageniti 只返回可安全序列化为 JSON 的结果。

如果 action 定义了输出 schema，runtime 会在返回成功前再做一次输出校验。这使得返回 envelope 可以稳定用于 CLI 输出、MCP structured content、自动化测试和机器间集成。