@ct-agents/protocol 0.0.1

package/src/tool.ts

@@ -0,0 +1,275 @@
+import type {
+  AgentActionRequestedPayload,
+  SessionEvent,
+  SessionRecord,
+  SessionStore,
+  ToolErrorPayload,
+} from './session/index.js';
+import { isSessionEventType as isCoreSessionEventType } from './session/index.js';
+import type { EnvironmentExecutionMode, EnvironmentHostedPolicy, ResourceSlots, SchemaContract } from './environment.js';
+import type { HarnessInfo } from './harness.js';
+
+/**
+ * 工具对外元数据：供 LLM 决定是否调用、以及前端展示。
+ *
+ * `inputSchema` / `resultSchema` 为 JSON Schema 形态的描述（面向模型与 UI），
+ * 与 {@link ToolHandler.inputSchema} 的运行时校验契约（{@link SchemaContract}）是两件事：
+ * 前者是「声明」，后者是「执行时校验」。
+ */
+export type ToolDescriptor = {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  resultSchema: Record<string, unknown>;
+  /** 工具执行前必须由 environment 绑定的 resource slot。 */
+  requiredResources?: string[];
+  annotations: {
+    readOnly: boolean;
+    idempotent: boolean;
+    openWorld: boolean;
+    destructive: boolean;
+  };
+};
+
+/**
+ * 工具执行产出的副作用。工具本身不直接写 session 事件，而是通过 effects 声明意图，
+ * 由 {@link Environment} 统一落库为 session 事件，保证「工具生命周期事件唯一写入者」。
+ */
+export type ToolEffect =
+  | { type: 'custom.event'; eventType: string; payload: unknown }
+  | { type: 'agent.action.request'; payload: AgentActionRequestedPayload };
+
+export type ToolEffectValidationResult =
+  | { valid: true; effect: ToolEffect }
+  | { valid: false; message: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeActionKind(value: unknown): AgentActionRequestedPayload['kind'] | null {
+  return value === 'ask_user' || value === 'tool_confirmation' || value === 'custom_tool_result'
+    ? value
+    : null;
+}
+
+function parseExternalActionPayload(value: unknown): ToolEffectValidationResult {
+  if (!isRecord(value)) {
+    return { valid: false, message: 'agent.action.request.payload 必须是对象' };
+  }
+  const kind = normalizeActionKind(value.kind);
+  if (!kind) {
+    return { valid: false, message: 'agent.action.request.payload.kind 无效' };
+  }
+  if (kind === 'custom_tool_result') {
+    return {
+      valid: false,
+      message: '外部 worker 不能创建 custom_tool_result action；该 action 只能由 hosted app catalog action-backed shim 产生',
+    };
+  }
+  const display = isRecord(value.display)
+    ? {
+        ...(typeof value.display.title === 'string' ? { title: value.display.title } : {}),
+        ...(typeof value.display.summary === 'string' ? { summary: value.display.summary } : {}),
+      }
+    : undefined;
+  return {
+    valid: true,
+    effect: {
+      type: 'agent.action.request',
+      payload: {
+        kind,
+        ...(typeof value.prompt === 'string' ? { prompt: value.prompt } : {}),
+        ...(Object.prototype.hasOwnProperty.call(value, 'input') ? { input: value.input } : {}),
+        ...(Array.isArray(value.allowedResults) ? { allowedResults: value.allowedResults } : {}),
+        ...(display && (display.title || display.summary) ? { display } : {}),
+        ...(typeof value.expiresAt === 'string' ? { expiresAt: value.expiresAt } : {}),
+      },
+    },
+  };
+}
+
+const RESERVED_SESSION_EVENT_PREFIXES = ['user.', 'assistant.', 'tool.', 'agent.', 'session.'] as const;
+
+function isReservedSessionEventNamespace(eventType: string) {
+  return RESERVED_SESSION_EVENT_PREFIXES.some((prefix) => eventType.startsWith(prefix));
+}
+
+/**
+ * 校验跨进程 worker 可回传的 tool effect。
+ *
+ * 外部 worker 持有环境密钥，但不应能伪造核心生命周期事件，也不能直接创建
+ * `custom_tool_result` action。保留 session 事件命名空间也禁止外部 worker 使用，
+ * 避免未知核心事件被提前伪造；业务扩展事件应使用非核心命名空间。
+ */
+export function parseExternalToolEffect(value: unknown): ToolEffectValidationResult {
+  if (!isRecord(value)) {
+    return { valid: false, message: 'effect 必须是对象' };
+  }
+  if (value.type === 'custom.event') {
+    const eventType = typeof value.eventType === 'string' ? value.eventType.trim() : '';
+    if (!eventType) {
+      return { valid: false, message: 'custom.event.eventType 必须是非空字符串' };
+    }
+    if (isCoreSessionEventType(eventType)) {
+      return { valid: false, message: `外部 worker 不能通过 custom.event 写核心事件：${eventType}` };
+    }
+    if (isReservedSessionEventNamespace(eventType)) {
+      return { valid: false, message: `外部 worker 不能通过 custom.event 写保留事件命名空间：${eventType}` };
+    }
+    return {
+      valid: true,
+      effect: {
+        type: 'custom.event',
+        eventType,
+        payload: value.payload,
+      },
+    };
+  }
+  if (value.type === 'agent.action.request') {
+    return parseExternalActionPayload(value.payload);
+  }
+  return { valid: false, message: 'effect.type 必须是 custom.event 或 agent.action.request' };
+}
+
+/** 工具执行完成：携带返回给模型的结果与可选副作用。 */
+export type ToolExecutionCompleted<TResult> = {
+  status: 'completed';
+  modelResult: TResult;
+  effects?: ToolEffect[];
+};
+
+/** 工具执行暂停：需要人工 action（如 ask-user / 工具确认）才能继续。 */
+export type ToolExecutionPaused = {
+  status: 'paused';
+  effects: ToolEffect[];
+};
+
+/** 工具执行失败：携带结构化错误，供 session 事件落库与重试决策。 */
+export type ToolExecutionFailed = {
+  status: 'failed';
+  error: ToolErrorPayload;
+  effects?: ToolEffect[];
+};
+
+/** 工具执行结果三态：完成 / 暂停（待 action）/ 失败。 */
+export type ToolExecution<TResult> =
+  | ToolExecutionCompleted<TResult>
+  | ToolExecutionPaused
+  | ToolExecutionFailed;
+
+/** 工具执行状态字面量，供跨进程 work queue 契约复用。 */
+export type ToolExecutionStatus = ToolExecution<unknown>['status'];
+
+/**
+ * 工具执行上下文：运行时注入给 handler 的只读环境。
+ *
+ * - `session` / `harness`：当前会话与 harness 配置快照。
+ * - `resources`：按环境配置实例化的资源（数据库 / sandbox 等业务能力）。
+ * - `toolCallEvent`：本次调用的 `tool.called` 事件，effects 以其为 parent 落库。
+ * - `abortSignal`：用户中断 / 会话停止时触发，handler 应及时终止。
+ */
+export type ToolHandlerContext = {
+  session: SessionRecord;
+  /**
+   * 当前会话绑定的 store（scope-free SessionStore），可选。
+   *
+   * Environment 主流程（executeTool / settleResolvedActions）总会注入；少数无 session 持久化
+   * 的调试入口可不传。子 Agent 委派工具据此为子 session 创建/驱动执行（见 §3.4/§4.4 决策 B），
+   * 用前应检查非空。普通工具一般不直接写事件——事件写入仍由 Environment 统一负责。
+   * 这一字段把「可写 session 的 store」暴露给工具 handler，因此「Environment 唯一写入者」
+   * 由结构保证降级为纪律约束（一方工具均为可信代码，可接受）。
+  */
+  sessionStore?: SessionStore;
+  harness: HarnessInfo;
+  executionMode: EnvironmentExecutionMode;
+  hostedPolicy?: EnvironmentHostedPolicy;
+  resources: ResourceSlots;
+  toolCallEvent: SessionEvent<'tool.called'>;
+  abortSignal?: AbortSignal;
+};
+
+/** 工具调用落库前的输入校验上下文；此时尚未创建 `tool.called` 事件。 */
+export type ToolPrepareInputContext = Omit<ToolHandlerContext, 'toolCallEvent'>;
+
+/**
+ * descriptor 动态解析上下文：orchestrator 在「组装工具列表交给模型」前注入。
+ *
+ * 仅含 wake 时已就绪、且产出 descriptor 所需的最小快照（当前会话 + harness）。
+ * 工具据此把「目录/索引」等会随会话变化的内容注入自身 description（见 {@link ToolHandler.resolveDescriptor}）。
+ */
+export type ToolDescriptorContext = {
+  session: SessionRecord;
+  harness: HarnessInfo;
+  resources: ResourceSlots;
+};
+
+/**
+ * 工具恢复执行输入：当暂停态的 action 被用户解决后，重新进入 handler 时携带的上下文。
+ *
+ * `originalInput` 为首次调用的入参；`actionEvent` / `resolvedEvent` 把 action 的请求与
+ * 解决结果成对交还给 handler，使其据此完成后续逻辑。
+ */
+export type ToolResumeInput<TInput> = {
+  originalInput: TInput;
+  actionEvent: SessionEvent<'agent.action.requested'>;
+  resolvedEvent: SessionEvent<'user.action.resolved'>;
+};
+
+/**
+ * 工具实现契约。
+ *
+ * 一个工具 = 元数据（descriptor）+ 运行时校验（inputSchema / resultSchema）+ 行为（execute / resume）。
+ * `inputSchema` / `resultSchema` 是 {@link SchemaContract}：协议只要求「能 parse」，
+ * 不绑定具体校验库；实现侧统一使用 zod（其 `ZodType` 结构兼容本契约）。
+ *
+ * `resume` 可选：声明该工具支持「暂停 → 等待用户 action → 恢复」的交互模式（如 ask-user）。
+ * 无 `resume` 的工具被 action 暂停后将无法恢复。
+ */
+export interface ToolHandler<TInput = unknown, TResult = unknown> {
+  /** 对外元数据，供 LLM 调用决策与前端展示。 */
+  descriptor: ToolDescriptor;
+  /**
+   * 可选：按当前会话/harness 动态产出 descriptor（默认用静态 {@link descriptor}）。
+   *
+   * orchestrator 在把工具列表交给模型前对每个工具调用一次，让工具把「目录/索引」等会随
+   * 会话变化的内容注入自身 description（如 load-memory 注入根索引、load-skill 注入关联 Skill 目录）。
+   * 实现应自带兜底：解析失败时回退静态 descriptor，不得让单个工具的 digest 失败阻断整次 wake。
+   */
+  resolveDescriptor?(context: ToolDescriptorContext): Promise<ToolDescriptor>;
+  /** 入参运行时校验契约：Environment 在执行前用它校验模型传入的 input。 */
+  inputSchema: SchemaContract<TInput>;
+  /** 结果运行时校验契约：Environment 在落库 tool.completed 前用它校验 handler 返回值。 */
+  resultSchema: SchemaContract<TResult>;
+  /**
+   * 可选：需要当前 session/app 上下文才能解析 schema 的工具，可在写 `tool.called` 前异步校验输入。
+   * 未提供时，Environment 使用同步 `inputSchema.parse`。
+   */
+  prepareInput?(input: unknown, context: ToolPrepareInputContext): Promise<TInput> | TInput;
+  /**
+   * 执行工具，返回三态结果（完成 / 暂停 / 失败）。
+   * 副作用通过 effects 声明，由 Environment 统一落库；handler 不应直接写 session 事件。
+   */
+  execute(input: TInput, context: ToolHandlerContext): Promise<ToolExecution<TResult>>;
+  /**
+   * 恢复暂停的工具。当 action 被 user.action.resolved 解决后由 Environment 调用，
+   * 使工具据解决结果完成后续逻辑。仅声明了 resume 的工具可被恢复。
+   */
+  resume?(input: ToolResumeInput<TInput>, context: ToolHandlerContext): Promise<ToolExecution<TResult>>;
+}
+
+/**
+ * 工具注册中心：按名称查找工具实现、枚举可用工具元数据。
+ *
+ * 由 apps/api 装配时填充具体实现（如 InMemoryToolRegistry / CompositeToolRegistry），
+ * 运行时（harness / orchestrator）面向本接口编程，不依赖具体实现类。
+ */
+export interface ToolRegistry {
+  /** 按工具名查找实现；不存在时由实现决定抛错或返回（当前实现抛 ToolNotFoundError）。 */
+  getTool(toolName: string): ToolHandler<unknown, unknown>;
+  /** 枚举所有已注册工具的对外元数据，供 LLM 工具列表与前端展示。 */
+  listTools(): ToolDescriptor[];
+  /** 可选：运行时动态追加工具（用于子 Agent 委派工具等按需注册场景）。 */
+  addTool?(handler: ToolHandler): void;
+}

package/src/work-queue.ts

@@ -0,0 +1,113 @@
+import type { ToolExecutionResult, ToolWorkItem } from './tool-exec.js';
+import type { EnvironmentExecutionMode } from './environment.js';
+
+/** 长轮询认领工作项的输入。按 app + environment 双维度限制 worker 权限。 */
+export interface ClaimWorkItemsInput {
+  appId: string;
+  environmentId: string;
+  /** 最长阻塞毫秒数；实现可按自身传输限制裁剪。 */
+  blockMs?: number;
+  /** 可选取消信号；仅用于进程内 SPI，不属于 HTTP wire body。 */
+  abortSignal?: AbortSignal;
+  /** 单次最多认领数量。 */
+  max?: number;
+  /** 可选执行面过滤；不传时保持旧 worker client 兼容。 */
+  executionMode?: EnvironmentExecutionMode;
+}
+
+/** lease 过期重认领输入。 */
+export interface ReclaimWorkItemsInput {
+  appId: string;
+  environmentId: string;
+  olderThanMs: number;
+  /** 可选执行面过滤；用于 hosted/self-hosted worker 只回收自己执行面的 lease。 */
+  executionMode?: EnvironmentExecutionMode;
+}
+
+/** 查询工作队列观测指标的输入。 */
+export interface GetWorkStatsInput {
+  appId: string;
+  environmentId: string;
+  /** 可选执行面过滤；用于观测单个执行面的队列深度。 */
+  executionMode?: EnvironmentExecutionMode;
+}
+
+/** 按调用方 scope 查询单个 work item，用于 resource proxy 等执行面二次校验。 */
+export interface GetWorkItemInput {
+  workId: string;
+  appId: string;
+  environmentId: string;
+  executionMode?: EnvironmentExecutionMode;
+}
+
+export type WorkItemSnapshotState = 'queued' | 'leased' | 'completed' | 'settled' | 'dead_letter';
+
+export interface WorkItemSnapshot {
+  item: ToolWorkItem;
+  state: WorkItemSnapshotState;
+}
+
+/** complete 的调用方已认证范围；HTTP wire body 不携带这些字段，由服务端鉴权层注入。 */
+export interface CompleteWorkItemScope {
+  appId: string;
+  environmentId: string;
+  /** 可选执行面过滤；外部 self-hosted worker 不应能 complete hosted 工作项。 */
+  executionMode?: EnvironmentExecutionMode;
+}
+
+/** 工作队列观测指标，对齐 Managed Agents work.stats 的核心字段。 */
+export interface WorkStats {
+  depth: number;
+  pending: number;
+  oldestQueuedAt: string | null;
+  workersPolling: number;
+}
+
+/**
+ * 业务 tool 工作队列 SPI。
+ *
+ * 平台实现负责 enqueue、lease、complete 幂等和超时 reclaim；worker 只通过环境密钥认领
+ * 自己 app/environment 的工作项，不能越权读取其他环境或创建 session。
+ */
+export interface WorkQueue {
+  enqueue(item: ToolWorkItem): Promise<void>;
+  claim(input: ClaimWorkItemsInput): Promise<ToolWorkItem[]>;
+  /** 返回 true 表示本次结果被接收；同范围内已 completed/settled 也应按幂等成功处理。 */
+  complete(result: ToolExecutionResult, scope?: CompleteWorkItemScope): Promise<boolean>;
+  reclaim(input: ReclaimWorkItemsInput): Promise<number>;
+  stats(input: GetWorkStatsInput): Promise<WorkStats>;
+  getItem?(input: GetWorkItemInput): Promise<WorkItemSnapshot | null>;
+}
+
+export type ClaimSettlableWorkInput = {
+  max?: number;
+};
+
+export type ClaimedSettlableWorkItem = {
+  item: ToolWorkItem;
+  result: ToolExecutionResult;
+  settlementAttempts?: number;
+};
+
+export type SettlementFailureInput = {
+  workId: string;
+  error: {
+    message: string;
+    code?: string;
+    details?: unknown;
+  };
+  deadLetter?: boolean;
+};
+
+/**
+ * 工具结果结算侧 SPI。
+ *
+ * 它与 worker 使用的 WorkQueue 分离，避免把平台内部结算方法暴露给 HttpWorkQueueClient。
+ */
+export interface WorkSettlementStore {
+  claimSettlable(input?: ClaimSettlableWorkInput): Promise<ClaimedSettlableWorkItem[]>;
+  /** 返回 false 表示当前实例不再持有结算 lease，调用方不得继续 wake 或计入成功。 */
+  markSettled(workId: string): Promise<boolean>;
+  /** 返回 false 表示当前实例不再持有结算 lease，失败状态未被可靠记录。 */
+  markSettlementFailed(input: SettlementFailureInput): Promise<boolean>;
+}