@x-otto/hook-contracts 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,74 @@
+# @x-otto/hook-contracts
+
+> Engine↔hooks pure type contracts. Zero runtime — `export type` only, compiled output is empty.
+
+`@x-otto/hook-contracts` defines the type-level contract between the engine (`@x-otto/agent`) and the hook system (`@x-otto/hooks`). It provides 25 hook timings with typed input/output payloads, the unified `AgentMessage` type, permission config shapes, and re-exports session event types from `@x-otto/interchange`. Both sides `import type`, avoiding a circular runtime dependency.
+
+## Installation
+
+```bash
+pnpm add @x-otto/hook-contracts
+```
+
+## Usage
+
+```ts
+import type {
+  HookTiming,
+  HookPayloadMap,
+  HookHandle,
+  ObserverTiming,
+  InterceptorTiming,
+} from '@x-otto/hook-contracts'
+
+// Define an observer (output is void)
+function logToolExecution(
+  input: HookPayloadMap['tool.execute.before']['input'],
+) {
+  console.log(`Tool ${input.toolName} starting`)
+}
+
+// Hook payload types are derived automatically
+type ToolBeforeOutput = HookPayloadMap['tool.execute.before']['output']
+```
+
+## API
+
+### Hook Timing Types
+- `HookTiming` — 25 timing string literals
+- `HookPayloadMap` — timing → `{ input, output }` type map
+- `HookInput<T extends HookTiming>` / `HookOutput<T extends HookTiming>` — extract payload by timing
+- `ObserverTiming` — compile-time subset: timings where output is `void` (read-only observation)
+- `InterceptorTiming` — compile-time subset: timings where output can modify behavior
+- `HookHandle<T extends HookTiming>` — derives correct handler signature
+
+### Hook Payload Types
+- `ChatMessageInput` / `ChatMessageOutput` — message interception
+- `ToolExecuteBeforeInput` / `ToolExecuteBeforeOutput` — tool pre-execution (with `PermissionDecision`)
+- `ToolExecuteAfterInput` / `ToolExecuteAfterOutput` — tool post-execution
+- `MessagesTransformInput` / `MessagesTransformOutput` — message array transformation
+- `ChatParamsInput` / `ChatParamsOutput` — LLM call parameter override
+- `SystemPromptTransformInput` / `SystemPromptTransformOutput` — system prompt injection
+- `SessionEventInput` — session lifecycle event observation
+
+### Permission & Agent Types
+- `PermissionMode`, `PermissionRuleConfig`, `PermissionPolicySetting` — permission config shapes
+- `PERMISSION_MODES` — `bypass` / `auto` / `confirm` / `strict` / `readonly`
+- `AgentMessage` — unified message type (user/assistant/tool/system/custom)
+- `SystemAgentMessage` — engine/host UI notifications (not sent to provider)
+- `CustomAgentMessages` — application-level declaration merging extension point
+- `ToolCallContext<Params>` — typed tool execution context
+
+### Session Event Re-exports (from `@x-otto/interchange`)
+- `AgentSessionEvent` / `AgentSessionEventType` — full session event discriminant union
+- `AskUserQuestion`, `GrillQuestion`, `GrillOption`, `GrillAnswer`, `GrillRequest` — HITL types
+- `AgentSessionSubscriber`, `AgentSessionEventMap`
+
+## Dependencies
+
+- Internal: `@x-otto/interchange` (type-only)
+- External: none
+
+## Related
+
+- [Architecture](./ARCHITECTURE.md)

package/dist/index.d.ts

@@ -0,0 +1,407 @@
+import { AgentSessionEvent, AgentSessionEventMap, AgentSessionEventType, AgentSessionSubscriber, AgentTool, AskUserQuestion, GrillAnswer, GrillOption, GrillQuestion, GrillRequest, Message, ToolCallContext, ToolCallEvent, ToolErrorKind, ToolResult } from "@x-otto/interchange";
+
+//#region src/messages.d.ts
+interface CustomAgentMessages {}
+type SystemMessageLevel = 'info' | 'warning' | 'error';
+/**
+ * 系统通知消息（M40-B0-04，对齐 CC SystemMessage 的本地子集）。
+ *
+ * 引擎/宿主产生的 UI 通知（回合耗时、记忆保存、压缩边界、API 错误等），
+ * 属于 AgentMessage（hooks/UI 域）但**不是协议消息**——agent 的
+ * convertToLLM 在类型边界过滤，绝不进 provider 请求（providers 按 role
+ * if/else 分支，未知角色会被静默丢弃或破坏请求构建）。
+ *
+ * subtype 驱动渲染分派（SystemTextMessage 的 subtype switch）；
+ * `(string & {})` 允许宿主扩展自定义子类型同时保留内建集的自动补全。
+ * level 驱动严重性门控（info 默认不渲染除非 verbose）与着色。
+ */
+interface SystemAgentMessage {
+  role: 'system';
+  subtype?: 'turn_duration' | 'memory_saved' | 'compact_boundary' | 'api_error' | 'local_command' | (string & {});
+  level?: SystemMessageLevel;
+  content: string;
+  /** Unix 时间戳（毫秒），与 @x-otto/interchange Timestamp 同语义。 */
+  timestamp: number;
+  /** 稳定消息身份（可选，同 @x-otto/interchange 消息的 uuid 语义）。 */
+  uuid?: string;
+}
+type AgentMessage = Message | SystemAgentMessage | CustomAgentMessages[keyof CustomAgentMessages];
+//#endregion
+//#region src/timings.d.ts
+type HookTiming = 'chat.message.before' | 'chat.message.after' | 'tool.execute.before' | 'tool.execute.after' | 'messages.transform' | 'chat.params' | 'session.created' | 'session.restored' | 'session.deleted' | 'session.idle' | 'session.error' | 'stream.start' | 'stream.end' | 'compaction.before' | 'compaction.after' | 'memory.prune.before' | 'process.spawned' | 'process.exited' | 'task.created' | 'task.started' | 'task.completed' | 'task.failed' | 'task.cancelled' | 'system.prompt.transform' | 'notification';
+interface ChatMessageInput {
+  message: AgentMessage;
+  sessionId: string;
+  isFirstMessage: boolean;
+  metadata: Record<string, unknown>;
+}
+interface ChatMessageOutput {
+  message: AgentMessage;
+  cancelled: boolean;
+  metadata: Record<string, unknown>;
+}
+interface ToolExecuteBeforeInput {
+  toolName: string;
+  toolCallId: string;
+  args: Record<string, unknown>;
+  agentName: string;
+  sessionId: string;
+  /**
+   * 执行器据工具声明的 AgentTool.pathParams 从 args 解析出的文件系统路径。
+   * PEP（permission/file guard）只读此字段做路径规则匹配，不再从 args 硬编码猜参数名。
+   */
+  paths?: readonly string[];
+  /**
+   * 工具是否为只读（AgentTool.readonly）。sandbox-guard 据此跳过写评估——
+   * read/grep/find/lsp 等只读工具的 paths 是读目标而非写目标，不应被当作越界写而误升 ask/deny。
+   */
+  readonly?: boolean;
+}
+type PermissionDecision = 'allow' | 'deny' | 'ask';
+/** 审批显示等级（仅驱动 UI 文案/排序，不参与 allow/deny/ask 裁决）。 */
+type ApprovalRisk = 'low' | 'medium' | 'high';
+interface ToolExecuteBeforeOutput {
+  args: Record<string, unknown>;
+  cancelled: boolean;
+  cancelReason?: string;
+  decision?: PermissionDecision;
+  decisionReason?: string;
+  /**
+   * decision==='ask' 时由权限层从 rich PermissionDecision（safety+policyName）派生的风险等级，
+   * 透传给 HITL UI 作显示提示。缺省时下游回退 'medium'。
+   */
+  risk?: ApprovalRisk;
+}
+interface ToolExecuteAfterInput {
+  toolName: string;
+  toolCallId: string;
+  args: Record<string, unknown>;
+  result: ToolResult;
+  agentName: string;
+  sessionId: string;
+  durationMs: number;
+  /**
+   * 工具是否为只读（AgentTool.readonly），由执行器从工具声明派生。
+   * after-hook（comment-checker / edit-files-panel）据此识别「会改文件的工具」，
+   * 取代各自硬编码的 write/edit 工具名集合——工具身份单源自注册表声明。
+   */
+  readonly?: boolean;
+}
+interface ToolExecuteAfterOutput {
+  result: ToolResult;
+  metadata: Record<string, unknown>;
+}
+interface MessagesTransformInput {
+  messages: AgentMessage[];
+  tools: AgentTool[];
+  agentName: string;
+  sessionId: string;
+}
+interface MessagesTransformOutput {
+  messages: AgentMessage[];
+}
+interface ChatParamsInput {
+  sessionId?: string;
+  model: string;
+  provider: string;
+  temperature?: number;
+  maxTokens?: number;
+  thinkingLevel?: string;
+}
+interface ChatParamsOutput {
+  temperature?: number;
+  maxTokens?: number;
+  thinkingLevel?: string;
+  metadata: Record<string, unknown>;
+}
+interface SystemPromptTransformInput {
+  systemPrompt: string;
+  sessionId: string;
+  tools: AgentTool[];
+  /** RFC-284 T3a：当前 prompt 的显式 user query，用于 volatile Relevant Hints。 */
+  userText?: string;
+}
+interface SystemPromptTransformOutput {
+  /** 会话内稳定的 system 前缀（进入 prompt cache）。稳定注入累加到这里。 */
+  systemPrompt: string;
+  /**
+   * 每轮可变（volatile）的 system 尾段：附在 stable 前缀的 cache 断点**之后**，
+   * 不破坏 prompt cache。逐轮变化的注入（如 phase context）写这里而非 systemPrompt。
+   */
+  systemTail?: string[];
+}
+interface SessionEventInput {
+  sessionId: string;
+  metadata: Record<string, unknown>;
+}
+interface MemoryPruneBeforeInput {
+  sessionId: string;
+  /** 即将参与裁剪判定的上下文消息条数。 */
+  messageCount: number;
+}
+interface MemoryPruneBeforeOutput {
+  /** true → 否决本轮裁剪（引擎据此对 process 传 skipPrune）。 */
+  cancelled: boolean;
+}
+interface HookPayloadMap {
+  'chat.message.before': {
+    input: ChatMessageInput;
+    output: ChatMessageOutput;
+  };
+  'chat.message.after': {
+    input: ChatMessageInput;
+    output: ChatMessageOutput;
+  };
+  'tool.execute.before': {
+    input: ToolExecuteBeforeInput;
+    output: ToolExecuteBeforeOutput;
+  };
+  'tool.execute.after': {
+    input: ToolExecuteAfterInput;
+    output: ToolExecuteAfterOutput;
+  };
+  'messages.transform': {
+    input: MessagesTransformInput;
+    output: MessagesTransformOutput;
+  };
+  'chat.params': {
+    input: ChatParamsInput;
+    output: ChatParamsOutput;
+  };
+  'session.created': {
+    input: SessionEventInput;
+    output: void;
+  };
+  'session.restored': {
+    input: SessionEventInput;
+    output: void;
+  };
+  'session.deleted': {
+    input: SessionEventInput;
+    output: void;
+  };
+  'session.idle': {
+    input: SessionEventInput;
+    output: void;
+  };
+  'session.error': {
+    input: SessionEventInput & {
+      error: Error;
+    };
+    output: void;
+  };
+  'stream.start': {
+    input: {
+      sessionId: string;
+      model: string;
+    };
+    output: void;
+  };
+  'stream.end': {
+    input: {
+      sessionId: string;
+      model: string;
+      stopReason: string;
+      /**
+       * RFC-129 D6：本次 done 事件的 token 用量（可选——向后兼容，既有消费方不读取新字段则
+       * 行为不变）。来源 `event.message.usage`（即时数据），非会话级累积状态。
+       */
+      tokenUsage?: {
+        input: number;
+        output: number;
+      };
+    };
+    output: void;
+  };
+  'compaction.before': {
+    input: {
+      sessionId: string;
+      messageCount: number;
+    };
+    output: void;
+  };
+  'compaction.after': {
+    input: {
+      sessionId: string;
+      retainedCount: number;
+    };
+    output: void;
+  };
+  'memory.prune.before': {
+    input: MemoryPruneBeforeInput;
+    output: MemoryPruneBeforeOutput;
+  };
+  'process.spawned': {
+    input: {
+      sessionId: string;
+      processId: string;
+      pid: number;
+      command: string;
+      port?: number;
+    };
+    output: void;
+  };
+  'process.exited': {
+    input: {
+      sessionId: string;
+      processId: string;
+      pid: number;
+      command: string;
+      status: string;
+      exitCode?: number;
+    };
+    output: void;
+  };
+  'task.created': {
+    input: {
+      task: TaskHookInfo;
+    };
+    output: void;
+  };
+  'task.started': {
+    input: {
+      task: TaskHookInfo;
+      agent: string;
+    };
+    output: void;
+  };
+  'task.completed': {
+    input: {
+      task: TaskHookInfo;
+      result: TaskHookOutput;
+      subagentResult?: TaskHookOutput;
+    };
+    output: void;
+  };
+  'task.failed': {
+    input: {
+      task: TaskHookInfo;
+      error: TaskHookError;
+    };
+    output: void;
+  };
+  'task.cancelled': {
+    input: {
+      taskId: string;
+    };
+    output: void;
+  };
+  'system.prompt.transform': {
+    input: SystemPromptTransformInput;
+    output: SystemPromptTransformOutput;
+  };
+  notification: {
+    input: NotificationHookInput;
+    output: void;
+  };
+}
+/**
+ * task.* hook 的 **hook-owned** payload 契约。
+ *
+ * Task/TaskResult/TaskError 定义在 orchestrator 领域包（依赖 hook-contracts），反向 import 成环；
+ * 故 hook 层拥有自己暴露的 payload 形状（生产者 orchestrator 的 Task 是其结构超集，emit 时直接赋值，
+ * spread 的额外字段经 TS 豁免）。取代原 `Record<string, unknown>` + orchestrator 侧 `as unknown as` 下降。
+ */
+interface TaskHookError {
+  code: string;
+  message: string;
+  retriable: boolean;
+}
+interface TaskHookOutput {
+  text: string;
+  summary?: string;
+  tokenUsage?: {
+    input: number;
+    output: number;
+    cacheRead: number;
+  };
+  durationMs?: number;
+}
+interface TaskHookInfo {
+  id: string;
+  parentId?: string;
+  status: string;
+  sessionId?: string;
+  attempts: number;
+  maxAttempts: number;
+  createdAt: number;
+  completedAt?: number;
+  output?: TaskHookOutput;
+  error?: TaskHookError;
+  /**
+   * Swarm 编排事件上下文（RFC-107 D1 / M-N6）。
+   * 当 task 属于 swarm 编排时由 Swarm.emitEvent 经 hookRegistry 桥接注入；
+   * 下游 hook 据此区分普通 task 与 swarm 成员 turn，并消费路由/编组元数据。
+   */
+  swarmEvent?: SwarmEventPayload;
+}
+/**
+ * Swarm 编排事件载荷（hook-contracts 拥有最小形状；实际数据由 orchestrator/swarm 填充）。
+ * 不新建 swarm.* HookTiming 家族——经既有 task.*（如 task.started）携带。
+ */
+interface SwarmEventPayload {
+  /** 事件类型：swarm.start | swarm.end | agent.start | agent.end | handoff |
+   *  routing.decision | parallel.fanOut | parallel.fanIn | pipeline.step |
+   *  hierarchy.delegate | error */
+  type: string;
+  /** 事件附加元数据（按 type 不同携带 agentId/durationMs/decision 等字段）。 */
+  [key: string]: unknown;
+}
+/** 通知 hook 出站 payload（producer=HookChannel；consumer=.claude 桥/用户 hook）。 */
+interface NotificationHookInput {
+  sessionId: string;
+  message: string;
+  title?: string;
+  /** 归一类别：turn_complete / error / approval_required / input_required（matcher 据此过滤）。 */
+  notification_type: string;
+}
+type HookInput<T extends HookTiming> = HookPayloadMap[T]['input'];
+type HookOutput<T extends HookTiming> = HookPayloadMap[T]['output'];
+type ObserverTiming = { [K in HookTiming]: HookPayloadMap[K]['output'] extends void ? K : never }[HookTiming];
+type InterceptorTiming = { [K in HookTiming]: HookPayloadMap[K]['output'] extends void ? never : K }[HookTiming];
+type HookHandle<T extends HookTiming> = T extends ObserverTiming ? (input: HookInput<T>) => void | Promise<void> : (input: HookInput<T>, output: HookOutput<T>) => void | Promise<void>;
+//#endregion
+//#region src/permission-config.d.ts
+/**
+ * 权限**配置形状**单一真源（RFC-077 mirror-debt 收口，HK-1）。
+ *
+ * 背景：权限配置形状（mode 词表 + policy/rule 的 config 结构）历史上双份定义——
+ * `@x-otto/setting` 的 zod schema（z.infer）与 `@x-otto/hooks` 引擎的手写 interface。二者层序不可互依
+ * （hooks L2 < setting L3，hooks 不能上依赖 setting），故各写一套、无 drift guard。
+ *
+ * 收口：把配置形状沉到二者都能**下依赖**的零依赖叶 `@x-otto/hook-contracts`（L1）：
+ * - `@x-otto/hooks` 引擎 import 这些类型（删手写镜像）。
+ * - `@x-otto/setting` 的 zod schema `satisfies z.ZodType<…>` 钉死到此（drift→编译报错），并 re-export。
+ *
+ * 这里只放**配置/wire 形状**（作者在 config.json 写的东西）；运行时引擎类型
+ * （PermissionPolicy/PermissionContext/PermissionDecision/PolicyScope 等，含 RegExp/函数/时间戳）
+ * 仍属引擎、留 `@x-otto/hooks`。
+ */
+/** 权限模式词表（config.json `permission_mode` + 运行时模式）。 */
+declare const PERMISSION_MODES: readonly ["bypass", "auto", "confirm", "strict", "readonly"];
+type PermissionMode = (typeof PERMISSION_MODES)[number];
+/** 规则效果。 */
+type RuleEffect = 'allow' | 'deny' | 'ask';
+/** 单条权限规则的**配置**形状（config.json）。运行时 `PermissionRule`（含编译后 RegExp）属引擎。 */
+interface PermissionRuleConfig {
+  name: string;
+  effect: RuleEffect;
+  tools?: string[];
+  paths?: string[];
+  deny_reason?: string;
+  ask_prompt?: string;
+}
+/** 单个权限策略的**配置**形状（config.json）。运行时 `PermissionPolicy`（含 safety/priority 语义）属引擎。 */
+interface PermissionPolicySetting {
+  name: string;
+  priority?: number;
+  enabled?: boolean;
+  scope?: {
+    agents?: string[];
+    sessions?: string[];
+  };
+  rules: PermissionRuleConfig[];
+}
+//#endregion
+export { type AgentMessage, type AgentSessionEvent, type AgentSessionEventMap, type AgentSessionEventType, type AgentSessionSubscriber, type AgentTool, type ApprovalRisk, type AskUserQuestion, type ChatMessageInput, type ChatMessageOutput, type ChatParamsInput, type ChatParamsOutput, type CustomAgentMessages, type GrillAnswer, type GrillOption, type GrillQuestion, type GrillRequest, type HookHandle, type HookInput, type HookOutput, type HookPayloadMap, type HookTiming, type InterceptorTiming, type MessagesTransformInput, type MessagesTransformOutput, type NotificationHookInput, type ObserverTiming, PERMISSION_MODES, type PermissionDecision, type PermissionMode, type PermissionPolicySetting, type PermissionRuleConfig, type RuleEffect, type SessionEventInput, type SwarmEventPayload, type SystemAgentMessage, type SystemMessageLevel, type SystemPromptTransformInput, type SystemPromptTransformOutput, type TaskHookError, type TaskHookInfo, type TaskHookOutput, type ToolCallContext, type ToolCallEvent, type ToolErrorKind, type ToolExecuteAfterInput, type ToolExecuteAfterOutput, type ToolExecuteBeforeInput, type ToolExecuteBeforeOutput, type ToolResult };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/messages.ts","../src/timings.ts","../src/permission-config.ts"],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,2 @@
+const e=[`bypass`,`auto`,`confirm`,`strict`,`readonly`];export{e as PERMISSION_MODES};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/permission-config.ts"],"sourcesContent":["/**\n * 权限**配置形状**单一真源（RFC-077 mirror-debt 收口，HK-1）。\n *\n * 背景：权限配置形状（mode 词表 + policy/rule 的 config 结构）历史上双份定义——\n * `@x-otto/setting` 的 zod schema（z.infer）与 `@x-otto/hooks` 引擎的手写 interface。二者层序不可互依\n * （hooks L2 < setting L3，hooks 不能上依赖 setting），故各写一套、无 drift guard。\n *\n * 收口：把配置形状沉到二者都能**下依赖**的零依赖叶 `@x-otto/hook-contracts`（L1）：\n * - `@x-otto/hooks` 引擎 import 这些类型（删手写镜像）。\n * - `@x-otto/setting` 的 zod schema `satisfies z.ZodType<…>` 钉死到此（drift→编译报错），并 re-export。\n *\n * 这里只放**配置/wire 形状**（作者在 config.json 写的东西）；运行时引擎类型\n * （PermissionPolicy/PermissionContext/PermissionDecision/PolicyScope 等，含 RegExp/函数/时间戳）\n * 仍属引擎、留 `@x-otto/hooks`。\n */\n\n/** 权限模式词表（config.json `permission_mode` + 运行时模式）。 */\nexport const PERMISSION_MODES = ['bypass', 'auto', 'confirm', 'strict', 'readonly'] as const\nexport type PermissionMode = (typeof PERMISSION_MODES)[number]\n\n/** 规则效果。 */\nexport type RuleEffect = 'allow' | 'deny' | 'ask'\n\n/** 单条权限规则的**配置**形状（config.json）。运行时 `PermissionRule`（含编译后 RegExp）属引擎。 */\nexport interface PermissionRuleConfig {\n  name: string\n  effect: RuleEffect\n  tools?: string[]\n  paths?: string[]\n  deny_reason?: string\n  ask_prompt?: string\n}\n\n/** 单个权限策略的**配置**形状（config.json）。运行时 `PermissionPolicy`（含 safety/priority 语义）属引擎。 */\nexport interface PermissionPolicySetting {\n  name: string\n  priority?: number\n  enabled?: boolean\n  scope?: {\n    agents?: string[]\n    sessions?: string[]\n  }\n  rules: PermissionRuleConfig[]\n}\n"],"mappings":"AAiBA,MAAa,EAAmB,CAAC,SAAU,OAAQ,UAAW,SAAU,WAAW"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@x-otto/hook-contracts",
+  "version": "0.0.1-alpha.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "alpha"
+  },
+  "dependencies": {
+    "@x-otto/interchange": "0.1.0-alpha.1"
+  },
+  "private": false,
+  "scripts": {
+    "build": "tsdown",
+    "typecheck:project": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}