@ct-agents/protocol 0.0.1

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@ct-agents/protocol",
+  "version": "0.0.1",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/context-resolve.ts

@@ -0,0 +1,109 @@
+import type { EnvironmentExecutionMode } from './environment.js';
+import type { ExecutionScope } from './session/scope.js';
+import type { SessionEvent } from './session/events.js';
+
+export type ContextResolveRequest = {
+  kind: 'prompt_context';
+  keys: string[];
+};
+
+export type ContextResolveWorkItem = {
+  workId: string;
+  leaseId?: string;
+  appId: string;
+  environmentId: string;
+  executionMode?: EnvironmentExecutionMode;
+  sessionId: string;
+  rootSessionId: string;
+  scope: ExecutionScope;
+  request: ContextResolveRequest;
+};
+
+export type ContextResolveResult =
+  | {
+      workId: string;
+      leaseId?: string;
+      status: 'completed';
+      snapshot: Record<string, unknown>;
+    }
+  | {
+      workId: string;
+      leaseId?: string;
+      status: 'failed';
+      error: {
+        message: string;
+        code?: string;
+        retryable?: boolean;
+        details?: unknown;
+      };
+    };
+
+export type ContextResolveQueueClaimInput = {
+  appId: string;
+  environmentId: string;
+  executionMode?: EnvironmentExecutionMode;
+  max?: number;
+};
+
+export type ContextResolveQueueReclaimInput = {
+  appId: string;
+  environmentId: string;
+  executionMode?: EnvironmentExecutionMode;
+  olderThanMs: number;
+};
+
+export type ContextResolveQueueStatsInput = {
+  appId: string;
+  environmentId: string;
+  executionMode?: EnvironmentExecutionMode;
+};
+
+export type CompleteContextResolveScope = {
+  appId: string;
+  environmentId: string;
+  executionMode?: EnvironmentExecutionMode;
+  leaseId?: string;
+};
+
+export type ContextResolveStats = {
+  depth: number;
+  pending: number;
+  oldestQueuedAt: string | null;
+};
+
+export interface ContextResolveQueue {
+  enqueue(item: ContextResolveWorkItem): Promise<void>;
+  claim(input: ContextResolveQueueClaimInput): Promise<ContextResolveWorkItem[]>;
+  complete(result: ContextResolveResult, scope?: CompleteContextResolveScope): Promise<boolean>;
+  reclaim(input: ContextResolveQueueReclaimInput): Promise<number>;
+  stats(input: ContextResolveQueueStatsInput): Promise<ContextResolveStats>;
+}
+
+export type ClaimedContextResolveWorkItem = {
+  item: ContextResolveWorkItem;
+  result: ContextResolveResult;
+  settlementAttempts?: number;
+};
+
+export type ContextResolveSettlementFailureInput = {
+  workId: string;
+  error: {
+    message: string;
+    code?: string;
+    details?: unknown;
+  };
+  deadLetter?: boolean;
+};
+
+export interface ContextResolveSettlementStore {
+  claimSettlable(input?: { max?: number }): Promise<ClaimedContextResolveWorkItem[]>;
+  markSettled(workId: string): Promise<boolean>;
+  markSettlementFailed(input: ContextResolveSettlementFailureInput): Promise<boolean>;
+}
+
+export type ContextSnapshotLookup = {
+  findResolvedContext(input: {
+    events: SessionEvent[];
+    request: ContextResolveRequest;
+  }): Record<string, unknown> | null;
+};

package/src/environment.ts

@@ -0,0 +1,406 @@
+import type {
+  SessionEvent,
+  SessionRecord,
+  ToolErrorPayload,
+  ToolOrphanedReason,
+} from './session/index.js';
+import type { SkillView } from './skill.js';
+import type {
+  AddMemoryInput,
+  DeleteMemoryInput,
+  MemoryListItem,
+  MemoryRecord,
+  UpdateMemoryInput,
+} from './memory.js';
+import type { ToolExecutionResult } from './tool-exec.js';
+import type { SessionStore } from './session/store.js';
+import type { Store } from './store.js';
+import type { HarnessInfo } from './harness.js';
+import type { ToolHandler } from './tool.js';
+
+/**
+ * 运行时 schema 校验契约。
+ *
+ * protocol 只要求实现能完成严格解析与宽松解析，不绑定 zod 等具体校验库；
+ * 工具入参、工具结果与资源 options 都通过这个结构化契约保持可替换。
+ */
+export interface SchemaContract<T> {
+  /**
+   * 严格解析：输入不合法时抛错，合法时返回解析后的强类型值。
+   *
+   * 用于「数据已通过其它约束、只需窄化为强类型」的 fail-fast 边界，
+   * 例如工具入参在执行前的校验。
+   */
+  parse(value: unknown): T;
+  /**
+   * 宽松解析：永不抛错，返回带 `success` 标记的结果对象。
+   *
+   * 用于「需收集全部校验问题而非首个即中断」的边界，例如环境资源配置表单的
+   * 字段级校验明细。`error` 为 `unknown`：协议不绑定具体校验库的错误结构，
+   * 由实现侧（当前统一为 zod）自行解释其 issues。
+   */
+  safeParse(value: unknown): { success: true; data: T } | { success: false; error: unknown };
+}
+
+/**
+ * 数据库资源能力 SPI。工具通过 {@link ResourceSlots.database} 访问，
+ * 具体实现由宿主应用注入。`options.readOnly === true` 是强契约：
+ * 实现必须使用只读账号、只读事务或等价机制强制只读，不能只依赖工具层 SQL 判定。
+ */
+export interface Database {
+  query(sql: string, params?: readonly unknown[], options?: { readOnly?: boolean; maxRows?: number; timeoutMs?: number }): Promise<unknown>;
+}
+
+/**
+ * Skill 运行时资源能力。
+ *
+ * 只暴露当前 session/harness 可见的 Skill 视图；app/global 过滤、harness 关联过滤等控制面规则
+ * 由装配层在构造 resource 时绑定，工具层不读取 appId/includeGlobal 等具名 scope 参数。
+ */
+export type RuntimeSkillView = Pick<SkillView, 'name' | 'description' | 'instructions' | 'version' | 'enabled'>;
+
+export interface SkillResource {
+  list(): Promise<Array<Pick<RuntimeSkillView, 'name' | 'description' | 'version'>>>;
+  get(name: string): Promise<RuntimeSkillView | null>;
+}
+
+/**
+ * Memory 运行时资源能力。
+ *
+ * 访问范围由实现层构造期绑定；工具只按 name 读写当前可见 memory，不感知 partition/owner/appId。
+ */
+export interface MemoryResource {
+  get(name: string): Promise<MemoryRecord | null>;
+  add(input: AddMemoryInput): Promise<MemoryRecord>;
+  update(input: UpdateMemoryInput): Promise<MemoryRecord>;
+  delete(input: DeleteMemoryInput): Promise<MemoryRecord>;
+  list(): Promise<MemoryListItem[]>;
+}
+
+/** 沙箱命令执行结果。 */
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
+  totalStdoutBytes?: number;
+  totalStderrBytes?: number;
+}
+
+/**
+ * 已就绪的会话沙箱句柄。
+ *
+ * 所有 fs/bash 类工具都经同一个会话级 sandbox 进入隔离环境；权限、路径 jail 与审批仍由工具层处理。
+ */
+export interface SandboxHandle {
+  readonly sessionId: string;
+  readonly workspaceRoot: string;
+  readonly isolated: boolean;
+  exec(command: string, opts?: { timeoutMs?: number; maxOutputBytes?: number }): Promise<ExecResult>;
+  readFile(path: string, opts?: { offset?: number; limit?: number; maxBytes?: number }): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+/**
+ * 沙箱驱动 SPI。
+ *
+ * 协议只描述按 session 启动沙箱，不携带 partition/owner 等隔离维度；具体实现若需要更多隔离信息，
+ * 应在 worker 实现层从不透明 scope 或本地配置中获取。
+ */
+export interface Sandbox {
+  readonly kind: 'local' | 'docker' | 'fargate';
+  readonly isolated: boolean;
+  launch(input: { sessionId: string }): Promise<SandboxHandle>;
+}
+
+/** 平台内置 slot 名保留字：业务 catalog 不得声明同名 slot。 */
+export const BUILTIN_SLOT_NAMES = ['database', 'sandbox', 'skills', 'memory'] as const;
+export type BuiltinSlotName = (typeof BUILTIN_SLOT_NAMES)[number];
+
+/** 内置 slot 的能力类型映射，供 SDK builder 做强类型推导。 */
+export type BuiltinSlots = {
+  database: Database;
+  sandbox: SandboxHandle;
+  skills: SkillResource;
+  memory: MemoryResource;
+};
+
+/**
+ * 已实例化的资源集合：按环境配置注入工具执行上下文。
+ * 协议只固定少数通用槽位，自定义 slot 以不透明实例透传，运行时不感知业务类型。
+ */
+export interface ResourceSlots {
+  database?: Database;
+  sandbox?: SandboxHandle;
+  skills?: SkillResource;
+  memory?: MemoryResource;
+  [slot: string]: unknown;
+}
+
+/** 资源工厂：按 options 实例化一个资源（同步或异步）。 */
+export type ResourceFactory<TResource, TOptions extends Record<string, unknown>> = (
+  options: TOptions,
+) => Promise<TResource> | TResource;
+
+/**
+ * 资源的单个实现定义。
+ *
+ * 一个 resource slot 可有多个 implementation（不同后端）。
+ * `optionsSchema` 是运行时 parse 契约，`optionsJsonSchema` 是 catalog/Console 展示契约。
+ * 二者位于不同边界：运行时只读取 `optionsSchema`，控制面只投影 `optionsJsonSchema`。
+ */
+export type ResourceImplementationDefinition<TResource, TOptions extends Record<string, unknown>> = {
+  id: string;
+  title?: string;
+  description?: string;
+  /**
+   * 平台内置实现可声明允许绑定的环境执行面。缺省表示不限制 hosted/self_hosted；
+   * 只有显式声明数组时才按当前 Environment executionMode 做准入校验。
+   */
+  supportedExecutionModes?: EnvironmentExecutionMode[];
+  optionsSchema: SchemaContract<TOptions>;
+  optionsJsonSchema?: Record<string, unknown>;
+  factory: ResourceFactory<TResource, TOptions>;
+};
+
+/**
+ * 资源定义：一个 resource id + 其可选的多个实现。
+ *
+ * 由 apps/api 在装配时注册到 {@link ResourceRegistry}；运行时按 EnvironmentConfig
+ * 选择的 implementationId 实例化对应实现。
+ */
+export type ResourceDefinition<TResource, TOptions extends Record<string, unknown>> = {
+  id: string;
+  title?: string;
+  description?: string;
+  implementations?: Array<ResourceImplementationDefinition<TResource, Record<string, unknown>>>;
+};
+
+/**
+ * 资源注册中心：登记所有可用 resource 定义，供环境实例化与配置 UI 查询。
+ *
+ * 由 apps/api 装配时填充具体实现；运行时面向本接口编程。
+ */
+export interface ResourceRegistry {
+  /** 注册一个 resource 定义（含其实现列表）。 */
+  register<TResource, TOptions extends Record<string, unknown>>(
+    definition: ResourceDefinition<TResource, TOptions>,
+  ): void;
+  /** 按 resource id 查找定义；不存在返回 undefined。 */
+  get(id: string): ResourceDefinition<unknown, Record<string, unknown>> | undefined;
+  /** 枚举全部 resource 定义，供配置后台 catalog 展示。 */
+  list(): Array<ResourceDefinition<unknown, Record<string, unknown>>>;
+};
+
+/** 环境配置中单个资源的绑定：slot 名由外层 key 提供，值只保存选定 implementation 与 options。 */
+export type EnvironmentResourceConfig = {
+  implementationId?: string;
+  options: Record<string, unknown>;
+};
+
+export type EnvironmentExecutionMode = 'hosted' | 'self_hosted';
+
+export type EnvironmentHostedPolicy = {
+  actionTimeoutMs?: number;
+};
+
+/** 资源槽位 DTO：把 slot 及 implementation options JSON Schema 组织成配置 UI 可消费的结构。 */
+export type EnvironmentResourceSlotDto = {
+  name: string;
+  origin?: 'platform_builtin' | 'app_catalog';
+  title: string;
+  description?: string;
+  implementations?: Array<{
+    id: string;
+    origin?: 'platform_builtin' | 'app_catalog';
+    title: string;
+    description?: string;
+    supportedExecutionModes?: EnvironmentExecutionMode[];
+    optionsSchema?: Record<string, unknown>;
+  }>;
+};
+
+/**
+ * 环境配置：一组 resource 绑定 + 启用状态，带乐观锁版本号。
+ * 多 harness 可共享同一 environment；配置变更通过版本号做乐观并发控制。
+ */
+export type EnvironmentConfig = {
+  appId?: string;
+  id: string;
+  version: number;
+  name: string;
+  executionMode: EnvironmentExecutionMode;
+  hostedPolicy?: EnvironmentHostedPolicy;
+  resources: Partial<Record<string, EnvironmentResourceConfig>>;
+  enabled: boolean;
+  createdAt?: string;
+  updatedAt?: string;
+};
+
+export type EnvironmentConfigKey = string | { appId?: string; id: string };
+export type EnvironmentConfigListQuery = { appId?: string };
+
+/** 保存环境配置输入；`baseVersion` 用于乐观锁冲突检测。 */
+export type SaveEnvironmentConfigInput = {
+  appId?: string;
+  id: string;
+  name: string;
+  executionMode: EnvironmentExecutionMode;
+  hostedPolicy?: EnvironmentHostedPolicy;
+  resources: Partial<Record<string, EnvironmentResourceConfig>>;
+  baseVersion?: number;
+  enabled?: boolean;
+};
+
+/**
+ * 环境配置存储 SPI：扩展基础 {@link Store} 增加 save / delete。
+ * 具体实现（PostgresEnvironmentConfigStore 等）由 apps/api 装配注入。
+ */
+export interface EnvironmentConfigStore extends Store<EnvironmentConfig, EnvironmentConfigKey> {
+  list(query?: EnvironmentConfigListQuery): Promise<EnvironmentConfig[]>;
+  save(input: SaveEnvironmentConfigInput): Promise<EnvironmentConfig>;
+  delete(key: EnvironmentConfigKey): Promise<void>;
+}
+
+/**
+ * 已实例化的环境容器：环境 id + 实例化后的资源集合。
+ * orchestrator 在 wake 时据此把 resources 注入 harness / 工具上下文。
+ */
+export type EnvironmentContainer<TResources extends object = object> = {
+  environmentId: string;
+  environmentUpdatedAt?: string;
+  resources: TResources;
+};
+
+/** 执行工具的输入：目标工具、入参、归属会话与资源、以及 provider 原生 toolCallId。 */
+export type ExecuteToolInput = {
+  sessionStore: SessionStore;
+  session: SessionRecord;
+  harness?: HarnessInfo;
+  executionMode: EnvironmentExecutionMode;
+  hostedPolicy?: EnvironmentHostedPolicy;
+  localToolNames?: readonly string[];
+  resources?: ResourceSlots;
+  resourceBindings?: Record<string, unknown>;
+  toolName: string;
+  input: unknown;
+  providerToolCallId?: string;
+  actor: SessionEvent<'tool.called'>['actor'];
+  turnId?: string;
+  abortSignal?: AbortSignal;
+};
+
+/** 结清已解决 action 的输入：对一组已 resolved 的 action 事件恢复执行对应工具。 */
+export type SettleResolvedActionsInput = {
+  sessionStore: SessionStore;
+  session: SessionRecord;
+  harness?: HarnessInfo;
+  executionMode: EnvironmentExecutionMode;
+  hostedPolicy?: EnvironmentHostedPolicy;
+  localToolNames?: readonly string[];
+  resources?: ResourceSlots;
+  resourceBindings?: Record<string, unknown>;
+  actionEventIds: string[];
+  abortSignal?: AbortSignal;
+};
+
+/** 收口悬空 tool 调用的输入：把无终态的 tool.called 标记为 orphaned 失败。 */
+export type FailOpenToolCallsInput = {
+  sessionStore: SessionStore;
+  session: SessionRecord;
+  events: SessionEvent[];
+  toolCallEventIds: string[];
+  reason: ToolOrphanedReason;
+  observedAt: string;
+  state?: unknown;
+  abortSignal?: AbortSignal;
+};
+
+/** 应用业务 worker 已完成的 tool work item 结果。 */
+export type ApplyCompletedWorkInput = {
+  sessionStore: SessionStore;
+  session: SessionRecord;
+  handler: ToolHandler<unknown, unknown>;
+  toolCallEvent: SessionEvent<'tool.called'>;
+  result: ToolExecutionResult;
+};
+
+/** 工具执行完成结果：携带落库后的 modelResult。 */
+export type EnvironmentToolCompletedResult = {
+  status: 'completed';
+  toolCallEventId: string;
+  modelResult: unknown;
+};
+
+/** 工具执行暂停结果：列出本次产生的 action 事件 id，等待用户解决。 */
+export type EnvironmentToolPausedResult = {
+  status: 'paused';
+  toolCallEventId: string;
+  actionEventIds: string[];
+};
+
+/** 工具已进入业务 worker 队列，当前模型轮需要等待回传后再恢复。 */
+export type EnvironmentToolQueuedResult = {
+  status: 'queued';
+  toolCallEventId: string;
+  workId: string;
+};
+
+/** 工具执行失败结果：携带结构化错误。 */
+export type EnvironmentToolFailedResult = {
+  status: 'failed';
+  /** 调用前校验失败时尚未写 `tool.called`，因此可能不存在。 */
+  toolCallEventId?: string;
+  error: ToolErrorPayload;
+};
+
+/** 工具执行结果：完成 / 暂停 / 入队等待 / 失败。 */
+export type EnvironmentToolResult =
+  | EnvironmentToolCompletedResult
+  | EnvironmentToolPausedResult
+  | EnvironmentToolQueuedResult
+  | EnvironmentToolFailedResult;
+
+/**
+ * action 结清结果：本地工具会完成或失败；业务 worker 工具会重新入队 resume，
+ * 待 worker 在真实资源上下文中执行后再由持久队列结算终态。
+ */
+export type SettledActionResult =
+  | EnvironmentToolCompletedResult
+  | EnvironmentToolFailedResult
+  | EnvironmentToolQueuedResult;
+
+/**
+ * 工具执行边界（核心 SPI）。
+ *
+ * Environment 是「工具生命周期事件的唯一写入者」：它调度工具 handler、把 handler 返回的
+ * effects 与结果按序落库为 session 事件（tool.called → effects → tool.completed/failed/interrupted）。
+ * 工具 handler 本身不直接写事件，全部经 Environment 中转，保证事件顺序与一致性。
+ *
+ * 由 apps/api 装配具体实现（DefaultEnvironment）注入 orchestrator；运行时面向本接口编程。
+ */
+export interface Environment {
+  /**
+   * 执行一次工具调用：校验入参 → 写 tool.called → 调 handler → 落库 effects 与终态事件。
+   * 返回三态结果；暂停态携带 action 事件 id 交还 harness。
+   */
+  executeTool(input: ExecuteToolInput): Promise<EnvironmentToolResult>;
+  /**
+   * 结清已解决的 action：对每个 resolved 的 action 恢复执行其工具（调 handler.resume），
+   * 把恢复结果落库为终态事件。返回每个 action 的结清结果。
+   */
+  settleResolvedActions(input: SettleResolvedActionsInput): Promise<SettledActionResult[]>;
+  /**
+   * 应用业务 worker 回传的完成结果：写 effects 与终态事件，或在 paused 时写 pending action。
+   * 该入口供持久化 work queue 的结算 runner 使用。
+   */
+  applyCompletedWork(input: ApplyCompletedWorkInput): Promise<EnvironmentToolResult>;
+  /**
+   * 收口悬空 tool 调用：把指定 tool.called（无终态、无未决 action）标记为 orphaned 失败。
+   * 由 orchestrator 的 stale-running reconciler 在会话恢复时调用，防止事件流残留开口调用。
+   */
+  failOpenToolCalls(input: FailOpenToolCallsInput): Promise<void>;
+}

package/src/harness.ts

@@ -0,0 +1,134 @@
+import type {
+  DerivedSessionState,
+  HarnessTrigger,
+  SessionEvent,
+  SessionEventPayload,
+  SessionEventType,
+  SessionRecord,
+  StopReason,
+} from './session/index.js';
+import type { AppendEventInput, GetEventsInput, SessionStore } from './session/store.js';
+import type { ResourceSlots, Environment, EnvironmentExecutionMode, EnvironmentHostedPolicy } from './environment.js';
+import type { ToolDescriptor } from './tool.js';
+
+/**
+ * 模型上下文的内容 part。
+ *
+ * 除了用户输入的 text/image/document（来自 user.message）外，投影会把 assistant 轮的
+ * 结构化产出也表达为 part，供各 provider adapter 组装成原生 block：
+ * - `tool-call`：assistant 发起的工具调用（Anthropic tool_use / OpenAI function_call）。
+ *   `toolCallId` 用于和 `tool-result` 配对；若 provider 返回了原生 id，则必须使用原生 id，
+ *   否则回退到 session events 里 tool.called 的事件 id。
+ * - `tool-result`：工具执行结果（Anthropic tool_result / OpenAI function_call_output）。
+ * - `reasoning`：assistant 的推理/thinking。`providerState` 是 provider 原生续传状态，协议层不解释。
+ *   回放时同一 model turn 的并行 tool_use 与其共享 thinking 块必须聚合进同一条 assistant 消息
+ *   （见 buildModelContextFromSessionEvents），否则部分 provider 会拒绝跨轮续传。
+ * - `json`：通用结构化文本兜底（如工具结果的非原生表达）。
+ */
+export type ModelContextContent =
+  | SessionEventPayload<'user.message'>['content'][number]
+  | { type: 'json'; value: unknown }
+  | { type: 'tool-call'; toolCallId: string; toolName: string; input: unknown }
+  | { type: 'tool-result'; toolCallId: string; toolName: string; result: unknown }
+  | { type: 'reasoning'; text: string; providerState?: Record<string, unknown> };
+
+export type ModelContextMessage = {
+  role: 'user' | 'assistant' | 'tool' | 'system';
+  toolName?: string;
+  content: ModelContextContent[];
+};
+
+export type ModelContext = {
+  messages: ModelContextMessage[];
+};
+
+export type BoundRuntimeSession = {
+  record: SessionRecord;
+  store: SessionStore;
+  appendEvent<TType extends SessionEventType>(
+    input: Omit<AppendEventInput<TType>, 'sessionId'>,
+  ): Promise<SessionEvent<TType>>;
+  getEvents(input?: Omit<GetEventsInput, 'sessionId'>): Promise<SessionEvent[]>;
+  getDerivedState(): Promise<DerivedSessionState>;
+};
+
+export type HarnessInfo = {
+  id: string;
+  version: number;
+  name?: string;
+  metadata: Record<string, unknown>;
+  contextResolve?: {
+    keys: string[];
+  };
+};
+
+export type RunUntilIdleInput = {
+  session: BoundRuntimeSession;
+  harness?: HarnessInfo & { model?: string };
+  modelOverride?: HarnessModelPort;
+  systemPrompt: string;
+  executionMode: EnvironmentExecutionMode;
+  hostedPolicy?: EnvironmentHostedPolicy;
+  localToolNames?: readonly string[];
+  resources: ResourceSlots;
+  resourceBindings?: Record<string, unknown>;
+  tools: ToolDescriptor[];
+  maxModelTurns?: number;
+  trigger: HarnessTrigger;
+  abortSignal?: AbortSignal;
+};
+
+export type RunUntilIdleResult = {
+  status: 'idle' | 'queued' | 'aborted' | 'failed';
+  reason?: string;
+  retryable?: boolean;
+  fatal?: boolean;
+};
+
+export interface Harness {
+  runUntilIdle(input: RunUntilIdleInput): Promise<RunUntilIdleResult>;
+}
+
+export type HarnessModelToolCall = {
+  // 模型 provider 返回的原生工具调用 id。Anthropic thinking signature 依赖原样回传同轮
+  // tool_use block，因此该 id 必须跨 Environment 落库并参与后续 tool_result 配对。
+  providerToolCallId?: string;
+  toolName: string;
+  input: unknown;
+};
+
+export type HarnessModelRunInput = {
+  context: ModelContext;
+  systemPrompt: string;
+  tools: ToolDescriptor[];
+  abortSignal?: AbortSignal;
+};
+
+export type HarnessModelRunResult =
+  | {
+      type: 'assistant_message';
+      text: string;
+      reasoningText?: string;
+      reasoningDisplayMode?: 'summary' | 'full';
+      // provider 原生续传状态，供 Harness 落库并在后续轮回传。
+      providerState?: Record<string, unknown>;
+    }
+  | {
+      type: 'tool_calls';
+      toolCalls: HarnessModelToolCall[];
+      // 模型可能在同一轮里既输出叙述文本/推理，又发起工具调用（Claude / DeepSeek 等
+      // 常见此行为）。这些字段携带同轮产出的助手文本，供 Harness 在执行工具前落库为
+      // assistant.output.* 事件；缺省（仅纯工具调用）时为 undefined。
+      text?: string;
+      reasoningText?: string;
+      reasoningDisplayMode?: 'summary' | 'full';
+      // provider 原生续传状态。工具轮尤其关键，部分 provider 要求下一轮带回原生状态。
+      providerState?: Record<string, unknown>;
+    }
+  | {
+      type: 'end_turn';
+    };
+
+export interface HarnessModelPort {
+  run(input: HarnessModelRunInput): Promise<HarnessModelRunResult>;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `@ct-agents/protocol` 是通用 Agent 协议与运行时契约包。
+ *
+ * 应用、前端和后端 packages 都可以从该根入口引入需要的 DTO、事件、配置类型与 SPI。
+ */
+export * from './store.js';
+export * from './session/index.js';
+export * from './session-api.js';
+export * from './tool.js';
+export * from './tool-exec.js';
+export * from './tool-registry.js';
+export * from './work-queue.js';
+export * from './context-resolve.js';
+export * from './environment.js';
+export * from './harness.js';
+export * from './orchestrator.js';
+export * from './prompt.js';
+export * from './skill.js';
+export * from './memory.js';