@ct-agents/protocol 0.0.1

package/src/memory.ts

@@ -0,0 +1,57 @@
+/**
+ * 通用 Agent Memory 契约。
+ *
+ * Memory 在协议层只是一组按实现访问范围隔离的 Markdown 文档；访问范围由实现包在构造期绑定，
+ * Harness、工具和 Orchestrator 只依赖这里的 scope-free KV 接口。
+ *
+ * 目录召回模型：MemoryStore.list() 返回所有存活条目的 {name, description, updatedAt}，
+ * load-memory 工具在每次 wake 时自动生成目录注入自身 description，无需手工维护根索引。
+ */
+export type MemoryRecord = {
+  name: string;
+  description: string;
+  content: string;
+  version: number;
+  deleted: boolean;
+  source?: string;
+  idempotencyKey?: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type AddMemoryInput = {
+  name: string;
+  description: string;
+  content: string;
+  source?: string;
+  idempotencyKey?: string;
+};
+
+export type UpdateMemoryInput = {
+  name: string;
+  description?: string;
+  content: string;
+  baseVersion: number;
+  source?: string;
+};
+
+export type DeleteMemoryInput = {
+  name: string;
+  baseVersion: number;
+};
+
+/** list() 返回条目，仅存活项（deleted=false）。 */
+export type MemoryListItem = {
+  name: string;
+  description: string;
+  updatedAt: string;
+};
+
+export interface MemoryStore {
+  get(name: string): Promise<MemoryRecord | null>;
+  add(input: AddMemoryInput): Promise<MemoryRecord>;
+  update(input: UpdateMemoryInput): Promise<MemoryRecord>;
+  delete(input: DeleteMemoryInput): Promise<MemoryRecord>;
+  /** 返回当前所有存活 memory 的目录项，供 load-memory 自动生成目录。 */
+  list(): Promise<MemoryListItem[]>;
+}

package/src/orchestrator.ts

@@ -0,0 +1,128 @@
+import type {
+  DerivedSessionState,
+  HarnessTrigger,
+  SessionEvent,
+  SessionEventPayload,
+  SessionRecord,
+  ExecutionScope,
+} from './session/index.js';
+import type { SessionStore } from './session/store.js';
+import type {
+  FailOpenToolCallsInput as EnvironmentFailOpenToolCallsInput,
+  EnvironmentConfigStore,
+  ResourceRegistry,
+} from './environment.js';
+import type { PromptRegistry } from './prompt.js';
+import type { ToolRegistry } from './tool.js';
+import type { Store } from './store.js';
+
+export type WakeSessionResult = {
+  accepted: boolean;
+  reason?: string;
+  trigger?: HarnessTrigger;
+};
+
+export type InterruptSessionResult = {
+  accepted: boolean;
+  reason?: string;
+};
+
+export type SessionWakeHandle = {
+  sessionId: string;
+  load(): Promise<LoadedSessionExecutionContext | null>;
+};
+
+export interface Orchestrator {
+  wakeSession(handle: SessionWakeHandle): Promise<WakeSessionResult>;
+  interruptSession(sessionId: string): Promise<InterruptSessionResult>;
+  reconcileStaleSessions(): Promise<void>;
+  start(): void;
+  stop(): Promise<void>;
+}
+
+export type HarnessConfig = {
+  appId?: string;
+  id: string;
+  version: number;
+  name: string;
+  description?: string;
+  model?: string;
+  promptFragmentIds: string[];
+  toolIds: string[];
+  subAgentHarnessIds: string[];
+  skills: Array<Record<string, unknown>>;
+  metadata: Record<string, unknown>;
+  maxModelTurns?: number;
+  contextResolve?: {
+    keys: string[];
+  };
+  createdAt?: string;
+};
+
+export type HarnessConfigLatestKey = string | { appId?: string; id: string };
+export type HarnessConfigListQuery = { appId?: string };
+
+export interface HarnessConfigStore extends Store<HarnessConfig, { appId?: string; id: string; version: number }> {
+  getLatest(key: HarnessConfigLatestKey): Promise<HarnessConfig | null>;
+  list(query?: HarnessConfigListQuery): Promise<HarnessConfig[]>;
+  listVersions(key: HarnessConfigLatestKey): Promise<HarnessConfig[]>;
+  save(input: HarnessConfig): Promise<HarnessConfig>;
+  publish(input: Omit<HarnessConfig, 'version' | 'createdAt'> & { baseVersion: number }): Promise<HarnessConfig>;
+}
+
+export type LoadedSessionExecutionContext = {
+  session: SessionRecord;
+  state: DerivedSessionState;
+  events: SessionEvent[];
+  sessionBackend: SessionStore;
+};
+
+export interface SessionExecutionContextLoader {
+  load(
+    sessionId: string,
+    scope?: ExecutionScope,
+  ): Promise<LoadedSessionExecutionContext | null>;
+}
+
+export interface ToolLifecycleReconciler {
+  failOpenToolCalls(input: EnvironmentFailOpenToolCallsInput): Promise<void>;
+}
+
+export type StaleRunningSessionCandidate = SessionWakeHandle;
+
+export interface StaleSessionScanner {
+  findStaleRunningSessions(input: {
+    observedAt: string;
+    staleRunningThresholdMs: number;
+  }): Promise<StaleRunningSessionCandidate[]>;
+}
+
+export type RetrySessionCandidate = SessionWakeHandle;
+
+export interface RetrySessionScanner {
+  findDueRetrySessions(input: {
+    observedAt: string;
+  }): Promise<RetrySessionCandidate[]>;
+}
+
+export type QueuedToolWakeSessionCandidate = SessionWakeHandle;
+
+export interface QueuedToolWakeScanner {
+  findQueuedToolWakeSessions(input: {
+    observedAt: string;
+  }): Promise<QueuedToolWakeSessionCandidate[]>;
+}
+
+export type ContextResolveWakeSessionCandidate = SessionWakeHandle;
+
+export interface ContextResolveWakeScanner {
+  findContextResolveWakeSessions(input: {
+    observedAt: string;
+  }): Promise<ContextResolveWakeSessionCandidate[]>;
+}
+
+export type OrchestratorRetryPolicy = {
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+};

package/src/prompt.ts

@@ -0,0 +1,122 @@
+import type { ResourceSlots } from './environment.js';
+import type { Store } from './store.js';
+
+export type PromptFragmentSourceKind = 'static' | 'persisted';
+
+export type PromptFragmentView = {
+  appId?: string | null;
+  id: string;
+  version: number;
+  name: string;
+  description?: string;
+  content: string;
+  enabled: boolean;
+  source: {
+    kind: PromptFragmentSourceKind;
+    sourcePath?: string;
+  };
+  createdAt?: string;
+  updatedAt?: string;
+};
+
+export type CreatePromptFragmentInput = {
+  appId?: string | null;
+  name: string;
+  description?: string;
+  content: string;
+  enabled?: boolean;
+};
+
+export type UpdatePromptFragmentInput = {
+  id: string;
+  baseVersion: number;
+  name?: string;
+  description?: string;
+  content?: string;
+  enabled?: boolean;
+};
+
+export type PromptFragmentListQuery = {
+  appId?: string;
+  includeGlobal?: boolean;
+};
+
+/**
+ * 组装系统提示词的输入参数。
+ *
+ * orchestrator 在每次 session wake 时调用 `PromptRegistry.assemblePrompt()`，
+ * 将 harness 配置中的 fragment ID 列表、metadata 和已实例化的 resources 传入，
+ * 最终拼接出完整的系统提示词。
+ *
+ * @template TMetadata - metadata 的具体 shape，默认为宽泛的 Record
+ * @template TResources - resources 的具体 shape，默认为宽泛的 Record
+ */
+export type AssemblePromptInput<
+  TMetadata extends Record<string, unknown> = Record<string, unknown>,
+  TResources extends object = object,
+> = {
+  /** 当前 session 所属 app；用于只装配该 app 可见的 fragment 与全局 fragment */
+  appId?: string;
+  /** harness 配置中声明的 prompt fragment ID 列表，按顺序拼接 */
+  promptFragmentIds?: string[];
+  /** 来自 harness 配置的静态 metadata（如行为规则开关） */
+  harnessMetadata?: TMetadata;
+  /** 来自 session 的动态 metadata（如 subject.id、applicationId） */
+  sessionMetadata?: TMetadata;
+  /** 已实例化且绑定了 scope 的 resource 集合，供 generator 异步获取数据 */
+  resources?: ResourceSlots & TResources;
+  /** 运行时动态追加的 prompt 片段（不经过 fragment store） */
+  dynamicFragments?: string[];
+};
+
+export interface PromptFragmentStore extends Store<PromptFragmentView> {
+  list(query?: PromptFragmentListQuery): Promise<PromptFragmentView[]>;
+  create(input: CreatePromptFragmentInput): Promise<PromptFragmentView>;
+  update(input: UpdatePromptFragmentInput): Promise<PromptFragmentView>;
+  delete(id: string): Promise<void>;
+}
+
+/**
+ * 提示词注册中心，管理 prompt fragments 的 CRUD 和系统提示词组装。
+ *
+ * orchestrator 在每次 session wake 时调用 `assemblePrompt()`，
+ * 按 harness 配置中声明的 fragment ID 顺序拼接最终系统提示词。
+ */
+export interface PromptRegistry {
+  assemblePrompt(input: AssemblePromptInput): Promise<string>;
+  listPromptFragments(query?: PromptFragmentListQuery): Promise<PromptFragmentView[]>;
+  getPromptFragment(id: string): Promise<PromptFragmentView | null>;
+  createPromptFragment(input: CreatePromptFragmentInput): Promise<PromptFragmentView>;
+  updatePromptFragment(input: UpdatePromptFragmentInput): Promise<PromptFragmentView>;
+  deletePromptFragment(id: string): Promise<void>;
+}
+
+/**
+ * 动态提示词生成器，通过 `generator:<id>` fragment ID 引用。
+ *
+ * 与静态 fragment 不同，generator 可以在运行时异步获取数据（通过 resources），
+ * 并根据 session metadata 动态生成提示词段落。
+ *
+ * @template TMetadata - generate() 接收的 metadata shape，默认宽泛
+ * @template TResources - generate() 接收的 resources shape，默认宽泛
+ */
+export interface PromptGenerator<
+  TMetadata extends Record<string, unknown> = Record<string, unknown>,
+  TResources extends object = object,
+> {
+  id: string;
+  generate(input: {
+    /** harnessMetadata 与 sessionMetadata 合并后的上下文 */
+    metadata: TMetadata;
+    /** 已实例化且绑定了 scope 的 resource 集合 */
+    resources: ResourceSlots & TResources;
+  }): Promise<string> | string;
+}
+
+/**
+ * generator 注册表，通过 ID 查找和注册 PromptGenerator 实例。
+ */
+export interface GeneratorRegistry {
+  get(id: string): PromptGenerator | undefined;
+  register(generator: PromptGenerator): void;
+}

package/src/session/derived-state.ts

@@ -0,0 +1,20 @@
+import type { StopReason } from './events.js';
+import type { SessionEvent } from './events.js';
+
+export type DerivedSessionStatus = 'idle' | 'running' | 'rescheduled' | 'terminated';
+
+export interface DerivedSessionState {
+  status: DerivedSessionStatus;
+  stopReason?: StopReason;
+  lastSeq: number;
+  handledInputSeq: number;
+  activeInputSeqMax?: number;
+  pendingUserMessageEventIds: string[];
+  pendingActionEventIds: string[];
+  openToolCallEventIds: string[];
+  orphanedToolCallEventIds: string[];
+}
+
+export type SessionStreamEnvelope =
+  | { kind: 'event'; event: SessionEvent }
+  | { kind: 'heartbeat'; emittedAt: string };

package/src/session/events.ts

@@ -0,0 +1,298 @@
+import type { SessionId } from './ids.js';
+import type { ExecutionScope } from './scope.js';
+
+// ─── 用户侧 payload ────────────────────────────────────────────────────
+
+/** user.message 内容 part：文本 / 图片引用 / 文档引用。 */
+export type UserMessageContent =
+  | { type: 'text'; text: string }
+  | { type: 'image'; mimeType: string; dataRef: string }
+  | { type: 'document'; mimeType: string; dataRef: string; title?: string };
+
+export type UserMessagePayload = {
+  // 内容 part 列表；运行时「至少一条」由 HTTP 边界 zod schema 的 `.min(1)` 保证，
+  // 类型层用普通数组以与 zod array 推断一致（zod 的 min 不影响类型）。
+  content: UserMessageContent[];
+};
+
+export type UserInterruptPayload = {
+  reason?: string;
+};
+
+export type UserActionResolvedPayload = {
+  kind: 'ask_user' | 'tool_confirmation' | 'custom_tool_result';
+  result: unknown;
+};
+
+// ─── assistant 侧 payload ───────────────────────────────────────────────
+
+export type AssistantOutputCompletedPayload = {
+  text: string;
+};
+
+export type AssistantReasoningCompletedPayload = {
+  text: string;
+  displayMode?: 'summary' | 'full';
+  // provider 原生续传状态。协议层不解释其内部结构，只负责随事件落库并在后续模型回放时原样交还。
+  providerState?: Record<string, unknown>;
+};
+
+// ─── 工具生命周期 payload ───────────────────────────────────────────────
+
+export type ToolCalledPayload = {
+  toolName: string;
+  // 模型 provider 返回的原生工具调用 id。Anthropic extended thinking 会校验同轮
+  // thinking + tool_use 的原始结构，后续回放必须优先使用该 id，而不是本地事件 id。
+  providerToolCallId?: string;
+  input: unknown;
+};
+
+export type ToolCompletedPayload = {
+  toolName: string;
+  result: unknown;
+};
+
+export type ToolErrorPayload = {
+  code?: string;
+  message: string;
+  retryable?: boolean;
+  details?: unknown;
+};
+
+export type ToolFailedPayload = {
+  toolName: string;
+  error: ToolErrorPayload;
+};
+
+export type ToolInterruptedPayload = {
+  toolName: string;
+  reason: 'user_interrupt' | 'abort_signal';
+};
+
+/**
+ * 工具调用未写入终态（进程崩溃 / stale running 收口）时，盖在 `tool.failed.error.code` 上的固定字面值。
+ *
+ * 这是 protocol 的**契约常量**：写方（`@ct-agents/environment`）与读方（`@ct-agents/session` 的派生状态）
+ * 必须对该字面值达成一致才能互操作，且无任何依赖——符合 protocol「零依赖契约字面量」判据。
+ */
+export const TOOL_ORPHANED_ERROR_CODE = 'TOOL_ORPHANED' as const;
+
+export type ToolOrphanedReason = 'process_crash' | 'stale_running_reconcile' | 'unknown';
+
+export type ToolOrphanedErrorDetails = {
+  reason: ToolOrphanedReason;
+  observedAt: string;
+};
+
+// ─── 子 Agent / action payload ──────────────────────────────────────────
+
+export type SessionChildSpawnedPayload = {
+  childSessionId: string;
+  agentId: string;
+  task: string;
+};
+
+export type AgentActionRequestedPayload = {
+  kind: 'ask_user' | 'tool_confirmation' | 'custom_tool_result';
+  prompt?: string;
+  input?: unknown;
+  allowedResults?: unknown[];
+  resultSchema?: Record<string, unknown>;
+  display?: {
+    title?: string;
+    summary?: string;
+  };
+  expiresAt?: string;
+};
+
+// ─── context resolve payload ───────────────────────────────────────────
+
+export type ContextResolveRequestPayload = {
+  kind: 'prompt_context';
+  keys: string[];
+};
+
+export type AgentContextResolvedPayload = {
+  workId: string;
+  request: ContextResolveRequestPayload;
+  snapshot: Record<string, unknown>;
+};
+
+export type AgentContextFailedPayload = {
+  workId: string;
+  request: ContextResolveRequestPayload;
+  error: ToolErrorPayload;
+};
+
+// ─── session 状态机 payload ─────────────────────────────────────────────
+
+export type HarnessTrigger =
+  | { type: 'user_message'; inputSeqMax: number }
+  | { type: 'action_resolved' }
+  | { type: 'resume_running' }
+  | { type: 'retry' };
+
+export type SessionStatusRunningPayload = {
+  inputSeqMax: number;
+  trigger: HarnessTrigger;
+};
+
+export type StopReason =
+  | { type: 'end_turn' }
+  | { type: 'requires_action'; eventIds: string[] }
+  | { type: 'queued_tool'; workIds: string[] }
+  | { type: 'context_resolve'; workIds: string[] }
+  | { type: 'interrupted'; eventId: string }
+  | { type: 'retries_exhausted' }
+  | { type: 'error'; message: string };
+
+export type SessionStatusIdlePayload = {
+  handledInputSeq: number;
+  stopReason: StopReason;
+};
+
+export type SessionStatusRescheduledPayload = {
+  retryAt?: string;
+  attempt?: number;
+  reason?: string;
+};
+
+export type SessionStatusTerminatedPayload = {
+  reason?: string;
+};
+
+export type SessionErrorPayload = {
+  message: string;
+  retryable?: boolean;
+  details?: unknown;
+};
+
+// ─── 事件类型登记表 ─────────────────────────────────────────────────────
+
+export const sessionEventTypes = [
+  'user.message',
+  'user.action.resolved',
+  'user.interrupt',
+  'assistant.output.started',
+  'assistant.output.completed',
+  'assistant.reasoning.started',
+  'assistant.reasoning.completed',
+  'tool.called',
+  'tool.completed',
+  'tool.failed',
+  'tool.interrupted',
+  'agent.action.requested',
+  'agent.context.resolved',
+  'agent.context.failed',
+  'session.child.spawned',
+  'session.status.running',
+  'session.status.idle',
+  'session.status.rescheduled',
+  'session.status.terminated',
+  'session.error',
+  'session.deleted',
+] as const;
+
+export type CoreSessionEventType = (typeof sessionEventTypes)[number];
+
+const sessionEventTypeSet = new Set<string>(sessionEventTypes);
+
+export function isSessionEventType(value: string): value is SessionEventType {
+  return sessionEventTypeSet.has(value);
+}
+
+export interface CoreSessionEventPayloadByType {
+  'user.message': UserMessagePayload;
+  'user.action.resolved': UserActionResolvedPayload;
+  'user.interrupt': UserInterruptPayload;
+  'assistant.output.started': Record<string, never>;
+  'assistant.output.completed': AssistantOutputCompletedPayload;
+  'assistant.reasoning.started': Record<string, never>;
+  'assistant.reasoning.completed': AssistantReasoningCompletedPayload;
+  'tool.called': ToolCalledPayload;
+  'tool.completed': ToolCompletedPayload;
+  'tool.failed': ToolFailedPayload;
+  'tool.interrupted': ToolInterruptedPayload;
+  'agent.action.requested': AgentActionRequestedPayload;
+  'agent.context.resolved': AgentContextResolvedPayload;
+  'agent.context.failed': AgentContextFailedPayload;
+  'session.child.spawned': SessionChildSpawnedPayload;
+  'session.status.running': SessionStatusRunningPayload;
+  'session.status.idle': SessionStatusIdlePayload;
+  'session.status.rescheduled': SessionStatusRescheduledPayload;
+  'session.status.terminated': SessionStatusTerminatedPayload;
+  'session.error': SessionErrorPayload;
+  'session.deleted': Record<string, never>;
+}
+
+/**
+ * 应用事件 payload 的扩展点。
+ *
+ * 业务事件（如 `workspace.*`）通过 module augmentation 注入本接口：
+ * `declare module '@ct-agents/protocol' { interface AppSessionEventPayloadByType {...} }`。
+ * protocol 本身保持业务无关，只提供这个空扩展点。
+ */
+export interface AppSessionEventPayloadByType {}
+
+export type SessionEventPayloadByType =
+  CoreSessionEventPayloadByType
+  & AppSessionEventPayloadByType;
+
+export type SessionEventType = keyof SessionEventPayloadByType & string;
+
+export type SessionEventPayload<TType extends SessionEventType = SessionEventType> =
+  SessionEventPayloadByType[TType];
+
+// ─── 事件结构（协议权威类型，手写定义，不从 schema 反推） ───────────────
+
+export type SessionEventActor = {
+  type: 'user' | 'assistant' | 'tool' | 'system';
+  id?: string;
+};
+
+/**
+ * 事件核心字段——不含数据面 scope 与存储关注点。
+ *
+ * `id` / `turnId` / `parentEventId` 用裸 `string`（忠实原 schema 语义），
+ * 持久化层的 branded 字段见 {@link PersistedSessionEvent}。
+ */
+export interface SessionEventCoreFields {
+  id: string;
+  seq: number;
+  globalSeq?: number;
+  turnId?: string;
+  parentEventId?: string;
+  actor: SessionEventActor;
+  createdAt: string;
+}
+
+/**
+ * 领域事件——harness / orchestrator / tools / frontend 使用。
+ *
+ * 这是 protocol 的权威事件类型，手写定义；不再由 zod schema 反推。
+ *
+ * 使用 distributive 条件类型是有意为之：当 `TType` 取默认值（全联合）时，`SessionEvent`
+ * 展开成「每个事件类型一个成员」的 discriminated union，使得下游 `switch (event.type)`
+ * 能正确收窄 `event.payload`。若改成普通 interface，`type` / `payload` 会退化为
+ * 「同对象内的两个独立联合字段」，丢失判别关联，TS 无法在 switch 中收窄 payload。
+ */
+export type SessionEvent<TType extends SessionEventType = SessionEventType> =
+  TType extends SessionEventType
+    ? SessionEventCoreFields & {
+        type: TType;
+        payload: SessionEventPayloadByType[TType];
+      }
+    : never;
+
+/**
+ * 存储事件——SessionStore / DB 层使用，在核心字段上叠加不透明 scope。
+ */
+export type PersistedSessionEvent<TType extends SessionEventType = SessionEventType> =
+  TType extends SessionEventType
+    ? SessionEvent<TType> & {
+        sessionId: SessionId;
+        rootSessionId?: SessionId;
+        scope: ExecutionScope;
+        idempotencyKey?: string;
+      }
+    : never;

package/src/session/ids.ts

@@ -0,0 +1,12 @@
+/**
+ * 品牌类型工具：给原始类型打上 nominal 标记，使不同语义的字符串 id 在类型层不可互换。
+ * 运行时零开销（brand 标记字段编译期擦除）。
+ */
+type Brand<TValue, TBrand extends string> = TValue & { readonly __brand: TBrand };
+
+export type SessionId = Brand<string, 'SessionId'>;
+export type EventId = Brand<string, 'EventId'>;
+export type UserId = Brand<string, 'UserId'>;
+export type HarnessId = Brand<string, 'HarnessId'>;
+export type EnvironmentId = Brand<string, 'EnvironmentId'>;
+export type TurnId = Brand<string, 'TurnId'>;

package/src/session/index.ts

@@ -0,0 +1,6 @@
+export * from './ids.js';
+export * from './scope.js';
+export * from './record.js';
+export * from './events.js';
+export * from './derived-state.js';
+export * from './store.js';

package/src/session/record.ts

@@ -0,0 +1,32 @@
+import type {
+  EnvironmentId,
+  EventId,
+  HarnessId,
+  SessionId,
+} from './ids.js';
+import type { ExecutionScope } from './scope.js';
+
+/**
+ * 会话记录：一次 Agent 对话的元数据。
+ *
+ * harness / environment 以 pin（`harnessId` + `harnessVersion` / `environmentId` +
+ * `environmentUpdatedAt`）固化会话使用的配置版本，配置变更不影响在跑会话；
+ * `appId` 是应用路由键；业务信息统一进 `metadata`，协议不解释其结构。
+ */
+export interface SessionRecord {
+  id: SessionId;
+  appId: string;
+  scope: ExecutionScope;
+  parentSessionId?: SessionId;
+  rootSessionId?: SessionId;
+  spawnedByEventId?: EventId;
+  harnessId: HarnessId;
+  harnessVersion: number;
+  environmentId: EnvironmentId;
+  environmentUpdatedAt: string;
+  title: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+  deletedAt?: string;
+}

package/src/session/scope.ts

@@ -0,0 +1,6 @@
+/**
+ * 跨进程 / 再入边界携带的隔离句柄。
+ *
+ * 协议只把它当作不透明字符串字典；具体键集由实现层约定和解释。
+ */
+export type ExecutionScope = Readonly<Record<string, string>>;