@ct-agents/protocol 0.0.1

package/src/session/store.ts

@@ -0,0 +1,127 @@
+import type { EnvironmentId, HarnessId } from './ids.js';
+import type { SessionRecord } from './record.js';
+import type { DerivedSessionState, SessionStreamEnvelope } from './derived-state.js';
+import type {
+  SessionEvent,
+  SessionEventActor,
+  SessionEventPayload,
+  SessionEventType,
+} from './events.js';
+
+/** 分页结果：items + 下一页游标（缺省表示无更多数据）。 */
+export interface Page<TItem> {
+  items: TItem[];
+  nextCursor?: string;
+}
+
+export class SessionEventAppendConflictError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SessionEventAppendConflictError';
+  }
+}
+
+// ─── SessionStore 公共接口（scope-free）──────────────────────────────────
+//
+// SessionStore 是 protocol 的 scope-free 会话存储契约：方法签名不含隔离维度，
+// 隔离由实现封装在实例内部（如 @ct-agents/session 的 ScopedSessionStore 在构造期绑定 scope，
+// 方法内部用 RLS 执行）。这样通用运行时（harness / orchestrator）面向本接口编程时无需感知隔离键。
+
+/** 创建会话输入：harness / environment 以 pin（id + version）固化，业务信息进 metadata。 */
+export type CreateSessionInput = {
+  appId?: string;
+  parentSessionId?: string;
+  rootSessionId?: string;
+  spawnedByEventId?: string;
+  harnessId: HarnessId;
+  harnessVersion: number;
+  environmentId: EnvironmentId;
+  environmentUpdatedAt: string;
+  title: string;
+  metadata: Record<string, unknown>;
+};
+
+/**
+ * 追加事件输入。泛型 `TType` 在编译期保证 type / payload 配对；
+ * `idempotencyKey` 让重复追加幂等（同 key 返回已存在事件，不产生新 seq）。
+ */
+export type AppendEventInput<TType extends SessionEventType = SessionEventType> = {
+  eventId?: string;
+  sessionId: string;
+  type: TType;
+  turnId?: string;
+  parentEventId?: string;
+  actor: SessionEventActor;
+  payload: SessionEventPayload<TType>;
+  idempotencyKey?: string;
+  /**
+   * 写入前置条件：当同一 session、同一 parentEventId 下已存在这些类型的子事件时拒绝追加。
+   *
+   * 用于把「某个父事件只能拥有一个终态/解决事件」这类状态机防线下沉到 store 事务内，
+   * 避免 runtime 在 check-then-append 间遇到并发窗口。
+   */
+  rejectIfParentHasTypes?: SessionEventType[];
+  /**
+   * 写入前置条件：当同一 session、指定事件下已存在这些类型的子事件时拒绝追加。
+   *
+   * 用于同时防守非当前 parent 的状态，例如基于 action 写工具超时失败时，
+   * 在同一事务内确认该 action 尚未被 `user.action.resolved` 解决。
+   */
+  rejectIfEventHasChildren?: Array<{
+    eventId: string;
+    types: SessionEventType[];
+  }>;
+};
+
+/** 读取事件输入：支持按 seq 区间、limit 分页、类型过滤与正倒序。 */
+export type GetEventsInput = {
+  sessionId: string;
+  eventIds?: string[];
+  parentEventId?: string;
+  fromSeq?: number;
+  toSeq?: number;
+  limit?: number;
+  order?: 'asc' | 'desc';
+  type?: SessionEventType[];
+};
+
+/** 订阅事件流输入：从 fromSeq 起 replay 历史并持续推送新事件，signal 终止时停止。 */
+export type StreamEventsInput = {
+  sessionId: string;
+  fromSeq?: number;
+  signal?: AbortSignal;
+};
+
+/** 列出会话输入；默认只返回顶层未删除 session。 */
+export type ListSessionsInput = {
+  includeDeleted?: boolean;
+};
+
+/**
+ * 会话存储 SPI（scope-free）。
+ *
+ * 持久化 session 元数据与 append-only 事件日志，并提供派生状态计算与事件流订阅。
+ * 由 apps/api 装配具体实现注入（生产用 ScopedSessionStore，测试用 InMemorySessionStore）；
+ * 运行时面向本接口编程，不依赖具体实现类。
+ */
+export interface SessionStore {
+  /** 创建一条新会话记录。 */
+  create(input: CreateSessionInput): Promise<SessionRecord>;
+  /** 按 id 读取会话；不存在返回 null。 */
+  get(sessionId: string): Promise<SessionRecord | null>;
+  /** 枚举当前 scope 内的顶层会话；默认不包含软删除记录。 */
+  list(input?: ListSessionsInput): Promise<SessionRecord[]>;
+  /**
+   * 追加一条事件到会话日志。seq 单调递增；idempotencyKey 命中时返回已存在事件。
+   * 写入口不再做运行时封闭校验——type / payload 由泛型在编译期保证配对。
+   */
+  appendEvent<TType extends SessionEventType>(
+    input: AppendEventInput<TType>,
+  ): Promise<SessionEvent<TType>>;
+  /** 按 seq 区间 / 类型 / 分页读取事件。 */
+  getEvents(input: GetEventsInput): Promise<Page<SessionEvent>>;
+  /** 由事件日志派生当前会话状态（status / pending action / open tool call 等）。 */
+  getDerivedState(sessionId: string): Promise<DerivedSessionState>;
+  /** 订阅事件流：先 replay fromSeq 之后的历史，再持续推送新事件。 */
+  streamEvents(input: StreamEventsInput): AsyncIterable<SessionStreamEnvelope>;
+}

package/src/session-api.ts

@@ -0,0 +1,121 @@
+import type { DerivedSessionState, SessionStreamEnvelope } from './session/derived-state.js';
+import type {
+  SessionEvent,
+  SessionEventPayload,
+  SessionEventType,
+  UserInterruptPayload,
+  UserMessagePayload,
+} from './session/events.js';
+import type { EnvironmentId, HarnessId } from './session/ids.js';
+import type { SessionRecord } from './session/record.js';
+import type { Page } from './session/store.js';
+
+/** BFF / 消费端创建 managed session 的请求体。 */
+export interface CreateManagedSessionRequest {
+  harnessId: HarnessId | string;
+  harnessVersion?: number;
+  environmentId: EnvironmentId | string;
+  title: string;
+  metadata?: Record<string, unknown>;
+  idempotencyKey?: string;
+}
+
+/** managed session 创建响应。 */
+export interface CreateManagedSessionResponse {
+  session: SessionRecord;
+}
+
+/** 向 session 追加用户消息并触发 wake 的请求体。 */
+export interface SendManagedSessionMessageRequest {
+  content: UserMessagePayload['content'];
+  idempotencyKey?: string;
+}
+
+/** 追加用户消息后的响应。 */
+export interface SendManagedSessionMessageResponse {
+  event: SessionEvent<'user.message'>;
+  wakeAccepted: boolean;
+  wakeReason?: string;
+}
+
+/** 批量追加事件请求，用于平台 API 与 SDK 的通用事件写入口。 */
+export interface SessionEventAppendRequest {
+  events: Array<{
+    type: SessionEventType;
+    payload: SessionEventPayload;
+    turnId?: string;
+    parentEventId?: string;
+  }>;
+  idempotencyKey?: string;
+}
+
+/** 批量追加事件响应。 */
+export interface SessionEventAppendResponse {
+  events: SessionEvent[];
+}
+
+/** 查询 session 列表的 wire 参数。 */
+export interface ListManagedSessionsRequest {
+  appId?: string;
+  rootSessionId?: string;
+  status?: DerivedSessionState['status'];
+  limit?: number;
+  cursor?: string;
+}
+
+/** session 列表响应。 */
+export type ListManagedSessionsResponse = Page<SessionRecord>;
+
+/** 查询 session 事件的 wire 参数。 */
+export interface ListManagedSessionEventsRequest {
+  fromSeq?: number;
+  toSeq?: number;
+  limit?: number;
+  order?: 'asc' | 'desc';
+  type?: SessionEventType[];
+}
+
+/** session 事件列表响应。 */
+export type ListManagedSessionEventsResponse = Page<SessionEvent>;
+
+/** SSE 事件流 envelope，直接复用 session store 的流式 envelope。 */
+export type ManagedSessionStreamEnvelope = SessionStreamEnvelope;
+
+/** 读取派生态响应。 */
+export interface GetManagedSessionStateResponse {
+  state: DerivedSessionState;
+}
+
+/** 中断 session 请求。 */
+export interface InterruptManagedSessionRequest extends UserInterruptPayload {
+  idempotencyKey?: string;
+}
+
+/** 中断 session 响应。 */
+export interface InterruptManagedSessionResponse {
+  accepted: boolean;
+  reason?: string;
+}
+
+/** 解决待处理 action 请求。 */
+export interface ResolveManagedSessionActionRequest {
+  result: unknown;
+  idempotencyKey?: string;
+}
+
+/** 解决待处理 action 响应。 */
+export interface ResolveManagedSessionActionResponse {
+  event: SessionEvent<'user.action.resolved'>;
+  wakeAccepted: boolean;
+  wakeReason?: string;
+}
+
+/** 删除 session 请求。 */
+export interface DeleteManagedSessionRequest {
+  idempotencyKey?: string;
+}
+
+/** 删除 session 响应。 */
+export interface DeleteManagedSessionResponse {
+  event: SessionEvent<'session.deleted'>;
+}

package/src/skill.ts

@@ -0,0 +1,42 @@
+import type { Store } from './store.js';
+
+// Skill 以 name 为唯一标识符（主键）：不再有独立 id 字段，也不带 `skill:` 前缀。
+export type SkillView = {
+  appId?: string | null;
+  name: string;
+  version: number;
+  description: string;
+  instructions: string;
+  enabled: boolean;
+  createdAt?: string;
+  updatedAt?: string;
+};
+
+export type CreateSkillInput = {
+  appId?: string | null;
+  name: string;
+  description: string;
+  instructions: string;
+  enabled?: boolean;
+};
+
+// name 为主键、创建后不可改，仅作为定位键；description/instructions/enabled 可更新。
+export type UpdateSkillInput = {
+  name: string;
+  baseVersion: number;
+  description?: string;
+  instructions?: string;
+  enabled?: boolean;
+};
+
+export type SkillListQuery = {
+  appId?: string;
+  includeGlobal?: boolean;
+};
+
+export interface SkillStore extends Store<SkillView> {
+  list(query?: SkillListQuery): Promise<SkillView[]>;
+  create(input: CreateSkillInput): Promise<SkillView>;
+  update(input: UpdateSkillInput): Promise<SkillView>;
+  delete(name: string): Promise<void>;
+}

package/src/store.ts

@@ -0,0 +1,11 @@
+/**
+ * 跨包共享的最小 Store 契约。
+ *
+ * 只抽离所有 store 真实共有的读取能力，写操作仍由各自领域 store 自行声明。
+ */
+export interface Store<TRecord, TKey = string> {
+  /** 按主键读取单条记录；不存在返回 null。 */
+  get(key: TKey): Promise<TRecord | null>;
+  /** 枚举全部记录（具体过滤 / 排序由实现决定）。 */
+  list(): Promise<TRecord[]>;
+}

package/src/tool-exec.ts

@@ -0,0 +1,69 @@
+import type { SessionEvent } from './session/index.js';
+import type { ToolEffect, ToolExecutionStatus } from './tool.js';
+import type { ExecutionScope } from './session/index.js';
+import type { EnvironmentExecutionMode } from './environment.js';
+
+export type ToolWorkItemMode = 'execute' | 'resume';
+
+export type ToolResumeWorkPayload = {
+  actionEvent: SessionEvent<'agent.action.requested'>;
+  resolvedEvent: SessionEvent<'user.action.resolved'>;
+};
+
+/**
+ * 平台下发给业务 worker 的一次 tool 调用。
+ *
+ * 该类型是跨进程执行边界的核心契约：平台只保存 opaque 输入与资源绑定信息，
+ * worker 侧用本地 ToolHandler 的 inputSchema 再做运行时校验，并在业务进程内访问资源和密钥。
+ */
+export interface ToolWorkItem {
+  /** 工作项幂等键，同时作为 lease / complete 的稳定关联标识。 */
+  workId: string;
+  /** 应用路由键，由消费端 key 或环境密钥派生。 */
+  appId: string;
+  /** 环境路由键，worker 只能认领自己环境下的工作项。 */
+  environmentId: string;
+  /**
+   * 工作项创建时的执行面快照。
+   *
+   * environment 配置之后可能被切换；claim/reclaim 必须按该快照过滤，避免平台 hosted
+   * worker 认领历史 self-hosted 工作项，或接入方 worker 认领 hosted 工作项。
+   */
+  executionMode?: EnvironmentExecutionMode;
+  sessionId: string;
+  rootSessionId: string;
+  scope: ExecutionScope;
+  /** 对应已经落库的 tool.called 事件，用于回写 terminal 事件和 effects parent。 */
+  toolCallEventId: string;
+  toolName: string;
+  /**
+   * 工作项模式。缺省为 execute，保持旧 worker item 兼容；resume 用于把人工审批后的
+   * 真实恢复执行重新交回业务 worker，而不是在平台进程调用 catalog stub handler。
+   */
+  mode?: ToolWorkItemMode;
+  /** 平台不解释输入结构，worker 侧按 handler.inputSchema 校验。 */
+  input: unknown;
+  /** resume 工作项携带的 action 请求与解决事件快照。 */
+  resume?: ToolResumeWorkPayload;
+  /** 环境资源绑定快照。这里只保存绑定信息，不保存业务数据本体或密钥。 */
+  resourceBindings?: Record<string, unknown>;
+}
+
+/**
+ * worker 回传给平台的 tool 执行结果。
+ *
+ * 保留 modelResult 与 effects 双通道：modelResult 回喂模型，effects 由平台作为 opaque
+ * session 事件写入日志，业务 UI 事件不会被塞进模型上下文。
+ */
+export interface ToolExecutionResult {
+  workId: string;
+  status: ToolExecutionStatus;
+  modelResult?: unknown;
+  effects?: ToolEffect[];
+  error?: {
+    code?: string;
+    message: string;
+    retryable?: boolean;
+    details?: unknown;
+  };
+}

package/src/tool-registry.ts

@@ -0,0 +1,49 @@
+import type { ToolDescriptor } from './tool.js';
+
+/** app 内唯一的 tool 名称。全局内置 tool 在引用处用 appId=null 表达。 */
+export type AppScopedToolName = string;
+
+/** harness 引用 tool 时使用的归属信息。null 表示平台全局内置 tool。 */
+export interface AppScopedToolReference {
+  appId: string | null;
+  toolName: AppScopedToolName;
+}
+
+export type ToolOrigin = 'platform_builtin' | 'app_catalog' | 'sub_agent';
+
+/** worker 上报的 resource implementation 描述；不允许提交平台内部 origin/capability。 */
+export type EnvironmentResourceImplementationRegistrationDto = {
+  id: string;
+  title: string;
+  description?: string;
+  optionsSchema?: Record<string, unknown>;
+};
+
+/** worker 上报的 public resource slot 描述；只描述业务自有 app catalog resource。 */
+export type EnvironmentResourceSlotRegistrationDto = {
+  name: string;
+  title: string;
+  description?: string;
+  implementations?: EnvironmentResourceImplementationRegistrationDto[];
+};
+
+/** 环境密钥上报的 public body：appId 只能由鉴权 scope 派生，不能由请求体覆盖。 */
+export interface ToolRegistrationRequestBody {
+  tools: ToolDescriptor[];
+  resourceSlots?: EnvironmentResourceSlotRegistrationDto[];
+}
+
+/** worker 连接平台时上报的 tool 目录。平台按 appId + toolName 幂等覆盖。 */
+export interface ToolRegistrationCommand {
+  appId: string;
+  tools: ToolDescriptor[];
+}
+
+/** 平台 DB 中持久化的 tool 描述符快照。descriptor 仍以代码上报为唯一真相源。 */
+export interface PersistedToolDescriptor {
+  appId: string;
+  toolName: string;
+  descriptor: ToolDescriptor;
+  origin: ToolOrigin;
+  updatedAt: string;
+}